From 09069b617285ab26f5b9ac696b51aad3a87079cc Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Fri, 8 Apr 2011 07:26:20 +0000 Subject: [PATCH] doxy move to header. SVN revision: 58477 --- legacy/evas/doc/evas.dox.in | 323 - legacy/evas/src/lib/Evas.h | 6963 +++++++++++++++-- legacy/evas/src/lib/Evas_GL.h | 91 +- legacy/evas/src/lib/canvas/Makefile.am | 1 - .../evas/src/lib/canvas/evas_async_events.c | 51 - legacy/evas/src/lib/canvas/evas_callbacks.c | 390 - legacy/evas/src/lib/canvas/evas_clip.c | 138 - legacy/evas/src/lib/canvas/evas_data.c | 84 - legacy/evas/src/lib/canvas/evas_events.c | 296 - legacy/evas/src/lib/canvas/evas_focus.c | 56 - legacy/evas/src/lib/canvas/evas_gl.c | 74 +- legacy/evas/src/lib/canvas/evas_key.c | 173 - legacy/evas/src/lib/canvas/evas_key_grab.c | 59 - legacy/evas/src/lib/canvas/evas_layer.c | 28 - legacy/evas/src/lib/canvas/evas_main.c | 620 -- legacy/evas/src/lib/canvas/evas_map.c | 471 -- legacy/evas/src/lib/canvas/evas_name.c | 28 - legacy/evas/src/lib/canvas/evas_object_box.c | 343 - .../evas/src/lib/canvas/evas_object_image.c | 632 -- .../src/lib/canvas/evas_object_intercept.c | 195 - legacy/evas/src/lib/canvas/evas_object_line.c | 35 - legacy/evas/src/lib/canvas/evas_object_main.c | 423 - .../evas/src/lib/canvas/evas_object_polygon.c | 25 - .../src/lib/canvas/evas_object_rectangle.c | 15 - .../evas/src/lib/canvas/evas_object_smart.c | 238 - .../lib/canvas/evas_object_smart_clipped.c | 69 - .../evas/src/lib/canvas/evas_object_table.c | 155 - legacy/evas/src/lib/canvas/evas_object_text.c | 362 +- .../src/lib/canvas/evas_object_textblock.c | 653 -- legacy/evas/src/lib/canvas/evas_render.c | 111 - legacy/evas/src/lib/canvas/evas_smart.c | 97 - legacy/evas/src/lib/canvas/evas_stack.c | 74 - legacy/evas/src/lib/canvas/evas_stats.c | 36 - legacy/evas/src/lib/canvas/evas_transform.c | 2 - 34 files changed, 6607 insertions(+), 6704 deletions(-) delete mode 100644 legacy/evas/src/lib/canvas/evas_transform.c diff --git a/legacy/evas/doc/evas.dox.in b/legacy/evas/doc/evas.dox.in index 2721361911..e69de29bb2 100644 --- a/legacy/evas/doc/evas.dox.in +++ b/legacy/evas/doc/evas.dox.in @@ -1,323 +0,0 @@ -/** - -@mainpage Evas - -@image html e_big.png - -@version @PACKAGE_VERSION@ -@author Carsten Haitzler -@author Till Adam -@author Steve Ireland -@author Brett Nash -@author Tilman Sauerbeck -@author Corey Donohoe -@author Yuri Hudobin -@author Nathan Ingersoll -@author Willem Monsuwe -@author Jose O Gonzalez -@author Bernhard Nemec -@author Jorge Luis Zapata Muga -@author Cedric Bail -@author Gustavo Sverzut Barbieri -@author Vincent Torri -@author Tim Horton -@author Tom Hacohen -@author Mathieu Taillefumier -@author Iván Briano -@author Gustavo Lima Chaves -@author Samsung Electronics -@author Samsung SAIT -@author Sung W. Park -@author Jiyoun Park -@date 2000-2011 - -@section toc Table of Contents - -@li @ref intro -@li @ref work -@li @ref compiling -@li @ref install -@li @ref next_steps -@li @ref intro_example - - -@section intro What is Evas? - -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 much and 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's small and lean, 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 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 Evas, Edje, 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 feed them to -Evas. Similarly, it will not create windows or report windows updates -to your system, rather just drawing the pixels and reporting to the -user the areas that were changed. Of course these operations are quite -common and thus they are ready to use in Ecore, particularly in -Ecore_Evas (http://docs.enlightenment.org/auto/ecore/). - - -@section 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 canvases state on the display. - -Immediate mode display systems retain very little, or no state. A program -will execute 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 how to redraw sections of the -screen whenever needed. Each successive command will be 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 more and more logic and display rendering code needs to be written -time and time again, each time the application needs to figure out how to -minimise redraws so that display is fast and interactive, and keep track of -redraw logic. The power comes at a high-price, lots of extra code and work. -Programmers not very familiar with graphics programming will often make -mistakes at this level and produce code that is sub optimal. Those familiar -with this kind of programming will 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 was 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 - -The clever reader 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 tends 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! The developer 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 quickly one realizes 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, -the programmer only moves, resizes, shows, hides etc. the objects that they -need to change. The programmer simply thinks at the object logic level, and -the canvas software does the rest of the work for them, figuring out what -actually changed in the canvas since it was last drawn, how to most -efficiently redraw he 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 the programmer 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 etc. Since Evas also is -portable across different display systems, this also gives the programmer -the ability to have their code ported and display 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, push -buttons etc. - - -@section compiling How to compile using Evas ? - -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 @p 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 - -You simply have to make sure that pkg-config is in your shell's PATH (see -the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig -or its path is in the PKG_CONFIG_PATH environment variable. It's that simple -to link and use Evas once you have written your code to use it. - -Since the program is linked to Evas, it is now able to use any advertised -API calls to display graphics in a canvas managed by Evas, as well as use -the API calls provided to manage data as well. - -You should make sure you add any extra compile and link flags to your -compile commands that your application may need as well. The above example -is only guaranteed to make Evas add it's own requirements. - - -@section install How is it installed? - -Simple: - -@verbatim -./configure -make -su - -... -make install -@endverbatim - -@section 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 Ecore -(http://docs.enlightenment.org/auto/ecore/) and Edje -(http://docs.enlightenment.org/auto/edje/) as they will likely save -you tons of work compared to using just Evas directly. - -Recommended reading: - -@li @ref Evas_Object_Group -@li @ref Evas_Object_Rectangle -@li @ref Evas_Object_Image -@li @ref Evas_Object_Text -@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define - an object that provides custom functions to handle clipping, - hiding, moving, resizing, setting the color and more. These could - be as simple as a group of objects that move together (see @ref - Evas_Smart_Object_Clipped). These smart objects can implement what - ends to be a widget, providing some intelligence (thus the name), - like a button or check box. - -@section intro_example Introductory Example - -@include evas-buffer-simple.c - - - -@todo (1.0) Need a way ot scaling an image and just PRODUCING the output (scaling direct to target buffe r- no blend/copy etc.) -@todo (1.0) Could improve evas's scaling down code to limit multiple samples per output pixel to maybe 2x2? -@todo (1.0) Document API -@todo (1.0) Evas needs to check delete_me member for all object functions -@todo (1.0) Evas engine that renders to Evas_Objects -@todo (1.0) OpenGL engine needs to use texture meshes -@todo (1.0) OpenGL engine needs texture cache and size setting -@todo (1.0) OpenGL Engine needs YUV import API to YUV texture -@todo (1.0) All engines need pixel import API -@todo (1.0) Add parital render through composite layer api to engines -@todo (1.0) Move callback processing to a queue and do it asynchronously??? -@todo (1.0) Add button grabbing -@todo (1.0) Add generic object method call system -@todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too. -@todo (1.0) Add font load query calls (so we know if a font load failed) -@todo (1.0) Add font listing calls -@todo (1.0) Add ability to check image comments & disk format -@todo (1.0) Add fontset support -@todo (1.0) Export engine rendering API cleanly to Evas API -@todo (1.0) Add smart object ability to provide rendering callback -@todo (1.1) Make freetype optional and put in optional graymap font engine -@todo (1.1) Free images if object invisible (and put back in chache) -@todo (1.1) Check robustness of malloc/calloc/realloc failures. -@todo (1.1) Add memory use reduction code if any allocations fail -@todo (1.1) If image loads fails due to memory allocatue failure, load reduced res version -@todo (1.1) If image load fails due to memory allocation failure, try split it up into tiles and demand-load them -@todo (1.2) Add external image loaders (application provided callbacks to load) -@todo (1.2) Add loadable image loader module support (evas loads file.so) -@todo (1.2) Add external image loader modules (application provides path to file.so) -@todo (1.3) Add X11 primtive engine (ie pixmap) -@todo (1.3) Add immediate mode drawing commands to image objects -@todo (1.3) Fix FB engine to allocate vt and release properly -@todo (1.4) Add ellipse objects (circle, arc, ellipse etc.) -@todo (1.5) Make software engine draw lines & polys etc. with aa -@todo (1.5) Add radial gradients to gradient objects -@todo (1.5) Add Symbian Engine -@todo (1.6) Add PalmOS Engine -@todo (1.6) Add Apple OpenGL Engine -@todo (1.7) Document engine API and other internals -@todo (1.7) Allow any object to clip any other object, and not just rectangles -@todo (1.8) Add more evas demos -@todo (1.9) Write the error mechanism in evas_xcb_buffer.c -@todo (1.9) Rewrite the render xcb engine -@todo (1.10) Improve Win32 Direct3D Engine - -*/ diff --git a/legacy/evas/src/lib/Evas.h b/legacy/evas/src/lib/Evas.h index 8c39345d76..dd2da6c5a8 100644 --- a/legacy/evas/src/lib/Evas.h +++ b/legacy/evas/src/lib/Evas.h @@ -1,3 +1,278 @@ +/** +@mainpage Evas + +@image html e_big.png + +@version 1.0.0 +@author Carsten Haitzler +@author Till Adam +@author Steve Ireland +@author Brett Nash +@author Tilman Sauerbeck +@author Corey Donohoe +@author Yuri Hudobin +@author Nathan Ingersoll +@author Willem Monsuwe +@author Jose O Gonzalez +@author Bernhard Nemec +@author Jorge Luis Zapata Muga +@author Cedric Bail +@author Gustavo Sverzut Barbieri +@author Vincent Torri +@author Tim Horton +@author Tom Hacohen +@author Mathieu Taillefumier +@author Iván Briano +@author Gustavo Lima Chaves +@author Samsung Electronics +@author Samsung SAIT +@author Sung W. Park +@author Jiyoun Park +@date 2000-2011 + +@section toc Table of Contents + +@li @ref intro +@li @ref work +@li @ref compiling +@li @ref install +@li @ref next_steps +@li @ref intro_example + + +@section intro What is Evas? + +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 much and 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's small and lean, 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 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 Evas, Edje, 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 feed them to +Evas. Similarly, it will not create windows or report windows updates +to your system, rather just drawing the pixels and reporting to the +user the areas that were changed. Of course these operations are quite +common and thus they are ready to use in Ecore, particularly in +Ecore_Evas (http://docs.enlightenment.org/auto/ecore/). + + +@section 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 canvases state on the display. + +Immediate mode display systems retain very little, or no state. A program +will execute 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 how to redraw sections of the +screen whenever needed. Each successive command will be 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 more and more logic and display rendering code needs to be written +time and time again, each time the application needs to figure out how to +minimise redraws so that display is fast and interactive, and keep track of +redraw logic. The power comes at a high-price, lots of extra code and work. +Programmers not very familiar with graphics programming will often make +mistakes at this level and produce code that is sub optimal. Those familiar +with this kind of programming will 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 was 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 + +The clever reader 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 tends 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! The developer 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 quickly one realizes 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, +the programmer only moves, resizes, shows, hides etc. the objects that they +need to change. The programmer simply thinks at the object logic level, and +the canvas software does the rest of the work for them, figuring out what +actually changed in the canvas since it was last drawn, how to most +efficiently redraw he 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 the programmer 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 etc. Since Evas also is +portable across different display systems, this also gives the programmer +the ability to have their code ported and display 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, push +buttons etc. + + +@section compiling How to compile using Evas ? + +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 @p 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 + +You simply have to make sure that pkg-config is in your shell's PATH (see +the manual page for your appropriate shell) and evas.pc in /usr/lib/pkgconfig +or its path is in the PKG_CONFIG_PATH environment variable. It's that simple +to link and use Evas once you have written your code to use it. + +Since the program is linked to Evas, it is now able to use any advertised +API calls to display graphics in a canvas managed by Evas, as well as use +the API calls provided to manage data as well. + +You should make sure you add any extra compile and link flags to your +compile commands that your application may need as well. The above example +is only guaranteed to make Evas add it's own requirements. + + +@section install How is it installed? + +Simple: + +@verbatim +./configure +make +su - +... +make install +@endverbatim + +@section 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 Ecore +(http://docs.enlightenment.org/auto/ecore/) and Edje +(http://docs.enlightenment.org/auto/edje/) as they will likely save +you tons of work compared to using just Evas directly. + +Recommended reading: + +@li @ref Evas_Object_Group +@li @ref Evas_Object_Rectangle +@li @ref Evas_Object_Image +@li @ref Evas_Object_Text +@li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group to define + an object that provides custom functions to handle clipping, + hiding, moving, resizing, setting the color and more. These could + be as simple as a group of objects that move together (see @ref + Evas_Smart_Object_Clipped). These smart objects can implement what + ends to be a widget, providing some intelligence (thus the name), + like a button or check box. + +@section intro_example Introductory Example + +@include evas-buffer-simple.c +*/ + #ifndef _EVAS_H #define _EVAS_H @@ -654,8 +929,34 @@ typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type t * * Functions that affect Evas as a whole. */ - EAPI int evas_init (void); - EAPI int evas_shutdown (void); + +/** + * Initialize Evas + * + * @return The init counter value. + * + * This function initialize evas, increments a counter of the number + * of calls to this function and returns this value. + * + * @see evas_shutdown(). + * + * @ingroup Evas_Group + */ +EAPI int evas_init (void); + +/** + * Shutdown Evas + * + * @return The init counter value. + * + * This function finalize evas, decrements the counter of the number + * of calls to the function evas_init() and returns this value. + * + * @see evas_init(). + * + * @ingroup Evas_Group + */ +EAPI int evas_shutdown (void); /** @@ -711,9 +1012,63 @@ typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type t */ EAPI Evas_Alloc_Error evas_alloc_error (void); - EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE; - EAPI int evas_async_events_process (void); - 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); + +/** + * @brief Get evas' internal asynchronous events read file descriptor. + * + * @return The canvas' asynchronous events read file descriptor. + * + * 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. + * + * An example of actual use of this API is for image asynchronous + * preload inside evas. If the canvas was instantiated through + * ecore-evas usage, ecore itself will take care of calling those + * events' processing. + * + * This function returns the read file descriptor where to get the + * asynchronous events of the canvas. Naturally, other mainloops, + * apart from ecore, may make use of it. + * + * @ingroup Evas_Group + */ +EAPI int evas_async_events_fd_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * @brief Trigger the processing of all events waiting on the file + * descriptor returned by evas_async_events_fd_get(). + * + * @return The number of events processed. + * + * 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. + * + * @ingroup Evas_Group + */ +EAPI int evas_async_events_process (void); + +/** +* Insert asynchronous events on the canvas. + * + * @param target The target to be affected by the events. + * @param type The type of callback function. + * @param event_info Information about the event. + * @param func The callback function pointer. + * + * 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. + * + * @ingroup Evas_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 @@ -724,27 +1079,240 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * */ - EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; - EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Creates a new empty evas. + * + * Note that before you can use the evas, you will to at a minimum: + * @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 . + * + * This function should only fail if the memory allocation fails + * + * @note this function is very low level. 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/. + * + * @attention it is recommended that one calls evas_init() before + * creating new canvas. + * + * @return A new uninitialised Evas canvas on success. Otherwise, @c + * NULL. + * @ingroup Evas_Canvas + */ +EAPI Evas *evas_new (void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * Frees the given evas and any objects created on it. + * + * Any objects with 'free' callbacks will have those callbacks called + * in this function. + * + * @param e The given evas. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_free (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_focus_in (Evas *e); - EAPI void evas_focus_out (Evas *e); - EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE; - EAPI void evas_nochange_push (Evas *e); - EAPI void evas_nochange_pop (Evas *e); + +/** + * Inform to the evas that it got the focus. + * + * @param e The evas to change information. + * @ingroup Evas_Canvas + */ +EAPI void evas_focus_in (Evas *e); + +/** + * Inform to the evas that it lost the focus. + * + * @param e The evas to change information. + * @ingroup Evas_Canvas + */ +EAPI void evas_focus_out (Evas *e); + +/** + * Get the focus state known by the given evas + * + * @param e The evas to query information. + * @ingroup Evas_Canvas + */ +EAPI Eina_Bool evas_focus_state_get (const Evas *e) EINA_PURE; + +/** + * Push the nochange flag up 1 + * + * This tells evas, that while the nochange flag is greater than 0, do not + * mark objects as "changed" when making changes. + * + * @param e The evas to change information. + * @ingroup Evas_Canvas + */ +EAPI void evas_nochange_push (Evas *e); + +/** + * Pop the nochange flag down 1 + * + * This tells evas, that while the nochange flag is greater than 0, do not + * mark objects as "changed" when making changes. + * + * @param e The evas to change information. + * @ingroup Evas_Canvas + */ +EAPI void evas_nochange_pop (Evas *e); - EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1); - EAPI void *evas_data_attach_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Attaches a specific pointer to the evas for fetching later + * + * @param e The canvas to attach the pointer to + * @param data The pointer to attach + * @ingroup Evas_Canvas + */ +EAPI void evas_data_attach_set (Evas *e, void *data) EINA_ARG_NONNULL(1); + +/** + * Returns the pointer attached by evas_data_attach_set() + * + * @param 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) EINA_PURE; - EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1); - EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI void evas_render_updates_free (Eina_List *updates); - EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Add a damage rectangle. + * + * @param e The given canvas pointer. + * @param x The rectangle's left position. + * @param y The rectangle's top position. + * @param w The rectangle's width. + * @param h The rectangle's height. + * + * This is the function by which one tells evas that a part of the + * canvas has to be repainted. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * Add an obscured region. + * + * @param e The given canvas pointer. + * @param x The rectangle's left position. + * @param y The rectangle's top position + * @param w The rectangle's width. + * @param h The rectangle's height. + * + * This is the function by which one tells evas that a part of the + * canvas has not to be repainted. To make this region one that have + * to be repainted, call the function evas_obscured_clear(). + * + * @see evas_obscured_clear(). + * + * @ingroup Evas_Canvas + */ +EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * Remove all obscured region rectangles from the canvas. + * + * @param e The given canvas pointer. + * + * This function removes all the rectangles from the obscured list of + * the canvas. It takes obscured areas added with + * evas_obscured_rectangle_add() and makes it a region that have to be + * repainted. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Force immediate renderization of the given canvas. + * + * @param e The given canvas pointer. + * @return A newly allocated list of updated rectangles of the canvas. + * Free this list with evas_render_updates_free(). + * + * This function forces an immediate renderization update of the given + * given canvas. + * + * @ingroup Evas_Canvas + */ +EAPI Eina_List *evas_render_updates (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Free the rectangles returned by evas_render_updates(). + * + * @param updates The list of updated rectangles of the canvas. + * + * This function removes the region from the render updates list. It + * makes the region doesn't be render updated anymore. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_updates_free (Eina_List *updates); + +/** + * Force renderization of the given canvas. + * + * @param e The given canvas pointer. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Update the canvas internal objects but not triggering immediate + * renderization. + * + * @param e The given canvas pointer. + * + * This function updates the canvas internal objects not triggering + * renderization. To force renderization function evas_render() should + * be used. + * + * @see evas_render. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_norender (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Make the canvas discard internally cached data used for rendering. + * + * @param e The given canvas pointer. + * + * This function flushes the arrays of delete, active and render objects. + * Other things it may also discard are: shared memory segments, + * temporary scratch buffers, cached data to avoid re-compute of that data etc. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_idle_flush (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Make the canvas discard as much data as possible used by the engine at + * runtime. + * + * @param e The given canvas pointer. + * + * This function will unload images, delete 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. + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_dump (Evas *e) EINA_ARG_NONNULL(1); /** * @defgroup Evas_Output_Method Render Engine Functions @@ -777,15 +1345,179 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT; - EAPI void evas_render_method_list_free (Eina_List *list); + +/** + * Look up a numeric ID from a string name of a rendering engine. + * + * @param name The string name of an engine + * @return A numeric (opaque) ID for the rendering engine + * @ingroup Evas_Output_Method + * + * This function looks up a numeric return value for the named engine + * in the string @p name. This is a normal C string, NUL byte + * terminated. The name is case sensitive. If the rendering engine is + * available, a numeric ID for that engine is returned that is not + * 0. If the engine is not available, 0 is returned, indicating an + * invalid engine. + * + * The programmer should NEVER rely on the numeric ID of an engine + * unless it is returned by this function. Programs should NOT be + * written accessing render method ID's directly, without first + * obtaining it from this function. + * + * @attention it is mandatory that one calls evas_init() before + * looking up the render method. + * + * Example: + * @code + * int engine_id; + * Evas *evas; + * + * evas_init(); + * + * evas = evas_new(); + * if (!evas) + * { + * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n"); + * exit(-1); + * } + * engine_id = evas_render_method_lookup("software_x11"); + * if (!engine_id) + * { + * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n"); + * exit(-1); + * } + * evas_output_method_set(evas, engine_id); + * @endcode + */ +EAPI int evas_render_method_lookup (const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * List all the rendering engines compiled into the copy of the Evas library + * + * @return A linked list whose data members are C strings of engine names + * @ingroup Evas_Output_Method + * + * Calling this will return a handle (pointer) to an Evas linked + * list. Each node in the linked list will have the data pointer be a + * (char *) pointer to the string name 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, NULL will be returned. + * + * Example: + * @code + * Eina_List *engine_list, *l; + * char *engine_name; + * + * engine_list = evas_render_method_list(); + * if (!engine_list) + * { + * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); + * exit(-1); + * } + * printf("Availible Evas Engines:\n"); + * EINA_LIST_FOREACH(engine_list, l, engine_name) + * printf("%s\n", engine_name); + * evas_render_method_list_free(engine_list); + * @endcode + */ +EAPI Eina_List *evas_render_method_list (void) EINA_WARN_UNUSED_RESULT; + +/** + * This function should be called to free a list of engine names + * + * @param list The Eina_List base pointer for the engine list to be freed + * @ingroup Evas_Output_Method + * + * When this function is called it will free the engine list passed in + * as @p list. The list should only be a list of engines generated by + * calling evas_render_method_list(). If @p list is NULL, nothing will + * happen. + * + * Example: + * @code + * Eina_List *engine_list, *l; + * char *engine_name; + * + * engine_list = evas_render_method_list(); + * if (!engine_list) + * { + * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); + * exit(-1); + * } + * printf("Availible Evas Engines:\n"); + * EINA_LIST_FOREACH(engine_list, l, engine_name) + * printf("%s\n", engine_name); + * evas_render_method_list_free(engine_list); + * @endcode + */ +EAPI void evas_render_method_list_free (Eina_List *list); - EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1); - EAPI int evas_output_method_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the output engine for the given evas. + * + * Once the output engine for an evas is set, any attempt to change it + * will be ignored. The value for @p render_method can be found using + * @ref evas_render_method_lookup . + * + * @attention it is mandatory that one calls evas_init() before + * setting the output method. + * + * @param e The given evas. + * @param 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); + +/** + * Retrieves the number of the output engine used for the given evas. + * @param e The given evas. + * @return The ID number of the output engine being used. @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) EINA_PURE; - EAPI Evas_Engine_Info *evas_engine_info_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Eina_Bool evas_engine_info_set (Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1); + +/** + * Retrieves the current render engine info struct from the given evas. + * + * The returned structure is publicly modifiable. The contents are + * valid until either @ref evas_engine_info_set or @ref evas_render + * are called. + * + * This structure does not need to be freed by the caller. + * + * @param e The given evas. + * @return A pointer to the Engine Info structure. @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) EINA_PURE; + +/** + * Applies the engine settings for the given evas from the given @c + * Evas_Engine_Info structure. + * + * 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. + * + * You will 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. + * + * Once called, the @p info pointer should be considered invalid. + * + * @param e The pointer to the Evas Canvas + * @param info The pointer to the Engine Info to use + * @return 1 if no error occurred, 0 otherwise + * @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 @@ -795,10 +1527,85 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI void evas_output_size_set (Evas *e, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_output_size_get (const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1); - EAPI void evas_output_viewport_set (Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); - 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); + +/** + * Sets the output size of the render engine of the given evas. + * + * The evas will render to a rectangle of the given size once this + * function is called. The output size is independent of the viewport + * size. The viewport will be stretched to fill the given rectangle. + * + * The units used for @p w and @p h depend on the engine used by the + * evas. + * + * @param e The given evas. + * @param w The width in output units, usually pixels. + * @param 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); + +/** + * Retrieve the output size of the render engine of the given evas. + * + * The output size is given in whatever the output units are for the + * engine. + * + * If either @p w or @p h is @c NULL, then it is ignored. If @p e is + * invalid, the returned results are undefined. + * + * @param e The given evas. + * @param w The pointer to an integer to store the width in. + * @param 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); + +/** + * Sets the output viewport of the given evas in evas units. + * + * The output viewport is the area of the evas that will be visible to + * the viewer. The viewport will be stretched to fit the output + * target of the evas when rendering is performed. + * + * @note 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 e The given evas. + * @param x The top-left corner x value of the viewport. + * @param y The top-left corner y value of the viewport. + * @param w The width of the viewport. Must be greater than 0. + * @param h The height of the viewport. Must be greater than 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); + +/** + * Get the render engine's output viewport co-ordinates in canvas units. + * @param e The pointer to the Evas Canvas + * @param x The pointer to a x variable to be filled in + * @param y The pointer to a y variable to be filled in + * @param w The pointer to a width variable to be filled in + * @param h The pointer to a height variable to be filled in + * @ingroup Evas_Output_Size + * + * Calling this function writes the current canvas output viewport + * size and location values into the variables pointed to by @p x, @p + * y, @p w and @p h. On success the variables have the output + * location and size values written to them in canvas units. Any of @p + * x, @p y, @p w or @p h that are NULL will not be written to. If @p e + * is invalid, the results are undefined. + * + * Example: + * @code + * extern Evas *evas; + * Evas_Coord x, y, width, height; + * + * evas_output_viewport_get(evas, &x, &y, &w, &h); + * @endcode + */ +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); /** * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions @@ -808,10 +1615,102 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI int evas_coord_world_y_to_screen (const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Convert/scale an ouput screen co-ordinate into canvas co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param x The screen/output x co-ordinate + * @return The screen co-ordinate translated to canvas unit co-ordinates + * @ingroup Evas_Coord_Mapping_Group + * + * This function takes in a horizontal co-ordinate as the @p x + * parameter and converts it into canvas units, accounting for output + * size, viewport size and location, returning it as the function + * return value. If @p e is invalid, the results are undefined. + * + * 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 + */ +EAPI Evas_Coord evas_coord_screen_x_to_world (const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Convert/scale an ouput screen co-ordinate into canvas co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param y The screen/output y co-ordinate + * @return The screen co-ordinate translated to canvas unit co-ordinates + * @ingroup Evas_Coord_Mapping_Group + * + * This function takes in a vertical co-ordinate as the @p y parameter + * and converts it into canvas units, accounting for output size, + * viewport size and location, returning it as the function return + * value. If @p e is invalid, the results are undefined. + * + * 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 + */ +EAPI Evas_Coord evas_coord_screen_y_to_world (const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Convert/scale a canvas co-ordinate into output screen co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param x The canvas x co-ordinate + * @return The output/screen co-ordinate translated to output co-ordinates + * @ingroup Evas_Coord_Mapping_Group + * + * This function takes in a horizontal co-ordinate as the @p x + * parameter and converts it into output units, accounting for output + * size, viewport size and location, returning it as the function + * return value. If @p e is invalid, the results are undefined. + * + * 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 + */ +EAPI int evas_coord_world_x_to_screen (const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Convert/scale a canvas co-ordinate into output screen co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param y The canvas y co-ordinate + * @return The output/screen co-ordinate translated to output co-ordinates + * @ingroup Evas_Coord_Mapping_Group + * + * This function takes in a vertical co-ordinate as the @p x parameter + * and converts it into output units, accounting for output size, + * viewport size and location, returning it as the function return + * value. If @p e is invalid, the results are undefined. + * + * 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 + */ +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 @@ -820,10 +1719,123 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1); - EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1); - EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * This function returns the current known pointer co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param x The pointer to an integer to be filled in + * @param y The pointer to an integer to be filled in + * @ingroup Evas_Pointer_Group + * + * This function returns the current known screen/output co-ordinates + * of the mouse pointer and sets the contents of the integers pointed + * to by @p x and @p y to contain these co-ordinates. If @p e is not a + * valid canvas the results of this function are undefined. + * + * 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 + */ +EAPI void evas_pointer_output_xy_get (const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1); + +/** + * This function returns the current known pointer co-ordinates + * + * @param e The pointer to the Evas Canvas + * @param x The pointer to a Evas_Coord to be filled in + * @param y The pointer to a Evas_Coord to be filled in + * @ingroup Evas_Pointer_Group + * + * 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 @p x and @p y to contain these co-ordinates. If @p e is not a + * valid canvas the results of this function are undefined. + * + * 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 + */ +EAPI void evas_pointer_canvas_xy_get (const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1); + +/** + * Returns a bitmask with the mouse buttons currently pressed, set to 1 + * + * @param e The pointer to the Evas Canvas + * @return A bitmask of the currently depressed buttons on the cavas + * @ingroup Evas_Pointer_Group + * + * Calling this function will return a 32-bit integer with the + * appropriate bits set to 1 that correspond to a mouse button being + * depressed. This limits Evas to a mouse devices with a maximum of 32 + * buttons, but that is generally in excess of any host system's + * pointing device abilities. + * + * A canvas by default begins with no mouse buttons being pressed and + * only calls to evas_event_feed_mouse_down(), + * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and + * evas_event_feed_mouse_up_data() will alter that. + * + * 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). + * + * If @p e is not a valid canvas, the return value is undefined. + * + * 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 + */ +EAPI int evas_pointer_button_down_mask_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Returns whether the mouse pointer is logically inside the canvas + * + * @param e The pointer to the Evas Canvas + * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise + * @ingroup Evas_Pointer_Group + * + * When this function is called it will return a value of either 0 or + * 1, depending on if evas_event_feed_mouse_in(), + * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(), + * evas_event_feed_mouse_out_data() have been called to feed in a + * mouse enter event into the canvas. + * + * A return value of 1 indicates the mouse is logically inside the + * canvas, and 0 implies it is logically outside the canvas. + * + * A canvas begins with the mouse being assumed outside (0). + * + * If @p e is not a valid canvas, the return value is undefined. + * + * Example: + * @code + * extern Evas *evas; + * + * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n"); + * else printf("Mouse is out!\n"); + * @endcode + */ +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); /** @@ -834,9 +1846,63 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1); - EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Freeze all event processing. + * @param e The canvas to freeze event processing on. + * + * This function will indicate to evas that the canvas @p e is to have + * all event processing frozen until a matching evas_event_thaw() + * function is called on the same canvas. Every freeze call must be + * matched by a thaw call in order to completely thaw out a canvas. + * + * Example: + * @code + * extern Evas *evas; + * extern Evas_Object *object; + * + * evas_event_freeze(evas); + * evas_object_move(object, 50, 100); + * evas_object_resize(object, 200, 200); + * evas_event_thaw(evas); + * @endcode + */ +EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Thaw a canvas out after freezing. + * + * @param e The canvas to thaw out. + * + * This will thaw out a canvas after a matching evas_event_freeze() + * call. If this call completely thaws out a canvas, events will start + * being processed again after this call, but this call will not + * invole any "missed" events to be evaluated. + * + * See evas_event_freeze() for an example. + */ +EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Return the freeze count of a given canvas. + * @param e The canvas to fetch the freeze count from. + * + * This returns the number of times the canvas has been told to freeze + * 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. + * + * Example: + * @code + * extern Evas *evas; + * + * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas); + * @endcode + * + */ +EAPI int evas_event_freeze_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @defgroup Evas_Event_Feeding_Group Event Feeding Functions @@ -851,19 +1917,163 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_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); - 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); - EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); - EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); - EAPI void evas_event_feed_mouse_out (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Mouse down event feed. + * + * @param e The given canvas pointer. + * @param b The button number. + * @param flags The evas button flags. + * @param timestamp The timestamp of the mouse down event. + * @param data The data for canvas. + * + * This function will set some evas properties that is necessary when + * the mouse button is pressed. It prepares information to be treated + * by the callback function. + * + */ +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); + +/** + * Mouse up event feed. + * + * @param e The given canvas pointer. + * @param b The button number. + * @param flags evas button flags. + * @param timestamp The timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will set some evas properties that is necessary when + * the mouse button is released. It prepares information to be treated + * by the callback function. + * + */ +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); + +/** + * Mouse move event feed. + * + * @param e The given canvas pointer. + * @param x The horizontal position of the mouse pointer. + * @param y The vertical position of the mouse pointer. + * @param timestamp The timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will set 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. + * + */ +EAPI void evas_event_feed_mouse_move (Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Mouse in event feed. + * + * @param e The given canvas pointer. + * @param timestamp The timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will set some evas properties that is necessary when + * the mouse in event happens. It prepares information to be treated + * by the callback function. + * + */ +EAPI void evas_event_feed_mouse_in (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Mouse out event feed. + * + * @param e The given canvas pointer. + * @param timestamp Timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will set some evas properties that is necessary when + * the mouse out event happens. It prepares information to be treated + * by the callback function. + * + */ +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); - EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); - EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); - 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); - 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); - EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Mouse cancel event feed. + * + * @param e The given canvas pointer. + * @param timestamp The timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will call evas_event_feed_mouse_up() when a + * mouse cancel event happens. + * + */ +EAPI void evas_event_feed_mouse_cancel (Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Mouse wheel event feed. + * + * @param e The given canvas pointer. + * @param direction The wheel mouse direction. + * @param z How much mouse wheel was scrolled up or down. + * @param timestamp The timestamp of the mouse up event. + * @param data The data for canvas. + * + * This function will set 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. + * + */ +EAPI void evas_event_feed_mouse_wheel (Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * Key down event feed + * + * @param e The canvas to thaw out + * @param keyname Name of the key + * @param key The key pressed. + * @param string A String + * @param compose The compose string + * @param timestamp Timestamp of the mouse up event + * @param data Data for canvas. + * + * This function will set some evas properties that is necessary when + * a key is pressed. It prepares information to be treated by the + * callback function. + * + */ +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); + +/** + * Key up event feed + * + * @param e The canvas to thaw out + * @param keyname Name of the key + * @param key The key released. + * @param string string + * @param compose compose + * @param timestamp Timestamp of the mouse up event + * @param data Data for canvas. + * + * This function will set some evas properties that is necessary when + * a key is released. It prepares information to be treated by the + * callback function. + * + */ +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); + +/** + * Hold event feed + * + * @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. + * + * This function makes the object to stop sending events. + * + */ +EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); /** * @defgroup Evas_Canvas_Events Canvas Events @@ -873,12 +2083,177 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * @ingroup Evas_Canvas */ - EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); - EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3); - 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); - EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); - EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func); - EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** + * Add a callback function to the canvas. + * + * @param e Canvas to attach a callback to + * @param type The type of event that will trigger the callback + * @param func The function to be called when the event is triggered + * @param data The data pointer to be passed to @p func + * + * This function adds a function callback to the canvas when the event + * of type @p type occurs on canvas @p e. The function is @p func. + * + * In the event of a memory allocation error during 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. + * + * The function will be passed the pointer @p data when it is + * called. A callback function must look like this: + * + * @code + * void callback (void *data, Evas *e, void *event_info); + * @endcode + * + * The first parameter @p data in this function will be the same value + * passed to evas_event_callback_add() as the @p data parameter. The + * second parameter @p e is the canvas handle on which the event + * occurred. The third parameter @p 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. + * + * The event type @p type to trigger the function may be one of + * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST, + * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT. + * This determines the kind of event that will trigger the callback to + * be called. So far none of the event types provide useful data, so + * in all of them @p event_info pointer is @c NULL. + * + * Example: + * @code + * extern Evas *e; + * extern void *my_data; + * void focus_in_callback(void *data, Evas *e, void *event_info); + * void focus_out_callback(void *data, Evas *e, void *event_info); + * + * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, focus_out_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * @endcode + */ + +/** + * @addtogroup Evas_Canvas_Events + * @{ + */ +EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * Delete a callback function from the canvas. + * + * @param e Canvas to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * canvas @p e which was triggered by the event type @p type and was + * calling the function @p func when triggered. If the removal is + * successful it will also return the data pointer that was passed to + * evas_event_callback_add() when the callback was added to the + * canvas. If not successful NULL will be returned. + * + * 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 + */ +EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3); + +/** + * Delete a callback function from the canvas. + * + * @param e Canvas to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @param data The data pointer that was to be passed to the callback + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * canvas @p e which was triggered by the event type @p type and was + * calling the function @p func with data @p data when triggered. If + * the removal is successful it will also return the data pointer that + * was passed to evas_event_callback_add() (that will be the same as + * the parameter) when the callback was added to the canvas. If not + * successful NULL will be returned. + * + * 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_full(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); + * @endcode + */ +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); + +/** + * Push a callback on the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * @param data The data pointer to be passed to the callback + * + * 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 al the callbacks + * in each object triggered). When all these have been called, the stack is + * unwond from most recently to least recently pushed item and removed from the + * stack calling the callback set for it. + * + * This is intended for doing reverse logic-like processing, example - when a + * child object that happens to get the event later is meant to be able to + * "steal" functions from a parent and thus on unwind of this stack hav its + * function called first, thus being able to set flags, or return 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). + * + */ +EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** + * Remove a callback from the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * + * 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. + */ +EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func); + +/** + * Remove a callback from the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * @param data The data pointer to be passed to the callback + * + * 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. + */ +EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); /** * @defgroup Evas_Image_Group Image Functions @@ -887,10 +2262,47 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1); - EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Flush the image cache of the canvas. + * + * @param e The given evas pointer. + * + * This function flushes image cache of canvas. + * + */ +EAPI void evas_image_cache_flush (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Reload the image cache + * + * @param e The given evas pointer. + * + * This function reloads the image cache of canvas. + * + */ +EAPI void evas_image_cache_reload (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Set the image cache. + * + * @param e The given evas pointer. + * @param size The cache size. + * + * This function sets the image cache of canvas. + * + */ +EAPI void evas_image_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1); + +/** + * Set the image cache + * + * @param e The given evas pointer. + * + * This function returns the image cache of canvas. + * + */ +EAPI int evas_image_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @defgroup Evas_Font_Group Font Functions @@ -899,16 +2311,93 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Canvas */ - EAPI void evas_font_hinting_set (Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1); - EAPI Evas_Font_Hinting_Flags evas_font_hinting_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Eina_Bool evas_font_hinting_can_hint (const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Changes the font hinting for the given evas. + * + * @param e The given evas. + * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, #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); + +/** + * Retrieves the font hinting used by the given evas. + * + * @param e The given evas to query. + * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, #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) EINA_PURE; + +/** + * Checks if the font hinting is supported by the given evas. + * + * @param e The given evas to query. + * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. + * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise. + * @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) EINA_PURE; - EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1); - EAPI int evas_font_cache_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Force the given evas and associated engine to flush its font cache. + * + * @param e The given evas to flush font cache. + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_cache_flush (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Changes the size of font cache of the given evas. + * + * @param e The given evas to flush font cache. + * @param size The size, in bytes. + * + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_cache_set (Evas *e, int size) EINA_ARG_NONNULL(1); + +/** + * Changes the size of font cache of the given evas. + * + * @param 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) EINA_PURE; - EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1); + +/** + * List of available font descriptions known or found by this evas. + * + * 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 e The evas instance to query. + * @return a newly allocated list of strings. Do not change the + * strings. Be sure to call evas_font_available_list_free() + * after you're done. + * + * @ingroup Evas_Font_Group + */ +EAPI Eina_List *evas_font_available_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Free list of font descriptions returned by evas_font_dir_available_list(). + * + * @param e The evas instance that returned such list. + * @param 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); /** * @defgroup Evas_Font_Path_Group Font Path Functions @@ -917,10 +2406,37 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Font_Group */ - EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1); - EAPI void evas_font_path_append (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2); - EAPI void evas_font_path_prepend (Evas *e, const char *path) EINA_ARG_NONNULL(1, 2); - EAPI const Eina_List *evas_font_path_list (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Removes all font paths loaded into memory for the given evas. + * @param e The given evas. + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_clear (Evas *e) EINA_ARG_NONNULL(1); + +/** + * Appends a font path to the list of font paths used by the given evas. + * @param e The given evas. + * @param 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); + +/** + * Prepends a font path to the list of font paths used by the given evas. + * @param e The given evas. + * @param 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); + +/** + * Retrieves the list of font paths used by the given evas. + * @param 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) EINA_PURE; /** * @defgroup Evas_Object_Group Generic Object Functions @@ -936,45 +2452,449 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2); - EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_clip_unset (Evas_Object *obj); - EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Clip one object to another. + * @param obj The object to be clipped + * @param clip The object to clip @p obj by + * + * This function will clip the object @p obj to the area occupied by the + * object @p clipper. This means the object @p obj will only be visible within + * the area occupied by the clipping object (@p clip). The color of the object + * being clipped will be multiplied by the color of the clipping object, so + * the resulting color for the clipped object is + * RESULT = (OBJ * CLIP) / (255 * 255) per color element (red, green, blue and + * alpha). Clipping is recursive, so clip objects may be clipped by other + * objects, and their color will in tern be multiplied. You may 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. Objects which do not clip + * others are visible as normal, those that clip 1 or more objects become + * invisible themselves, only affecting what they clip. If an object ceases to + * have other objects being clipped by it, it will become visible again. The + * visibility of an object affects the objects that are clipped by it, so if + * the object clipping others is not shown, the objects clipped will not be + * shown either. If the object was being clipped by another object when this + * function is called, it is implicitly removed from the clipper it is being + * clipped to, and now is made to clip its new clipper. + * + * At the moment the only objects that can validly be used to clip other + * objects are rectangle objects. All other object types are invalid and the + * result of using them is undefined. + * + * The clip object @p clip must be a valid object, but may also be NULL in + * which case the effect of this function is the same as calling + * evas_object_clip_unset() on the @p obj object. + * + * Example: + * @code + * extern Evas *evas; + * extern Evas_Object *obj; + * Evas_Object *clipper; + * + * clipper = evas_object_rectangle_add(evas); + * evas_object_color_set(clipper, 255, 255, 255, 255); + * evas_object_move(clipper, 10, 10); + * evas_object_resize(clipper, 20, 50); + * evas_object_clip_set(obj, clipper); + * evas_object_show(clipper); + * @endcode + * + */ +EAPI void evas_object_clip_set (Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2); + +/** + * Get the object clipping this one (if any). + * @param obj The object to get the clipper from + * + * This function returns the the object clipping @p obj. If @p obj not being + * clipped, NULL is returned. The object @p obj must be a valid object. + * + * See also evas_object_clip_set(), evas_object_clip_unset() and + * evas_object_clipees_get(). + * + * Example: + * @code + * extern Evas_Object *obj; + * Evas_Object *clipper; + * + * clipper = evas_object_clip_get(obj); + * if (clipper) evas_object_show(clipper); + * @endcode + * + */ +EAPI Evas_Object *evas_object_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Disable clipping for an object. + * + * @param obj The object to cease clipping on + * + * This function disables clipping for the object @p obj, if it was already + * clipped. If it wasn't, this has no effect. The object @p obj must be a + * valid object. + * + * See also evas_object_clip_set(), evas_object_clipees_get() and + * evas_object_clip_get(). + * + * Example: + * @code + * extern Evas_Object *obj; + * Evas_Object *clipper; + * + * clipper = evas_object_clip_get(obj); + * if (clipper) + * { + * evas_object_clip_unset(obj); + * evas_object_hide(obj); + * } + * @endcode + * + */ +EAPI void evas_object_clip_unset (Evas_Object *obj); + +/** + * Return a list of objects currently clipped by a specific object. + * + * @param obj The object to get a list of clippees from + * + * This returns the inernal list handle that contains all objects clipped by + * the object @p obj. If none are clipped, it returns 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, are deleted or the clipper is + * deleted. These operations will 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, not limited just to strange behavior but possible + * segfaults and other strange memory errors. The object @p obj must be a valid + * object. + * + * See also evas_object_clip_set(), evas_object_clip_unset() and + * evas_object_clip_get(). + * + * 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 + */ +EAPI const Eina_List *evas_object_clipees_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets focus to the given object. + * + * @param obj The object to be focused or unfocused. + * @param focus set or remove focus to the object. + * + * Changing focus only affects where key events go. There can be only + * one object focused at any time.

If the parameter (@p focus) is + * set, the passed object will be set as the currently focused object. + * It will receive all keyboard events that are not exclusive key + * grabs on other objects. + * + * @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); + +/** + * Test if the object has focus. + * + * @param obj The object to be tested. + * + * If the passed object is the currently focused object 1 is returned, + * 0 otherwise. + * + * @see evas_object_focus_set + * @see evas_focus_get + * @see evas_object_key_grab + * @see evas_object_key_ungrab + * + * @return 1 if the object has the focus, 0 otherwise. + */ +EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1); - EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the layer of the evas that the given object will be part of. + * + * It is not possible to change the layer of a smart object's child. + * + * @param obj The given evas object. + * @param l The number of the layer to place the object on. + * Between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX. + */ +EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1); + +/** + * Retrieves the layer of the evas that the given object is part of. + * + * Be careful, it doesn't make sense to change the layer of smart object's + * child. So the returned value could be wrong in some case. Don't rely on + * it's accuracy. + * + * @param obj The given evas object. + * @return Number of the layer. + */ +EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1); - EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the name of the given evas object to the given name. + * @param obj The given object. + * @param name The given name. + */ +EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1); + +/** + * Retrieves the name of the given evas object. + * @param obj The given object. + * @return The name of the object. @c NULL if no name has been given + * to the object. + */ +EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_ref (Evas_Object *obj); - EAPI void evas_object_unref (Evas_Object *obj); + +/** + * Increments object reference count to defer deletion + * + * This increments the reference count of an object, which if greater than + * 0 will defer deletion by evas_object_del() until all references are + * released back to 0. References cannot go below 0 and unreferencing more + * times that referencing will result in the reference count being limited + * to 0. References are limited to 2^32 - 1 for an object. Referencing it more + * than this will result in it being limited to this value. + * + * @param obj The given evas object to reference + * @ingroup Evas_Object_Group_Basic + * @since 1.1.0 + */ +EAPI void evas_object_ref (Evas_Object *obj); + +/** + * Decrements object reference count to defer deletion + * + * This decrements the reference count of an object. If the object has had + * evas_object_del() called on it while references were more than 0, it will + * be deleted at the time this function is called as it normally would have + * been. See evas_object_ref() for more information. + * + * @param obj The given evas object to unreference + * @ingroup Evas_Object_Group_Basic + * @since 1.1.0 + */ +EAPI void evas_object_unref (Evas_Object *obj); - EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); - EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); - 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); + +/** + * Deletes the given evas object and frees its memory. + * + * The object's 'free' callback is called when this function is called. + * If the object currently has the focus, its 'focus out' callback is + * also called. + * + * @param obj The given evas object. + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Moves the given evas object to the given location. + * @param obj The given evas object. + * @param x X position to move the object to, in canvas units. + * @param y 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); + +/** + * Changes the size of the given evas object. + * @param obj The given evas object. + * @param w The new width of the evas object. + * @param h The new height of the evas object. + * + * @note 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. 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 + * This is more evident in images, but text, textblock, lines + * and polygons will behave similarly. Check their specific APIs + * to know how to achieve your desired behavior. + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * Retrieves the position and rectangular size of the given evas object. + * + * Note that if any of @p x, @p y, @p w or @p h are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param x Pointer to an integer in which to store the X coordinate of + * the object. + * @param y Pointer to an integer in which to store the Y coordinate of + * the object. + * @param w Pointer to an integer in which to store the width of the + * object. + * @param h 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); - EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Makes the given evas object visible. + * @param obj The given evas object. + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Makes the given evas object invisible. + * @param obj The given evas object. + * + * @note the hidden objects will not be checked for changes and will + * not catch events. That is, they are much ligher than an + * object that is invisible due indirect effects, such as + * clipped or out-of-viewport. + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Retrieves whether or not the given evas object is visible. + * @param obj The given evas object. + * @return @c 1 if the object is visible. @c 0 otherwise. + * @ingroup Evas_Object_Group_Basic + */ +EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); - EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * Sets the general colour of the given evas object to the given colour. + * @param obj The given evas object. + * @param r The red component of the given colour. + * @param g The green component of the given colour. + * @param b The blue component of the given colour. + * @param a The alpha component of the given colour. + * @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); + +/** + * Retrieves the general colour of the given evas object. + * + * Note that if any of @p r, @p g, @p b or @p a are @c NULL, then the + * @c NULL parameters are ignored. + * + * @param obj The given evas object. + * @param r Pointer to an integer in which to store the red component of + * the colour. + * @param g Pointer to an integer in which to store the green component of + * the colour. + * @param b Pointer to an integer in which to store the blue component of + * the colour. + * @param a Pointer to an integer in which to store the alpha component of + * the colour. + * @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); - EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieves the evas that the given evas object is on. + * @param obj The given evas object. + * @return The evas that 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) EINA_PURE; EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2); - EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Raise @p obj to the top of its layer. + * + * @param obj the object to raise + */ +EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Lower @p obj to the bottom of its layer. + * + * @param obj the object to lower + */ +EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Stack @p obj immediately above @p above + * + * If @p obj is a member of a smart object, then @p above must also be + * a member of the same smart object. + * + * Similarly, if @p obj is not a member of smart object, @p above may + * not either. + * + * @param obj the object to stack + * @param above the object above which to stack + */ +EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2); + +/** + * Stack @p obj immediately below @p below + * + * If @p obj is a member of a smart object, then @p below must also be + * a member of the same smart object. + * + * Similarly, if @p obj is not a member of smart object, @p below may + * not either. + * + * @param obj the object to stack + * @param below the object below which to stack + */ +EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2); + +/** + * Get the evas object above @p obj + * + * @param obj an Evas_Object + * @return the Evas_Object directly above + */ +EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get the evas object below @p obj + * + * @param obj an Evas_Object + * @return the Evas_Object directly below + */ +EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @defgroup Evas_Object_Group_Events Object Events @@ -988,16 +2908,308 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - 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); - EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3); - 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); - EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @addtogroup Evas_Object_Group_Events + * @{ + */ + +/** + * Add a callback function to an object + * + * @param obj Object to attach a callback to + * @param type The type of event that will trigger the callback + * @param func The function to be called when the event is triggered + * @param data The data pointer to be passed to @p func + * + * This function adds a function callback to an object when the event + * of type @p type occurs on object @p obj. The function is @p func. + * + * 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. + * + * The function will be passed the pointer @p data when it is + * called. A callback function must look like this: + * + * @code + * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info); + * @endcode + * + * The first parameter @p data in this function will be the same value + * passed to evas_object_event_callback_add() as the @p data + * parameter. The second parameter is a convenience for the programmer + * to know what evas canvas the event occurred on. The third parameter + * @p obj is the Object handle on which the event occurred. The foruth + * parameter @p 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. + * + * The event type @p type to trigger the function may be one of + * #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_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 or #EVAS_CALLBACK_RESTACK. + * This determines the kind of event that will trigger the callback to + * be called. The @p event_info pointer passed to the callback will + * be one of the following, depending on the event triggering it: + * + * #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In + * + * This event is triggered when the mouse pointer enters the region of + * the object @p obj. This may occur by the mouse pointer being moved + * by evas_event_feed_mouse_move() or + * evas_event_feed_mouse_move_data() calls, or by the object being + * shown, raised, moved, resized, or other objects being moved out of + * the way, hidden, lowered or moved out of the way. + * + * #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out + * + * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but + * occurs when the mouse pointer exits an object. Note that no out + * events will be reported if the mouse pointer is implicitly grabbed + * to an object (the mouse buttons are down at all and any were + * pressed on that object). An out event will be reported as soon as + * the mouse is no longer grabbed (no mouse buttons are + * depressed). Out events will be reported once all buttons are + * released, if the mouse has left the object. + * + * #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to + * Evas_Event_Mouse_Down + * + * This event is triggered by a mouse button being depressed while + * over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB + * (default) this causes this object to passively grab the mouse until + * all mouse buttons have been released. That means if this mouse + * button is the first to be pressed, all future mouse events will be + * reported to only this object until no buttons are down. That + * includes mouse move events, in and out events, and further button + * presses. When all buttons are released, event propagation occurs as + * normal. + * + * #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up + * + * This event is triggered by a mouse button being released while over + * an object or when passively grabbed to an object. If this is the + * last mouse button to be raised on an object then the passive grab + * is released and event processing will continue as normal. + * + * #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move + * + * This event is triggered by the mouse pointer moving while over an + * object or passively grabbed to an object. + * + * #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to + * Evas_Event_Mouse_Wheel + * + * This event is triggered by the mouse wheel being rolled while over + * an object or passively grabbed to an object. + * + * #EVAS_CALLBACK_FREE: event_info = NULL + * + * 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 this callback + * returns, there is no guarantee on the object's validity. + * + * #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down + * + * 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: event_info = pointer to Evas_Event_Key_Up + * + * 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: event_info = NULL + * + * This event is called when an object gains the focus. When the + * callback is called the object has already gained the focus. + * + * #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL + * + * This event is triggered by an object losing the focus. When the + * callback is called the object has already lost the focus. + * + * #EVAS_CALLBACK_SHOW: event_info = NULL + * + * This event is triggered by the object being shown by + * evas_object_show(). + * + * #EVAS_CALLBACK_HIDE: event_info = NULL + * + * This event is triggered by an object being hidden by + * evas_object_hide(). + * + * #EVAS_CALLBACK_MOVE: event_info = NULL + * + * 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: event_info = NULL + * + * 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. + * + * Example: + * @code + * extern Evas_Object *object; + * extern void *my_data; + * void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); + * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); + * + * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * @endcode + */ + 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); + +/** + * Delete a callback function from an object + * + * @param obj Object to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * object @p obj which was triggered by the event type @p type and was + * calling the function @p func when triggered. If the removal is + * successful it will also return the data pointer that was passed to + * evas_object_event_callback_add() when the callback was added to the + * object. If not successful NULL will be returned. + * + * 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 + */ +EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3); + +/** + * Delete a callback function from an object + * + * @param obj Object to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @param data The data pointer that was to be passed to the callback + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * object @p obj which was triggered by the event type @p type and was + * calling the function @p func with data @p data when triggered. If + * the removal is successful it will also return the data pointer that + * was passed to evas_object_event_callback_add() (that will be the + * same as the parameter) when the callback was added to the + * object. If not successful NULL will be returned. + * + * 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 + */ +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); + + +/** + * Set an object's pass events state. + * @param obj the evas object + * @param pass whether to pass events or not + * + * If @p pass is true, this will cause events on @p obj to be ignored. + * They will be triggered on the next lower object (that is not set to + * pass events) instead. + * + * If @p pass is false, events will be processed as normal. + */ +EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1); + +/** + * Determine whether an object is set to pass events. + * @param obj + * @return pass events state + */ +EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set an object's repeat events state. + * @param obj the object + * @param repeat wheter to repeat events or not + * + * If @p repeat is true, this will cause events on @p obj to trigger + * callbacks, but also to be repeated on the next lower object in the + * stack. + * + * If @p repeat is false, events occurring on @p obj will be processed + * normally. + */ +EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1); + +/** + * Determine whether an object is set to repeat events. + * @param obj + * @return repeat events state + */ +EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set whether events on a smart member object should propagate to its + * parent. + * + * @param obj the smart member object + * @param prop wheter to propagate events or not + * + * This function has no effect if @p obj is not a member of a smart + * object. + * + * If @p prop is true, events occurring on this object will propagate on + * to the smart object of which @p obj is a member. + * + * If @p prop is false, events for which callbacks are set on the member + * object, @p obj, will not be passed on to the parent smart object. + * + * The default value is true. + */ +EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1); + +/** + * Determine whether an object is set to propagate events. + * @param obj + * @return propagate events state + */ +EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspecitve, 3D...) @@ -1025,38 +3237,535 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled); - EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj); - EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src); - EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj); - EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map); - EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj); + +/** + * Enable or disable the map that is set. + * + * This enables the map that is set or disables it. On enable, the object + * geometry will be saved, and the new geometry will change (position and + * size) to reflect the map geometry set. If none is set yet, this may be + * an undefined geometry, unless you have already set the map with + * evas_object_map_set(). It is suggested you first set a map with + * evas_object_map_set() with valid useful coordinates then enable and + * disable the map with evas_object_map_enable_set() as needed. + * + * @param obj object to enable the map on + * @param enabled enabled state + */ +EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled); + +/** + * Get the map enabled state + * + * This 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(). + * + * @param obj object to get the map enabled state from + * @return the map enabled state + */ +EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj); + +/** + * Set the map source object + * + * This sets the object from which the map is taken - can be any object that + * has map enabled on it. + * + * Currently not implemented. for future use. + * + * @param obj object to set the map source of + * @param src the source object from which the map is taken + */ +EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src); + +/** + * Get the map source object + * + * See evas_object_map_source_set() + * + * @param obj object to set the map source of + * @return the object set as the source + */ +EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj); + +/** + * Set current object transformation map. + * + * This sets the map on a given object. It is copied from the @p map pointer, + * so there is no need to keep the @p map object if you don't need it anymore. + * + * A map is a set of 4 points which have canvas x, y coordinates per point, + * with an optional z point value as a hint for perspective correction, if it + * is available. As well each point has u and 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/point. The u corresponds to the x + * coordinate of this mapped point and v, the 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: + * + * @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 + * + * Note that the map points a uv coordinates match the image geometry. If + * the @p map parameter is NULL, the stored map will be freed and geometry + * prior to enabling/setting a map will be restored. + * + * @param obj object to change transformation map + * @param map new map to use + * + * @see evas_map_new() + */ +EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map); + +/** + * Get current object transformation map. + * + * This returns the current internal map set on the indicated object. It is + * intended for read-only acces 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: + * + * @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); + * evas_map_free(m2); + * @endcode + * + * @param obj object to query transformation map. + * @return map reference to map in use. 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); - EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z); - EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj); - 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); - EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a); - EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy); - EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy); - 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); - 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); - EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc); - EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m); + +/** + * Populate source and destination map points to match exactly object. + * + * Usually one initialize map of an object to match it's 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 m map to change all 4 points (must be of size 4). + * @param obj object to use unmapped geometry to populate map coordinates. + * @param z Point Z Coordinate hint (pre-perspective transform). This value + * will be 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); + +/** + * Populate source and destination map points to match exactly object. + * + * Usually one initialize map of an object to match it's 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. + * + * Z Point coordinate is assumed as 0 (zero). + * + * @param m map to change all 4 points (must be of size 4). + * @param obj 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); + +/** + * Populate source and destination map points to match given geometry. + * + * 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 will be used to calculate destination + * points (evas_map_point_coord_set()) and set the image uv + * (evas_map_point_image_uv_set()). + * + * @param m map to change all 4 points (must be of size 4). + * @param x Point X Coordinate + * @param y Point Y Coordinate + * @param w width to use to calculate second and third points. + * @param h height to use to calculate third and fourth points. + * @param z Point Z Coordinate hint (pre-perspective transform). This value + * will be 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); + +/** + * Set color of all points to given color. + * + * This call is useful to reuse maps after they had 3d lightning or + * any other colorization applied before. + * + * @param m map to change the color of. + * @param r red (0 - 255) + * @param g green (0 - 255) + * @param b blue (0 - 255) + * @param a alpha (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); + +/** + * Change the map to apply the given rotation. + * + * This rotates the indicated map's coordinates around the center coordinate + * given by @p cx and @p cy as the rotation center. The points will have their + * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a + * full rotation). Negative values for degrees will rotate counter-clockwise + * by that amount. All coordinates are canvas global coordinates. + * + * @param m map to change. + * @param degrees amount of degrees from 0.0 to 360.0 to rotate. + * @param cx rotation's center horizontal position. + * @param cy 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); + +/** + * Change the map to apply the given zooming. + * + * Like evas_map_util_rotate(), this zooms the points of the map from a center + * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy + * parameters specific how much to zoom in the X and Y direction respectively. + * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is + * "half the size" etc. All coordinates are canvas global coordinates. + * + * @param m map to change. + * @param zoomx horizontal zoom to use. + * @param zoomy vertical zoom to use. + * @param cx zooming center horizontal position. + * @param cy 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); + +/** + * Rotate the map around 3 axes in 3D + * + * This will rotate not just around the "Z" axis as in evas_map_util_rotate() + * (which is a convenience call for those only wanting 2D). This will rotate + * 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(0 you provide a center point to rotate around (in 3D). + * + * @param m map to change. + * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis. + * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis. + * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis. + * @param cx rotation's center horizontal position. + * @param cy rotation's center vertical position. + * @param cz 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); + +/** + * Perform lighting calculations on the given Map + * + * This is used to apply lighting calculations (from a single light source) + * to a given map. The R, G and B values of each vertex will be 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 be 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. + * + * @param m map to change. + * @param lx X coordinate in space of light point + * @param ly Y coordinate in space of light point + * @param lz Z coordinate in space of light point + * @param lr light red value (0 - 255) + * @param lg light green value (0 - 255) + * @param lb light blue value (0 - 255) + * @param ar ambient color red value (0 - 255) + * @param ag ambient color green value (0 - 255) + * @param ab 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); + +/** + * Apply a perspective transform to the map + * + * This 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 @p z0 value specifis the z value at which there is a 1:1 + * mapping between spatial coorinates and screen coordinates. Any points + * on this z value will not have their X and Y values modified in the transform. + * Those further away (Z value higher) will shrink into the distance, and + * those less than this value will expand and become bigger. The @p 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 @p foc must be greater than 0. + * + * @param m map to change. + * @param px The pespective distance X coordinate + * @param py The pespective distance Y coordinate + * @param z0 The "0" z plane value + * @param 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); + +/** + * Get the clockwise state of a map + * + * This determines if the output points (X and Y. Z is not used) are + * clockwise or anti-clockwise. This can be used for "back-face culling". This + * is where you hide objects that "face away" from you. In this case objects + * that are not clockwise. + * + * @param m map to query. + * @return 1 if clockwise, 0 otherwise + */ +EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m); - EAPI Evas_Map *evas_map_new (int count); - EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled); - EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m); - EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled); - EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m); - EAPI Evas_Map *evas_map_dup (const Evas_Map *m); - EAPI void evas_map_free (Evas_Map *m); - EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST; - EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z); - EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z); - EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v); - EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v); - EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a); - EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a); + +/** + * Create map of transformation points to be later used with an evas object. + * + * This creates a set of points (currently only 4 is supported. no other + * number for @p count will work). That is empty and ready to be modified + * with evas_map calls. + * + * @param count number of points in the map. * + * @return a newly allocated map or 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); + +/** + * Set the smoothing for map rendering + * + * This 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. + * + * @param m map to modify. Must not be NULL. + * @param enabled enable or disable smooth map rendering + */ +EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled); + +/** + * get the smoothing for map rendering + * + * This gets smoothing for map rendering. + * + * @param m map to get the smooth from. Must not be NULL. + */ +EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m); + +/** + * Set the alpha flag for map rendering + * + * This sets alpha flag for map rendering. If the object is a type that has + * its own alpha settings, then this will take precedence. Only image objects + * have this currently. Fits stops alpha blending of the map area, and is + * useful if you know the object and/or all sub-objects is 100% solid. + * + * @param m map to modify. Must not be NULL. + * @param enabled enable or disable alpha map rendering + */ +EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled); + +/** + * get the alpha flag for map rendering + * + * This gets the alph flag for map rendering. + * + * @param m map to get the alpha from. Must not be NULL. + */ +EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m); + +/** + * Copy a previously allocated map. + * + * This makes a duplicate of the @p m object and returns it. + * + * @param m map to copy. Must not be NULL. + * @return newly allocated map with the same count and contents as @p m. + */ +EAPI Evas_Map *evas_map_dup (const Evas_Map *m); + +/** + * Free a previously allocated map. + * + * This frees a givem map @p m and all memory associated with it. You must NOT + * free a map returned by evas_object_map_get() as this is internal. + * + * @param m map to free. + */ +EAPI void evas_map_free (Evas_Map *m); + +/** + * Get a maps size. + * + * Returns the number of points in a map. Should be at least 4. + * + * @param m map to get size. + * @return -1 on error, points otherwise. + */ +EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST; + +/** + * Change the map point's coordinate. + * + * This sets the fixen point's coordinate in the map. Note that points + * describe the outline of a quadrangle and are ordered either clockwise + * or anit-clock-wise. 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 will use points 0 and 1 , 1 and 2, + * 2 and 3, and 3 and 0 to describe the edges of the quandrangle. + * + * The X and 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. + * + * Remember all coordinates are canvas global ones like with move and reize + * in evas. + * + * @param m map to change point. Must not be @c NULL. + * @param idx index of point to change. Must be smaller than map size. + * @param x Point X Coordinate + * @param y Point Y Coordinate + * @param z Point 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); + +/** + * Get the map point's coordinate. + * + * This returns the coordinates of the given point in the map. + * + * @param m map to query point. + * @param idx index of point to query. Must be smaller than map size. + * @param x where to return the X coordinate. + * @param y where to return the Y coordinate. + * @param z where to return 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); + +/** + * Change the map point's U and V texture source point + * + * 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. Notes that these points do select the pixel, but + * are double floating point values to allow for accuracy and sub-pixel + * selection. + * + * @param m map to change the point of. + * @param idx index of point to change. Must be smaller than map size. + * @param u the X coordinate within the image/texture source + * @param v the Y coordinate within the image/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); + +/** + * Get the map point's U and V texture source points + * + * This returns the texture points set by evas_map_point_image_uv_set(). + * + * @param m map to query point. + * @param idx index of point to query. Must be smaller than map size. + * @param u where to write the X coordinate within the image/texture source + * @param v where to write the Y coordinate within the image/texture source + */ +EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v); + +/** + * Set the color of a vertex in the map + * + * This sets the color of the vertex in the map. Colors will be linearly + * interpolated between vertex points through the map. Color will multiply + * 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 will + * have no affect on modifying the texture pixels. + * + * @param m map to change the color of. + * @param idx index of point to change. Must be smaller than map size. + * @param r red (0 - 255) + * @param g green (0 - 255) + * @param b blue (0 - 255) + * @param a alpha (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); + +/** + * Get the color set on a vertex in the map + * + * This gets the color set by evas_map_point_color_set() on the given vertex + * of the map. + * + * @param m map to get the color of the vertex from. + * @param idx index of point get. Must be smaller than map size. + * @param r pointer to red return + * @param g pointer to green return + * @param b pointer to blue return + * @param a pointer to alpha return (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 @@ -1068,20 +3777,215 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); - 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); - 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); - EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); - EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); - 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); - 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); + +/** + * Retrieves the size hint for the minimum size. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p w or @p h are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param w Pointer to an integer in which to store the minimum width. + * @param h Pointer to an integer in which to store the minimum height. + */ +EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * Sets the size hint for the minimum size. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Value 0 is considered unset. + * + * @param obj The given evas object. + * @param w Integer to use as the minimum width hint. + * @param h Integer to use as the minimum height hint. + */ +EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * Retrieves the size hint for the maximum size. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p w or @p h are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param w Pointer to an integer in which to store the maximum width. + * @param h Pointer to an integer in which to store the maximum height. + */ +EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * Sets the size hint for the maximum size. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Value -1 is considered unset. + * + * @param obj The given evas object. + * @param w Integer to use as the maximum width hint. + * @param h Integer to use as the maximum height hint. + */ +EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * Retrieves the size request hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p w or @p h are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param w Pointer to an integer in which to store the requested width. + * @param h Pointer to an integer in which to store the requested height. + */ +EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * Sets the requested size hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Value 0 is considered unset. + * + * @param obj The given evas object. + * @param w Integer to use as the preferred width hint. + * @param h Integer to use as the preferred height hint. + */ +EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * Retrieves the size aspect control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p aspect, @p w or @p h are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param aspect Returns the hint on how size should be calculated. + * @param w Pointer to an integer in which to store the aspect width. + * @param h Pointer to an integer in which to store the aspect height. + */ +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); + +/** + * Sets the size aspect control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * @param obj The given evas object. + * @param aspect Hint on how to calculate size. + * @param w Integer to use as aspect width hint. + * @param h Integer to use as aspect height hint. + */ +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); + +/** + * Retrieves the size align control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p x or @p y are @c NULL, the @c NULL + * parameters are ignored. + * + * @param obj The given evas object. + * @param x Pointer to a double in which to store the align x. + * @param y Pointer to a double in which to store the align y. + */ +EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); + +/** + * Sets the size align control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Accepted values are in the 0.0 to 1.0 range, with the special value + * -1.0 used to specify "justify" or "fill" by some users. See + * documentation of possible users. + * + * @param obj The given evas object. + * @param x Double (0.0..1.0 or -1.0) to use as align x hint. + * @param y Double (0.0..1.0 or -1.0) to use as align y hint. + */ +EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); + +/** + * Retrieves the size weight control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p x or @p y are @c NULL, the @c NULL + * parameters are ignored. + * + * Accepted values are zero or positive values. Some users might use + * this hint as a boolean, but some might consider it as a proportion, + * see documentation of possible users. + * + * @param obj The given evas object. + * @param x Pointer to a double in which to store the weight x. + * @param y Pointer to a double in which to store the weight y. + */ +EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); + +/** + * Sets the size weight control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * @param obj The given evas object. + * @param x Double (0.0-1.0) to use as weight x hint. + * @param y Double (0.0-1.0) to use as weight y hint. + */ +EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); + +/** + * Retrieves the size padding control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * Note that if any of @p l, @p r, @p t or @p b are @c NULL, the @c + * NULL parameters are ignored. + * + * @param obj The given evas object. + * @param l Pointer to an integer in which to store left padding. + * @param r Pointer to an integer in which to store right padding. + * @param t Pointer to an integer in which to store top padding. + * @param b Pointer to an integer in which to store bottom padding. + */ +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); + +/** + * Sets the size padding control hint. + * + * This is not a size enforcement in any way, it's just a hint that should + * be used whenever appropriate. + * + * @param obj The given evas object. + * @param l Integer to specify left padding. + * @param r Integer to specify right padding. + * @param t Integer to specify top padding. + * @param b Integer to specify bottom padding. + */ +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 @@ -1091,21 +3995,179 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2); - EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @addtogroup Evas_Object_Group_Extras + * @{ + */ + +/** + * Set an attached data pointer to an object with a given string key. + * @param obj The object to attach the data pointer to + * @param key The string key for the data to access it + * @param data The ponter to the data to be attached + * + * This attaches the pointer @p data to the object @p obj given the string + * @p key. This pointer will stay "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 @p obj, the + * pointers will not be accessible from the object anymore. + * + * 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 @p data when it is no longer required. + * + * If @p data is NULL, the old value stored at @p key will be removed but no + * new value will be stored. This is synonymous with calling + * evas_object_data_del() with @p obj and @p key. + * + * 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 was attached was %p\n", evas_object_data_get(obj, "name_of_data")); + * @endcode + */ +EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Return an attached data pointer by its given string key. + * @param obj The object to which the data was attached + * @param key The string key the data was stored under + * @return The data pointer stored, or NULL if none was stored + * + * This function will return the data pointer attached to the object @p obj + * stored using the string key @p key. If the object is valid and data was + * stored under the given key, the pointer that was stored will be reuturned. + * If this is not the case, NULL will be returned, signifying an invalid object + * or non-existent key. It is possible a NULL pointer was stored given that + * key, but this situation is non-sensical and thus can be considered an error + * as well. NULL pointers are never stored as this is the return value if an + * error occurs. + * + * 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 was %p\n", my_data); + * else printf("No data was stored on the object\n"); + * @endcode + */ +EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Delete at attached data pointer from an object. + * @param obj The object to delete the data pointer from + * @param key The string key the data was stored under + * @return The original data pointer stored at @p key on @p obj + * + * This will remove thee stored data pointer from @p obj stored under @p key, + * and return the original pointer stored under @p key, if any, nor NULL if + * nothing was stored under that key. + * + * Example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = evas_object_data_del(obj, "name_of_my_data"); + * @endcode + */ +EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1); - EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set pointer behavior. + * + * @param obj + * @param setting desired behavior. + * + * This function has direct effect on event callbacks related to + * mouse. + * + * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse + * is down at this object, events will be restricted to it as source, + * mouse moves, for example, will be emitted even if outside this + * object area. + * + * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will + * be emitted just when inside this object area. + * + * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB. + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1); + +/** + * Determine how pointer will behave. + * @param obj + * @return 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) EINA_PURE; - EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets whether or not the given evas object is to be drawn anti-aliased. + * + * @param obj The given evas object. + * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise. + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1); + +/** + * Retrieves whether or not the given evas object is to be drawn anti_aliased. + * @param obj The given evas object. + * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise. + * @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) EINA_PURE; - EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1); - EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the scaling factor for an evas object. Does not affect all objects. + * + * @param obj The given evas object. + * @param scale The scaling factor. 1.0 == none. + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1); + +/** + * Retrieves the scaling factor for the given evas object. + * @param obj The given evas object. + * @return The scaling factor. + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1); - EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the render_op to be used for rendering the evas object. + * @param obj The given evas object. + * @param render_op one of the Evas_Render_Op values. + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1); + +/** + * Retrieves the current value of the operation used for rendering the evas object. + * @param obj The given evas object. + * @return one of the enumerated values 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) EINA_PURE; EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1); EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -1121,19 +4183,102 @@ EAPI Evas_Alloc_Error evas_alloc_error (void); * * @ingroup Evas_Object_Group */ - EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieve the object that currently has focus. + * + * @param e The @c Evas canvas to query focus on. + * + * Returns the object that currently has focus, NULL otherwise. + * + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_object_key_grab + * @see evas_object_key_ungrab + * + * @return The object that has focus or NULL is there is not one. + * + * @ingroup Evas_Object_Group_Find + */ +EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieves the object on the given evas with the given name. + * @param e The given evas. + * @param name The given name. + * @return If successful, the evas object with the given name. Otherwise, + * @c NULL. + * @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) EINA_PURE; - 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) EINA_PURE; - EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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) EINA_PURE; + +/** + * Retrieves the top object at the given position (x,y) + * @param e The given evas object. + * @param x The horizontal coordinate + * @param y The vertical coordinate + * @param include_pass_events_objects Boolean Flag to include or not + * pass events objects + * @param include_hidden_objects Boolean Flag to include or not hidden objects + * @return The evas object that is over all others 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) EINA_PURE; + +/** + * Retrieves the top object at mouse pointer position + * @param e The given evas object. + * @return The evas object that is over all others objects at the + * pointer position. + */ +EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieves the top object in the given rectangle region + * @param e The given evas object. + * @param x The horizontal coordinate. + * @param y The vertical coordinate. + * @param w The width size. + * @param h The height size. + * @param include_pass_events_objects Boolean Flag to include or not pass events objects + * @param include_hidden_objects Boolean Flag to include or not hidden objects + * @return The evas object that is over all others objects at the pointer position. + * + */ +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) EINA_PURE; - 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) EINA_PURE; + +/** + * Retrieves the objects at the given position + * @param e The given evas object. + * @param x The horizontal coordinate. + * @param y The vertical coordinate. + * @param include_pass_events_objects Boolean Flag to include or not + * pass events objects + * @param include_hidden_objects Boolean Flag to include or not hidden objects + * @return The list of evas objects at the pointer position. + * + */ +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) EINA_PURE; 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) EINA_PURE; - EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get the lowest evas object on the Evas @p e + * + * @param e an Evas + * @return the lowest object + */ +EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get the highest evas object on the Evas @p e + * + * @param e an Evas + * @return the highest object + */ +EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors @@ -1159,12 +4304,97 @@ typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj 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); - 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); - EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2); - 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); - EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2); - 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); - EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a show event of a object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a show event + * of a canvas object. + * + * @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); + +/** + * Unset the callback function that intercepts a show event of a + * object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a show event + * of a canvas object. + * + * @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); + +/** + * Set the callback function that intercepts a hide event of a object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a hide event + * of a canvas object. + * + * @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); + +/** + * Unset the callback function that intercepts a hide event of a + * object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a hide event + * of a canvas object. + * + * @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); + +/** + * Set the callback function that intercepts a move event of a object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a move event + * of a canvas object. + * + * @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); + +/** + * Unset the callback function that intercepts a move event of a + * object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a move event + * of a canvas object. + * + * @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); @@ -1184,8 +4414,6 @@ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *ob 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 * @@ -1200,7 +4428,13 @@ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *ob * * @ingroup Evas_Object_Specific */ - EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Adds a rectangle to the given evas. + * @param 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 @@ -1294,65 +4528,700 @@ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *ob */ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); - EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Creates a new image object on the given evas. + * + * @param e The given evas. + * @return The created image object. + */ +EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Creates a new image object that automatically scales on the given evas. + * + * This is a helper around evas_object_image_add() and + * evas_object_image_filled_set(), it will track object resizes and apply + * evas_object_image_fill_set() with the new geometry. + * + * @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; - EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1); - EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale); - EAPI double evas_object_image_border_scale_get (const Evas_Object *obj); - 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); - 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); - EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1); - EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); - EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); - EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1); - 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); - EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2); - 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); - EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1); - EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1); - EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the data for an image from memory to be loaded + * + * This 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 @p data at the address is copied and stored for future use, so + * no @p data needs to be kept after this call is made. It will be managed and + * freed for you when no longer needed. The @p size is limited to 2 gigabytes + * in size, and must be greater than 0. A NULL @p data pointer is also invalid. + * Set the filename to NULL to reset to empty state and have the image file + * data freed from memory using evas_object_image_file_set(). + * + * The @p format is optional (pass NULL if you don't 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" or "png" or "gif" etc. + * + * @param obj The given image object. + * @param data The image file data address + * @param size The size of the image file data in bytes + * @param format The format of the file (optional), or NULL if not needed + * @param key The image key in file, or NULL. + */ +EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2); + +/** + * Sets the filename and key of the given image object. + * + * If the file supports multiple data stored in it as eet, you can + * specify the key to be used as the index of the image in this file. + * + * @param obj The given image object. + * @param file The image filename. + * @param key The image key in file, or NULL. + */ +EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1); + +/** + * Retrieves the filename and key of the given image object. + * + * @param obj The given image object. + * @param file Location to store the image filename, or NULL. + * @param key Location to store the image key, or NULL. + */ +EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2); + +/** + * Sets how much of each border of the given image object is not + * to be scaled. + * + * When rendering, the image may be scaled to fit the size of the + * image object. This function sets what area around the border of the + * image is not to be scaled. This sort of function is useful for + * widget theming, where, for example, buttons may be of varying + * sizes, but the border size must remain constant. + * + * The units used for @p l, @p r, @p t and @p b are output units. + * + * @param obj The given image object. + * @param l Distance of the left border that is not to be stretched. + * @param r Distance of the right border that is not to be stretched. + * @param t Distance of the top border that is not to be stretched. + * @param b Distance of the bottom border that is not to be stretched. + */ +EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1); + +/** + * Retrieves how much of each border of the given image object is not + * to be scaled. + * + * See @ref evas_object_image_border_set for more details. + * + * @param obj The given image object. + * @param l Location to store the left border width in, or NULL. + * @param r Location to store the right border width in, or NULL. + * @param t Location to store the top border width in, or NULL. + * @param b Location to store the bottom border width in, or NULL. + */ +EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1); + +/** + * Sets if the center part of the given image object (not the border) + * should be drawn. + * + * When rendering, the image may be scaled to fit the size of the + * image object. This function sets if the center part of the scaled + * image is to be drawn or left completely blank, or forced to be + * solid. Very useful for frames and decorations. + * + * @param obj The given image object. + * @param fill Fill mode of the middle. + */ +EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1); + +/** + * Retrieves if the center of the given image object is to be drawn or + * not. + * + * See @ref evas_object_image_fill_set for more details. + * + * @param obj The given image object. + * @return Fill mode of the center. + */ +EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets if image fill property should track object size. + * + * If set to true, then every evas_object_resize() will automatically + * trigger call to evas_object_image_fill_set() with the new size so + * image will fill the whole object area. + * + * @param obj The given image object. + * @param setting whether to follow object size. + * + * @see evas_object_image_filled_add() + * @see evas_object_image_fill_set() + */ +EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1); + +/** + * Retrieves if image fill property is tracking object size. + * + * @param obj The given image object. + * @return 1 if it is tracking, 0 if not and evas_object_fill_set() + * must be called manually. + */ +EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets a scale factor (multiplier) for the borders of an image + * + * @param obj The given image object. + * @param scale The scale factor (default is 1.0 - i.e. no scale) + */ +EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale); + +/** + * Retrieves the border scale factor + * + * See evas_object_image_border_scale_set() + * + * @param obj The given image object. + * @return The scale factor + */ +EAPI double evas_object_image_border_scale_get (const Evas_Object *obj); + +/** + * Sets the rectangle of the given image object that the image will be + * drawn to. + * + * Note that the image will be tiled around this one rectangle. To + * have only one copy of the image drawn, @p x and @p y must be 0 and + * @p w and @p h need to be the width and height of the image object + * respectively. + * + * The default values for the fill parameters is @p x = 0, @p y = 0, + * @p w = 32 and @p h = 32. + * + * @param obj The given image object. + * @param x The X coordinate for the top left corner of the image. + * @param y The Y coordinate for the top left corner of the image. + * @param w The width of the image. + * @param h The height of the image. + */ +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); + +/** + * Retrieves the dimensions of the rectangle of the given image object + * that the image will be drawn to. + * + * See @ref evas_object_image_fill_set for more details. + * + * @param obj The given image object. + * @param x Location to store the X coordinate for the top left corner of the image in, or NULL. + * @param y Location to store the Y coordinate for the top left corner of the image in, or NULL. + * @param w Location to store the width of the image in, or NULL. + * @param h Location to store the height of the image in, or NULL. + */ +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); + +/** + * Sets the tiling mode for the given evas image object's fill. + * @param obj The given evas image object. + * @param 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); + +/** + * Retrieves the spread (tiling mode) for the given image object's + * fill. + * + * @param 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) EINA_PURE; + +/** + * Sets the size of the given image object. + * + * This function will scale down or crop 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 will be cropped. If the size given is + * larger, then the image will be treated as if it were in the upper + * left hand corner of a larger image that is otherwise transparent. + * + * @param obj The given image object. + * @param w The new width of the image. + * @param 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); + +/** + * Retrieves the size of the given image object. + * + * See @ref evas_object_image_size_set for more details. + * + * @param obj The given image object. + * @param w Location to store the width of the image in, or NULL. + * @param h Location to store the height of the image in, or NULL. + */ +EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * Retrieves the row stride of the given image object, + * + * The row stride is the number of units between the start of a + * row and the start of the next row. + * + * @param obj The given image object. + * @return The stride of the image. + */ +EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieves a number representing any error that occurred during the last + * load of the given image object. + * + * @param obj The given image object. + * @return A value giving the last error that occurred. It should be one of + * the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is + * returned if there was no error. + */ +EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets the raw image data of the given image object. + * + * Note that the raw data must be of the same size and colorspace of + * the image. If data is NULL the current image data will be freed. + * + * @param obj The given image object. + * @param data The raw data, or NULL. + */ +EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * Converts the raw image data of the given image object to the + * specified colorspace. + * + * 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 NULL is returned. You should use + * evas_object_image_colorspace_get() to check the current image + * colorspace. + * + * See @ref evas_object_image_colorspace_get. + * + * @param obj The given image object. + * @param to_cspace The colorspace to which the image raw data will be converted. + * @return data A newly allocated data in the format specified by to_cspace. + */ +EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get a pointer to the raw image data of the given image object. + * + * 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 will be marked dirty so that it gets redrawn at + * the next update. + * + * This is best suited when you want to modify an existing image, + * without changing its dimensions. + * + * @param obj The given image object. + * @param for_writing Whether the data being retrieved will be modified. + * @return The raw image data. + */ +EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Replaces the raw image data of the given image object. + * + * This function lets the application replace an image object's + * internal pixel buffer with a 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. + * + * This call is best suited for when you will be 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. + * + * Note that the caller is responsible for freeing the buffer when + * finished with it, as user-set image data will not be automatically + * freed when the image object is deleted. + * + * See @ref evas_object_image_data_get for more details. + * + * @param obj The given image object. + * @param data The raw data. + */ +EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * Mark a sub-region of the given image object to be redrawn. + * + * This function schedules a particular rectangular region of an image + * object to be updated (redrawn) at the next render. + * + * @param obj The given image object. + * @param x X-offset of the region to be updated. + * @param y Y-offset of the region to be updated. + * @param w Width of the region to be updated. + * @param h 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); + +/** + * Enable or disable alpha channel of the given image object. + * + * This function sets a flag on an image object indicating whether or + * not to use alpha channel data. A value of 1 indicates to use alpha + * channel data, and 0 indicates to ignore any alpha channel + * data. Note that this has nothing to do with an object's color as + * manipulated by evas_object_color_set(). + * + * @param obj The given image object. + * @param has_alpha Whether to use alpha channel data or not. + */ +EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1); + +/** + * @brief Retrieves the alpha channel setting of the given image object. + * + * @param obj The given image object. + * @return Whether the alpha channel data is being used. + * + * This function returns 1 if the image object's alpha channel is + * being used, or 0 otherwise. + * + * See @ref evas_object_image_alpha_set for more details. + */ +EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Sets whether to use of high-quality image scaling algorithm + * of the given image object. + * + * When enabled, a higher quality image scaling algorithm is used when + * scaling images to sizes other than the source image. This gives + * better results but is more computationally expensive. + * + * @param obj The given image object. + * @param smooth_scale Whether to use smooth scale or not. + */ +EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1); + +/** + * Retrieves whether the given image object is using use a + * high-quality image scaling algorithm. + * + * See @ref evas_object_image_smooth_scale_set for more details. + * + * @param obj The given image object. + * @return Whether smooth scale is being used. + */ +EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Preload image in the background + * + * This function request the preload of the data image in the + * background. The worked is queued before being processed. + * + * If image data is already loaded, it will callback + * EVAS_CALLBACK_IMAGE_PRELOADED immediatelly and do nothing else. + * + * If cancel is set, it will remove the image from the workqueue. + * + * @param obj The given image object. + * @param cancel 0 means add to the workqueue, 1 remove it. + */ +EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1); + +/** + * Reload a image of the canvas. + * + * @param obj The given image object pointer. + * + * This function reloads a image of the given canvas. + * + */ +EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Save the given image object to a file. + * + * Note that you should pass the filename extension when saving. If + * the file supports multiple data stored in it as eet, you can + * specify the key to be used as the index of the image in this file. + * + * You can specify some flags when saving the image. Currently + * acceptable flags are quality and compress. Eg.: "quality=100 + * compress=9" + * + * @param obj The given image object. + * @param file The filename to be used to save the image. + * @param key The image key in file, or NULL. + * @param flags String containing the flags to be used. + */ +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); + +/** + * Import pixels from given source to a given canvas image object. + * + * @param obj The given canvas object. + * @param pixels The pixel's source to be imported. + * + * This function imports pixels from a given source to a given canvas image. + * + */ +EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function to get pixels from a canva's image. + * + * @param obj The given canvas pointer. + * @param func The callback function. + * @param data The data pointer to be passed to @a func. + * + * This functions sets a function to be the callback function that get + * pixes from a image of the canvas. + * + */ +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); + +/** + * Mark whether the given image object is dirty (needs to be redrawn). + * + * @param obj The given image object. + * @param dirty Whether the image is dirty. + */ +EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1); + +/** + * Retrieves whether the given image object is dirty (needs to be redrawn). + * + * @param obj The given image object. + * @return Whether the image is dirty. + */ +EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the dpi resolution of a loaded image of the canvas. + * + * @param obj The given canvas pointer. + * @param dpi The new dpi resolution. + * + * This function set the dpi resolution of a given loaded canvas image. + * + */ +EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1); + +/** + * Get the dpi resolution of a loaded image of the canvas. + * + * @param obj The given canvas pointer. + * @return The dpi resolution of the given canvas image. + * + * This function returns the dpi resolution of given canvas image. + * + */ +EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the size of a loaded image of the canvas. + * + * @param obj The given canvas object. + * @param w The new width of the canvas image given. + * @param h The new height of the canvas image given. + * + * This function sets a new size for the given canvas image. + * + */ +EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1); + +/** + * Get the size of a loaded image of the canvas. + * + * @param obj The given canvas object. + * @param w The width of the canvas image given. + * @param h The height of the canvas image given. + * + * This function get the size of the given canvas image. + * + */ +EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * Set the scale down of a loaded image of the canvas. + * + * @param obj The given canvas pointer. + * @param scale_down The scale to down value. + * + * This function sets the scale down of a given canvas image. + * + */ +EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1); + +/** + * Get the scale down value of given image of the canvas. + * + * @param obj The given image object pointer. + * + * This function returns the scale down value of a given canvas image. + * + */ +EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1); - EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2); - EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1); - EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1); - EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the colorspace of a given image of the canvas. + * + * @param obj The given image object pointer. + * @param cspace The new color space. + * + * This function sets the colorspace of given canvas image. + * + */ +EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1); + +/** + * Get the colorspace of a given image of the canvas. + * + * @param obj The given image object pointer. + * @return The colorspace of the image. + * + * This function returns the colorspace of given canvas image. + * + */ +EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the native surface of a given image of the canvas + * + * @param obj The given canvas pointer. + * @param surf The new native surface. + * + * This function sets a native surface of a given canvas image. + * + */ +EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2); + +/** + * Get the native surface of a given image of the canvas + * + * @param obj The given canvas pointer. + * @return The native surface of the given canvas image. + * + * This function returns the native surface of a 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) EINA_PURE; + +/** + * Set the scale hint of a given image of the canvas. + * + * @param obj The given canvas pointer. + * @param hint The scale hint value. + * + * This function sets the scale hint value of the given image of the canvas. + * + */ +EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1); + +/** + * Get the scale hint of a given image of the canvas. + * + * @param obj The given canvas pointer. + * + * This function returns the scale hint value of the given image of the canvas. + * + */ +EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the content hint of a given image of the canvas. + * + * @param obj The given canvas pointer. + * @param hint The content hint value. + * + * This function sets the content hint value of the given image of the canvas. + * + */ +EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1); + +/** + * Get the content hint of a given image of the canvas. + * + * @param obj The given canvas pointer. + * + * This function returns the content hint value of the given image of the canvas. + * + */ +EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1); - EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Enable an image to be used as an alpha mask. + * + * This will set any flags, and discard any excess image data not used as an + * alpha mask. + * + * Note there is little point in using a image as alpha mask unless it has an + * alpha channel. + * + * @param obj Object to use as an alpha mask. + * @param ismask Use image as alphamask, must be true. + */ +EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1); + +/** + * Set the source object on a proxy object. + * + * The source must be another object. The proxy will have the same base + * appearance of the source object. Obviously other effects may be applied to + * the proxy, such as a map to create a reflection of the original object. + * + * Any existing source object will be removed. Setting the src to NULL clears + * the proxy object. + * + * You cannot set a proxy on a proxy. + * + * @param obj Proxy object. + * @param src Source of the proxy. + * @return EINA_TRUE on success, EINA_FALSE on error. + */ +EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1); + +/** + * Get the current source object of an image. + * + * @param obj Image object + * @return Source object, or NULL on error. + */ +EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Clear the source on a proxy image. + * + * This is equivalent to calling evas_object_image_source_set with a NULL + * source. + * + * @param obj Image object to clear source of. + * @return EINA_TRUE on success, EINA_FALSE on error. + */ +EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1); /** * @defgroup Evas_Object_Text Text Object Functions @@ -1377,13 +5246,50 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); EVAS_TEXT_STYLE_FAR_SOFT_SHADOW } Evas_Text_Style_Type; - EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Creates a new text @c Evas_Object on the provided @c Evas canvas. + * + * @param e The @c Evas canvas to create the text object upon. + * + * @see evas_object_text_font_source_set + * @see evas_object_text_font_set + * @see evas_object_text_text_set + * + * @returns NULL on error, A pointer to a new @c Evas_Object on success. + */ +EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1); EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1); - EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); - EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Query evas for font information of a text @c Evas_Object. + * + * This function allows the font name and size of a text @c Evas_Object as + * created with evas_object_text_add() to be queried. Be aware that the font + * name string is still owned by Evas and should NOT have free() called on + * it by the caller of the function. + * + * @param obj The evas text object to query for font information. + * @param font A pointer to the location to store the font name in (may be NULL). + * @param size A pointer to the location to store the font size in (may be NULL). + */ +EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2); + +/** + * Sets the text to be displayed by the given evas text object. + * @param obj Evas text object. + * @param text Text to display. + */ +EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); + +/** + * Retrieves the text currently being displayed by the given evas text object. + * @param obj The given evas text object. + * @return The text currently being displayed. Do not free it. + */ +EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -1391,9 +5297,34 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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); + +/** + * Retrieve position and dimension information of a character within a text @c Evas_Object. + * + * This function is used to obtain the X, Y, width and height of a the character + * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object + * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx, + * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that + * parameter. + * + * @param obj The text object to retrieve position information for. + * @param pos The character position to request co-ordinates for. + * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL). + * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL). + * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL). + * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL). + * + * @returns EINA_FALSE on error, EINA_TRUE on success. + */ +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); 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); - EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * Returns the logical position of the last char in the text + * up to the pos given. this is NOT the position of the last char + * because of the possibility of RTL in the text. + */ +EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1); EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); @@ -1404,8 +5335,26 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); - EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1); - EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Gets the text style pad of a text object. + * + * @param obj The given text object. + * @param l The left pad (or NULL). + * @param r The right pad (or NULL). + * @param t The top pad (or NULL). + * @param b The bottom pad (or 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); + +/** + * Retrieves the direction of the text currently being displayed in the + * text object. + * @param 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; /** * @defgroup Evas_Object_Textblock Textblock Object Functions @@ -1418,6 +5367,71 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); * @todo put here some usage examples * * @ingroup Evas_Object_Specific + */ + +/** + * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial + * + * This part explains about the textblock object's API and proper usage. + * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal. + * The main user of the textblock object is the edje entry object in Edje, so + * that's a good place to learn from, but I think this document is more than + * enough, if it's not, please request for me info and I'll update it. + * + * @subsection textblock_intro Introduction + * The textblock objects 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. + * + * @subsection textblock_cursors Textblock Object Cursors + * A textblock Cursor @ref Evas_Textblock_Cursor is 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 obj and you can't 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'll + * still point to it even after you change the whole object completely (as long + * as the char was not deleted), this is not possible without updating, because + * as mentioned, each cursor holds a character position. There are many + * functions that handle cursors, just check out the evas_textblock_cursor* + * functions. For creation and deletion of cursors check out: + * @see evas_object_textblock_cursor_new() + * @see evas_textblock_cursor_free() + * @note Cursors are generally the correct way to handle text in the textblock object, and there are enough functions to do everything you need with them (no need to get big chunks of text and processing them yourself). + * + * @subsection textblock_paragraphs Textblock Object Paragraphs + * The textblock object is made out of text splitted 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, i.e formats that + * occupy space, for example: newlines, tabs, items and etc. Some visible items + * are made of two parts, in this case, only the opening tag is visible. + * A closing tag (i.e a tag) should NEVER be visible. + * Invisible: formats that don't occupy space, for example: bold and underline. + * Being able to access format nodes is very important for some uses. For + * example, edje uses the "" 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, take a look at all the evas_textblock_node_format_* + * functions. + * The translation of "" 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 + * This section is not yet written. If you want some info about styles/formats + * and how to use them, expedite's textblock_basic test is a great start. + * @todo Write @textblock_special_formats */ typedef struct _Evas_Textblock_Style Evas_Textblock_Style; typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor; @@ -1446,94 +5460,731 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); EVAS_TEXTBLOCK_CURSOR_BEFORE } Evas_Textblock_Cursor_Type; - EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Adds a textblock to the given evas. + * @param 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; - EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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) EINA_PURE; + +/** + * Returns the unescaped version of escape. + * @param 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) EINA_PURE; + +/** + * Returns the escaped version of the string. + * @param string to escape + * @param len_ret the len of the new escape + * @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) EINA_PURE; + +/** + * Return the unescaped version of the string between start and end. + * + * @param escape_start the start of the string. + * @param 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) EINA_PURE; - EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; - EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1); - EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Creates a new textblock style. + * @return The new textblock style. + */ +EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * Destroys a textblock style. + * @param ts The textblock style to free. + */ +EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); + +/** + * Sets the style ts to the style passed as text by text. + * Expected a string consisting of many (or none) tag='format' pairs. + * + * @param ts the style to set. + * @param text the text to parse - NOT NULL. + * @return Returns no value. + */ +EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1); + +/** + * Return the text of the style ts. + * @param ts the style to get it's text. + * @return the text of the style or null on error. + */ +EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); - EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1); - EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align); - EAPI double evas_object_textblock_valign_get(const Evas_Object *obj); + +/** + * Set the objects style to ts. + * @param obj the evas object to set the style to. + * @param ts the style to set. + * @return Returns no value. + */ +EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); + +/** + * Return the style of an object. + * @param 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) EINA_PURE; + +/** + * @brief Set the "replacement character" to use for the given textblock object. + * + * @param obj The given textblock object. + * @param ch The charset name. + */ +EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Get the "replacement character" for given textblock object. Returns + * NULL if no replacement character is in use. + * + * @param obj The given textblock object + * @return replacement character or NULL + */ +EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Sets the vertical alignment of text within the textblock object + * as a whole. + * + * Normally alignment is 0.0 (top of object). Values given should be + * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered + * etc.). + * + * @param obj The given textblock object. + * @param align A value between 0.0 and 1.0 + * @since 1.1.0 + */ +EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align); + +/** + * @brief Gets the vertical alignment of a textblock + * + * @param obj The given textblock object. + * @return The elignment set for the object + * @since 1.1.0 + */ +EAPI double evas_object_textblock_valign_get(const Evas_Object *obj); - EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Sets newline mode. When true, newline character will behave + * as a paragraph separator. + * + * @param obj The given textblock object. + * @param mode EINA_TRUE for PS mode, EINA_FALSE otherwise. + * @since 1.1.0 + */ +EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1); + +/** + * @brief Gets newline mode. When true, newline character behaves + * as a paragraph separator. + * + * @param obj The given textblock object. + * @return EINA_TRUE if in PS mode, EINA_FALSE otherwise. + * @since 1.1.0 + */ +EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); - EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); - EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Sets the tetxblock's text to the markup text. + * + * @note assumes text does not include the unicode object replacement char (0xFFFC) + * + * @param obj the textblock object. + * @param text the markup text to use. + * @return Return no value. + */ +EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); + +/** + * Prepends markup to the cursor cur. + * + * @note assumes text does not include the unicode object replacement char (0xFFFC) + * + * @param cur the cursor to prepend to. + * @param text the markup text to prepend. + * @return Return no value. + */ +EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); + +/** + * Return the markup of the object. + * + * @param 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); - EAPI const Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Return the object's main cursor. + * + * @param obj the object. + * @return the obj's main cursor. + */ +EAPI const Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Create a new cursor, associate it to the obj and init it to point + * to the start of the textblock. Association to the object means the cursor + * will be updated when the object will change. + * + * @note if you need speed and you know what you are doing, it's slightly faster to just allocate the cursor yourself and not associate it. (only people developing the actual object, and not users of the object). + * + * @param obj the object to associate to. + * @return the new cursor. + */ +EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Free the cursor and unassociate it from the object. + * @note do not use it to free unassociated cursors. + * + * @param cur the cursor to free. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); - EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); - EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); - EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(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) EINA_PURE; - EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2); + +/** + * Sets the cursor to the start of the first text node. + * + * @param cur the cursor to update. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * sets the cursor to the end of the last text node. + * + * @param cur the cursor to set. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Advances to the the start of the next text node + * + * @param cur the cursor to update + * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Advances to the the end of the previous text node + * + * @param cur the cursor to update + * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Returns the first format node. + * + * @param obj The evas, must not be NULL. + * @return Returns the first format node, may be null if there are none. + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Returns the last format node. + * + * @param obj The evas textblock, must not be NULL. + * @return Returns the first format node, may be null if there are none. + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Returns the next format node (after n) + * + * @param n the current format node - not null. + * @return Returns the next format node, may be null. + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); + +/** + * Returns the prev format node (after n) + * + * @param n the current format node - not null. + * @return Returns the prev format node, may be null. + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); + +/** + * Remove a format node and it's match. i.e, removes a pair. + * Assumes the node is the first part of i.e, this won't work if + * n is a closing tag. + * + * @param obj the evas object of the textblock - not null. + * @param n the current format node - not null. + */ +EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); + +/** + * Sets the cursor to point to the place where format points to. + * + * @param cur the cursor to update. + * @param n the format node to update according. + */ +EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); + +/** + * Return the format node at the position pointed by cur. + * + * @param cur the position to look at. + * @return the format node if found, NULL otherwise. + * @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); + +/** + * Get the text format representation of the format node. + * + * @param fmt 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 *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Set the cursor to point to the position of fmt. + * + * @param cur the cursor to update + * @param 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); + +/** + * Check if the current cursor position is a visible format. This way is more + * efficient than evas_textblock_cursor_format_get() to check for the existence + * of a visible format. + * + * @param cur the cursor to look at. + * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise. + * @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) EINA_PURE; + +/** + * Advances to the next format node + * + * @param cur the cursor to be updated. + * @return #EINA_TRUE on success #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Advances to the previous format node. + * + * @param cur the cursor to update. + * @return #EINA_TRUE on success #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Returns true if the cursor points to a format. + * + * @param cur the cursor to check. + * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Advances 1 char forward. + * + * @param cur the cursor to advance. + * @return #EINA_TRUE on success #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Advances 1 char backward. + * + * @param cur the cursor to advance. + * @return #EINA_TRUE on success #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Go to the first char in the node the cursor is pointing on. + * + * @param cur the cursor to update. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Go to the last char in a text node. + * + * @param cur the cursor to update. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Go to the start of the current line + * + * @param cur the cursor to update. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Go to the end of the current line. + * + * @param cur the cursor to update. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Return the current cursor pos. + * + * @param cur the cursor to take the position from. + * @return the position or -1 on error + */ +EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Set the cursor pos. + * + * @param cur the cursor to be set. + * @param pos the pos to set. + */ +EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1); + +/** + * Go to the start of the line passed + * + * @param cur cursor to update. + * @param line numer to set. + * @return #EINA_TRUE on success, #EINA_FALSE on error. + */ +EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1); + +/** + * Compare two cursors. + * + * @param cur1 the first cursor. + * @param cur2 the second cursor. + * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise. + */ +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) EINA_PURE; + +/** + * Make cur_dest point to the same place as cur. Does not work if they don't + * point to the same object. + * + * @param cur the source cursor. + * @param cur_dest destination cursor. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2); - EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); - EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); + +/** + * Adds text to the current cursor position and set the cursor to *before* + * the start of the text just added. + * + * @param cur the cursor to where to add text at. + * @param _text the text to add. + * @return Returns the len 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); + +/** + * Adds text to the current cursor position and set the cursor to *after* + * the start of the text just added. + * + * @param cur the cursor to where to add text at. + * @param _text the text to add. + * @return Returns the len 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); - EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); + +/** + * Adds format to the current cursor position. 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. + * + * This function works with native formats, that means that style defined + * tags like
won't work here. For those kind of things use markup prepend. + * + * @param cur the cursor to where to add format at. + * @param format the format to add. + * @return Returns true if a visible format was added, false otherwise. + * @see evas_textblock_cursor_format_prepend() + */ + +/** + * Check if the current cursor position points to the terminating null of the + * last paragraph. (shouldn't be allowed to point to the terminating null of + * any previous paragraph anyway. + * + * @param cur the cursor to look at. + * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); + +/** + * Adds format to the current cursor position. 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. + * + * This function works with native formats, that means that style defined + * tags like
won't work here. For those kind of things use markup prepend. + * + * @param cur the cursor to where to add format at. + * @param 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_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); EAPI void evas_textblock_cursor_node_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); - EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2); + +/** + * Delete the character at the location of the cursor. If there's a format + * pointing to this position, delete it as well. + * + * @param cur the cursor pointing to the current location. + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * Delete the range between cur1 and cur2. + * + * @param cur1 one side of the range. + * @param cur2 the second side of the range + * @return Returns no value. + */ +EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2); - EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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) EINA_PURE; - EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Return the text of the paragraph cur points to - returns the text in markup.. + * + * @param cur the cursor pointing to the paragraph. + * @return the text on success, NULL otherwise. + */ +EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Return the length of the paragraph, cheaper the eina_unicode_strlen() + * + * @param cur the position of the paragraph. + * @return the length of the paragraph on success, -1 otehrwise. + */ +EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Return the text in the range between cur1 and cur2 + * + * FIXME: format is currently unused, you always get markup back. + * + * @param cur1 one side of the range. + * @param cur2 the other side of the range + * @param format to be documented + * @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) EINA_PURE; + +/** + * Return the content of the cursor. + * + * @param cur the cursor + * @return the text in the range + */ +EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - 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); - 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); - 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); - 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); - EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); - EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1); - 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) EINA_PURE; + +/** + * Returns the geometry of the cursor. 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. + * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry + * get, except for the case of the last char of a line which depends on the + * paragraph direction. + * + * in '|' cursor mode (i.e a line between two chars) it is very varyable. + * 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 cur the cursor. + * @param cx the x of the cursor + * @param cy the y of the cursor + * @param cw the width of the cursor + * @param ch the height of the cursor + * @param dir the direction of the cursor, can be NULL. + * @param ctype the type of the cursor. + * @return line number of the char on success, -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); + +/** + * Returns the geometry of the char at cur. + * + * @param cur the position of the char. + * @param cx the x of the char. + * @param cy the y of the char. + * @param cw the w of the char. + * @param ch the h of the char. + * @return line number of the char on success, -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); + +/** + * Returns the geometry of the pen at cur. + * + * @param cur the position of the char. + * @param cpen_x the pen_x of the char. + * @param cy the y of the char. + * @param cadv the adv of the char. + * @param ch the h of the char. + * @return line number of the char on success, -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); + +/** + * Returns the geometry of the line at cur. + * + * @param cur the position of the line. + * @param cx the x of the line. + * @param cy the y of the line. + * @param cw the width of the line. + * @param ch the height of the line. + * @return line number of the line on success, -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); + +/** + * Set the position of the cursor according to the X and Y coordinates. + * + * @param cur the cursor to set. + * @param x coord to set by. + * @param y coord to set by. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * Set the cursor position according to the y coord. + * + * @param cur the cur to be set. + * @param y the coord to set by. + * @return the line number found, -1 on error. + */ +EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * Get the geometry of a range. + * + * @param cur1 one side of the range. + * @param cur2 other side 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) EINA_PURE; 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); - EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Checks if the cursor points to the end of the line. + * + * @param cur the cursor to check. + * @return #EINA_TRUE if true, #EINA_FALSE otherwise. + */ +EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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); - EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); - EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * Get the geometry of a line number. + * + * @param obj the object. + * @param line the line number. + * @param cx x coord of the line. + * @param cy y coord of the line. + * @param cw w coord of the line. + * @param ch h coord of the line. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + */ +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); + +/** + * Clear the textblock object. + * @note Does *NOT* free the evas object itself. + * + * @param obj the object to clear. + * @return nothing. + */ +EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Get the formatted width and height. 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 wrapping into account + * it just calculates the real width of the object if it was placed on an + * infinite canvas, while this function gives the size after wrapping + * according to the size restrictions of the object. + * + * For example for 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 obj the evas object. + * @param w[out] the width of the object. + * @param h[out] the height of the object + * @return Returns no value. + * @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); + +/** + * Get the native width and height. This calculates the actual size without taking 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 was placed on an + * infinite canvas, while the "formatted" function gives the size after + * wrapping text according to the size restrictions of the object. + * + * For example for 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 obj the evas object of the textblock + * @param w[out] the width returned + * @param h[out] the height returned + * @return Returns no value. + */ +EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); 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); /** @@ -1543,9 +6194,37 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); * * @ingroup Evas_Object_Specific */ - EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2); - EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2); + +/** + * Adds a new evas line object to the given evas. + * @param 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; + +/** + * Sets the coordinates of the end points of the given evas line object. + * @param obj The given evas line object. + * @param x1 The X coordinate of the first point. + * @param y1 The Y coordinate of the first point. + * @param x2 The X coordinate of the second point. + * @param 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); + +/** + * Retrieves the coordinates of the end points of the given evas line object. + * @param obj The given line object. + * @param x1 Pointer to an integer in which to store the X coordinate of the + * first end point. + * @param y1 Pointer to an integer in which to store the Y coordinate of the + * first end point. + * @param x2 Pointer to an integer in which to store the X coordinate of the + * second end point. + * @param y2 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 @@ -1557,9 +6236,28 @@ typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o); * * @ingroup Evas_Object_Specific */ - EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); - EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Adds a new evas polygon object to the given evas. + * @param 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; + +/** + * Adds the given point to the given evas polygon object. + * @param obj The given evas polygon object. + * @param x The X coordinate of the given point. + * @param 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); + +/** + * Removes all of the points from the given evas polygon object. + * @param obj The given polygon object. + */ +EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1); /** * @defgroup Evas_Smart_Group Smart Functions @@ -1827,14 +6525,111 @@ struct _Evas_Smart_Cb_Description evas_object_smart_data_set(o, priv); \ } - EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1); - EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI const Evas_Smart_Class *evas_smart_class_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Free an Evas_Smart + * + * If this smart was created using evas_smart_class_new(), the associated + * Evas_Smart_Class will not be freed. + * + * @param s the Evas_Smart to free + * + */ +EAPI void evas_smart_free (Evas_Smart *s) EINA_ARG_NONNULL(1); + +/** + * Creates an Evas_Smart from an Evas_Smart_Class. + * + * @param sc the smart class definition + * @return an Evas_Smart + */ +EAPI Evas_Smart *evas_smart_class_new (const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Get the Evas_Smart_Class of an Evas_Smart + * + * @param s the Evas_Smart + * @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) EINA_PURE; - EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * @brief Get the data pointer set on an Evas_Smart. + * + * @param s Evas_Smart + * + * This data pointer is set either as the final parameter to + * evas_smart_new or as the data field in the Evas_Smart_Class passed + * in to evas_smart_class_new + */ +EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - 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); +/** + * Get the callbacks known by this Evas_Smart. + * + * This is likely different from Evas_Smart_Class::callbacks as it + * will contain the callbacks of all class hierarchy sorted, while the + * direct smart class member refers only to that specific class and + * should not include parent's. + * + * If no callbacks are known, this function returns @c NULL. + * + * The array elements and thus their contents will be reference to + * original values given to evas_smart_new() as + * Evas_Smart_Class::callbacks. + * + * The array is sorted by name. The last array element is the @c NULL + * pointer and is not counted in @a count. Loop iterations can check + * any of these cases. + * + * @param s the Evas_Smart. + * @param count returns the number of elements in returned array. + * @return the array with callback descriptions known by this class, + * its size is returned in @a count parameter. It should not + * be modified anyhow. If no callbacks are known, @c NULL is + * returned. The array is sorted by name and elements refer to + * the original value given to evas_smart_new(). + * + * @note objects may provide per-instance callbacks, use + * evas_object_smart_callbacks_descriptions_get() to get those + * as well. + * @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); + + +/** + * Find callback description for callback called @a name. + * + * @param s the Evas_Smart. + * @param name name of desired callback, must @b not be @c NULL. The + * search have a special case for @a name being the same + * pointer as registered with Evas_Smart_Cb_Description, one + * can use it to avoid excessive use of strcmp(). + * @return reference to description if found, @c NULL if not found. + */ +EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2) EINA_PURE; + + +/** + * Sets one class to inherit from the other. + * + * Copy all function pointers, set @c parent to @a parent_sc and copy + * everything after sizeof(Evas_Smart_Class) present in @a parent_sc, + * using @a parent_sc_size as reference. + * + * This is recommended instead of a single memcpy() since it will take + * care to not modify @a sc name, version, callbacks and possible + * other members. + * + * @param sc child class. + * @param parent_sc parent class, will provide attributes. + * @param parent_sc_size size of parent_sc structure, child should be at least + * this size. 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); /** * @def evas_smart_class_inherit * Easy to use version of evas_smart_class_inherit_full(). @@ -1861,30 +6656,289 @@ struct _Evas_Smart_Cb_Description * * @see @ref Evas_Smart_Group for class definitions. */ - EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC; - EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Eina_Bool evas_object_smart_type_check (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - 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) EINA_PURE; - EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); - 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); - EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3); - EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2); + +/** + * Instantiates a new smart object described by @p s. + * + * @param e the evas on which to add the object + * @param s the Evas_Smart describing the smart object + * @return a new Evas_Object + * @ingroup Evas_Smart_Object_Group + */ +EAPI Evas_Object *evas_object_smart_add (Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC; + +/** + * Set an evas object as a member of a smart object. + * + * @param obj The member object + * @param smart_obj The smart object + * + * Members will automatically be stacked and layered with the smart object. + * The various stacking function will operate on members relative to the + * other members instead of the entire canvas. + * + * Non-member objects can not interleave a smart object's members. + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2); + +/** + * Removes a member object from a smart object. + * + * @param obj the member object + * @ingroup Evas_Smart_Object_Group + * + * This removes a member object from a smart object. The object will still + * be on the canvas, but no longer associated with whichever smart object + * it was associated with. + * + */ +EAPI void evas_object_smart_member_del (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Gets the smart parent of an Evas_Object + * @param obj the Evas_Object you want to get the parent + * @return Returns the smart parent of @a obj, or NULL if @a obj is not a smart member of another Evas_Object + * @ingroup Evas_Smart_Object_Group + */ +EAPI Evas_Object *evas_object_smart_parent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Checks the Smart type of the object and its parents + * @param obj the Evas_Object to check the type of + * @param type the type to check for + * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise + * @ingroup Evas_Smart_Object_Group + */ +EAPI Eina_Bool evas_object_smart_type_check (const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Checks the Smart type of the object and its parents using pointer comparison + * @param obj the Evas_Object to check the type of + * @param type the type to check for. Must be the name pointer in the smart class used to create the object + * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise + * @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) EINA_PURE; + +/** + * Gets the list of the member objects of an Evas_Object + * @param obj the Evas_Object you want to get the list of member objects + * @return Returns the list of the member objects of @a obj. + * The returned list should be freed with eina_list_free() when you no longer need it + */ +EAPI Eina_List *evas_object_smart_members_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get the Evas_Smart from which @p obj was created. + * + * @param obj a smart object + * @return the Evas_Smart + * @ingroup Evas_Smart_Object_Group + */ +EAPI Evas_Smart *evas_object_smart_smart_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Retrieve user data stored on a smart object. + * + * @param obj The smart object + * @return A pointer to data stored using evas_object_smart_data_set(), or + * NULL if none has been set. + * @ingroup Evas_Smart_Object_Group + */ +EAPI void *evas_object_smart_data_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Store a pointer to user data for a smart object. + * + * @param obj The smart object + * @param data A pointer to user data + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * Add a callback for the smart event specified by @p event. + * + * @param obj a smart object + * @param event the event name + * @param func the callback function + * @param data user data to be passed to the callback function + * @ingroup Evas_Smart_Object_Group + */ +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); + +/** + * Remove a smart callback + * + * Removes a callback that was added by evas_object_smart_callback_add() + * + * @param obj a smart object + * @param event the event name + * @param func the callback function + * @return the data pointer + * @ingroup Evas_Smart_Object_Group + */ +EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3); + +/** + * Call any smart callbacks on @p obj for @p event. + * + * @param obj the smart object + * @param event the event name + * @param event_info an event specific struct of info to pass to the callback + * + * This should be called internally in the smart object when some specific + * event has occurred. The documentation for the smart object should include + * a list of possible events and what type of @p event_info to expect. + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1); - 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); - 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); + +/** + * Set smart object instance callbacks descriptions. + * + * These descriptions are hints to be used by introspection and are + * not enforced in any way. + * + * It will not be checked if instance callbacks descriptions have the + * same name as another in class. Both are kept in different arrays + * and users of evas_object_smart_callbacks_descriptions_get() should + * handle this case as they wish. + * + * @param obj The smart object + * @param descriptions NULL terminated (name != NULL) array with + * descriptions. Array elements will not be modified, but + * reference to them and their contents will be made, so this + * array should be kept alive during object lifetime. + * @return 1 on success, 0 on failure. + * @ingroup Evas_Smart_Object_Group + * + * @note while instance callbacks descriptions are possible, they are + * not recommended. Use class callbacks descriptions instead as they + * make user's life simpler and will use less memory as descriptions + * and arrays will be shared among all instances. + */ +EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1); + +/** + * Get the callbacks descriptions known by this smart object. + * + * This call retrieves processed callbacks descriptions for both + * instance and class. These arrays are sorted by description's name + * and are @c NULL terminated, so both @a class_count and + * @a instance_count can be ignored, the terminator @c NULL is not + * counted in these values. + * + * @param obj the smart object. + * @param class_descriptions where to store class callbacks + * descriptions array, if any is known. If no descriptions are + * known, @c NULL is returned. This parameter may be @c NULL if + * it is not of interest. + * @param class_count returns how many class callbacks descriptions + * are known. + * @param instance_descriptions where to store instance callbacks + * descriptions array, if any is known. If no descriptions are + * known, @c NULL is returned. This parameter may be @c NULL if + * it is not of interest. + * @param instance_count returns how many instance callbacks + * descriptions are known. + * + * @note if just class descriptions are of interest, try + * evas_smart_callbacks_descriptions_get() instead. + * + * @see evas_smart_callbacks_descriptions_get() + * @ingroup Evas_Smart_Object_Group + */ +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); + +/** + * Find callback description for callback called @a name. + * + * @param obj the smart object. + * @param name name of desired callback, must @b not be @c NULL. The + * search have a special case for @a name being the same + * pointer as registered with Evas_Smart_Cb_Description, one + * can use it to avoid excessive use of strcmp(). + * @param class_description pointer to return class description or @c + * NULL if not found. If parameter is @c NULL, no search will + * be done on class descriptions. + * @param instance_description pointer to return instance description + * or @c NULL if not found. If parameter is @c NULL, no search + * will be done on instance descriptions. + * @return reference to description if found, @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); - EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Mark smart object as changed, dirty. + * + * This will inform the scene that it changed and needs to be redraw, also + * setting need_recalculate on the given object. + * + * @see evas_object_smart_need_recalculate_set(). + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_changed (Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * Set the need_recalculate flag of given smart object. + * + * If this flag is set then calculate() callback (method) of the given + * smart object will be called, if one is provided, during render phase + * usually evas_render(). After this step, this flag will be automatically + * unset. + * + * If no calculate() is provided, this flag will be left unchanged. + * + * @note just setting this flag will not make scene dirty and evas_render() + * will have no effect. To do that, use evas_object_smart_changed(), + * that will automatically call this function with 1 as parameter. + * + * @param obj the smart object + * @param value if one want to set or unset the need_recalculate flag. + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1); + +/** + * Get the current value of need_recalculate flag. + * + * @note this flag will be unset during the render phase, after calculate() + * is called if one is provided. If no calculate() is provided, then + * the flag will be left unchanged after render phase. + * + * @param obj the smart object + * @return if flag is set or not. + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Call user provided calculate() and unset need_calculate. + * + * @param obj the smart object + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_object_smart_calculate (Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI void evas_smart_objects_calculate (Evas *e); + +/** + * Call user provided calculate() and unset need_calculate on all objects. + * + * @param e The canvas to calculate all objects in + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI void evas_smart_objects_calculate (Evas *e); /** * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object @@ -1914,11 +6968,75 @@ struct _Evas_Smart_Cb_Description Evas *evas; }; - EAPI Evas_Object *evas_object_smart_clipped_clipper_get (Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1); - EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST; + +/** + * Get the clipper object for the given clipped smart object. + * + * @param obj the clipped smart object to retrieve the associated clipper. + * @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) EINA_PURE; + +/** + * Set smart class callbacks so it implements the "Clipped Smart Object". + * + * This call will assign all the required methods of Evas_Smart_Class, + * if one wants to "subclass" it, call this function and later + * override values, if one wants to call the original method, save it + * somewhere, 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 ≻ + * } + * @endcode + * + * Default behavior is: + * - add: creates a hidden clipper with "infinite" size; + * - del: delete all children objects; + * - move: move all objects relative relatively; + * - resize: not defined; + * - show: if there are children objects, show clipper; + * - hide: hides clipper; + * - color_set: set the color of clipper; + * - clip_set: set clipper of clipper; + * - clip_unset: unset the clipper of clipper; + */ +EAPI void evas_object_smart_clipped_smart_set (Evas_Smart_Class *sc) EINA_ARG_NONNULL(1); + +/** + * Get a pointer to the Clipped Smart Class to use for proper inheritance + */ +EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get (void) EINA_CONST; - EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1); + +/** + * Moves all children objects relative to given offset. + * + * @param obj the smart evas object to use. + * @param dx horizontal offset. + * @param dy vertical offset. + */ +EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1); /** * @defgroup Evas_Object_Box Box (Sequence) Smart Object. @@ -2087,46 +7205,415 @@ struct _Evas_Smart_Cb_Description Evas_Coord alloc_size; }; - EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1); - EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST; - 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); + +/** + * Set the default box @a api struct (Evas_Object_Box_Api) + * with the default values. May be used to extend that API. + */ +EAPI void evas_object_box_smart_set (Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1); + +/** + * Get Box Smart Class for inheritance purposes + */ +EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get (void) EINA_CONST; + +/** + * Set a 'calculate' callback (@a cb) to the @a o box's smart class, + * which here defines its genre (horizontal, vertical, homogeneous, + * etc.). + */ +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); - EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Evas_Object *evas_object_box_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Create a new box. + * + * Its layout function must be set via evas_object_box_layout_set() + * (defaults to evas_object_box_layout_horizontal()). The other + * properties of the box must be set/retrieved via + * evas_object_box_{h,v}_{align,padding}_{get,set)(). + */ +EAPI Evas_Object *evas_object_box_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Create a box that is child of a given element @a parent. + * + * @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; - EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - 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); - 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); - EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a (basic) horizontal + * box. @a priv must be the smart data of the box. + * + * The object's overall behavior is controlled by its properties, + * which are set by the evas_object_box_{h,v}_{align,padding}_set() + * family of functions. The properties of the elements in the box -- + * set by evas_object_size_hint_{align,padding,weight}_set() 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 0, children are aligned + * to the left. A value of 1 lets 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 container width, + * the children will be displayed out of its bounds. A negative value + * of @c align_h makes the box to *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 don't contribute to its behaviour + * when this layout is chosen. + * + * \par Child element's properties: + * @c align_x does 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/positioning 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 not pre-defined. If the container can't accommodate + * all its children, it sets the widths of the children *with weights* + * 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 children's (which have weights) widths as to fit the + * remaining space. The @c weight_x property, besides telling the + * element is resizable, gives a *weight* for the resizing process. + * The parent box will try to distribute (or take off) widths + * accordingly to the *normalized* list of weigths: most weighted + * children remain/get larger in this process than the the least ones. + * @c weight_y does not influence the layout. + * + * If one desires that, besides having weights, child elements must be + * resized bounded to a minimum or maximum size, their size hint + * properties must be set (by the + * evas_object_size_hint_{min,max}_set() functions. + */ +EAPI void evas_object_box_layout_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a (basic) vertical box. + * @a priv must be the smart data of the box. + * + * This function behaves analogously to + * evas_object_box_layout_horizontal(). The description of its + * behaviour can be derived from that function's documentation. + */ +EAPI void evas_object_box_layout_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a *homogeneous* vertical + * box. @a priv must be the smart data of the box. + * + * This function behaves analogously to + * evas_object_box_layout_homogeneous_horizontal(). The description + * of its behaviour can be derived from that function's documentation. + */ +EAPI void evas_object_box_layout_homogeneous_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a *homogeneous* + * horizontal box. @a priv must be the smart data of the box. + * + * In a homogeneous horizontal box, its width is divided equally + * between the contained objects. The box's overall behavior is + * controlled by its properties, which are set by the + * evas_object_box_{h,v}_{align,padding}_set() family of functions. + * The properties of the elements in the box -- set by + * evas_object_size_hint_{align,padding,weight}_set() 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 (still equal) child objects's cells. The @c + * align_v and @c padding_v properties of the box don't 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 (0 to extreme + * left, 1 to extreme right). A value of -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 its horizontal padding properties). The child's @c + * padding_t, @c padding_b and @c align_y properties apply for + * padding/positioning relative to the overall height of the box. A + * value of -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). + */ +EAPI void evas_object_box_layout_homogeneous_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a *max size-homogeneous* + * horizontal box. @a priv must be the smart data of the box. + * + * In a max size-homogeneous horizontal box, the equal sized cells + * reserved for the child objects have the width of the space required + * by the largest child (in width). The box's overall behavior is + * controlled by its properties, which are set by the + * evas_object_box_{h,v}_{align,padding}_set() family of functions. + * The properties of the elements in the box -- set by + * evas_object_size_hint_{align,padding,weight}_set() 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's cells. @c align_h controls the + * horizontal alignment of the child objects relative to the + * containing box. When set to 0, children are aligned to the left. A + * value of 1 lets them aligned to the right border. Values in + * between align them proportionally. A negative value of @c align_h + * makes the box to *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 don't 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 (0 to extreme + * left, 1 to extreme right). A value of -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 its horizontal padding properties). The child's @c + * padding_t, @c padding_b and @c align_y properties apply for + * padding/positioning relative to the overall height of the box. A + * value of -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). + */ +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); + +/** + * Layout function which sets the box @a o to a *max size-homogeneous* + * vertical box. @a priv must be the smart data of the box. + * + * 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. + */ +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); + +/** + * Layout function which sets the box @a o to a *flow* horizontal box. + * @a priv must be the smart data of the box. + * + * In a flow horizontal box, the box's child elements are placed in + * 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 + * evas_object_box_{h,v}_{align,padding}_set() family of functions. + * The properties of the elements in the box -- set by + * evas_object_size_hint_{align,padding,weight}_set() 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's cells. @c align_h dictates the + * horizontal alignment of the rows (0 to left align them, 1 to right + * align). A value of -1.0 to @c align_h lets the rows *justified* + * horizontally. @c align_v controls the vertical alignment of the + * entire set of rows (0 to top, 1 to bottom). A value of -1.0 to @c + * align_v makes the box to *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 *largest height* + * required by a child object in the actual row. + */ +EAPI void evas_object_box_layout_flow_horizontal (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to a *flow* vertical box. + * @a priv must be the smart data of the box. + * + * This function behaves analogously to + * evas_object_box_layout_flow_horizontal(). The description of its + * behaviour can be derived from that function's documentation. + */ +EAPI void evas_object_box_layout_flow_vertical (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Layout function which sets the box @a o to set all children to the + * size of the object. @a priv must be the smart data of the box. + * + * In a stack box, all children will be given the same size and they + * will be stacked on above the other, so the first object will be the + * bottom most. + * + * \par box's properties: + * No box option is 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 (0 to extreme + * left, 1 to extreme right). A value of -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 its horizontal padding properties). Same applies to + * vertical axis. + */ +EAPI void evas_object_box_layout_stack (Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); + +/** + * Set the alignment of the whole bounding box of contents. + */ +EAPI void evas_object_box_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); + +/** + * Get alignment of the whole bounding box of contents. + */ +EAPI void evas_object_box_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); + +/** + * Set the space (padding) between cells. + */ +EAPI void evas_object_box_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); + +/** + * Get the (space) padding between cells. + */ +EAPI void evas_object_box_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); - EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); - EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); - 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); - EAPI Evas_Object_Box_Option *evas_object_box_insert_after (Evas_Object *o, Evas_Object *child, const Evas_Object *referente) EINA_ARG_NONNULL(1, 2, 3); - EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); - EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Append a new object @a child to the box @a o. On error, @c NULL is + * returned. + */ +EAPI Evas_Object_Box_Option *evas_object_box_append (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * Prepend a new object @a child to the box @a o. On error, @c NULL is + * returned. + */ +EAPI Evas_Object_Box_Option *evas_object_box_prepend (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * Prepend a new object @a child to the box @c o relative to element @a + * reference. If @a reference is not contained in the box or any other + * error occurs, @c NULL is returned. + */ +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); + +/** + * Append a new object @a child to the box @c o relative to element @a + * reference. If @a reference is not contained in the box or any other + * error occurs, @c NULL is returend. + */ +EAPI Evas_Object_Box_Option *evas_object_box_insert_after (Evas_Object *o, Evas_Object *child, const Evas_Object *referente) EINA_ARG_NONNULL(1, 2, 3); + +/** + * Insert a new object @a child to the box @a o at position @a pos. On + * error, @c NULL is returned. + */ +EAPI Evas_Object_Box_Option *evas_object_box_insert_at (Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2); + +/** + * Remove an object @a child from the box @a o. On error, @c 0 is + * returned. + */ +EAPI Eina_Bool evas_object_box_remove (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * Remove an object from the box @a o which occupies position @a + * pos. On error, @c 0 is returned. + */ +EAPI Eina_Bool evas_object_box_remove_at (Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1); + +/** + * Remove all child objects. + * @return 0 on errors + */ +EAPI Eina_Bool evas_object_box_remove_all (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); + +/** + * Get an iterator to walk the list of children for the box. + * + * @note Do not remove or delete objects while walking the list. + */ +EAPI Eina_Iterator *evas_object_box_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Get an accessor to get random access to the list of children for the box. + * + * @note Do not remove or delete objects while walking the list. + */ +EAPI Eina_Accessor *evas_object_box_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Get the list of children for the box. + * + * @note This is a duplicate of the list kept by the box internally. + * It's up to the user to destroy it when it no longer needs it. + * It's possible to remove objects from the box when walking this + * list, but these removals won't be reflected on it. + */ +EAPI Eina_List *evas_object_box_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI const char *evas_object_box_option_property_name_get (Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI int evas_object_box_option_property_id_get (Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); - 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); - EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); - EAPI Eina_Bool evas_object_box_option_property_vget (Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2); + +/** + * Get the name of the property of the child elements of the box @a o + * whose id is @a property. On error, @c NULL is returned. + */ +EAPI const char *evas_object_box_option_property_name_get (Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Get the id of the property of the child elements of the box @a o + * whose name is @a name. On error, @c -1 is returned. + */ +EAPI int evas_object_box_option_property_id_get (Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Set the property (with id @a property) of the child element of the + * box @a o whose property struct is @a opt. The property's values + * must be the last arguments and their type *must* match that of the + * property itself. On error, @c 0 is returned. + */ +EAPI Eina_Bool evas_object_box_option_property_set (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); + +/** + * Set the property (with id @a property) of the child element of the + * box @a o whose property struct is @a opt. The property's values + * must be the args which the va_list @a args is initialized with and + * their type *must* match that of the property itself. On error, @c 0 + * is returned. + */ +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); + +/** + * Get the property (with id @a property) of the child element of the + * box @a o whose property struct is @a opt. The last arguments must + * be addresses of variables with the same type of that property. On + * error, @c 0 is returned. + */ +EAPI Eina_Bool evas_object_box_option_property_get (Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); + +/** + * Get the property (with id @a property) of the child element of the + * box @a o whose property struct is @a opt. The args which the + * va_list @a args is initialized with must be addresses of variables + * with the same type of that property. On error, @c 0 is returned. + */ +EAPI Eina_Bool evas_object_box_option_property_vget (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. @@ -2139,25 +7626,189 @@ struct _Evas_Smart_Cb_Description * * @ingroup Evas_Smart_Object_Group */ - EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Evas_Object *evas_object_table_add_to (Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1); - EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); - EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1); - EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1); + +/** + * Create a new table. + * + * It's set to non-homogeneous by default, add children with + * evas_object_table_pack(). + */ +EAPI Evas_Object *evas_object_table_add (Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Create a table that is child of a given element @a parent. + * + * @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; + +/** + * Set 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 will + * be 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 will be considered as 0.5. + * + * @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 will get WIDTH / + * COLUMNS pixels. If children have minimum size that is larger + * than this amount (including padding), then it will overflow and be + * aligned respecting the alignment hint, possible overlapping sibling + * cells. @b Weight hint is used as a boolean, if greater than zero it + * will make the child expand in that axis, taking as much space as + * possible (bounded to maximum size hint). Negative alignment will be + * considered as 0.5. + * + * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM + * When homogeneous is relative to item it means the greatest minimum + * cell size will be used. That is, if no element is set to expand, + * the table will have its contents to a minimum size, the bounding + * box of all these children will be 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 will + * keep their size and the bounding box will overflow the box area, + * still respecting the alignment. @b Weight hint is used as a + * boolean, if greater than zero it will make that cell expand in that + * axis, toggling the expand mode, which makes the table behave + * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the + * bounding box will overflow and items will not overlap siblings. If + * no minimum size is provided at all then the table will fallback to + * expand mode as well. + */ +EAPI void evas_object_table_homogeneous_set (Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1); + +/** + * Get the current layout 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) EINA_PURE; + +/** + * Set padding between cells. + */ +EAPI void evas_object_table_padding_set (Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); + +/** + * Get padding between cells. + */ +EAPI void evas_object_table_padding_get (const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); + +/** + * Set the alignment of the whole bounding box of contents. + */ +EAPI void evas_object_table_align_set (Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); + +/** + * Get alignment of the whole bounding box of contents. + */ +EAPI void evas_object_table_align_get (const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); + +/** + * Sets the mirrored mode of the table. In mirrored mode the table items go + * from right to left instead of left to right. That is, 1,1 is top right, not + * to left. + * + * @param obj The table object. + * @param mirrored the mirrored mode to set + * @since 1.1.0 + */ +EAPI void evas_object_table_mirrored_set (Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1); + +/** + * Gets the mirrored mode of the table. In mirrored mode the table items go + * from right to left instead of left to right. That is, 1,1 is top right, not + * to left. + * + * @param obj The table object. + * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise. + * @since 1.1.0 + */ - 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); - EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); - EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); +/** + * Get a child from the table using its coordinates + * + * @note This does not take into account col/row spanning + */ +EAPI Eina_Bool evas_object_table_mirrored_get (const Evas_Object *o) EINA_ARG_NONNULL(1); - EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1); - EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; - EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Add a new child to a table object. + * + * @param o The given table object. + * @param child The child object to add. + * @param col relative-horizontal position to place child. + * @param row relative-vertical position to place child. + * @param colspan how many relative-horizontal position to use for this child. + * @param rowspan how many relative-vertical position to use for this child. + * + * @return 1 on success, 0 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); + +/** + * Remove child from table. + * + * @note removing a child will immediately call a walk over children in order + * to recalculate numbers of columns and rows. If you plan to remove + * all children, use evas_object_table_clear() instead. + * + * @return 1 on success, 0 on failure. + */ +EAPI Eina_Bool evas_object_table_unpack (Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * Faster way to remove all child objects from a table object. + * + * @param o The given table object. + * @param clear if true, it will delete just removed children. + */ +EAPI void evas_object_table_clear (Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); + + +/** + * Get the number of columns and rows this table takes. + * + * @note 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 will be + * accounted proportionally. + */ +EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1); + +/** + * Get an iterator to walk the list of children for the table. + * + * @note Do not remove or delete objects while walking the list. + */ +EAPI Eina_Iterator *evas_object_table_iterator_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Get an accessor to get random access to the list of children for the table. + * + * @note Do not remove or delete objects while walking the list. + */ +EAPI Eina_Accessor *evas_object_table_accessor_new (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * Get the list of children for the table. + * + * @note This is a duplicate of the list kept by the table internally. + * It's up to the user to destroy it when it no longer needs it. + * It's possible to remove objects from the table when walking this + * list, but these removals won't be reflected on it. + */ +EAPI Eina_List *evas_object_table_children_get (const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; EAPI Evas_Object *evas_object_table_child_get (const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1); @@ -2233,13 +7884,55 @@ struct _Evas_Smart_Cb_Description int cache_item_timeout_check; }; - EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE; - EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT; - EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT; + +/** + * Retrieves if the system wants to share bitmaps using the server. + * @return @c EINA_TRUE if wants, @c EINA_FALSE otherwise. + * @ingroup Evas_Cserve + */ +EAPI Eina_Bool evas_cserve_want_get (void) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * Retrieves if the system is connected to the server used to shae bitmaps. + * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise. + * @ingroup Evas_Cserve + */ +EAPI Eina_Bool evas_cserve_connected_get (void) EINA_WARN_UNUSED_RESULT; + +/** + * Retrieves if the system wants to share bitmaps using the server. + * @param stats pointer to structure to fill with statistics about + * cache server. + * @return @c EINA_TRUE if @p stats were filled with data, + * @c EINA_FALSE otherwise and @p stats is untouched. + * @ingroup Evas_Cserve + */ +EAPI Eina_Bool evas_cserve_stats_get (Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT; EAPI void evas_cserve_image_cache_contents_clean (Evas_Cserve_Image_Cache *cache) EINA_PURE; - EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE; - EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE; - EAPI void evas_cserve_disconnect (void); + +/** + * Retrieves the current configuration of the server. + * @param config where to store current server configuration. + * @return @c EINA_TRUE if @p config were filled with data, + * @c EINA_FALSE otherwise and @p config is untouched. + * @ingroup Evas_Cserve + */ +EAPI Eina_Bool evas_cserve_config_get (Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * Changes the configuration of the server. + * @param config where to store current server configuration. + * @return @c EINA_TRUE if @p config were successfully applied, + * @c EINA_FALSE otherwise. + * @ingroup Evas_Cserve + */ +EAPI Eina_Bool evas_cserve_config_set (const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT EINA_PURE; + +/** + * Force system to disconnect from cache server. + * @ingroup Evas_Cserve + */ +EAPI void evas_cserve_disconnect (void); /** * @defgroup Evas_Utils General Utilities @@ -2247,51 +7940,439 @@ struct _Evas_Smart_Cb_Description * Some functions that are handy but are not specific of canvas or * objects. */ - EAPI const char *evas_load_error_str (Evas_Load_Error error); + +/** + * Converts the given error code into a string describing it in english. + * @param error the error code. + * @return Always return a valid string. If given @p error is not + * supported "Unknown error" is returned. + * @ingroup Evas_Utils + */ +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 */ - EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b); - EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v); + +/** + * Convert a given color from HSV to RGB format. + * + * @param h The Hue component of the color. + * @param s The Saturation component of the color. + * @param v The Value component of the color. + * @param r The Red component of the color. + * @param g The Green component of the color. + * @param b The Blue component of the color. + * + * This function converts a given color in HSV color format to RGB + * color format. + * + * @ingroup Evas_Utils + **/ +EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b); + +/** + * Convert a given color from RGB to HSV format. + * + * @param r The Red component of the color. + * @param g The Green component of the color. + * @param b The Blue component of the color. + * @param h The Hue component of the color. + * @param s The Saturation component of the color. + * @param v The Value component of the color. + * + * This function converts a given color in RGB color format to HSV + * color format. + * + * @ingroup Evas_Utils + **/ +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 */ - EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b); - EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b); + +/** + * Pre-multiplies a rgb triplet by an alpha factor. + * + * @param a The alpha factor. + * @param r The Red component of the color. + * @param g The Green component of the color. + * @param b The Blue component of the color. + * + * This function pre-multiplies a given rbg triplet by an alpha + * factor. Alpha factor is used to define transparency. + * + * @ingroup Evas_Utils + **/ +EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b); + +/** + * Undo pre-multiplication of a rgb triplet by an alpha factor. + * + * @param a The alpha factor. + * @param r The Red component of the color. + * @param g The Green component of the color. + * @param b The Blue component of the color. + * + * This function undoes pre-multiplication a given rbg triplet by an + * alpha factor. Alpha factor is used to define transparency. + * + * @see evas_color_argb_premul(). + * + * @ingroup Evas_Utils + **/ +EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b); - EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len); - EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len); + +/** + * Pre-multiplies data by an alpha factor. + * + * @param data The data value. + * @param len The length value. + * + * This function pre-multiplies a given data by an alpha + * factor. Alpha factor is used to define transparency. + * + * @ingroup Evas_Utils + **/ +EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len); + +/** + * Undo pre-multiplication data by an alpha factor. + * + * @param data The data value. + * @param len The length value. + * + * This function undoes pre-multiplication of a given data by an alpha + * factor. Alpha factor is used to define transparency. + * + * @ingroup Evas_Utils + **/ +EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len); /* string and font handling */ - EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); - EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); - EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Gets the next character in the string + * + * Given the UTF-8 string in @p str, and starting byte position in @p pos, + * this function will place in @p decoded the decoded code point at @p pos + * and return the byte index for the next character in the string. + * + * The only boundary check done is that @p pos must be >= 0. Other than that, + * no checks are performed, so passing an index value that's not within the + * length of the string will result in undefined behavior. + * + * @param str The UTF-8 string + * @param pos The byte index where to start + * @param decoded Address where to store the decoded code point. Optional. + * + * @return The byte index of the next character + * + * @ingroup Evas_Utils + */ +EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); + +/** + * Gets the previous character in the string + * + * Given the UTF-8 string in @p str, and starting byte position in @p pos, + * this function will place in @p decoded the decoded code point at @p pos + * and return the byte index for the previous character in the string. + * + * The only boundary check done is that @p pos must be >= 1. Other than that, + * no checks are performed, so passing an index value that's not within the + * length of the string will result in undefined behavior. + * + * @param str The UTF-8 string + * @param pos The byte index where to start + * @param decoded Address where to store the decoded code point. Optional. + * + * @return The byte index of the previous character + * + * @ingroup Evas_Utils + */ +EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); + +/** + * Get the length in characters of the string. + * @param str The string to get the length of. + * @return The length in characters (not bytes) + * @ingroup Evas_Utils + */ +EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * TO BE DOCUMENTED: * @todo document key modifiers. */ - EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Returns a handle to the modifiers available in the system. This is required to check + * for modifiers with the evas_key_modifier_is_set function. + * + * + * @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 + * + * @param e The pointer to the Evas Canvas + * + * @return An Evas_Modifier handle to query the modifier subsystem with + * evas_key_modifier_is_set, or NULL on error. + */ +EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * Returns a handle to the locks available in the system. This is required to check for + * locks with the evas_key_lock_is_set function. + * + * @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 + * @param e The pointer to the Evas Canvas + * + * @return An Evas_Lock handle to query the lock subsystem with + * evas_key_lock_is_set, or NULL on error. + */ +EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Checks the state of a given modifier. If the modifier is set, such as shift being pressed + * this function returns true. + * + * @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 + * + * @param m The current modifier set as returned by evas_key_modifier_get. + * @param keyname The name of the key to check its status. + * + * @return 1 if the @p keyname is on, 0 otherwise. + */ +EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Checks the state of a given lock. If the lock is set, such as caps lock, this function + * returns true. + * + * @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 + * + * @param l The current lock set as returned by evas_key_lock_get. + * @param keyname The name of the lock to add the the list. + * + * @param 1 if the @p keyname kock is set, 0 otherwise. + */ +EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Adds the @p keyname to the current list of modifiers. + * + * Modifiers can be keys like shift, alt and ctrl, as well as user defined. This allows + * custom modifiers to be added to the evas system as run time. It is then possible to set + * and unset the modifier for other parts of the program to check and act on. + * + * @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 + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the modifier to add to the list. + */ +EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Removes the @p keyname from the current list of modifiers. + * + * @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 + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the key to remove from the modifiers list. + */ +EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Adds the @p keyname to the current list of locks. + * + * Locks can be keys like caps lock, num lock or scroll lock, as well as user defined. This + * allows custom locks to be added to the evas system at run time. It is then possible to + * set and unset the lock for other parts of the program to check and act on. + * + * @see evas_key_lock_get + * @see evas_key_lock_del + * @see evas_key_lock_on + * @see evas_key_lock_off + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the key to remove from the modifier list. + */ +EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Removes The @p keyname from the current list of locks. + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_on + * @see evas_key_lock_off + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the key to remove from the lock list. + */ +EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Enables or turns on the modifier with name @p keyname. + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the modifier to set. + */ +EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Disables or turns off the modifier with name @p keyname. + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_is_set + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the modifier to un-set. + */ +EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Enables or turns on the lock with name @p keyname. + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_off + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the lock to set. + */ +EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * Disables or turns off the lock with name @p keyname. + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_on + * + * @param e The pointer to the Evas Canvas + * @param keyname The name of the lock to un-set. + */ +EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); - EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; + +/** + * Creates a bit mask from the @p keyname for use with events to check for the presence + * of the @p keyname modifier. + * + * @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 + * + * @param keyname The name of the modifier to create the mask for. + * + * @returns the bit mask or 0 if the @p keyname wasn't registered as a modifier. + */ +EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - 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); - 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); + +/** + * Requests @p keyname key events be directed to @p obj. + * + * Key grabs allow an object to receive key events for specific key + * strokes even if another object has focus. If the grab is + * non-exclusive then all objects that have grabs on the key will get + * the event, however if the grab is exclusive, no other object can + * get a grab on the key and only that object will get the event. + * + * @p keyname is a platform dependent symbolic name for the key + * pressed. It is sometimes possible to convert the string to an + * ASCII value of the key, but not always for example the enter key + * may be returned as the string 'Enter'. + * + * Typical platforms are Linux frame buffer (Ecore_FB) and X server + * (Ecore_X) when using Evas with Ecore and Ecore_Evas. + * + * For a list of keynames for the Linux frame buffer, please refer to + * the Ecore_FB documentation. + * + * @p modifiers and @p not_modifiers are bit masks of all the + * modifiers that are required and not required respectively for the + * new grab. Modifiers can be things such as shift and ctrl as well + * as user defigned types via evas_key_modifier_add. + * + * @see evas_object_key_ungrab + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_focus_get + * @see evas_key_modifier_add + * + * @param obj the object to direct @p keyname events to. + * @param keyname the key to request events for. + * @param modifiers a mask of modifiers that should be present to + * trigger the event. + * @param not_modifiers a mask of modifiers that should not be present + * to trigger the event. + * @param exclusive request that the @p obj is the only object + * receiving the @p keyname events. + * @return Boolean indicating whether the grab succeeded + */ +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); + +/** + * Request that the grab on @p obj be removed. + * + * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers + * match. + * + * @see evas_object_key_grab + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_focus_get + * + * @param obj the object that has an existing grab. + * @param keyname the key the grab is for. + * @param modifiers a mask of modifiers that should be present to + * trigger the event. + * @param not_modifiers a mask of modifiers that should not be present + * to trigger the event. + */ +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); #ifdef __cplusplus } diff --git a/legacy/evas/src/lib/Evas_GL.h b/legacy/evas/src/lib/Evas_GL.h index 0eb3720b49..687e9b15bd 100644 --- a/legacy/evas/src/lib/Evas_GL.h +++ b/legacy/evas/src/lib/Evas_GL.h @@ -7,6 +7,10 @@ extern "C" { #endif +/** + * @addtogroup Evas_GL + * @{ + */ typedef struct _Evas_GL Evas_GL; typedef struct _Evas_GL_Surface Evas_GL_Surface; typedef struct _Evas_GL_Context Evas_GL_Context; @@ -55,16 +59,82 @@ struct _Evas_GL_Config * @ingroup Evas_Canvas */ - EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI void evas_gl_free (Evas_GL *evas_gl) EINA_ARG_NONNULL(1, 2);; - EAPI Evas_GL_Surface *evas_gl_surface_create (Evas_GL *evas_gl, Evas_GL_Config *cfg, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2); - EAPI void evas_gl_surface_destroy (Evas_GL *evas_gl, Evas_GL_Surface *surf) EINA_ARG_NONNULL(1,2); - EAPI Evas_GL_Context *evas_gl_context_create (Evas_GL *evas_gl, Evas_GL_Context *share_ctx) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); - EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); - EAPI Evas_GL_Func evas_gl_proc_address_get (Evas_GL *evas_gl, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2) EINA_PURE; + +/** + * Creates a new Evas_GL object and returns a handle for gl rendering on efl. + * + * @param e The given evas. + * @return The created evas_gl object. + */ +EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Frees the created Evas_GL object. + * + * @param evas_gl The given Evas_GL object. + */ +EAPI void evas_gl_free (Evas_GL *evas_gl) EINA_ARG_NONNULL(1, 2);; + +/** + * Creates and returns new Evas_GL_Surface object for GL Rendering. + * + * @param evas_gl The given Evas_GL object. + * @param config The pixel format and configuration of the rendering surface. + * @param width The width of the surface. + * @param height The height of the surface. + * @return The created GL surface object. + */ +EAPI Evas_GL_Surface *evas_gl_surface_create (Evas_GL *evas_gl, Evas_GL_Config *cfg, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2); + +/** + * Destroys the created Evas GL Surface. + * + * @param evas_gl The given Evas_GL object. + * @param surf The given GL surface object. + */ +EAPI void evas_gl_surface_destroy (Evas_GL *evas_gl, Evas_GL_Surface *surf) EINA_ARG_NONNULL(1,2); + +/** + * Creates and returns a new Evas GL context object + * + * @param evas_gl The given Evas_GL object. + */ +EAPI Evas_GL_Context *evas_gl_context_create (Evas_GL *evas_gl, Evas_GL_Context *share_ctx) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * Destroys the given Evas GL context object + * + * @param evas_gl The given Evas_GL object. + * @param ctx The given Evas GL context. + */ +EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); + +/** + * Sets the given context as a current context for the given surface + * + * @param evas_gl The given Evas_GL object. + * @param surf The given Evas GL surface. + * @param ctx The given Evas GL context. + */ +EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); + +/** + * Returns a GL or the Glue Layer's extension function. + * + * @param evas_gl The given Evas_GL object. + * @param name The name of the function to return. + */ +EAPI Evas_GL_Func evas_gl_proc_address_get (Evas_GL *evas_gl, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2) EINA_PURE; - EAPI Eina_Bool evas_gl_native_surface_get (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) EINA_ARG_NONNULL(1,2,3); + +/** + * Fills in the Native Surface information from the given Evas GL surface. + * + * @param evas_gl The given Evas_GL object. + * @param surf The given Evas GL surface to retrieve the Native Surface info from. + * @param ns The native surface structure that the function fills in. + */ +EAPI Eina_Bool evas_gl_native_surface_get (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) EINA_ARG_NONNULL(1,2,3); // EAPI Evas_GL *evas_gl_api_get (Evas *e, Evas_GL_API *glapi) EINA_ARG_NONNULL(1, 2); @@ -73,3 +143,6 @@ struct _Evas_GL_Config #endif #endif +/** + * @} + */ diff --git a/legacy/evas/src/lib/canvas/Makefile.am b/legacy/evas/src/lib/canvas/Makefile.am index 2acbdc7620..3c7d34f6c1 100644 --- a/legacy/evas/src/lib/canvas/Makefile.am +++ b/legacy/evas/src/lib/canvas/Makefile.am @@ -46,7 +46,6 @@ evas_render.c \ evas_smart.c \ evas_stack.c \ evas_async_events.c \ -evas_transform.c \ evas_stats.c \ evas_map.c \ evas_gl.c diff --git a/legacy/evas/src/lib/canvas/evas_async_events.c b/legacy/evas/src/lib/canvas/evas_async_events.c index a88620d467..607473267b 100644 --- a/legacy/evas/src/lib/canvas/evas_async_events.c +++ b/legacy/evas/src/lib/canvas/evas_async_events.c @@ -62,29 +62,6 @@ evas_async_events_shutdown(void) #endif -/** - * @brief Get evas' internal asynchronous events read file descriptor. - * - * @return The canvas' asynchronous events read file descriptor. - * - * 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. - * - * An example of actual use of this API is for image asynchronous - * preload inside evas. If the canvas was instantiated through - * ecore-evas usage, ecore itself will take care of calling those - * events' processing. - * - * This function returns the read file descriptor where to get the - * asynchronous events of the canvas. Naturally, other mainloops, - * apart from ecore, may make use of it. - * - * @ingroup Evas_Group - */ EAPI int evas_async_events_fd_get(void) { @@ -95,19 +72,6 @@ evas_async_events_fd_get(void) #endif } -/** - * @brief Trigger the processing of all events waiting on the file - * descriptor returned by evas_async_events_fd_get(). - * - * @return The number of events processed. - * - * 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. - * - * @ingroup Evas_Group - */ EAPI int evas_async_events_process(void) { @@ -147,21 +111,6 @@ evas_async_events_process(void) #endif } -/** -* Insert asynchronous events on the canvas. - * - * @param target The target to be affected by the events. - * @param type The type of callback function. - * @param event_info Information about the event. - * @param func The callback function pointer. - * - * 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. - * - * @ingroup Evas_Group - */ EAPI Eina_Bool evas_async_events_put(const void *target, Evas_Callback_Type type, void *event_info, Evas_Async_Events_Put_Cb func) { diff --git a/legacy/evas/src/lib/canvas/evas_callbacks.c b/legacy/evas/src/lib/canvas/evas_callbacks.c index b45f0513ab..ffd62c2c9f 100644 --- a/legacy/evas/src/lib/canvas/evas_callbacks.c +++ b/legacy/evas/src/lib/canvas/evas_callbacks.c @@ -255,183 +255,7 @@ evas_object_event_callback_call(Evas_Object *obj, Evas_Callback_Type type, void } -/** - * @addtogroup Evas_Object_Group_Events - * @{ - */ -/** - * Add a callback function to an object - * - * @param obj Object to attach a callback to - * @param type The type of event that will trigger the callback - * @param func The function to be called when the event is triggered - * @param data The data pointer to be passed to @p func - * - * This function adds a function callback to an object when the event - * of type @p type occurs on object @p obj. The function is @p func. - * - * 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. - * - * The function will be passed the pointer @p data when it is - * called. A callback function must look like this: - * - * @code - * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info); - * @endcode - * - * The first parameter @p data in this function will be the same value - * passed to evas_object_event_callback_add() as the @p data - * parameter. The second parameter is a convenience for the programmer - * to know what evas canvas the event occurred on. The third parameter - * @p obj is the Object handle on which the event occurred. The foruth - * parameter @p 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. - * - * The event type @p type to trigger the function may be one of - * #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_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 or #EVAS_CALLBACK_RESTACK. - * This determines the kind of event that will trigger the callback to - * be called. The @p event_info pointer passed to the callback will - * be one of the following, depending on the event triggering it: - * - * #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In - * - * This event is triggered when the mouse pointer enters the region of - * the object @p obj. This may occur by the mouse pointer being moved - * by evas_event_feed_mouse_move() or - * evas_event_feed_mouse_move_data() calls, or by the object being - * shown, raised, moved, resized, or other objects being moved out of - * the way, hidden, lowered or moved out of the way. - * - * #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out - * - * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but - * occurs when the mouse pointer exits an object. Note that no out - * events will be reported if the mouse pointer is implicitly grabbed - * to an object (the mouse buttons are down at all and any were - * pressed on that object). An out event will be reported as soon as - * the mouse is no longer grabbed (no mouse buttons are - * depressed). Out events will be reported once all buttons are - * released, if the mouse has left the object. - * - * #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to - * Evas_Event_Mouse_Down - * - * This event is triggered by a mouse button being depressed while - * over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB - * (default) this causes this object to passively grab the mouse until - * all mouse buttons have been released. That means if this mouse - * button is the first to be pressed, all future mouse events will be - * reported to only this object until no buttons are down. That - * includes mouse move events, in and out events, and further button - * presses. When all buttons are released, event propagation occurs as - * normal. - * - * #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up - * - * This event is triggered by a mouse button being released while over - * an object or when passively grabbed to an object. If this is the - * last mouse button to be raised on an object then the passive grab - * is released and event processing will continue as normal. - * - * #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move - * - * This event is triggered by the mouse pointer moving while over an - * object or passively grabbed to an object. - * - * #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to - * Evas_Event_Mouse_Wheel - * - * This event is triggered by the mouse wheel being rolled while over - * an object or passively grabbed to an object. - * - * #EVAS_CALLBACK_FREE: event_info = NULL - * - * 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 this callback - * returns, there is no guarantee on the object's validity. - * - * #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down - * - * 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: event_info = pointer to Evas_Event_Key_Up - * - * 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: event_info = NULL - * - * This event is called when an object gains the focus. When the - * callback is called the object has already gained the focus. - * - * #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL - * - * This event is triggered by an object losing the focus. When the - * callback is called the object has already lost the focus. - * - * #EVAS_CALLBACK_SHOW: event_info = NULL - * - * This event is triggered by the object being shown by - * evas_object_show(). - * - * #EVAS_CALLBACK_HIDE: event_info = NULL - * - * This event is triggered by an object being hidden by - * evas_object_hide(). - * - * #EVAS_CALLBACK_MOVE: event_info = NULL - * - * 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: event_info = NULL - * - * 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. - * - * Example: - * @code - * extern Evas_Object *object; - * extern void *my_data; - * void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); - * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); - * - * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * @endcode - */ EAPI void evas_object_event_callback_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) { @@ -464,30 +288,6 @@ evas_object_event_callback_add(Evas_Object *obj, Evas_Callback_Type type, Evas_O eina_inlist_prepend(obj->callbacks->callbacks, EINA_INLIST_GET(fn)); } -/** - * Delete a callback function from an object - * - * @param obj Object to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * object @p obj which was triggered by the event type @p type and was - * calling the function @p func when triggered. If the removal is - * successful it will also return the data pointer that was passed to - * evas_object_event_callback_add() when the callback was added to the - * object. If not successful NULL will be returned. - * - * 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 - */ EAPI void * evas_object_event_callback_del(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) { @@ -519,32 +319,6 @@ evas_object_event_callback_del(Evas_Object *obj, Evas_Callback_Type type, Evas_O return NULL; } -/** - * Delete a callback function from an object - * - * @param obj Object to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @param data The data pointer that was to be passed to the callback - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * object @p obj which was triggered by the event type @p type and was - * calling the function @p func with data @p data when triggered. If - * the removal is successful it will also return the data pointer that - * was passed to evas_object_event_callback_add() (that will be the - * same as the parameter) when the callback was added to the - * object. If not successful NULL will be returned. - * - * 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 - */ EAPI void * evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) { @@ -576,73 +350,8 @@ evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, E return NULL; } -/** - * @} - */ -/** - * @addtogroup Evas_Canvas_Events - * @{ - */ -/** - * Add a callback function to the canvas. - * - * @param e Canvas to attach a callback to - * @param type The type of event that will trigger the callback - * @param func The function to be called when the event is triggered - * @param data The data pointer to be passed to @p func - * - * This function adds a function callback to the canvas when the event - * of type @p type occurs on canvas @p e. The function is @p func. - * - * In the event of a memory allocation error during 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. - * - * The function will be passed the pointer @p data when it is - * called. A callback function must look like this: - * - * @code - * void callback (void *data, Evas *e, void *event_info); - * @endcode - * - * The first parameter @p data in this function will be the same value - * passed to evas_event_callback_add() as the @p data parameter. The - * second parameter @p e is the canvas handle on which the event - * occurred. The third parameter @p 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. - * - * The event type @p type to trigger the function may be one of - * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST, - * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT. - * This determines the kind of event that will trigger the callback to - * be called. So far none of the event types provide useful data, so - * in all of them @p event_info pointer is @c NULL. - * - * Example: - * @code - * extern Evas *e; - * extern void *my_data; - * void focus_in_callback(void *data, Evas *e, void *event_info); - * void focus_out_callback(void *data, Evas *e, void *event_info); - * - * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, focus_out_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * @endcode - */ EAPI void evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) { @@ -675,30 +384,6 @@ evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, co eina_inlist_prepend(e->callbacks->callbacks, EINA_INLIST_GET(fn)); } -/** - * Delete a callback function from the canvas. - * - * @param e Canvas to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * canvas @p e which was triggered by the event type @p type and was - * calling the function @p func when triggered. If the removal is - * successful it will also return the data pointer that was passed to - * evas_event_callback_add() when the callback was added to the - * canvas. If not successful NULL will be returned. - * - * 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 - */ EAPI void * evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) { @@ -730,32 +415,6 @@ evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) return NULL; } -/** - * Delete a callback function from the canvas. - * - * @param e Canvas to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @param data The data pointer that was to be passed to the callback - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * canvas @p e which was triggered by the event type @p type and was - * calling the function @p func with data @p data when triggered. If - * the removal is successful it will also return the data pointer that - * was passed to evas_event_callback_add() (that will be the same as - * the parameter) when the callback was added to the canvas. If not - * successful NULL will be returned. - * - * 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_full(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); - * @endcode - */ EAPI void * evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) { @@ -787,29 +446,6 @@ evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb fun return NULL; } -/** - * Push a callback on the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * @param data The data pointer to be passed to the callback - * - * 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 al the callbacks - * in each object triggered). When all these have been called, the stack is - * unwond from most recently to least recently pushed item and removed from the - * stack calling the callback set for it. - * - * This is intended for doing reverse logic-like processing, example - when a - * child object that happens to get the event later is meant to be able to - * "steal" functions from a parent and thus on unwind of this stack hav its - * function called first, thus being able to set flags, or return 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). - * - */ EAPI void evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const void *data) { @@ -830,17 +466,6 @@ evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const voi e->post_events = eina_list_prepend(e->post_events, pc); } -/** - * Remove a callback from the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * - * 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. - */ EAPI void evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func) { @@ -861,18 +486,6 @@ evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func) } } -/** - * Remove a callback from the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * @param data The data pointer to be passed to the callback - * - * 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. - */ EAPI void evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, const void *data) { @@ -892,6 +505,3 @@ evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, co } } } -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_clip.c b/legacy/evas/src/lib/canvas/evas_clip.c index d556cb1113..9416b92183 100644 --- a/legacy/evas/src/lib/canvas/evas_clip.c +++ b/legacy/evas/src/lib/canvas/evas_clip.c @@ -160,58 +160,7 @@ evas_object_mapped_clip_across_mark(Evas_Object *obj) /* public functions */ -/** - * @addtogroup Evas_Object_Group_Basic - * @{ - */ -/** - * Clip one object to another. - * @param obj The object to be clipped - * @param clip The object to clip @p obj by - * - * This function will clip the object @p obj to the area occupied by the - * object @p clipper. This means the object @p obj will only be visible within - * the area occupied by the clipping object (@p clip). The color of the object - * being clipped will be multiplied by the color of the clipping object, so - * the resulting color for the clipped object is - * RESULT = (OBJ * CLIP) / (255 * 255) per color element (red, green, blue and - * alpha). Clipping is recursive, so clip objects may be clipped by other - * objects, and their color will in tern be multiplied. You may 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. Objects which do not clip - * others are visible as normal, those that clip 1 or more objects become - * invisible themselves, only affecting what they clip. If an object ceases to - * have other objects being clipped by it, it will become visible again. The - * visibility of an object affects the objects that are clipped by it, so if - * the object clipping others is not shown, the objects clipped will not be - * shown either. If the object was being clipped by another object when this - * function is called, it is implicitly removed from the clipper it is being - * clipped to, and now is made to clip its new clipper. - * - * At the moment the only objects that can validly be used to clip other - * objects are rectangle objects. All other object types are invalid and the - * result of using them is undefined. - * - * The clip object @p clip must be a valid object, but may also be NULL in - * which case the effect of this function is the same as calling - * evas_object_clip_unset() on the @p obj object. - * - * Example: - * @code - * extern Evas *evas; - * extern Evas_Object *obj; - * Evas_Object *clipper; - * - * clipper = evas_object_rectangle_add(evas); - * evas_object_color_set(clipper, 255, 255, 255, 255); - * evas_object_move(clipper, 10, 10); - * evas_object_resize(clipper, 20, 50); - * evas_object_clip_set(obj, clipper); - * evas_object_show(clipper); - * @endcode - * - */ EAPI void evas_object_clip_set(Evas_Object *obj, Evas_Object *clip) { @@ -299,26 +248,6 @@ evas_object_clip_set(Evas_Object *obj, Evas_Object *clip) evas_object_clip_across_check(obj); } -/** - * Get the object clipping this one (if any). - * @param obj The object to get the clipper from - * - * This function returns the the object clipping @p obj. If @p obj not being - * clipped, NULL is returned. The object @p obj must be a valid object. - * - * See also evas_object_clip_set(), evas_object_clip_unset() and - * evas_object_clipees_get(). - * - * Example: - * @code - * extern Evas_Object *obj; - * Evas_Object *clipper; - * - * clipper = evas_object_clip_get(obj); - * if (clipper) evas_object_show(clipper); - * @endcode - * - */ EAPI Evas_Object * evas_object_clip_get(const Evas_Object *obj) { @@ -328,32 +257,6 @@ evas_object_clip_get(const Evas_Object *obj) return obj->cur.clipper; } -/** - * Disable clipping for an object. - * - * @param obj The object to cease clipping on - * - * This function disables clipping for the object @p obj, if it was already - * clipped. If it wasn't, this has no effect. The object @p obj must be a - * valid object. - * - * See also evas_object_clip_set(), evas_object_clipees_get() and - * evas_object_clip_get(). - * - * Example: - * @code - * extern Evas_Object *obj; - * Evas_Object *clipper; - * - * clipper = evas_object_clip_get(obj); - * if (clipper) - * { - * evas_object_clip_unset(obj); - * evas_object_hide(obj); - * } - * @endcode - * - */ EAPI void evas_object_clip_unset(Evas_Object *obj) { @@ -402,43 +305,6 @@ evas_object_clip_unset(Evas_Object *obj) evas_object_clip_across_check(obj); } -/** - * Return a list of objects currently clipped by a specific object. - * - * @param obj The object to get a list of clippees from - * - * This returns the inernal list handle that contains all objects clipped by - * the object @p obj. If none are clipped, it returns 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, are deleted or the clipper is - * deleted. These operations will 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, not limited just to strange behavior but possible - * segfaults and other strange memory errors. The object @p obj must be a valid - * object. - * - * See also evas_object_clip_set(), evas_object_clip_unset() and - * evas_object_clip_get(). - * - * 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 - */ EAPI const Eina_List * evas_object_clipees_get(const Evas_Object *obj) { @@ -447,7 +313,3 @@ evas_object_clipees_get(const Evas_Object *obj) MAGIC_CHECK_END(); return obj->clip.clipees; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_data.c b/legacy/evas/src/lib/canvas/evas_data.c index 4aaf475bec..3ac9d63577 100644 --- a/legacy/evas/src/lib/canvas/evas_data.c +++ b/legacy/evas/src/lib/canvas/evas_data.c @@ -1,42 +1,7 @@ #include "evas_common.h" #include "evas_private.h" -/** - * @addtogroup Evas_Object_Group_Extras - * @{ - */ -/** - * Set an attached data pointer to an object with a given string key. - * @param obj The object to attach the data pointer to - * @param key The string key for the data to access it - * @param data The ponter to the data to be attached - * - * This attaches the pointer @p data to the object @p obj given the string - * @p key. This pointer will stay "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 @p obj, the - * pointers will not be accessible from the object anymore. - * - * 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 @p data when it is no longer required. - * - * If @p data is NULL, the old value stored at @p key will be removed but no - * new value will be stored. This is synonymous with calling - * evas_object_data_del() with @p obj and @p key. - * - * 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 was attached was %p\n", evas_object_data_get(obj, "name_of_data")); - * @endcode - */ EAPI void evas_object_data_set(Evas_Object *obj, const char *key, const void *data) { @@ -56,32 +21,6 @@ evas_object_data_set(Evas_Object *obj, const char *key, const void *data) obj->data.elements = eina_list_prepend(obj->data.elements, node); } -/** - * Return an attached data pointer by its given string key. - * @param obj The object to which the data was attached - * @param key The string key the data was stored under - * @return The data pointer stored, or NULL if none was stored - * - * This function will return the data pointer attached to the object @p obj - * stored using the string key @p key. If the object is valid and data was - * stored under the given key, the pointer that was stored will be reuturned. - * If this is not the case, NULL will be returned, signifying an invalid object - * or non-existent key. It is possible a NULL pointer was stored given that - * key, but this situation is non-sensical and thus can be considered an error - * as well. NULL pointers are never stored as this is the return value if an - * error occurs. - * - * 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 was %p\n", my_data); - * else printf("No data was stored on the object\n"); - * @endcode - */ EAPI void * evas_object_data_get(const Evas_Object *obj, const char *key) { @@ -107,25 +46,6 @@ evas_object_data_get(const Evas_Object *obj, const char *key) return NULL; } -/** - * Delete at attached data pointer from an object. - * @param obj The object to delete the data pointer from - * @param key The string key the data was stored under - * @return The original data pointer stored at @p key on @p obj - * - * This will remove thee stored data pointer from @p obj stored under @p key, - * and return the original pointer stored under @p key, if any, nor NULL if - * nothing was stored under that key. - * - * Example: - * - * @code - * int *my_data; - * extern Evas_Object *obj; - * - * my_data = evas_object_data_del(obj, "name_of_my_data"); - * @endcode - */ EAPI void * evas_object_data_del(Evas_Object *obj, const char *key) { @@ -150,7 +70,3 @@ evas_object_data_del(Evas_Object *obj, const char *key) } return NULL; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_events.c b/legacy/evas/src/lib/canvas/evas_events.c index 92512a4f24..c4bc3f700e 100644 --- a/legacy/evas/src/lib/canvas/evas_events.c +++ b/legacy/evas/src/lib/canvas/evas_events.c @@ -146,31 +146,6 @@ evas_event_list_copy(Eina_List *list) } /* public functions */ -/** - * @addtogroup Evas_Event_Freezing_Group - * @{ - */ - -/** - * Freeze all event processing. - * @param e The canvas to freeze event processing on. - * - * This function will indicate to evas that the canvas @p e is to have - * all event processing frozen until a matching evas_event_thaw() - * function is called on the same canvas. Every freeze call must be - * matched by a thaw call in order to completely thaw out a canvas. - * - * Example: - * @code - * extern Evas *evas; - * extern Evas_Object *object; - * - * evas_event_freeze(evas); - * evas_object_move(object, 50, 100); - * evas_object_resize(object, 200, 200); - * evas_event_thaw(evas); - * @endcode - */ EAPI void evas_event_freeze(Evas *e) { @@ -180,18 +155,6 @@ evas_event_freeze(Evas *e) e->events_frozen++; } -/** - * Thaw a canvas out after freezing. - * - * @param e The canvas to thaw out. - * - * This will thaw out a canvas after a matching evas_event_freeze() - * call. If this call completely thaws out a canvas, events will start - * being processed again after this call, but this call will not - * invole any "missed" events to be evaluated. - * - * See evas_event_freeze() for an example. - */ EAPI void evas_event_thaw(Evas *e) { @@ -218,34 +181,6 @@ evas_event_thaw(Evas *e) evas_debug_generic(" Thaw of events when already thawed!!!\n"); } -/** - * @} - */ - -/** - * @addtogroup Evas_Event_Feeding_Group - * @{ - */ - -/** - * Return the freeze count of a given canvas. - * @param e The canvas to fetch the freeze count from. - * - * This returns the number of times the canvas has been told to freeze - * 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. - * - * Example: - * @code - * extern Evas *evas; - * - * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas); - * @endcode - * - */ EAPI int evas_event_freeze_get(const Evas *e) { @@ -256,20 +191,6 @@ evas_event_freeze_get(const Evas *e) } -/** - * Mouse down event feed. - * - * @param e The given canvas pointer. - * @param b The button number. - * @param flags The evas button flags. - * @param timestamp The timestamp of the mouse down event. - * @param data The data for canvas. - * - * This function will set some evas properties that is necessary when - * the mouse button is pressed. It prepares information to be treated - * by the callback function. - * - */ EAPI void evas_event_feed_mouse_down(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) { @@ -333,20 +254,6 @@ evas_event_feed_mouse_down(Evas *e, int b, Evas_Button_Flags flags, unsigned int _evas_unwalk(e); } -/** - * Mouse up event feed. - * - * @param e The given canvas pointer. - * @param b The button number. - * @param flags evas button flags. - * @param timestamp The timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will set some evas properties that is necessary when - * the mouse button is released. It prepares information to be treated - * by the callback function. - * - */ EAPI void evas_event_feed_mouse_up(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) { @@ -513,18 +420,6 @@ evas_event_feed_mouse_up(Evas *e, int b, Evas_Button_Flags flags, unsigned int t _evas_unwalk(e); } - -/** - * Mouse cancel event feed. - * - * @param e The given canvas pointer. - * @param timestamp The timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will call evas_event_feed_mouse_up() when a - * mouse cancel event happens. - * - */ EAPI void evas_event_feed_mouse_cancel(Evas *e, unsigned int timestamp, const void *data) { @@ -545,20 +440,6 @@ evas_event_feed_mouse_cancel(Evas *e, unsigned int timestamp, const void *data) _evas_unwalk(e); } -/** - * Mouse wheel event feed. - * - * @param e The given canvas pointer. - * @param direction The wheel mouse direction. - * @param z How much mouse wheel was scrolled up or down. - * @param timestamp The timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will set 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. - * - */ EAPI void evas_event_feed_mouse_wheel(Evas *e, int direction, int z, unsigned int timestamp, const void *data) { @@ -605,20 +486,6 @@ evas_event_feed_mouse_wheel(Evas *e, int direction, int z, unsigned int timestam _evas_unwalk(e); } -/** - * Mouse move event feed. - * - * @param e The given canvas pointer. - * @param x The horizontal position of the mouse pointer. - * @param y The vertical position of the mouse pointer. - * @param timestamp The timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will set 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. - * - */ EAPI void evas_event_feed_mouse_move(Evas *e, int x, int y, unsigned int timestamp, const void *data) { @@ -861,18 +728,6 @@ evas_event_feed_mouse_move(Evas *e, int x, int y, unsigned int timestamp, const _evas_unwalk(e); } -/** - * Mouse in event feed. - * - * @param e The given canvas pointer. - * @param timestamp The timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will set some evas properties that is necessary when - * the mouse in event happens. It prepares information to be treated - * by the callback function. - * - */ EAPI void evas_event_feed_mouse_in(Evas *e, unsigned int timestamp, const void *data) { @@ -932,18 +787,6 @@ evas_event_feed_mouse_in(Evas *e, unsigned int timestamp, const void *data) _evas_unwalk(e); } -/** - * Mouse out event feed. - * - * @param e The given canvas pointer. - * @param timestamp Timestamp of the mouse up event. - * @param data The data for canvas. - * - * This function will set some evas properties that is necessary when - * the mouse out event happens. It prepares information to be treated - * by the callback function. - * - */ EAPI void evas_event_feed_mouse_out(Evas *e, unsigned int timestamp, const void *data) { @@ -1269,22 +1112,6 @@ evas_event_feed_multi_move(Evas *e, _evas_unwalk(e); } -/** - * Key down event feed - * - * @param e The canvas to thaw out - * @param keyname Name of the key - * @param key The key pressed. - * @param string A String - * @param compose The compose string - * @param timestamp Timestamp of the mouse up event - * @param data Data for canvas. - * - * This function will set some evas properties that is necessary when - * a key is pressed. It prepares information to be treated by the - * callback function. - * - */ 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) { @@ -1364,22 +1191,6 @@ evas_event_feed_key_down(Evas *e, const char *keyname, const char *key, const ch _evas_unwalk(e); } -/** - * Key up event feed - * - * @param e The canvas to thaw out - * @param keyname Name of the key - * @param key The key released. - * @param string string - * @param compose compose - * @param timestamp Timestamp of the mouse up event - * @param data Data for canvas. - * - * This function will set some evas properties that is necessary when - * a key is released. It prepares information to be treated by the - * callback function. - * - */ 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) { @@ -1459,17 +1270,6 @@ evas_event_feed_key_up(Evas *e, const char *keyname, const char *key, const char _evas_unwalk(e); } -/** - * Hold event feed - * - * @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. - * - * This function makes the object to stop sending events. - * - */ EAPI void evas_event_feed_hold(Evas *e, int hold, unsigned int timestamp, const void *data) { @@ -1505,26 +1305,6 @@ evas_event_feed_hold(Evas *e, int hold, unsigned int timestamp, const void *data _evas_object_event_new(); } -/** - * @} - */ - -/** - * @addtogroup Evas_Object_Group_Events - * @{ - */ - -/** - * Set an object's pass events state. - * @param obj the evas object - * @param pass whether to pass events or not - * - * If @p pass is true, this will cause events on @p obj to be ignored. - * They will be triggered on the next lower object (that is not set to - * pass events) instead. - * - * If @p pass is false, events will be processed as normal. - */ EAPI void evas_object_pass_events_set(Evas_Object *obj, Eina_Bool pass) { @@ -1549,11 +1329,6 @@ evas_object_pass_events_set(Evas_Object *obj, Eina_Bool pass) NULL); } -/** - * Determine whether an object is set to pass events. - * @param obj - * @return pass events state - */ EAPI Eina_Bool evas_object_pass_events_get(const Evas_Object *obj) { @@ -1563,18 +1338,6 @@ evas_object_pass_events_get(const Evas_Object *obj) return obj->pass_events; } -/** - * Set an object's repeat events state. - * @param obj the object - * @param repeat wheter to repeat events or not - * - * If @p repeat is true, this will cause events on @p obj to trigger - * callbacks, but also to be repeated on the next lower object in the - * stack. - * - * If @p repeat is false, events occurring on @p obj will be processed - * normally. - */ EAPI void evas_object_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) { @@ -1598,11 +1361,6 @@ evas_object_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) NULL); } -/** - * Determine whether an object is set to repeat events. - * @param obj - * @return repeat events state - */ EAPI Eina_Bool evas_object_repeat_events_get(const Evas_Object *obj) { @@ -1612,24 +1370,6 @@ evas_object_repeat_events_get(const Evas_Object *obj) return obj->repeat_events; } -/** - * Set whether events on a smart member object should propagate to its - * parent. - * - * @param obj the smart member object - * @param prop wheter to propagate events or not - * - * This function has no effect if @p obj is not a member of a smart - * object. - * - * If @p prop is true, events occurring on this object will propagate on - * to the smart object of which @p obj is a member. - * - * If @p prop is false, events for which callbacks are set on the member - * object, @p obj, will not be passed on to the parent smart object. - * - * The default value is true. - */ EAPI void evas_object_propagate_events_set(Evas_Object *obj, Eina_Bool prop) { @@ -1639,11 +1379,6 @@ evas_object_propagate_events_set(Evas_Object *obj, Eina_Bool prop) obj->no_propagate = !prop; } -/** - * Determine whether an object is set to propagate events. - * @param obj - * @return propagate events state - */ EAPI Eina_Bool evas_object_propagate_events_get(const Evas_Object *obj) { @@ -1653,31 +1388,6 @@ evas_object_propagate_events_get(const Evas_Object *obj) return !(obj->no_propagate); } -/** - * @} - */ - -/** - * Set pointer behavior. - * - * @param obj - * @param setting desired behavior. - * - * This function has direct effect on event callbacks related to - * mouse. - * - * If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse - * is down at this object, events will be restricted to it as source, - * mouse moves, for example, will be emitted even if outside this - * object area. - * - * If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will - * be emitted just when inside this object area. - * - * The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB. - * - * @ingroup Evas_Object_Group_Extras - */ EAPI void evas_object_pointer_mode_set(Evas_Object *obj, Evas_Object_Pointer_Mode setting) { @@ -1687,12 +1397,6 @@ evas_object_pointer_mode_set(Evas_Object *obj, Evas_Object_Pointer_Mode setting) obj->pointer_mode = setting; } -/** - * Determine how pointer will behave. - * @param obj - * @return pointer behavior. - * @ingroup Evas_Object_Group_Extras - */ EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get(const Evas_Object *obj) { diff --git a/legacy/evas/src/lib/canvas/evas_focus.c b/legacy/evas/src/lib/canvas/evas_focus.c index 5ace30d260..a1a3bcae4e 100644 --- a/legacy/evas/src/lib/canvas/evas_focus.c +++ b/legacy/evas/src/lib/canvas/evas_focus.c @@ -7,27 +7,6 @@ /* public calls */ -/** - * @addtogroup Evas_Object_Group_Basic - * @{ - */ -/** - * Sets focus to the given object. - * - * @param obj The object to be focused or unfocused. - * @param focus set or remove focus to the object. - * - * Changing focus only affects where key events go. There can be only - * one object focused at any time.

If the parameter (@p focus) is - * set, the passed object will be set as the currently focused object. - * It will receive all keyboard events that are not exclusive key - * grabs on other objects. - * - * @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) { @@ -61,21 +40,6 @@ evas_object_focus_set(Evas_Object *obj, Eina_Bool focus) _evas_post_event_callback_call(obj->layer->evas); } -/** - * Test if the object has focus. - * - * @param obj The object to be tested. - * - * If the passed object is the currently focused object 1 is returned, - * 0 otherwise. - * - * @see evas_object_focus_set - * @see evas_focus_get - * @see evas_object_key_grab - * @see evas_object_key_ungrab - * - * @return 1 if the object has the focus, 0 otherwise. - */ EAPI Eina_Bool evas_object_focus_get(const Evas_Object *obj) { @@ -85,26 +49,6 @@ evas_object_focus_get(const Evas_Object *obj) return obj->focused; } -/** - * @} - */ - -/** - * Retrieve the object that currently has focus. - * - * @param e The @c Evas canvas to query focus on. - * - * Returns the object that currently has focus, NULL otherwise. - * - * @see evas_object_focus_set - * @see evas_object_focus_get - * @see evas_object_key_grab - * @see evas_object_key_ungrab - * - * @return The object that has focus or NULL is there is not one. - * - * @ingroup Evas_Object_Group_Find - */ EAPI Evas_Object * evas_focus_get(const Evas *e) { diff --git a/legacy/evas/src/lib/canvas/evas_gl.c b/legacy/evas/src/lib/canvas/evas_gl.c index 4fb90914ab..f88b8c18e2 100644 --- a/legacy/evas/src/lib/canvas/evas_gl.c +++ b/legacy/evas/src/lib/canvas/evas_gl.c @@ -1,3 +1,4 @@ +/* vim:set ts=8 sw=3 sts=3 expandtab cino=>5n-2f0^-2{2(0W1st0 :*/ #include "evas_common.h" #include "evas_private.h" #include "Evas_GL.h" @@ -21,18 +22,6 @@ struct _Evas_GL_Surface void *data; }; - -/** - * @addtogroup Evas_GL - * @{ - */ - -/** - * Creates a new Evas_GL object and returns a handle for gl rendering on efl. - * - * @param e The given evas. - * @return The created evas_gl object. - */ EAPI Evas_GL * evas_gl_new(Evas *e) { @@ -51,11 +40,6 @@ evas_gl_new(Evas *e) return evas_gl; } -/** - * Frees the created Evas_GL object. - * - * @param evas_gl The given Evas_GL object. - */ EAPI void evas_gl_free(Evas_GL *evas_gl) { @@ -76,15 +60,6 @@ evas_gl_free(Evas_GL *evas_gl) evas_gl = NULL; } -/** - * Creates and returns new Evas_GL_Surface object for GL Rendering. - * - * @param evas_gl The given Evas_GL object. - * @param config The pixel format and configuration of the rendering surface. - * @param width The width of the surface. - * @param height The height of the surface. - * @return The created GL surface object. - */ EAPI Evas_GL_Surface * evas_gl_surface_create(Evas_GL *evas_gl, Evas_GL_Config *config, int width, int height) { @@ -111,12 +86,6 @@ evas_gl_surface_create(Evas_GL *evas_gl, Evas_GL_Config *config, int width, int return surf; } -/** - * Destroys the created Evas GL Surface. - * - * @param evas_gl The given Evas_GL object. - * @param surf The given GL surface object. - */ EAPI void evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf) { @@ -142,11 +111,6 @@ evas_gl_surface_destroy(Evas_GL *evas_gl, Evas_GL_Surface *surf) surf = NULL; } -/** - * Creates and returns a new Evas GL context object - * - * @param evas_gl The given Evas_GL object. - */ EAPI Evas_GL_Context * evas_gl_context_create(Evas_GL *evas_gl, Evas_GL_Context *share_ctx) { @@ -190,12 +154,6 @@ evas_gl_context_create(Evas_GL *evas_gl, Evas_GL_Context *share_ctx) } -/** - * Destroys the given Evas GL context object - * - * @param evas_gl The given Evas_GL object. - * @param ctx The given Evas GL context. - */ EAPI void evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx) { @@ -221,13 +179,6 @@ evas_gl_context_destroy(Evas_GL *evas_gl, Evas_GL_Context *ctx) ctx = NULL; } -/** - * Sets the given context as a current context for the given surface - * - * @param evas_gl The given Evas_GL object. - * @param surf The given Evas GL surface. - * @param ctx The given Evas GL context. - */ EAPI Eina_Bool evas_gl_make_current(Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) { @@ -245,12 +196,6 @@ evas_gl_make_current(Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *c return ret; } -/** - * Returns a GL or the Glue Layer's extension function. - * - * @param evas_gl The given Evas_GL object. - * @param name The name of the function to return. - */ EAPI Evas_GL_Func evas_gl_proc_address_get(Evas_GL *evas_gl, const char *name) { @@ -261,27 +206,12 @@ evas_gl_proc_address_get(Evas_GL *evas_gl, const char *name) return (Evas_GL_Func)evas_gl->evas->engine.func->gl_proc_address_get(evas_gl->evas->engine.data.output, name); } -/** - * Fills in the Native Surface information from the given Evas GL surface. - * - * @param evas_gl The given Evas_GL object. - * @param surf The given Evas GL surface to retrieve the Native Surface info from. - * @param ns The native surface structure that the function fills in. - */ EAPI Eina_Bool -evas_gl_native_surface_get (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) +evas_gl_native_surface_get(Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_Native_Surface *ns) { - MAGIC_CHECK(evas_gl, Evas_GL, MAGIC_EVAS_GL); return EINA_FALSE; MAGIC_CHECK_END(); return (Eina_Bool)evas_gl->evas->engine.func->gl_native_surface_get(evas_gl->evas->engine.data.output, surf->data, ns); } - -/** - * @} - */ - - -/* vim:set ts=8 sw=3 sts=3 expandtab cino=>5n-2f0^-2{2(0W1st0 :*/ diff --git a/legacy/evas/src/lib/canvas/evas_key.c b/legacy/evas/src/lib/canvas/evas_key.c index 77239606db..f74ef3498f 100644 --- a/legacy/evas/src/lib/canvas/evas_key.c +++ b/legacy/evas/src/lib/canvas/evas_key.c @@ -31,22 +31,6 @@ evas_key_lock_number(const Evas_Lock *l, const char *keyname) /* public calls */ -/** - * Returns a handle to the modifiers available in the system. This is required to check - * for modifiers with the evas_key_modifier_is_set function. - * - * - * @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 - * - * @param e The pointer to the Evas Canvas - * - * @return An Evas_Modifier handle to query the modifier subsystem with - * evas_key_modifier_is_set, or NULL on error. - */ EAPI const Evas_Modifier * evas_key_modifier_get(const Evas *e) { @@ -56,21 +40,6 @@ evas_key_modifier_get(const Evas *e) return &(e->modifiers); } -/** - * Returns a handle to the locks available in the system. This is required to check for - * locks with the evas_key_lock_is_set function. - * - * @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 - * @param e The pointer to the Evas Canvas - * - * @return An Evas_Lock handle to query the lock subsystem with - * evas_key_lock_is_set, or NULL on error. - */ EAPI const Evas_Lock * evas_key_lock_get(const Evas *e) { @@ -80,21 +49,6 @@ evas_key_lock_get(const Evas *e) return &(e->locks); } -/** - * Checks the state of a given modifier. If the modifier is set, such as shift being pressed - * this function returns true. - * - * @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 - * - * @param m The current modifier set as returned by evas_key_modifier_get. - * @param keyname The name of the key to check its status. - * - * @return 1 if the @p keyname is on, 0 otherwise. - */ EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) { @@ -111,21 +65,6 @@ evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) return 0; } -/** - * Checks the state of a given lock. If the lock is set, such as caps lock, this function - * returns true. - * - * @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 - * - * @param l The current lock set as returned by evas_key_lock_get. - * @param keyname The name of the lock to add the the list. - * - * @param 1 if the @p keyname kock is set, 0 otherwise. - */ EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) { @@ -142,22 +81,6 @@ evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) return 0; } -/** - * Adds the @p keyname to the current list of modifiers. - * - * Modifiers can be keys like shift, alt and ctrl, as well as user defined. This allows - * custom modifiers to be added to the evas system as run time. It is then possible to set - * and unset the modifier for other parts of the program to check and act on. - * - * @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 - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the modifier to add to the list. - */ EAPI void evas_key_modifier_add(Evas *e, const char *keyname) { @@ -173,18 +96,6 @@ evas_key_modifier_add(Evas *e, const char *keyname) e->modifiers.mask = 0; } -/** - * Removes the @p keyname from the current list of modifiers. - * - * @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 - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the key to remove from the modifiers list. - */ EAPI void evas_key_modifier_del(Evas *e, const char *keyname) { @@ -210,21 +121,6 @@ evas_key_modifier_del(Evas *e, const char *keyname) } } -/** - * Adds the @p keyname to the current list of locks. - * - * Locks can be keys like caps lock, num lock or scroll lock, as well as user defined. This - * allows custom locks to be added to the evas system at run time. It is then possible to - * set and unset the lock for other parts of the program to check and act on. - * - * @see evas_key_lock_get - * @see evas_key_lock_del - * @see evas_key_lock_on - * @see evas_key_lock_off - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the key to remove from the modifier list. - */ EAPI void evas_key_lock_add(Evas *e, const char *keyname) { @@ -240,17 +136,6 @@ evas_key_lock_add(Evas *e, const char *keyname) e->locks.mask = 0; } -/** - * Removes The @p keyname from the current list of locks. - * - * @see evas_key_lock_get - * @see evas_key_lock_add - * @see evas_key_lock_on - * @see evas_key_lock_off - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the key to remove from the lock list. - */ EAPI void evas_key_lock_del(Evas *e, const char *keyname) { @@ -277,17 +162,6 @@ evas_key_lock_del(Evas *e, const char *keyname) } } -/** - * Enables or turns on the modifier with name @p keyname. - * - * @see evas_key_modifier_add - * @see evas_key_modifier_get - * @see evas_key_modifier_off - * @see evas_key_modifier_is_set - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the modifier to set. - */ EAPI void evas_key_modifier_on(Evas *e, const char *keyname) { @@ -304,17 +178,6 @@ evas_key_modifier_on(Evas *e, const char *keyname) e->modifiers.mask |= num; } -/** - * Disables or turns off the modifier with name @p keyname. - * - * @see evas_key_modifier_add - * @see evas_key_modifier_get - * @see evas_key_modifier_on - * @see evas_key_modifier_is_set - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the modifier to un-set. - */ EAPI void evas_key_modifier_off(Evas *e, const char *keyname) { @@ -331,17 +194,6 @@ evas_key_modifier_off(Evas *e, const char *keyname) e->modifiers.mask &= ~num; } -/** - * Enables or turns on the lock with name @p keyname. - * - * @see evas_key_lock_get - * @see evas_key_lock_add - * @see evas_key_lock_del - * @see evas_key_lock_off - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the lock to set. - */ EAPI void evas_key_lock_on(Evas *e, const char *keyname) { @@ -358,17 +210,6 @@ evas_key_lock_on(Evas *e, const char *keyname) e->locks.mask |= num; } -/** - * Disables or turns off the lock with name @p keyname. - * - * @see evas_key_lock_get - * @see evas_key_lock_add - * @see evas_key_lock_del - * @see evas_key_lock_on - * - * @param e The pointer to the Evas Canvas - * @param keyname The name of the lock to un-set. - */ EAPI void evas_key_lock_off(Evas *e, const char *keyname) { @@ -387,20 +228,6 @@ evas_key_lock_off(Evas *e, const char *keyname) /* errr need to add key grabbing/ungrabbing calls - missing modifier stuff. */ -/** - * Creates a bit mask from the @p keyname for use with events to check for the presence - * of the @p keyname modifier. - * - * @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 - * - * @param keyname The name of the modifier to create the mask for. - * - * @returns the bit mask or 0 if the @p keyname wasn't registered as a modifier. - */ EAPI Evas_Modifier_Mask evas_key_modifier_mask_get(const Evas *e, const char *keyname) { diff --git a/legacy/evas/src/lib/canvas/evas_key_grab.c b/legacy/evas/src/lib/canvas/evas_key_grab.c index 5152842cbb..3408d9d70c 100644 --- a/legacy/evas/src/lib/canvas/evas_key_grab.c +++ b/legacy/evas/src/lib/canvas/evas_key_grab.c @@ -134,47 +134,6 @@ evas_key_grab_free(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask mod /* public calls */ -/** - * Requests @p keyname key events be directed to @p obj. - * - * Key grabs allow an object to receive key events for specific key - * strokes even if another object has focus. If the grab is - * non-exclusive then all objects that have grabs on the key will get - * the event, however if the grab is exclusive, no other object can - * get a grab on the key and only that object will get the event. - * - * @p keyname is a platform dependent symbolic name for the key - * pressed. It is sometimes possible to convert the string to an - * ASCII value of the key, but not always for example the enter key - * may be returned as the string 'Enter'. - * - * Typical platforms are Linux frame buffer (Ecore_FB) and X server - * (Ecore_X) when using Evas with Ecore and Ecore_Evas. - * - * For a list of keynames for the Linux frame buffer, please refer to - * the Ecore_FB documentation. - * - * @p modifiers and @p not_modifiers are bit masks of all the - * modifiers that are required and not required respectively for the - * new grab. Modifiers can be things such as shift and ctrl as well - * as user defigned types via evas_key_modifier_add. - * - * @see evas_object_key_ungrab - * @see evas_object_focus_set - * @see evas_object_focus_get - * @see evas_focus_get - * @see evas_key_modifier_add - * - * @param obj the object to direct @p keyname events to. - * @param keyname the key to request events for. - * @param modifiers a mask of modifiers that should be present to - * trigger the event. - * @param not_modifiers a mask of modifiers that should not be present - * to trigger the event. - * @param exclusive request that the @p obj is the only object - * receiving the @p keyname events. - * @return Boolean indicating whether the grab succeeded - */ 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) { @@ -195,24 +154,6 @@ evas_object_key_grab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask m return 1; } -/** - * Request that the grab on @p obj be removed. - * - * Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers - * match. - * - * @see evas_object_key_grab - * @see evas_object_focus_set - * @see evas_object_focus_get - * @see evas_focus_get - * - * @param obj the object that has an existing grab. - * @param keyname the key the grab is for. - * @param modifiers a mask of modifiers that should be present to - * trigger the event. - * @param not_modifiers a mask of modifiers that should not be present - * to trigger the event. - */ EAPI void evas_object_key_ungrab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) { diff --git a/legacy/evas/src/lib/canvas/evas_layer.c b/legacy/evas/src/lib/canvas/evas_layer.c index 0175da13b7..076814c3f9 100644 --- a/legacy/evas/src/lib/canvas/evas_layer.c +++ b/legacy/evas/src/lib/canvas/evas_layer.c @@ -135,20 +135,6 @@ evas_layer_del(Evas_Layer *lay) /* public functions */ -/** - * @addtogroup Evas_Object_Group_Basic - * @{ - */ - -/** - * Sets the layer of the evas that the given object will be part of. - * - * It is not possible to change the layer of a smart object's child. - * - * @param obj The given evas object. - * @param l The number of the layer to place the object on. - * Between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX. - */ EAPI void evas_object_layer_set(Evas_Object *obj, short l) { @@ -192,16 +178,6 @@ evas_object_layer_set(Evas_Object *obj, short l) evas_object_inform_call_restack(obj); } -/** - * Retrieves the layer of the evas that the given object is part of. - * - * Be careful, it doesn't make sense to change the layer of smart object's - * child. So the returned value could be wrong in some case. Don't rely on - * it's accuracy. - * - * @param obj The given evas object. - * @return Number of the layer. - */ EAPI short evas_object_layer_get(const Evas_Object *obj) { @@ -214,7 +190,3 @@ evas_object_layer_get(const Evas_Object *obj) } return obj->cur.layer; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_main.c b/legacy/evas/src/lib/canvas/evas_main.c index 7742dc817b..94d9abf7d6 100644 --- a/legacy/evas/src/lib/canvas/evas_main.c +++ b/legacy/evas/src/lib/canvas/evas_main.c @@ -9,18 +9,6 @@ EAPI int lockmax = 0; static int _evas_init_count = 0; int _evas_log_dom_global = -1; -/** - * Initialize Evas - * - * @return The init counter value. - * - * This function initialize evas, increments a counter of the number - * of calls to this function and returns this value. - * - * @see evas_shutdown(). - * - * @ingroup Evas_Group - */ EAPI int evas_init(void) { @@ -83,18 +71,6 @@ evas_init(void) return --_evas_init_count; } -/** - * Shutdown Evas - * - * @return The init counter value. - * - * This function finalize evas, decrements the counter of the number - * of calls to the function evas_init() and returns this value. - * - * @see evas_init(). - * - * @ingroup Evas_Group - */ EAPI int evas_shutdown(void) { @@ -130,30 +106,6 @@ evas_shutdown(void) } -/** - * Creates a new empty evas. - * - * Note that before you can use the evas, you will to at a minimum: - * @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 . - * - * This function should only fail if the memory allocation fails - * - * @note this function is very low level. 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/. - * - * @attention it is recommended that one calls evas_init() before - * creating new canvas. - * - * @return A new uninitialised Evas canvas on success. Otherwise, @c - * NULL. - * @ingroup Evas_Canvas - */ EAPI Evas * evas_new(void) { @@ -187,16 +139,6 @@ evas_new(void) return e; } -/** - * Frees the given evas and any objects created on it. - * - * Any objects with 'free' callbacks will have those callbacks called - * in this function. - * - * @param e The given evas. - * - * @ingroup Evas_Canvas - */ EAPI void evas_free(Evas *e) { @@ -311,20 +253,6 @@ evas_free(Evas *e) free(e); } -/** - * Sets the output engine for the given evas. - * - * Once the output engine for an evas is set, any attempt to change it - * will be ignored. The value for @p render_method can be found using - * @ref evas_render_method_lookup . - * - * @attention it is mandatory that one calls evas_init() before - * setting the output method. - * - * @param e The given evas. - * @param render_method The numeric engine value to use. - * @ingroup Evas_Output_Method - */ EAPI void evas_output_method_set(Evas *e, int render_method) { @@ -356,13 +284,6 @@ evas_output_method_set(Evas *e, int render_method) return; } -/** - * Retrieves the number of the output engine used for the given evas. - * @param e The given evas. - * @return The ID number of the output engine being used. @c 0 is - * returned if there is an error. - * @ingroup Evas_Output_Method - */ EAPI int evas_output_method_get(const Evas *e) { @@ -373,20 +294,6 @@ evas_output_method_get(const Evas *e) return e->output.render_method; } -/** - * Retrieves the current render engine info struct from the given evas. - * - * The returned structure is publicly modifiable. The contents are - * valid until either @ref evas_engine_info_set or @ref evas_render - * are called. - * - * This structure does not need to be freed by the caller. - * - * @param e The given evas. - * @return A pointer to the Engine Info structure. @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) { @@ -404,25 +311,6 @@ evas_engine_info_get(const Evas *e) return info; } -/** - * Applies the engine settings for the given evas from the given @c - * Evas_Engine_Info structure. - * - * 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. - * - * You will 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. - * - * Once called, the @p info pointer should be considered invalid. - * - * @param e The pointer to the Evas Canvas - * @param info The pointer to the Engine Info to use - * @return 1 if no error occurred, 0 otherwise - * @ingroup Evas_Output_Method - */ EAPI Eina_Bool evas_engine_info_set(Evas *e, Evas_Engine_Info *info) { @@ -435,21 +323,6 @@ evas_engine_info_set(Evas *e, Evas_Engine_Info *info) return (Eina_Bool)e->engine.func->setup(e, info); } -/** - * Sets the output size of the render engine of the given evas. - * - * The evas will render to a rectangle of the given size once this - * function is called. The output size is independent of the viewport - * size. The viewport will be stretched to fill the given rectangle. - * - * The units used for @p w and @p h depend on the engine used by the - * evas. - * - * @param e The given evas. - * @param w The width in output units, usually pixels. - * @param h The height in output units, usually pixels. - * @ingroup Evas_Output_Size - */ EAPI void evas_output_size_set(Evas *e, int w, int h) { @@ -473,20 +346,6 @@ evas_output_size_set(Evas *e, int w, int h) evas_render_invalidate(e); } -/** - * Retrieve the output size of the render engine of the given evas. - * - * The output size is given in whatever the output units are for the - * engine. - * - * If either @p w or @p h is @c NULL, then it is ignored. If @p e is - * invalid, the returned results are undefined. - * - * @param e The given evas. - * @param w The pointer to an integer to store the width in. - * @param 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) { @@ -500,24 +359,6 @@ evas_output_size_get(const Evas *e, int *w, int *h) if (h) *h = e->output.h; } -/** - * Sets the output viewport of the given evas in evas units. - * - * The output viewport is the area of the evas that will be visible to - * the viewer. The viewport will be stretched to fit the output - * target of the evas when rendering is performed. - * - * @note 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 e The given evas. - * @param x The top-left corner x value of the viewport. - * @param y The top-left corner y value of the viewport. - * @param w The width of the viewport. Must be greater than 0. - * @param h The height of the viewport. Must be greater than 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) { @@ -544,30 +385,6 @@ evas_output_viewport_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas e->changed = 1; } -/** - * Get the render engine's output viewport co-ordinates in canvas units. - * @param e The pointer to the Evas Canvas - * @param x The pointer to a x variable to be filled in - * @param y The pointer to a y variable to be filled in - * @param w The pointer to a width variable to be filled in - * @param h The pointer to a height variable to be filled in - * @ingroup Evas_Output_Size - * - * Calling this function writes the current canvas output viewport - * size and location values into the variables pointed to by @p x, @p - * y, @p w and @p h. On success the variables have the output - * location and size values written to them in canvas units. Any of @p - * x, @p y, @p w or @p h that are NULL will not be written to. If @p e - * is invalid, the results are undefined. - * - * Example: - * @code - * extern Evas *evas; - * Evas_Coord x, y, width, height; - * - * evas_output_viewport_get(evas, &x, &y, &w, &h); - * @endcode - */ EAPI void evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) { @@ -585,28 +402,6 @@ evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord if (h) *h = e->viewport.h; } -/** - * Convert/scale an ouput screen co-ordinate into canvas co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param x The screen/output x co-ordinate - * @return The screen co-ordinate translated to canvas unit co-ordinates - * @ingroup Evas_Coord_Mapping_Group - * - * This function takes in a horizontal co-ordinate as the @p x - * parameter and converts it into canvas units, accounting for output - * size, viewport size and location, returning it as the function - * return value. If @p e is invalid, the results are undefined. - * - * 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 - */ EAPI Evas_Coord evas_coord_screen_x_to_world(const Evas *e, int x) { @@ -617,28 +412,6 @@ evas_coord_screen_x_to_world(const Evas *e, int x) return (long long)e->viewport.x + (((long long)x * (long long)e->viewport.w) / (long long)e->output.w); } -/** - * Convert/scale an ouput screen co-ordinate into canvas co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param y The screen/output y co-ordinate - * @return The screen co-ordinate translated to canvas unit co-ordinates - * @ingroup Evas_Coord_Mapping_Group - * - * This function takes in a vertical co-ordinate as the @p y parameter - * and converts it into canvas units, accounting for output size, - * viewport size and location, returning it as the function return - * value. If @p e is invalid, the results are undefined. - * - * 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 - */ EAPI Evas_Coord evas_coord_screen_y_to_world(const Evas *e, int y) { @@ -649,28 +422,6 @@ evas_coord_screen_y_to_world(const Evas *e, int y) return (long long)e->viewport.y + (((long long)y * (long long)e->viewport.h) / (long long)e->output.h); } -/** - * Convert/scale a canvas co-ordinate into output screen co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param x The canvas x co-ordinate - * @return The output/screen co-ordinate translated to output co-ordinates - * @ingroup Evas_Coord_Mapping_Group - * - * This function takes in a horizontal co-ordinate as the @p x - * parameter and converts it into output units, accounting for output - * size, viewport size and location, returning it as the function - * return value. If @p e is invalid, the results are undefined. - * - * 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 - */ EAPI int evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x) { @@ -681,28 +432,6 @@ evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x) return (int)((((long long)x - (long long)e->viewport.x) * (long long)e->output.w) / (long long)e->viewport.w); } -/** - * Convert/scale a canvas co-ordinate into output screen co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param y The canvas y co-ordinate - * @return The output/screen co-ordinate translated to output co-ordinates - * @ingroup Evas_Coord_Mapping_Group - * - * This function takes in a vertical co-ordinate as the @p x parameter - * and converts it into output units, accounting for output size, - * viewport size and location, returning it as the function return - * value. If @p e is invalid, the results are undefined. - * - * 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 - */ EAPI int evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y) { @@ -713,50 +442,6 @@ evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y) return (int)((((long long)y - (long long)e->viewport.y) * (long long)e->output.h) / (long long)e->viewport.h); } -/** - * Look up a numeric ID from a string name of a rendering engine. - * - * @param name The string name of an engine - * @return A numeric (opaque) ID for the rendering engine - * @ingroup Evas_Output_Method - * - * This function looks up a numeric return value for the named engine - * in the string @p name. This is a normal C string, NUL byte - * terminated. The name is case sensitive. If the rendering engine is - * available, a numeric ID for that engine is returned that is not - * 0. If the engine is not available, 0 is returned, indicating an - * invalid engine. - * - * The programmer should NEVER rely on the numeric ID of an engine - * unless it is returned by this function. Programs should NOT be - * written accessing render method ID's directly, without first - * obtaining it from this function. - * - * @attention it is mandatory that one calls evas_init() before - * looking up the render method. - * - * Example: - * @code - * int engine_id; - * Evas *evas; - * - * evas_init(); - * - * evas = evas_new(); - * if (!evas) - * { - * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n"); - * exit(-1); - * } - * engine_id = evas_render_method_lookup("software_x11"); - * if (!engine_id) - * { - * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n"); - * exit(-1); - * } - * evas_output_method_set(evas, engine_id); - * @endcode - */ EAPI int evas_render_method_lookup(const char *name) { @@ -770,37 +455,6 @@ evas_render_method_lookup(const char *name) return em->id_engine; } -/** - * List all the rendering engines compiled into the copy of the Evas library - * - * @return A linked list whose data members are C strings of engine names - * @ingroup Evas_Output_Method - * - * Calling this will return a handle (pointer) to an Evas linked - * list. Each node in the linked list will have the data pointer be a - * (char *) pointer to the string name 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, NULL will be returned. - * - * Example: - * @code - * Eina_List *engine_list, *l; - * char *engine_name; - * - * engine_list = evas_render_method_list(); - * if (!engine_list) - * { - * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); - * exit(-1); - * } - * printf("Availible Evas Engines:\n"); - * EINA_LIST_FOREACH(engine_list, l, engine_name) - * printf("%s\n", engine_name); - * evas_render_method_list_free(engine_list); - * @endcode - */ EAPI Eina_List * evas_render_method_list(void) { @@ -850,62 +504,12 @@ evas_render_method_list(void) return methods; } -/** - * This function should be called to free a list of engine names - * - * @param list The Eina_List base pointer for the engine list to be freed - * @ingroup Evas_Output_Method - * - * When this function is called it will free the engine list passed in - * as @p list. The list should only be a list of engines generated by - * calling evas_render_method_list(). If @p list is NULL, nothing will - * happen. - * - * Example: - * @code - * Eina_List *engine_list, *l; - * char *engine_name; - * - * engine_list = evas_render_method_list(); - * if (!engine_list) - * { - * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); - * exit(-1); - * } - * printf("Availible Evas Engines:\n"); - * EINA_LIST_FOREACH(engine_list, l, engine_name) - * printf("%s\n", engine_name); - * evas_render_method_list_free(engine_list); - * @endcode - */ EAPI void evas_render_method_list_free(Eina_List *list) { eina_list_free(list); } -/** - * This function returns the current known pointer co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param x The pointer to an integer to be filled in - * @param y The pointer to an integer to be filled in - * @ingroup Evas_Pointer_Group - * - * This function returns the current known screen/output co-ordinates - * of the mouse pointer and sets the contents of the integers pointed - * to by @p x and @p y to contain these co-ordinates. If @p e is not a - * valid canvas the results of this function are undefined. - * - * 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 - */ EAPI void evas_pointer_output_xy_get(const Evas *e, int *x, int *y) { @@ -918,28 +522,6 @@ evas_pointer_output_xy_get(const Evas *e, int *x, int *y) if (y) *y = e->pointer.y; } -/** - * This function returns the current known pointer co-ordinates - * - * @param e The pointer to the Evas Canvas - * @param x The pointer to a Evas_Coord to be filled in - * @param y The pointer to a Evas_Coord to be filled in - * @ingroup Evas_Pointer_Group - * - * 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 @p x and @p y to contain these co-ordinates. If @p e is not a - * valid canvas the results of this function are undefined. - * - * 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 - */ EAPI void evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y) { @@ -952,43 +534,6 @@ evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y) if (y) *y = e->pointer.y; } -/** - * Returns a bitmask with the mouse buttons currently pressed, set to 1 - * - * @param e The pointer to the Evas Canvas - * @return A bitmask of the currently depressed buttons on the cavas - * @ingroup Evas_Pointer_Group - * - * Calling this function will return a 32-bit integer with the - * appropriate bits set to 1 that correspond to a mouse button being - * depressed. This limits Evas to a mouse devices with a maximum of 32 - * buttons, but that is generally in excess of any host system's - * pointing device abilities. - * - * A canvas by default begins with no mouse buttons being pressed and - * only calls to evas_event_feed_mouse_down(), - * evas_event_feed_mouse_down_data(), evas_event_feed_mouse_up() and - * evas_event_feed_mouse_up_data() will alter that. - * - * 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). - * - * If @p e is not a valid canvas, the return value is undefined. - * - * 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 - */ EAPI int evas_pointer_button_down_mask_get(const Evas *e) { @@ -998,34 +543,6 @@ evas_pointer_button_down_mask_get(const Evas *e) return (int)e->pointer.button; } -/** - * Returns whether the mouse pointer is logically inside the canvas - * - * @param e The pointer to the Evas Canvas - * @return An integer that is 1 if the mouse is inside the canvas, 0 otherwise - * @ingroup Evas_Pointer_Group - * - * When this function is called it will return a value of either 0 or - * 1, depending on if evas_event_feed_mouse_in(), - * evas_event_feed_mouse_in_data(), or evas_event_feed_mouse_out(), - * evas_event_feed_mouse_out_data() have been called to feed in a - * mouse enter event into the canvas. - * - * A return value of 1 indicates the mouse is logically inside the - * canvas, and 0 implies it is logically outside the canvas. - * - * A canvas begins with the mouse being assumed outside (0). - * - * If @p e is not a valid canvas, the return value is undefined. - * - * Example: - * @code - * extern Evas *evas; - * - * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n"); - * else printf("Mouse is out!\n"); - * @endcode - */ EAPI Eina_Bool evas_pointer_inside_get(const Evas *e) { @@ -1035,13 +552,6 @@ evas_pointer_inside_get(const Evas *e) return (int)e->pointer.inside; } -/** - * Attaches a specific pointer to the evas for fetching later - * - * @param e The canvas to attach the pointer to - * @param data The pointer to attach - * @ingroup Evas_Canvas - */ EAPI void evas_data_attach_set(Evas *e, void *data) { @@ -1051,13 +561,6 @@ evas_data_attach_set(Evas *e, void *data) e->attach_data = data; } -/** - * Returns the pointer attached by evas_data_attach_set() - * - * @param e The canvas to attach the pointer to - * @return The pointer attached - * @ingroup Evas_Canvas - */ EAPI void * evas_data_attach_get(const Evas *e) { @@ -1067,12 +570,6 @@ evas_data_attach_get(const Evas *e) return e->attach_data; } -/** - * Inform to the evas that it got the focus. - * - * @param e The evas to change information. - * @ingroup Evas_Canvas - */ EAPI void evas_focus_in(Evas *e) { @@ -1084,12 +581,6 @@ evas_focus_in(Evas *e) evas_event_callback_call(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, NULL); } -/** - * Inform to the evas that it lost the focus. - * - * @param e The evas to change information. - * @ingroup Evas_Canvas - */ EAPI void evas_focus_out(Evas *e) { @@ -1101,12 +592,6 @@ evas_focus_out(Evas *e) evas_event_callback_call(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, NULL); } -/** - * Get the focus state known by the given evas - * - * @param e The evas to query information. - * @ingroup Evas_Canvas - */ EAPI Eina_Bool evas_focus_state_get(const Evas *e) { @@ -1116,30 +601,12 @@ evas_focus_state_get(const Evas *e) return e->focus; } -/** - * Push the nochange flag up 1 - * - * This tells evas, that while the nochange flag is greater than 0, do not - * mark objects as "changed" when making changes. - * - * @param e The evas to change information. - * @ingroup Evas_Canvas - */ EAPI void evas_nochange_push(Evas *e) { e->nochange++; } -/** - * Pop the nochange flag down 1 - * - * This tells evas, that while the nochange flag is greater than 0, do not - * mark objects as "changed" when making changes. - * - * @param e The evas to change information. - * @ingroup Evas_Canvas - */ EAPI void evas_nochange_pop(Evas *e) { @@ -1159,13 +626,6 @@ _evas_unwalk(Evas *e) if ((e->walking_list == 0) && (e->delete_me)) evas_free(e); } -/** - * Converts the given error code into a string describing it in english. - * @param error the error code. - * @return Always return a valid string. If given @p error is not - * supported "Unknown error" is returned. - * @ingroup Evas_Utils - */ EAPI const char * evas_load_error_str(Evas_Load_Error error) { @@ -1190,99 +650,30 @@ evas_load_error_str(Evas_Load_Error error) } } -/** - * Convert a given color from HSV to RGB format. - * - * @param h The Hue component of the color. - * @param s The Saturation component of the color. - * @param v The Value component of the color. - * @param r The Red component of the color. - * @param g The Green component of the color. - * @param b The Blue component of the color. - * - * This function converts a given color in HSV color format to RGB - * color format. - * - * @ingroup Evas_Utils - **/ EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b) { evas_common_convert_color_hsv_to_rgb(h, s, v, r, g, b); } -/** - * Convert a given color from RGB to HSV format. - * - * @param r The Red component of the color. - * @param g The Green component of the color. - * @param b The Blue component of the color. - * @param h The Hue component of the color. - * @param s The Saturation component of the color. - * @param v The Value component of the color. - * - * This function converts a given color in RGB color format to HSV - * color format. - * - * @ingroup Evas_Utils - **/ EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v) { evas_common_convert_color_rgb_to_hsv(r, g, b, h, s, v); } -/** - * Pre-multiplies a rgb triplet by an alpha factor. - * - * @param a The alpha factor. - * @param r The Red component of the color. - * @param g The Green component of the color. - * @param b The Blue component of the color. - * - * This function pre-multiplies a given rbg triplet by an alpha - * factor. Alpha factor is used to define transparency. - * - * @ingroup Evas_Utils - **/ EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b) { evas_common_convert_color_argb_premul(a, r, g, b); } -/** - * Undo pre-multiplication of a rgb triplet by an alpha factor. - * - * @param a The alpha factor. - * @param r The Red component of the color. - * @param g The Green component of the color. - * @param b The Blue component of the color. - * - * This function undoes pre-multiplication a given rbg triplet by an - * alpha factor. Alpha factor is used to define transparency. - * - * @see evas_color_argb_premul(). - * - * @ingroup Evas_Utils - **/ EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b) { evas_common_convert_color_argb_unpremul(a, r, g, b); } -/** - * Pre-multiplies data by an alpha factor. - * - * @param data The data value. - * @param len The length value. - * - * This function pre-multiplies a given data by an alpha - * factor. Alpha factor is used to define transparency. - * - * @ingroup Evas_Utils - **/ EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len) { @@ -1290,17 +681,6 @@ evas_data_argb_premul(unsigned int *data, unsigned int len) evas_common_convert_argb_premul(data, len); } -/** - * Undo pre-multiplication data by an alpha factor. - * - * @param data The data value. - * @param len The length value. - * - * This function undoes pre-multiplication of a given data by an alpha - * factor. Alpha factor is used to define transparency. - * - * @ingroup Evas_Utils - **/ EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len) { diff --git a/legacy/evas/src/lib/canvas/evas_map.c b/legacy/evas/src/lib/canvas/evas_map.c index a0469c52ec..6ae1d54029 100644 --- a/legacy/evas/src/lib/canvas/evas_map.c +++ b/legacy/evas/src/lib/canvas/evas_map.c @@ -305,20 +305,6 @@ evas_map_inside_get(const Evas_Map *m, Evas_Coord x, Evas_Coord y) } -/** - * Enable or disable the map that is set. - * - * This enables the map that is set or disables it. On enable, the object - * geometry will be saved, and the new geometry will change (position and - * size) to reflect the map geometry set. If none is set yet, this may be - * an undefined geometry, unless you have already set the map with - * evas_object_map_set(). It is suggested you first set a map with - * evas_object_map_set() with valid useful coordinates then enable and - * disable the map with evas_object_map_enable_set() as needed. - * - * @param obj object to enable the map on - * @param enabled enabled state - */ EAPI void evas_object_map_enable_set(Evas_Object *obj, Eina_Bool enabled) { @@ -349,16 +335,6 @@ evas_object_map_enable_set(Evas_Object *obj, Eina_Bool enabled) evas_object_change(obj); } -/** - * Get the map enabled state - * - * This 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(). - * - * @param obj object to get the map enabled state from - * @return the map enabled state - */ EAPI Eina_Bool evas_object_map_enable_get(const Evas_Object *obj) { @@ -369,17 +345,6 @@ evas_object_map_enable_get(const Evas_Object *obj) } -/** - * Set the map source object - * - * This sets the object from which the map is taken - can be any object that - * has map enabled on it. - * - * Currently not implemented. for future use. - * - * @param obj object to set the map source of - * @param src the source object from which the map is taken - */ EAPI void evas_object_map_source_set(Evas_Object *obj, Evas_Object *src) { @@ -389,14 +354,6 @@ evas_object_map_source_set(Evas_Object *obj, Evas_Object *src) (void)src; /* method still needs to be implemented. */ } -/** - * Get the map source object - * - * See evas_object_map_source_set() - * - * @param obj object to set the map source of - * @return the object set as the source - */ EAPI Evas_Object * evas_object_map_source_get(const Evas_Object *obj) { @@ -406,45 +363,6 @@ evas_object_map_source_get(const Evas_Object *obj) return NULL; } -/** - * Set current object transformation map. - * - * This sets the map on a given object. It is copied from the @p map pointer, - * so there is no need to keep the @p map object if you don't need it anymore. - * - * A map is a set of 4 points which have canvas x, y coordinates per point, - * with an optional z point value as a hint for perspective correction, if it - * is available. As well each point has u and 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/point. The u corresponds to the x - * coordinate of this mapped point and v, the 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: - * - * @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 - * - * Note that the map points a uv coordinates match the image geometry. If - * the @p map parameter is NULL, the stored map will be freed and geometry - * prior to enabling/setting a map will be restored. - * - * @param obj object to change transformation map - * @param map new map to use - * - * @see evas_map_new() - */ EAPI void evas_object_map_set(Evas_Object *obj, const Evas_Map *map) { @@ -499,28 +417,6 @@ evas_object_map_set(Evas_Object *obj, const Evas_Map *map) _evas_map_calc_map_geometry(obj); } -/** - * Get current object transformation map. - * - * This returns the current internal map set on the indicated object. It is - * intended for read-only acces 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: - * - * @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); - * evas_map_free(m2); - * @endcode - * - * @param obj object to query transformation map. - * @return map reference to map in use. 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) { @@ -531,25 +427,6 @@ evas_object_map_get(const Evas_Object *obj) return NULL; } -/** - * Create map of transformation points to be later used with an evas object. - * - * This creates a set of points (currently only 4 is supported. no other - * number for @p count will work). That is empty and ready to be modified - * with evas_map calls. - * - * @param count number of points in the map. * - * @return a newly allocated map or 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) { @@ -561,16 +438,6 @@ evas_map_new(int count) return _evas_map_new(count); } -/** - * Set the smoothing for map rendering - * - * This 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. - * - * @param m map to modify. Must not be NULL. - * @param enabled enable or disable smooth map rendering - */ EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled) { @@ -578,13 +445,6 @@ evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled) m->smooth = enabled; } -/** - * get the smoothing for map rendering - * - * This gets smoothing for map rendering. - * - * @param m map to get the smooth from. Must not be NULL. - */ EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m) { @@ -592,17 +452,6 @@ evas_map_smooth_get(const Evas_Map *m) return m->smooth; } -/** - * Set the alpha flag for map rendering - * - * This sets alpha flag for map rendering. If the object is a type that has - * its own alpha settings, then this will take precedence. Only image objects - * have this currently. Fits stops alpha blending of the map area, and is - * useful if you know the object and/or all sub-objects is 100% solid. - * - * @param m map to modify. Must not be NULL. - * @param enabled enable or disable alpha map rendering - */ EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled) { @@ -610,13 +459,6 @@ evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled) m->alpha = enabled; } -/** - * get the alpha flag for map rendering - * - * This gets the alph flag for map rendering. - * - * @param m map to get the alpha from. Must not be NULL. - */ EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m) { @@ -624,14 +466,6 @@ evas_map_alpha_get(const Evas_Map *m) return m->alpha; } -/** - * Copy a previously allocated map. - * - * This makes a duplicate of the @p m object and returns it. - * - * @param m map to copy. Must not be NULL. - * @return newly allocated map with the same count and contents as @p m. - */ EAPI Evas_Map * evas_map_dup(const Evas_Map *m) { @@ -639,14 +473,6 @@ evas_map_dup(const Evas_Map *m) return _evas_map_dup(m); } -/** - * Free a previously allocated map. - * - * This frees a givem map @p m and all memory associated with it. You must NOT - * free a map returned by evas_object_map_get() as this is internal. - * - * @param m map to free. - */ EAPI void evas_map_free(Evas_Map *m) { @@ -654,14 +480,6 @@ evas_map_free(Evas_Map *m) _evas_map_free(NULL, m); } -/** - * Get a maps size. - * - * Returns the number of points in a map. Should be at least 4. - * - * @param m map to get size. - * @return -1 on error, points otherwise. - */ EAPI int evas_map_count_get(const Evas_Map *m) { @@ -669,35 +487,6 @@ evas_map_count_get(const Evas_Map *m) return m->count; } -/** - * Change the map point's coordinate. - * - * This sets the fixen point's coordinate in the map. Note that points - * describe the outline of a quadrangle and are ordered either clockwise - * or anit-clock-wise. 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 will use points 0 and 1 , 1 and 2, - * 2 and 3, and 3 and 0 to describe the edges of the quandrangle. - * - * The X and 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. - * - * Remember all coordinates are canvas global ones like with move and reize - * in evas. - * - * @param m map to change point. Must not be @c NULL. - * @param idx index of point to change. Must be smaller than map size. - * @param x Point X Coordinate - * @param y Point Y Coordinate - * @param z Point 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) { @@ -710,17 +499,6 @@ evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_ p->z = z; } -/** - * Get the map point's coordinate. - * - * This returns the coordinates of the given point in the map. - * - * @param m map to query point. - * @param idx index of point to query. Must be smaller than map size. - * @param x where to return the X coordinate. - * @param y where to return the Y coordinate. - * @param z where to return 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) { @@ -740,25 +518,6 @@ evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord * if (z) *z = 0; } -/** - * Change the map point's U and V texture source point - * - * 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. Notes that these points do select the pixel, but - * are double floating point values to allow for accuracy and sub-pixel - * selection. - * - * @param m map to change the point of. - * @param idx index of point to change. Must be smaller than map size. - * @param u the X coordinate within the image/texture source - * @param v the Y coordinate within the image/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) { @@ -770,16 +529,6 @@ evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v) p->v = v; } -/** - * Get the map point's U and V texture source points - * - * This returns the texture points set by evas_map_point_image_uv_set(). - * - * @param m map to query point. - * @param idx index of point to query. Must be smaller than map size. - * @param u where to write the X coordinate within the image/texture source - * @param v where to write the Y coordinate within the image/texture source - */ EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v) { @@ -796,26 +545,6 @@ evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v) if (v) *v = 0.0; } -/** - * Set the color of a vertex in the map - * - * This sets the color of the vertex in the map. Colors will be linearly - * interpolated between vertex points through the map. Color will multiply - * 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 will - * have no affect on modifying the texture pixels. - * - * @param m map to change the color of. - * @param idx index of point to change. Must be smaller than map size. - * @param r red (0 - 255) - * @param g green (0 - 255) - * @param b blue (0 - 255) - * @param a alpha (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) { @@ -829,22 +558,6 @@ evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a) p->a = a; } -/** - * Get the color set on a vertex in the map - * - * This gets the color set by evas_map_point_color_set() on the given vertex - * of the map. - * - * @param m map to get the color of the vertex from. - * @param idx index of point get. Must be smaller than map size. - * @param r pointer to red return - * @param g pointer to green return - * @param b pointer to blue return - * @param a pointer to alpha return (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) { @@ -898,24 +611,6 @@ _evas_map_util_points_populate(Evas_Map *m, const Evas_Coord x, const Evas_Coord } } -/** - * Populate source and destination map points to match exactly object. - * - * Usually one initialize map of an object to match it's 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 m map to change all 4 points (must be of size 4). - * @param obj object to use unmapped geometry to populate map coordinates. - * @param z Point Z Coordinate hint (pre-perspective transform). This value - * will be 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) { @@ -936,25 +631,6 @@ evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *o obj->cur.geometry.w, obj->cur.geometry.h, z); } -/** - * Populate source and destination map points to match exactly object. - * - * Usually one initialize map of an object to match it's 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. - * - * Z Point coordinate is assumed as 0 (zero). - * - * @param m map to change all 4 points (must be of size 4). - * @param obj 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) { @@ -975,27 +651,6 @@ evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj) obj->cur.geometry.w, obj->cur.geometry.h, 0); } -/** - * Populate source and destination map points to match given geometry. - * - * 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 will be used to calculate destination - * points (evas_map_point_coord_set()) and set the image uv - * (evas_map_point_image_uv_set()). - * - * @param m map to change all 4 points (must be of size 4). - * @param x Point X Coordinate - * @param y Point Y Coordinate - * @param w width to use to calculate second and third points. - * @param h height to use to calculate third and fourth points. - * @param z Point Z Coordinate hint (pre-perspective transform). This value - * will be 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) { @@ -1012,20 +667,6 @@ evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coor _evas_map_util_points_populate(m, x, y, w, h, z); } -/** - * Set color of all points to given color. - * - * This call is useful to reuse maps after they had 3d lightning or - * any other colorization applied before. - * - * @param m map to change the color of. - * @param r red (0 - 255) - * @param g green (0 - 255) - * @param b blue (0 - 255) - * @param a alpha (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) { @@ -1046,23 +687,6 @@ evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a) } } -/** - * Change the map to apply the given rotation. - * - * This rotates the indicated map's coordinates around the center coordinate - * given by @p cx and @p cy as the rotation center. The points will have their - * X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a - * full rotation). Negative values for degrees will rotate counter-clockwise - * by that amount. All coordinates are canvas global coordinates. - * - * @param m map to change. - * @param degrees amount of degrees from 0.0 to 360.0 to rotate. - * @param cx rotation's center horizontal position. - * @param cy 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) { @@ -1090,24 +714,6 @@ evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy) } } -/** - * Change the map to apply the given zooming. - * - * Like evas_map_util_rotate(), this zooms the points of the map from a center - * point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy - * parameters specific how much to zoom in the X and Y direction respectively. - * A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is - * "half the size" etc. All coordinates are canvas global coordinates. - * - * @param m map to change. - * @param zoomx horizontal zoom to use. - * @param zoomy vertical zoom to use. - * @param cx zooming center horizontal position. - * @param cy 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) { @@ -1132,24 +738,6 @@ evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_ } } -/** - * Rotate the map around 3 axes in 3D - * - * This will rotate not just around the "Z" axis as in evas_map_util_rotate() - * (which is a convenience call for those only wanting 2D). This will rotate - * 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(0 you provide a center point to rotate around (in 3D). - * - * @param m map to change. - * @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis. - * @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis. - * @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis. - * @param cx rotation's center horizontal position. - * @param cy rotation's center vertical position. - * @param cz 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) @@ -1201,28 +789,6 @@ evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, } } -/** - * Perform lighting calculations on the given Map - * - * This is used to apply lighting calculations (from a single light source) - * to a given map. The R, G and B values of each vertex will be 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 be 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. - * - * @param m map to change. - * @param lx X coordinate in space of light point - * @param ly Y coordinate in space of light point - * @param lz Z coordinate in space of light point - * @param lr light red value (0 - 255) - * @param lg light green value (0 - 255) - * @param lb light blue value (0 - 255) - * @param ar ambient color red value (0 - 255) - * @param ag ambient color green value (0 - 255) - * @param ab 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, @@ -1299,28 +865,6 @@ evas_map_util_3d_lighting(Evas_Map *m, } } -/** - * Apply a perspective transform to the map -* - * This 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 @p z0 value specifis the z value at which there is a 1:1 - * mapping between spatial coorinates and screen coordinates. Any points - * on this z value will not have their X and Y values modified in the transform. - * Those further away (Z value higher) will shrink into the distance, and - * those less than this value will expand and become bigger. The @p 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 @p foc must be greater than 0. - * - * @param m map to change. - * @param px The pespective distance X coordinate - * @param py The pespective distance Y coordinate - * @param z0 The "0" z plane value - * @param foc The focal distance - */ EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, @@ -1359,17 +903,6 @@ evas_map_util_3d_perspective(Evas_Map *m, } } -/** - * Get the clockwise state of a map - * - * This determines if the output points (X and Y. Z is not used) are - * clockwise or anti-clockwise. This can be used for "back-face culling". This - * is where you hide objects that "face away" from you. In this case objects - * that are not clockwise. - * - * @param m map to query. - * @return 1 if clockwise, 0 otherwise - */ EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m) { @@ -1396,7 +929,3 @@ evas_map_util_clockwise_get(Evas_Map *m) if (count > 0) return 1; return 0; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_name.c b/legacy/evas/src/lib/canvas/evas_name.c index f5e204ba68..ad3b71f14d 100644 --- a/legacy/evas/src/lib/canvas/evas_name.c +++ b/legacy/evas/src/lib/canvas/evas_name.c @@ -1,16 +1,6 @@ #include "evas_common.h" #include "evas_private.h" -/** - * @addtogroup Evas_Object_Group_Basic - * @{ - */ - -/** - * Sets the name of the given evas object to the given name. - * @param obj The given object. - * @param name The given name. - */ EAPI void evas_object_name_set(Evas_Object *obj, const char *name) { @@ -30,12 +20,6 @@ evas_object_name_set(Evas_Object *obj, const char *name) } } -/** - * Retrieves the name of the given evas object. - * @param obj The given object. - * @return The name of the object. @c NULL if no name has been given - * to the object. - */ EAPI const char * evas_object_name_get(const Evas_Object *obj) { @@ -45,18 +29,6 @@ evas_object_name_get(const Evas_Object *obj) return obj->name; } -/** - * @} - */ - -/** - * Retrieves the object on the given evas with the given name. - * @param e The given evas. - * @param name The given name. - * @return If successful, the evas object with the given name. Otherwise, - * @c NULL. - * @ingroup Evas_Object_Group_Find - */ EAPI Evas_Object * evas_object_name_find(const Evas *e, const char *name) { diff --git a/legacy/evas/src/lib/canvas/evas_object_box.c b/legacy/evas/src/lib/canvas/evas_object_box.c index 8503cf4f7b..ae5563f378 100644 --- a/legacy/evas/src/lib/canvas/evas_object_box.c +++ b/legacy/evas/src/lib/canvas/evas_object_box.c @@ -23,11 +23,6 @@ struct _Evas_Object_Box_Accessor const Evas_Object *box; }; -/** - * @addtogroup Evas_Object_Box - * @{ - */ - #define _evas_object_box_type "Evas_Object_Box" #define SIG_CHILD_ADDED "child,added" #define SIG_CHILD_REMOVED "child,removed" @@ -548,25 +543,12 @@ _evas_object_box_smart_set_user(Evas_Object_Box_Api *api) api->option_free = _evas_object_box_option_free_default; } -/** - * Create a new box. - * - * Its layout function must be set via evas_object_box_layout_set() - * (defaults to evas_object_box_layout_horizontal()). The other - * properties of the box must be set/retrieved via - * evas_object_box_{h,v}_{align,padding}_{get,set)(). - */ EAPI Evas_Object * evas_object_box_add(Evas *evas) { return evas_object_smart_add(evas, _evas_object_box_smart_class_new()); } -/** - * Create a box that is child of a given element @a parent. - * - * @see evas_object_box_add() - */ EAPI Evas_Object * evas_object_box_add_to(Evas_Object *parent) { @@ -579,10 +561,6 @@ evas_object_box_add_to(Evas_Object *parent) return o; } -/** - * Set the default box @a api struct (Evas_Object_Box_Api) - * with the default values. May be used to extend that API. - */ EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) { @@ -591,9 +569,6 @@ evas_object_box_smart_set(Evas_Object_Box_Api *api) _evas_object_box_smart_set(api); } -/** - * Get Box Smart Class for inheritance purposes - */ EAPI const Evas_Object_Box_Api * evas_object_box_smart_class_get(void) { @@ -610,11 +585,6 @@ evas_object_box_smart_class_get(void) return class; } -/** - * Set a 'calculate' callback (@a cb) to the @a o box's smart class, - * which here defines its genre (horizontal, vertical, homogeneous, - * etc.). - */ EAPI void evas_object_box_layout_set(Evas_Object *o, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) { @@ -774,55 +744,6 @@ _evas_object_box_layout_horizontal_weight_apply(Evas_Object_Box_Data *priv, Evas return remaining - rem_diff; } -/** - * Layout function which sets the box @a o to a (basic) horizontal - * box. @a priv must be the smart data of the box. - * - * The object's overall behavior is controlled by its properties, - * which are set by the evas_object_box_{h,v}_{align,padding}_set() - * family of functions. The properties of the elements in the box -- - * set by evas_object_size_hint_{align,padding,weight}_set() 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 0, children are aligned - * to the left. A value of 1 lets 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 container width, - * the children will be displayed out of its bounds. A negative value - * of @c align_h makes the box to *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 don't contribute to its behaviour - * when this layout is chosen. - * - * \par Child element's properties: - * @c align_x does 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/positioning 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 not pre-defined. If the container can't accommodate - * all its children, it sets the widths of the children *with weights* - * 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 children's (which have weights) widths as to fit the - * remaining space. The @c weight_x property, besides telling the - * element is resizable, gives a *weight* for the resizing process. - * The parent box will try to distribute (or take off) widths - * accordingly to the *normalized* list of weigths: most weighted - * children remain/get larger in this process than the the least ones. - * @c weight_y does not influence the layout. - * - * If one desires that, besides having weights, child elements must be - * resized bounded to a minimum or maximum size, their size hint - * properties must be set (by the - * evas_object_size_hint_{min,max}_set() functions. - */ EAPI void evas_object_box_layout_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -981,14 +902,6 @@ _evas_object_box_layout_vertical_weight_apply(Evas_Object_Box_Data *priv, Evas_O return remaining - rem_diff; } -/** - * Layout function which sets the box @a o to a (basic) vertical box. - * @a priv must be the smart data of the box. - * - * This function behaves analogously to - * evas_object_box_layout_horizontal(). The description of its - * behaviour can be derived from that function's documentation. - */ EAPI void evas_object_box_layout_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1094,39 +1007,6 @@ evas_object_box_layout_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void evas_object_size_hint_min_set(o, top_w, req_h); } -/** - * Layout function which sets the box @a o to a *homogeneous* - * horizontal box. @a priv must be the smart data of the box. - * - * In a homogeneous horizontal box, its width is divided equally - * between the contained objects. The box's overall behavior is - * controlled by its properties, which are set by the - * evas_object_box_{h,v}_{align,padding}_set() family of functions. - * The properties of the elements in the box -- set by - * evas_object_size_hint_{align,padding,weight}_set() 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 (still equal) child objects's cells. The @c - * align_v and @c padding_v properties of the box don't 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 (0 to extreme - * left, 1 to extreme right). A value of -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 its horizontal padding properties). The child's @c - * padding_t, @c padding_b and @c align_y properties apply for - * padding/positioning relative to the overall height of the box. A - * value of -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). - */ EAPI void evas_object_box_layout_homogeneous_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1188,14 +1068,6 @@ evas_object_box_layout_homogeneous_horizontal(Evas_Object *o, Evas_Object_Box_Da evas_object_size_hint_min_set(o, w, h); } -/** - * Layout function which sets the box @a o to a *homogeneous* vertical - * box. @a priv must be the smart data of the box. - * - * This function behaves analogously to - * evas_object_box_layout_homogeneous_horizontal(). The description - * of its behaviour can be derived from that function's documentation. - */ EAPI void evas_object_box_layout_homogeneous_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1256,47 +1128,6 @@ evas_object_box_layout_homogeneous_vertical(Evas_Object *o, Evas_Object_Box_Data evas_object_size_hint_min_set(o, w, h); } -/** - * Layout function which sets the box @a o to a *max size-homogeneous* - * horizontal box. @a priv must be the smart data of the box. - * - * In a max size-homogeneous horizontal box, the equal sized cells - * reserved for the child objects have the width of the space required - * by the largest child (in width). The box's overall behavior is - * controlled by its properties, which are set by the - * evas_object_box_{h,v}_{align,padding}_set() family of functions. - * The properties of the elements in the box -- set by - * evas_object_size_hint_{align,padding,weight}_set() 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's cells. @c align_h controls the - * horizontal alignment of the child objects relative to the - * containing box. When set to 0, children are aligned to the left. A - * value of 1 lets them aligned to the right border. Values in - * between align them proportionally. A negative value of @c align_h - * makes the box to *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 don't 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 (0 to extreme - * left, 1 to extreme right). A value of -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 its horizontal padding properties). The child's @c - * padding_t, @c padding_b and @c align_y properties apply for - * padding/positioning relative to the overall height of the box. A - * value of -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). - */ EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1381,15 +1212,6 @@ evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Obje evas_object_size_hint_min_set(o, x, top_h); } -/** - * Layout function which sets the box @a o to a *max size-homogeneous* - * vertical box. @a priv must be the smart data of the box. - * - * 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. - */ EAPI void evas_object_box_layout_homogeneous_max_size_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1538,41 +1360,6 @@ _evas_object_box_layout_flow_horizontal_row_info_collect(Evas_Object_Box_Data *p *max_h_ret = max_h; } -/** - * Layout function which sets the box @a o to a *flow* horizontal box. - * @a priv must be the smart data of the box. - * - * In a flow horizontal box, the box's child elements are placed in - * 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 - * evas_object_box_{h,v}_{align,padding}_set() family of functions. - * The properties of the elements in the box -- set by - * evas_object_size_hint_{align,padding,weight}_set() 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's cells. @c align_h dictates the - * horizontal alignment of the rows (0 to left align them, 1 to right - * align). A value of -1.0 to @c align_h lets the rows *justified* - * horizontally. @c align_v controls the vertical alignment of the - * entire set of rows (0 to top, 1 to bottom). A value of -1.0 to @c - * align_v makes the box to *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 *largest height* - * required by a child object in the actual row. - */ EAPI void evas_object_box_layout_flow_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1754,14 +1541,6 @@ _evas_object_box_layout_flow_vertical_col_info_collect(Evas_Object_Box_Data *pri *max_w_ret = max_w; } -/** - * Layout function which sets the box @a o to a *flow* vertical box. - * @a priv must be the smart data of the box. - * - * This function behaves analogously to - * evas_object_box_layout_flow_horizontal(). The description of its - * behaviour can be derived from that function's documentation. - */ EAPI void evas_object_box_layout_flow_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1877,27 +1656,6 @@ evas_object_box_layout_flow_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, evas_object_size_hint_min_set(o, min_w, min_h); } -/** - * Layout function which sets the box @a o to set all children to the - * size of the object. @a priv must be the smart data of the box. - * - * In a stack box, all children will be given the same size and they - * will be stacked on above the other, so the first object will be the - * bottom most. - * - * \par box's properties: - * No box option is 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 (0 to extreme - * left, 1 to extreme right). A value of -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 its horizontal padding properties). Same applies to - * vertical axis. - */ EAPI void evas_object_box_layout_stack(Evas_Object *o, Evas_Object_Box_Data *priv, void *data __UNUSED__) { @@ -1946,9 +1704,6 @@ evas_object_box_layout_stack(Evas_Object *o, Evas_Object_Box_Data *priv, void *d evas_object_size_hint_min_set(o, top_w, top_h); } -/** - * Set the alignment of the whole bounding box of contents. - */ EAPI void evas_object_box_align_set(Evas_Object *o, double horizontal, double vertical) { @@ -1960,9 +1715,6 @@ evas_object_box_align_set(Evas_Object *o, double horizontal, double vertical) evas_object_smart_changed(o); } -/** - * Get alignment of the whole bounding box of contents. - */ EAPI void evas_object_box_align_get(const Evas_Object *o, double *horizontal, double *vertical) { @@ -1979,9 +1731,6 @@ evas_object_box_align_get(const Evas_Object *o, double *horizontal, double *vert } } -/** - * Set the space (padding) between cells. - */ EAPI void evas_object_box_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) { @@ -1993,9 +1742,6 @@ evas_object_box_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord ve evas_object_smart_changed(o); } -/** - * Get the (space) padding between cells. - */ EAPI void evas_object_box_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) { @@ -2012,10 +1758,6 @@ evas_object_box_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_C } } -/** - * Append a new object @a child to the box @a o. On error, @c NULL is - * returned. - */ EAPI Evas_Object_Box_Option * evas_object_box_append(Evas_Object *o, Evas_Object *child) { @@ -2042,10 +1784,6 @@ evas_object_box_append(Evas_Object *o, Evas_Object *child) return NULL; } -/** - * Prepend a new object @a child to the box @a o. On error, @c NULL is - * returned. - */ EAPI Evas_Object_Box_Option * evas_object_box_prepend(Evas_Object *o, Evas_Object *child) { @@ -2072,11 +1810,6 @@ evas_object_box_prepend(Evas_Object *o, Evas_Object *child) return NULL; } -/** - * Prepend a new object @a child to the box @c o relative to element @a - * reference. If @a reference is not contained in the box or any other - * error occurs, @c NULL is returned. - */ EAPI Evas_Object_Box_Option * evas_object_box_insert_before(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) { @@ -2103,11 +1836,6 @@ evas_object_box_insert_before(Evas_Object *o, Evas_Object *child, const Evas_Obj return NULL; } -/** - * Append a new object @a child to the box @c o relative to element @a - * reference. If @a reference is not contained in the box or any other - * error occurs, @c NULL is returend. - */ EAPI Evas_Object_Box_Option * evas_object_box_insert_after(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) { @@ -2134,10 +1862,6 @@ evas_object_box_insert_after(Evas_Object *o, Evas_Object *child, const Evas_Obje return NULL; } -/** - * Insert a new object @a child to the box @a o at position @a pos. On - * error, @c NULL is returned. - */ EAPI Evas_Object_Box_Option * evas_object_box_insert_at(Evas_Object *o, Evas_Object *child, unsigned int pos) { @@ -2164,10 +1888,6 @@ evas_object_box_insert_at(Evas_Object *o, Evas_Object *child, unsigned int pos) return NULL; } -/** - * Remove an object @a child from the box @a o. On error, @c 0 is - * returned. - */ EAPI Eina_Bool evas_object_box_remove(Evas_Object *o, Evas_Object *child) { @@ -2194,10 +1914,6 @@ evas_object_box_remove(Evas_Object *o, Evas_Object *child) return EINA_FALSE; } -/** - * Remove an object from the box @a o which occupies position @a - * pos. On error, @c 0 is returned. - */ EAPI Eina_Bool evas_object_box_remove_at(Evas_Object *o, unsigned int pos) { @@ -2221,10 +1937,6 @@ evas_object_box_remove_at(Evas_Object *o, unsigned int pos) return EINA_FALSE; } -/** - * Remove all child objects. - * @return 0 on errors - */ EAPI Eina_Bool evas_object_box_remove_all(Evas_Object *o, Eina_Bool clear) { @@ -2256,11 +1968,6 @@ evas_object_box_remove_all(Evas_Object *o, Eina_Bool clear) return EINA_TRUE; } -/** - * Get an iterator to walk the list of children for the box. - * - * @note Do not remove or delete objects while walking the list. - */ EAPI Eina_Iterator * evas_object_box_iterator_new(const Evas_Object *o) { @@ -2285,11 +1992,6 @@ evas_object_box_iterator_new(const Evas_Object *o) return &it->iterator; } -/** - * Get an accessor to get random access to the list of children for the box. - * - * @note Do not remove or delete objects while walking the list. - */ EAPI Eina_Accessor * evas_object_box_accessor_new(const Evas_Object *o) { @@ -2314,14 +2016,6 @@ evas_object_box_accessor_new(const Evas_Object *o) return &it->accessor; } -/** - * Get the list of children for the box. - * - * @note This is a duplicate of the list kept by the box internally. - * It's up to the user to destroy it when it no longer needs it. - * It's possible to remove objects from the box when walking this - * list, but these removals won't be reflected on it. - */ EAPI Eina_List * evas_object_box_children_get(const Evas_Object *o) { @@ -2336,10 +2030,6 @@ evas_object_box_children_get(const Evas_Object *o) return new_list; } -/** - * Get the name of the property of the child elements of the box @a o - * whose id is @a property. On error, @c NULL is returned. - */ EAPI const char * evas_object_box_option_property_name_get(Evas_Object *o, int property) { @@ -2357,10 +2047,6 @@ evas_object_box_option_property_name_get(Evas_Object *o, int property) return api->property_name_get(o, property); } -/** - * Get the id of the property of the child elements of the box @a o - * whose name is @a name. On error, @c -1 is returned. - */ EAPI int evas_object_box_option_property_id_get(Evas_Object *o, const char *name) { @@ -2378,12 +2064,6 @@ evas_object_box_option_property_id_get(Evas_Object *o, const char *name) return api->property_id_get(o, name); } -/** - * Set the property (with id @a property) of the child element of the - * box @a o whose property struct is @a opt. The property's values - * must be the last arguments and their type *must* match that of the - * property itself. On error, @c 0 is returned. - */ EAPI Eina_Bool evas_object_box_option_property_set(Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) { @@ -2397,13 +2077,6 @@ evas_object_box_option_property_set(Evas_Object *o, Evas_Object_Box_Option *opt, return ret; } -/** - * Set the property (with id @a property) of the child element of the - * box @a o whose property struct is @a opt. The property's values - * must be the args which the va_list @a args is initialized with and - * their type *must* match that of the property itself. On error, @c 0 - * is returned. - */ EAPI Eina_Bool evas_object_box_option_property_vset(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) @@ -2425,12 +2098,6 @@ evas_object_box_option_property_vset(Evas_Object *o, Evas_Object_Box_Option *opt return EINA_TRUE; } -/** - * Get the property (with id @a property) of the child element of the - * box @a o whose property struct is @a opt. The last arguments must - * be addresses of variables with the same type of that property. On - * error, @c 0 is returned. - */ EAPI Eina_Bool evas_object_box_option_property_get(Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) { @@ -2444,12 +2111,6 @@ evas_object_box_option_property_get(Evas_Object *o, Evas_Object_Box_Option *opt, return ret; } -/** - * Get the property (with id @a property) of the child element of the - * box @a o whose property struct is @a opt. The args which the - * va_list @a args is initialized with must be addresses of variables - * with the same type of that property. On error, @c 0 is returned. - */ EAPI Eina_Bool evas_object_box_option_property_vget(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) { @@ -2465,7 +2126,3 @@ evas_object_box_option_property_vget(Evas_Object *o, Evas_Object_Box_Option *opt return api->property_get(o, opt, property, args); } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_object_image.c b/legacy/evas/src/lib/canvas/evas_object_image.c index 2940f9da53..960ed87a1b 100644 --- a/legacy/evas/src/lib/canvas/evas_object_image.c +++ b/legacy/evas/src/lib/canvas/evas_object_image.c @@ -136,20 +136,8 @@ static const Evas_Object_Func object_func = evas_object_image_can_map }; - -/** - * @addtogroup Evas_Object_Image - * @{ - */ - EVAS_MEMPOOL(_mp_obj); -/** - * Creates a new image object on the given evas. - * - * @param e The given evas. - * @return The created image object. - */ EAPI Evas_Object * evas_object_image_add(Evas *e) { @@ -168,17 +156,6 @@ evas_object_image_add(Evas *e) return obj; } -/** - * Creates a new image object that automatically scales on the given evas. - * - * This is a helper around evas_object_image_add() and - * evas_object_image_filled_set(), it will track object resizes and apply - * evas_object_image_fill_set() with the new geometry. - * - * @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) { @@ -251,29 +228,6 @@ _create_tmpf(Evas_Object *obj, void *data, int size, char *format __UNUSED__) munmap(dst, size); } -/** - * Sets the data for an image from memory to be loaded - * - * This 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 @p data at the address is copied and stored for future use, so - * no @p data needs to be kept after this call is made. It will be managed and - * freed for you when no longer needed. The @p size is limited to 2 gigabytes - * in size, and must be greater than 0. A NULL @p data pointer is also invalid. - * Set the filename to NULL to reset to empty state and have the image file - * data freed from memory using evas_object_image_file_set(). - * - * The @p format is optional (pass NULL if you don't 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" or "png" or "gif" etc. - * - * @param obj The given image object. - * @param data The image file data address - * @param size The size of the image file data in bytes - * @param format The format of the file (optional), or NULL if not needed - * @param key The image key in file, or NULL. - */ EAPI void evas_object_image_memfile_set(Evas_Object *obj, void *data, int size, char *format, char *key) { @@ -302,16 +256,6 @@ evas_object_image_memfile_set(Evas_Object *obj, void *data, int size, char *form evas_object_image_alpha_set(obj, !o->cur.has_alpha); } -/** - * Sets the filename and key of the given image object. - * - * If the file supports multiple data stored in it as eet, you can - * specify the key to be used as the index of the image in this file. - * - * @param obj The given image object. - * @param file The image filename. - * @param key The image key in file, or NULL. - */ EAPI void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) { @@ -405,13 +349,6 @@ evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) evas_object_change(obj); } -/** - * Retrieves the filename and key of the given image object. - * - * @param obj The given image object. - * @param file Location to store the image filename, or NULL. - * @param key Location to store the image key, or NULL. - */ EAPI void evas_object_image_file_get(const Evas_Object *obj, const char **file, const char **key) { @@ -432,22 +369,6 @@ evas_object_image_file_get(const Evas_Object *obj, const char **file, const char if (key) *key = o->cur.key; } -/** - * Set the source object on a proxy object. - * - * The source must be another object. The proxy will have the same base - * appearance of the source object. Obviously other effects may be applied to - * the proxy, such as a map to create a reflection of the original object. - * - * Any existing source object will be removed. Setting the src to NULL clears - * the proxy object. - * - * You cannot set a proxy on a proxy. - * - * @param obj Proxy object. - * @param src Source of the proxy. - * @return EINA_TRUE on success, EINA_FALSE on error. - */ EAPI Eina_Bool evas_object_image_source_set(Evas_Object *obj, Evas_Object *src) { @@ -482,12 +403,6 @@ evas_object_image_source_set(Evas_Object *obj, Evas_Object *src) } -/** - * Get the current source object of an image. - * - * @param obj Image object - * @return Source object, or NULL on error. - */ EAPI Evas_Object * evas_object_image_source_get(Evas_Object *obj) { @@ -504,39 +419,12 @@ evas_object_image_source_get(Evas_Object *obj) return o->cur.source; } -/** - * Clear the source on a proxy image. - * - * This is equivalent to calling evas_object_image_source_set with a NULL - * source. - * - * @param obj Image object to clear source of. - * @return EINA_TRUE on success, EINA_FALSE on error. - */ EAPI Eina_Bool evas_object_image_source_unset(Evas_Object *obj) { return evas_object_image_source_set(obj, NULL); } -/** - * Sets how much of each border of the given image object is not - * to be scaled. - * - * When rendering, the image may be scaled to fit the size of the - * image object. This function sets what area around the border of the - * image is not to be scaled. This sort of function is useful for - * widget theming, where, for example, buttons may be of varying - * sizes, but the border size must remain constant. - * - * The units used for @p l, @p r, @p t and @p b are output units. - * - * @param obj The given image object. - * @param l Distance of the left border that is not to be stretched. - * @param r Distance of the right border that is not to be stretched. - * @param t Distance of the top border that is not to be stretched. - * @param b Distance of the bottom border that is not to be stretched. - */ EAPI void evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) { @@ -566,18 +454,6 @@ evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) evas_object_change(obj); } -/** - * Retrieves how much of each border of the given image object is not - * to be scaled. - * - * See @ref evas_object_image_border_set for more details. - * - * @param obj The given image object. - * @param l Location to store the left border width in, or NULL. - * @param r Location to store the right border width in, or NULL. - * @param t Location to store the top border width in, or NULL. - * @param b Location to store the bottom border width in, or NULL. - */ EAPI void evas_object_image_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) { @@ -604,18 +480,6 @@ evas_object_image_border_get(const Evas_Object *obj, int *l, int *r, int *t, int if (b) *b = o->cur.border.b; } -/** - * Sets if the center part of the given image object (not the border) - * should be drawn. - * - * When rendering, the image may be scaled to fit the size of the - * image object. This function sets if the center part of the scaled - * image is to be drawn or left completely blank, or forced to be - * solid. Very useful for frames and decorations. - * - * @param obj The given image object. - * @param fill Fill mode of the middle. - */ EAPI void evas_object_image_border_center_fill_set(Evas_Object *obj, Evas_Border_Fill_Mode fill) { @@ -634,15 +498,6 @@ evas_object_image_border_center_fill_set(Evas_Object *obj, Evas_Border_Fill_Mode evas_object_change(obj); } -/** - * Retrieves if the center of the given image object is to be drawn or - * not. - * - * See @ref evas_object_image_fill_set for more details. - * - * @param obj The given image object. - * @return Fill mode of the center. - */ EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get(const Evas_Object *obj) { @@ -658,19 +513,6 @@ evas_object_image_border_center_fill_get(const Evas_Object *obj) return o->cur.border.fill; } -/** - * Sets if image fill property should track object size. - * - * If set to true, then every evas_object_resize() will automatically - * trigger call to evas_object_image_fill_set() with the new size so - * image will fill the whole object area. - * - * @param obj The given image object. - * @param setting whether to follow object size. - * - * @see evas_object_image_filled_add() - * @see evas_object_image_fill_set() - */ EAPI void evas_object_image_filled_set(Evas_Object *obj, Eina_Bool setting) { @@ -701,13 +543,6 @@ evas_object_image_filled_set(Evas_Object *obj, Eina_Bool setting) } } -/** - * Retrieves if image fill property is tracking object size. - * - * @param obj The given image object. - * @return 1 if it is tracking, 0 if not and evas_object_fill_set() - * must be called manually. - */ EAPI Eina_Bool evas_object_image_filled_get(const Evas_Object *obj) { @@ -724,12 +559,6 @@ evas_object_image_filled_get(const Evas_Object *obj) return o->filled; } -/** - * Sets a scale factor (multiplier) for the borders of an image - * - * @param obj The given image object. - * @param scale The scale factor (default is 1.0 - i.e. no scale) - */ EAPI void evas_object_image_border_scale_set(Evas_Object *obj, double scale) { @@ -748,14 +577,6 @@ evas_object_image_border_scale_set(Evas_Object *obj, double scale) evas_object_change(obj); } -/** - * Retrieves the border scale factor - * - * See evas_object_image_border_scale_set() - * - * @param obj The given image object. - * @return The scale factor - */ EAPI double evas_object_image_border_scale_get(const Evas_Object *obj) { @@ -771,24 +592,6 @@ evas_object_image_border_scale_get(const Evas_Object *obj) return o->cur.border.scale; } -/** - * Sets the rectangle of the given image object that the image will be - * drawn to. - * - * Note that the image will be tiled around this one rectangle. To - * have only one copy of the image drawn, @p x and @p y must be 0 and - * @p w and @p h need to be the width and height of the image object - * respectively. - * - * The default values for the fill parameters is @p x = 0, @p y = 0, - * @p w = 32 and @p h = 32. - * - * @param obj The given image object. - * @param x The X coordinate for the top left corner of the image. - * @param y The Y coordinate for the top left corner of the image. - * @param w The width of the image. - * @param h The height of the image. - */ EAPI void evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) { @@ -818,18 +621,6 @@ evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Co evas_object_change(obj); } -/** - * Retrieves the dimensions of the rectangle of the given image object - * that the image will be drawn to. - * - * See @ref evas_object_image_fill_set for more details. - * - * @param obj The given image object. - * @param x Location to store the X coordinate for the top left corner of the image in, or NULL. - * @param y Location to store the Y coordinate for the top left corner of the image in, or NULL. - * @param w Location to store the width of the image in, or NULL. - * @param h Location to store the height of the image in, or NULL. - */ EAPI void evas_object_image_fill_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) { @@ -857,12 +648,6 @@ evas_object_image_fill_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, } -/** - * Sets the tiling mode for the given evas image object's fill. - * @param obj The given evas image object. - * @param 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) { @@ -881,13 +666,6 @@ evas_object_image_fill_spread_set(Evas_Object *obj, Evas_Fill_Spread spread) evas_object_change(obj); } -/** - * Retrieves the spread (tiling mode) for the given image object's - * fill. - * - * @param 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) { @@ -903,19 +681,6 @@ evas_object_image_fill_spread_get(const Evas_Object *obj) return (Evas_Fill_Spread)o->cur.spread; } -/** - * Sets the size of the given image object. - * - * This function will scale down or crop 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 will be cropped. If the size given is - * larger, then the image will be treated as if it were in the upper - * left hand corner of a larger image that is otherwise transparent. - * - * @param obj The given image object. - * @param w The new width of the image. - * @param h The new height of the image. - */ EAPI void evas_object_image_size_set(Evas_Object *obj, int w, int h) { @@ -978,15 +743,6 @@ evas_object_image_size_set(Evas_Object *obj, int w, int h) evas_object_change(obj); } -/** - * Retrieves the size of the given image object. - * - * See @ref evas_object_image_size_set for more details. - * - * @param obj The given image object. - * @param w Location to store the width of the image in, or NULL. - * @param h Location to store the height of the image in, or NULL. - */ EAPI void evas_object_image_size_get(const Evas_Object *obj, int *w, int *h) { @@ -1007,15 +763,6 @@ evas_object_image_size_get(const Evas_Object *obj, int *w, int *h) if (h) *h = o->cur.image.h; } -/** - * Retrieves the row stride of the given image object, - * - * The row stride is the number of units between the start of a - * row and the start of the next row. - * - * @param obj The given image object. - * @return The stride of the image. - */ EAPI int evas_object_image_stride_get(const Evas_Object *obj) { @@ -1031,15 +778,6 @@ evas_object_image_stride_get(const Evas_Object *obj) return o->cur.image.stride; } -/** - * Retrieves a number representing any error that occurred during the last - * load of the given image object. - * - * @param obj The given image object. - * @return A value giving the last error that occurred. It should be one of - * the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is - * returned if there was no error. - */ EAPI Evas_Load_Error evas_object_image_load_error_get(const Evas_Object *obj) { @@ -1055,22 +793,6 @@ evas_object_image_load_error_get(const Evas_Object *obj) return o->load_error; } -/** - * Converts the raw image data of the given image object to the - * specified colorspace. - * - * 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 NULL is returned. You should use - * evas_object_image_colorspace_get() to check the current image - * colorspace. - * - * See @ref evas_object_image_colorspace_get. - * - * @param obj The given image object. - * @param to_cspace The colorspace to which the image raw data will be converted. - * @return data A newly allocated data in the format specified by to_cspace. - */ EAPI void * evas_object_image_data_convert(Evas_Object *obj, Evas_Colorspace to_cspace) { @@ -1094,15 +816,6 @@ evas_object_image_data_convert(Evas_Object *obj, Evas_Colorspace to_cspace) return evas_object_image_data_convert_internal(o, data, to_cspace); } -/** - * Sets the raw image data of the given image object. - * - * Note that the raw data must be of the same size and colorspace of - * the image. If data is NULL the current image data will be freed. - * - * @param obj The given image object. - * @param data The raw data, or NULL. - */ EAPI void evas_object_image_data_set(Evas_Object *obj, void *data) { @@ -1182,21 +895,6 @@ evas_object_image_data_set(Evas_Object *obj, void *data) evas_object_change(obj); } -/** - * Get a pointer to the raw image data of the given image object. - * - * 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 will be marked dirty so that it gets redrawn at - * the next update. - * - * This is best suited when you want to modify an existing image, - * without changing its dimensions. - * - * @param obj The given image object. - * @param for_writing Whether the data being retrieved will be modified. - * @return The raw image data. - */ EAPI void * evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing) { @@ -1249,20 +947,6 @@ evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing) return data; } -/** - * Preload image in the background - * - * This function request the preload of the data image in the - * background. The worked is queued before being processed. - * - * If image data is already loaded, it will callback - * EVAS_CALLBACK_IMAGE_PRELOADED immediatelly and do nothing else. - * - * If cancel is set, it will remove the image from the workqueue. - * - * @param obj The given image object. - * @param cancel 0 means add to the workqueue, 1 remove it. - */ EAPI void evas_object_image_preload(Evas_Object *obj, Eina_Bool cancel) { @@ -1290,28 +974,6 @@ evas_object_image_preload(Evas_Object *obj, Eina_Bool cancel) obj); } -/** - * Replaces the raw image data of the given image object. - * - * This function lets the application replace an image object's - * internal pixel buffer with a 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. - * - * This call is best suited for when you will be 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. - * - * Note that the caller is responsible for freeing the buffer when - * finished with it, as user-set image data will not be automatically - * freed when the image object is deleted. - * - * See @ref evas_object_image_data_get for more details. - * - * @param obj The given image object. - * @param data The raw data. - */ EAPI void evas_object_image_data_copy_set(Evas_Object *obj, void *data) { @@ -1363,18 +1025,6 @@ evas_object_image_data_copy_set(Evas_Object *obj, void *data) EVAS_OBJECT_IMAGE_FREE_FILE_AND_KEY(o); } -/** - * Mark a sub-region of the given image object to be redrawn. - * - * This function schedules a particular rectangular region of an image - * object to be updated (redrawn) at the next render. - * - * @param obj The given image object. - * @param x X-offset of the region to be updated. - * @param y Y-offset of the region to be updated. - * @param w Width of the region to be updated. - * @param h 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) { @@ -1396,18 +1046,6 @@ evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h) evas_object_change(obj); } -/** - * Enable or disable alpha channel of the given image object. - * - * This function sets a flag on an image object indicating whether or - * not to use alpha channel data. A value of 1 indicates to use alpha - * channel data, and 0 indicates to ignore any alpha channel - * data. Note that this has nothing to do with an object's color as - * manipulated by evas_object_color_set(). - * - * @param obj The given image object. - * @param has_alpha Whether to use alpha channel data or not. - */ EAPI void evas_object_image_alpha_set(Evas_Object *obj, Eina_Bool has_alpha) { @@ -1455,17 +1093,6 @@ evas_object_image_alpha_set(Evas_Object *obj, Eina_Bool has_alpha) } -/** - * @brief Retrieves the alpha channel setting of the given image object. - * - * @param obj The given image object. - * @return Whether the alpha channel data is being used. - * - * This function returns 1 if the image object's alpha channel is - * being used, or 0 otherwise. - * - * See @ref evas_object_image_alpha_set for more details. - */ EAPI Eina_Bool evas_object_image_alpha_get(const Evas_Object *obj) { @@ -1481,17 +1108,6 @@ evas_object_image_alpha_get(const Evas_Object *obj) return o->cur.has_alpha; } -/** - * Sets whether to use of high-quality image scaling algorithm - * of the given image object. - * - * When enabled, a higher quality image scaling algorithm is used when - * scaling images to sizes other than the source image. This gives - * better results but is more computationally expensive. - * - * @param obj The given image object. - * @param smooth_scale Whether to use smooth scale or not. - */ EAPI void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smooth_scale) { @@ -1512,15 +1128,6 @@ evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smooth_scale) evas_object_change(obj); } -/** - * Retrieves whether the given image object is using use a - * high-quality image scaling algorithm. - * - * See @ref evas_object_image_smooth_scale_set for more details. - * - * @param obj The given image object. - * @return Whether smooth scale is being used. - */ EAPI Eina_Bool evas_object_image_smooth_scale_get(const Evas_Object *obj) { @@ -1536,14 +1143,6 @@ evas_object_image_smooth_scale_get(const Evas_Object *obj) return o->cur.smooth_scale; } -/** - * Reload a image of the canvas. - * - * @param obj The given image object pointer. - * - * This function reloads a image of the given canvas. - * - */ EAPI void evas_object_image_reload(Evas_Object *obj) { @@ -1569,22 +1168,6 @@ evas_object_image_reload(Evas_Object *obj) evas_object_change(obj); } -/** - * Save the given image object to a file. - * - * Note that you should pass the filename extension when saving. If - * the file supports multiple data stored in it as eet, you can - * specify the key to be used as the index of the image in this file. - * - * You can specify some flags when saving the image. Currently - * acceptable flags are quality and compress. Eg.: "quality=100 - * compress=9" - * - * @param obj The given image object. - * @param file The filename to be used to save the image. - * @param key The image key in file, or NULL. - * @param flags String containing the flags to be used. - */ EAPI Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags) { @@ -1651,15 +1234,6 @@ evas_object_image_save(const Evas_Object *obj, const char *file, const char *key return ok; } -/** - * Import pixels from given source to a given canvas image object. - * - * @param obj The given canvas object. - * @param pixels The pixel's source to be imported. - * - * This function imports pixels from a given source to a given canvas image. - * - */ EAPI Eina_Bool evas_object_image_pixels_import(Evas_Object *obj, Evas_Pixel_Import_Source *pixels) { @@ -1746,17 +1320,6 @@ evas_object_image_pixels_import(Evas_Object *obj, Evas_Pixel_Import_Source *pixe return 1; } -/** - * Set the callback function to get pixels from a canva's image. - * - * @param obj The given canvas pointer. - * @param func The callback function. - * @param data The data pointer to be passed to @a func. - * - * This functions sets a function to be the callback function that get - * pixes from a image of the canvas. - * - */ EAPI void evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pixels_Get_Cb func, void *data) { @@ -1773,12 +1336,6 @@ evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pi o->func.get_pixels_data = data; } -/** - * Mark whether the given image object is dirty (needs to be redrawn). - * - * @param obj The given image object. - * @param dirty Whether the image is dirty. - */ EAPI void evas_object_image_pixels_dirty_set(Evas_Object *obj, Eina_Bool dirty) { @@ -1797,12 +1354,6 @@ evas_object_image_pixels_dirty_set(Evas_Object *obj, Eina_Bool dirty) evas_object_change(obj); } -/** - * Retrieves whether the given image object is dirty (needs to be redrawn). - * - * @param obj The given image object. - * @return Whether the image is dirty. - */ EAPI Eina_Bool evas_object_image_pixels_dirty_get(const Evas_Object *obj) { @@ -1819,15 +1370,6 @@ evas_object_image_pixels_dirty_get(const Evas_Object *obj) return 0; } -/** - * Set the dpi resolution of a loaded image of the canvas. - * - * @param obj The given canvas pointer. - * @param dpi The new dpi resolution. - * - * This function set the dpi resolution of a given loaded canvas image. - * - */ EAPI void evas_object_image_load_dpi_set(Evas_Object *obj, double dpi) { @@ -1852,15 +1394,6 @@ evas_object_image_load_dpi_set(Evas_Object *obj, double dpi) } } -/** - * Get the dpi resolution of a loaded image of the canvas. - * - * @param obj The given canvas pointer. - * @return The dpi resolution of the given canvas image. - * - * This function returns the dpi resolution of given canvas image. - * - */ EAPI double evas_object_image_load_dpi_get(const Evas_Object *obj) { @@ -1876,16 +1409,6 @@ evas_object_image_load_dpi_get(const Evas_Object *obj) return o->load_opts.dpi; } -/** - * Set the size of a loaded image of the canvas. - * - * @param obj The given canvas object. - * @param w The new width of the canvas image given. - * @param h The new height of the canvas image given. - * - * This function sets a new size for the given canvas image. - * - */ EAPI void evas_object_image_load_size_set(Evas_Object *obj, int w, int h) { @@ -1911,16 +1434,6 @@ evas_object_image_load_size_set(Evas_Object *obj, int w, int h) } } -/** - * Get the size of a loaded image of the canvas. - * - * @param obj The given canvas object. - * @param w The width of the canvas image given. - * @param h The height of the canvas image given. - * - * This function get the size of the given canvas image. - * - */ EAPI void evas_object_image_load_size_get(const Evas_Object *obj, int *w, int *h) { @@ -1937,15 +1450,6 @@ evas_object_image_load_size_get(const Evas_Object *obj, int *w, int *h) if (h) *h = o->load_opts.h; } -/** - * Set the scale down of a loaded image of the canvas. - * - * @param obj The given canvas pointer. - * @param scale_down The scale to down value. - * - * This function sets the scale down of a given canvas image. - * - */ EAPI void evas_object_image_load_scale_down_set(Evas_Object *obj, int scale_down) { @@ -1970,14 +1474,6 @@ evas_object_image_load_scale_down_set(Evas_Object *obj, int scale_down) } } -/** - * Get the scale down value of given image of the canvas. - * - * @param obj The given image object pointer. - * - * This function returns the scale down value of a given canvas image. - * - */ EAPI int evas_object_image_load_scale_down_get(const Evas_Object *obj) { @@ -2039,15 +1535,6 @@ evas_object_image_load_region_get(const Evas_Object *obj, int *x, int *y, int *w if (h) *h = o->load_opts.region.h; } -/** - * Set the colorspace of a given image of the canvas. - * - * @param obj The given image object pointer. - * @param cspace The new color space. - * - * This function sets the colorspace of given canvas image. - * - */ EAPI void evas_object_image_colorspace_set(Evas_Object *obj, Evas_Colorspace cspace) { @@ -2076,15 +1563,6 @@ evas_object_image_colorspace_set(Evas_Object *obj, Evas_Colorspace cspace) cspace); } -/** - * Get the colorspace of a given image of the canvas. - * - * @param obj The given image object pointer. - * @return The colorspace of the image. - * - * This function returns the colorspace of given canvas image. - * - */ EAPI Evas_Colorspace evas_object_image_colorspace_get(const Evas_Object *obj) { @@ -2100,15 +1578,6 @@ evas_object_image_colorspace_get(const Evas_Object *obj) return o->cur.cspace; } -/** - * Set the native surface of a given image of the canvas - * - * @param obj The given canvas pointer. - * @param surf The new native surface. - * - * This function sets a native surface of a given canvas image. - * - */ EAPI void evas_object_image_native_surface_set(Evas_Object *obj, Evas_Native_Surface *surf) { @@ -2132,15 +1601,6 @@ evas_object_image_native_surface_set(Evas_Object *obj, Evas_Native_Surface *surf surf); } -/** - * Get the native surface of a given image of the canvas - * - * @param obj The given canvas pointer. - * @return The native surface of the given canvas image. - * - * This function returns the native surface of a given canvas image. - * - */ EAPI Evas_Native_Surface * evas_object_image_native_surface_get(const Evas_Object *obj) { @@ -2158,15 +1618,6 @@ evas_object_image_native_surface_get(const Evas_Object *obj) o->engine_data); } -/** - * Set the scale hint of a given image of the canvas. - * - * @param obj The given canvas pointer. - * @param hint The scale hint value. - * - * This function sets the scale hint value of the given image of the canvas. - * - */ EAPI void evas_object_image_scale_hint_set(Evas_Object *obj, Evas_Image_Scale_Hint hint) { @@ -2203,14 +1654,6 @@ evas_object_image_scale_hint_set(Evas_Object *obj, Evas_Image_Scale_Hint hint) } } -/** - * Get the scale hint of a given image of the canvas. - * - * @param obj The given canvas pointer. - * - * This function returns the scale hint value of the given image of the canvas. - * - */ EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get(const Evas_Object *obj) { @@ -2226,15 +1669,6 @@ evas_object_image_scale_hint_get(const Evas_Object *obj) return o->scale_hint; } -/** - * Set the content hint of a given image of the canvas. - * - * @param obj The given canvas pointer. - * @param hint The content hint value. - * - * This function sets the content hint value of the given image of the canvas. - * - */ EAPI void evas_object_image_content_hint_set(Evas_Object *obj, Evas_Image_Content_Hint hint) { @@ -2271,18 +1705,6 @@ evas_object_image_content_hint_set(Evas_Object *obj, Evas_Image_Content_Hint hin } } -/** - * Enable an image to be used as an alpha mask. - * - * This will set any flags, and discard any excess image data not used as an - * alpha mask. - * - * Note there is little point in using a image as alpha mask unless it has an - * alpha channel. - * - * @param obj Object to use as an alpha mask. - * @param ismask Use image as alphamask, must be true. - */ EAPI void evas_object_image_alpha_mask_set(Evas_Object *obj, Eina_Bool ismask) { @@ -2304,14 +1726,6 @@ evas_object_image_alpha_mask_set(Evas_Object *obj, Eina_Bool ismask) } -/** - * Get the content hint of a given image of the canvas. - * - * @param obj The given canvas pointer. - * - * This function returns the content hint value of the given image of the canvas. - * - */ EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get(const Evas_Object *obj) { @@ -2327,23 +1741,6 @@ evas_object_image_content_hint_get(const Evas_Object *obj) return o->content_hint; } -/** - * @} - */ - -/** - * @addtogroup Evas_Image_Group - * @{ - */ - -/** - * Flush the image cache of the canvas. - * - * @param e The given evas pointer. - * - * This function flushes image cache of canvas. - * - */ EAPI void evas_image_cache_flush(Evas *e) { @@ -2354,14 +1751,6 @@ evas_image_cache_flush(Evas *e) e->engine.func->image_cache_flush(e->engine.data.output); } -/** - * Reload the image cache - * - * @param e The given evas pointer. - * - * This function reloads the image cache of canvas. - * - */ EAPI void evas_image_cache_reload(Evas *e) { @@ -2409,15 +1798,6 @@ evas_image_cache_reload(Evas *e) evas_image_cache_flush(e); } -/** - * Set the image cache. - * - * @param e The given evas pointer. - * @param size The cache size. - * - * This function sets the image cache of canvas. - * - */ EAPI void evas_image_cache_set(Evas *e, int size) { @@ -2429,14 +1809,6 @@ evas_image_cache_set(Evas *e, int size) e->engine.func->image_cache_set(e->engine.data.output, size); } -/** - * Set the image cache - * - * @param e The given evas pointer. - * - * This function returns the image cache of canvas. - * - */ EAPI int evas_image_cache_get(const Evas *e) { @@ -2447,10 +1819,6 @@ evas_image_cache_get(const Evas *e) return e->engine.func->image_cache_get(e->engine.data.output); } -/** - * @} - */ - /* all nice and private */ static void _proxy_unset(Evas_Object *proxy) diff --git a/legacy/evas/src/lib/canvas/evas_object_intercept.c b/legacy/evas/src/lib/canvas/evas_object_intercept.c index bf13a403f0..c3e5e244d8 100644 --- a/legacy/evas/src/lib/canvas/evas_object_intercept.c +++ b/legacy/evas/src/lib/canvas/evas_object_intercept.c @@ -239,24 +239,6 @@ evas_object_intercept_call_clip_unset(Evas_Object *obj) /* public calls */ -/** - * @addtogroup Evas_Object_Group_Interceptors - * @{ - */ - -/** - * Set the callback function that intercepts a show event of a object. - * - * @param obj The given canvas object pointer. - * @param func The given function to be the callback function. - * @param data The data passed to the callback function. - * - * This function sets a callback function to intercepts a show event - * of a canvas object. - * - * @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) { @@ -272,19 +254,6 @@ evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_ obj->interceptors->show.data = (void *)data; } -/** - * Unset the callback function that intercepts a show event of a - * object. - * - * @param obj The given canvas object pointer. - * @param func The given callback function. - * - * This function sets a callback function to intercepts a show event - * of a canvas object. - * - * @see evas_object_intercept_show_callback_add(). - * - */ EAPI void * evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) { @@ -303,19 +272,6 @@ evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object_Intercept_ return data; } -/** - * Set the callback function that intercepts a hide event of a object. - * - * @param obj The given canvas object pointer. - * @param func The given function to be the callback function. - * @param data The data passed to the callback function. - * - * This function sets a callback function to intercepts a hide event - * of a canvas object. - * - * @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) { @@ -330,19 +286,6 @@ evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_ obj->interceptors->hide.data = (void *)data; } -/** - * Unset the callback function that intercepts a hide event of a - * object. - * - * @param obj The given canvas object pointer. - * @param func The given callback function. - * - * This function sets a callback function to intercepts a hide event - * of a canvas object. - * - * @see evas_object_intercept_hide_callback_add(). - * - */ EAPI void * evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) { @@ -361,19 +304,6 @@ evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_ return data; } -/** - * Set the callback function that intercepts a move event of a object. - * - * @param obj The given canvas object pointer. - * @param func The given function to be the callback function. - * @param data The data passed to the callback function. - * - * This function sets a callback function to intercepts a move event - * of a canvas object. - * - * @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) { @@ -388,19 +318,6 @@ evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_ obj->interceptors->move.data = (void *)data; } -/** - * Unset the callback function that intercepts a move event of a - * object. - * - * @param obj The given canvas object pointer. - * @param func The given callback function. - * - * This function sets a callback function to intercepts a move event - * of a canvas object. - * - * @see evas_object_intercept_move_callback_add(). - * - */ EAPI void * evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) { @@ -419,12 +336,6 @@ evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_ return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) { @@ -439,12 +350,6 @@ evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercep obj->interceptors->resize.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) { @@ -463,12 +368,6 @@ evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercep return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) { @@ -483,12 +382,6 @@ evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept obj->interceptors->raise.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) { @@ -507,12 +400,6 @@ evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) { @@ -527,12 +414,6 @@ evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept obj->interceptors->lower.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) { @@ -551,12 +432,6 @@ evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) { @@ -571,12 +446,6 @@ evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Int obj->interceptors->stack_above.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) { @@ -595,12 +464,6 @@ evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Int return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) { @@ -615,12 +478,6 @@ evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Int obj->interceptors->stack_below.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) { @@ -639,12 +496,6 @@ evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Int return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) { @@ -659,12 +510,6 @@ evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Inter obj->interceptors->layer_set.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) { @@ -683,12 +528,6 @@ evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Inter return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) { @@ -703,12 +542,6 @@ evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Inter obj->interceptors->color_set.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) { @@ -727,12 +560,6 @@ evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Inter return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) { @@ -747,12 +574,6 @@ evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Interc obj->interceptors->clip_set.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) { @@ -771,12 +592,6 @@ evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Interc return data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) { @@ -791,12 +606,6 @@ evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Inte obj->interceptors->clip_unset.data = (void *)data; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void * evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) { @@ -814,7 +623,3 @@ evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Inte evas_object_intercept_deinit(obj); return data; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_object_line.c b/legacy/evas/src/lib/canvas/evas_object_line.c index f835aeef1f..c7f9dce5ad 100644 --- a/legacy/evas/src/lib/canvas/evas_object_line.c +++ b/legacy/evas/src/lib/canvas/evas_object_line.c @@ -72,19 +72,8 @@ static const Evas_Object_Func object_func = /* the actual api call to add a rect */ /* it has no other api calls as all properties are standard */ - -/** - * @addtogroup Evas_Line_Group - * @{ - */ - EVAS_MEMPOOL(_mp_obj); -/** - * Adds a new evas line object to the given evas. - * @param e The given evas. - * @return The new evas line object. - */ EAPI Evas_Object * evas_object_line_add(Evas *e) { @@ -99,14 +88,6 @@ evas_object_line_add(Evas *e) return obj; } -/** - * Sets the coordinates of the end points of the given evas line object. - * @param obj The given evas line object. - * @param x1 The X coordinate of the first point. - * @param y1 The Y coordinate of the first point. - * @param x2 The X coordinate of the second point. - * @param 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) { @@ -182,18 +163,6 @@ evas_object_line_xy_set(Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coo evas_object_inform_call_resize(obj); } -/** - * Retrieves the coordinates of the end points of the given evas line object. - * @param obj The given line object. - * @param x1 Pointer to an integer in which to store the X coordinate of the - * first end point. - * @param y1 Pointer to an integer in which to store the Y coordinate of the - * first end point. - * @param x2 Pointer to an integer in which to store the X coordinate of the - * second end point. - * @param y2 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) { @@ -220,10 +189,6 @@ evas_object_line_xy_get(const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, if (y2) *y2 = obj->cur.geometry.y + o->cur.y2; } -/** - * @} - */ - /* all nice and private */ static void evas_object_line_init(Evas_Object *obj) diff --git a/legacy/evas/src/lib/canvas/evas_object_main.c b/legacy/evas/src/lib/canvas/evas_object_main.c index c7a58da663..f7b7ee8865 100644 --- a/legacy/evas/src/lib/canvas/evas_object_main.c +++ b/legacy/evas/src/lib/canvas/evas_object_main.c @@ -355,20 +355,6 @@ evas_object_was_inside(Evas_Object *obj, Evas_Coord x, Evas_Coord y) } /* routines apps will call */ -/** - * Increments object reference count to defer deletion - * - * This increments the reference count of an object, which if greater than - * 0 will defer deletion by evas_object_del() until all references are - * released back to 0. References cannot go below 0 and unreferencing more - * times that referencing will result in the reference count being limited - * to 0. References are limited to 2^32 - 1 for an object. Referencing it more - * than this will result in it being limited to this value. - * - * @param obj The given evas object to reference - * @ingroup Evas_Object_Group_Basic - * @since 1.1.0 - */ EAPI void evas_object_ref(Evas_Object *obj) { @@ -379,18 +365,6 @@ evas_object_ref(Evas_Object *obj) if (obj->ref == 0) obj->ref--; } -/** - * Decrements object reference count to defer deletion - * - * This decrements the reference count of an object. If the object has had - * evas_object_del() called on it while references were more than 0, it will - * be deleted at the time this function is called as it normally would have - * been. See evas_object_ref() for more information. - * - * @param obj The given evas object to unreference - * @ingroup Evas_Object_Group_Basic - * @since 1.1.0 - */ EAPI void evas_object_unref(Evas_Object *obj) { @@ -402,16 +376,6 @@ evas_object_unref(Evas_Object *obj) if ((obj->del_ref) && (obj->ref == 0)) evas_object_del(obj); } -/** - * Deletes the given evas object and frees its memory. - * - * The object's 'free' callback is called when this function is called. - * If the object currently has the focus, its 'focus out' callback is - * also called. - * - * @param obj The given evas object. - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_del(Evas_Object *obj) { @@ -467,13 +431,6 @@ evas_object_del(Evas_Object *obj) evas_object_change(obj); } -/** - * Moves the given evas object to the given location. - * @param obj The given evas object. - * @param x X position to move the object to, in canvas units. - * @param y 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) { @@ -533,30 +490,6 @@ evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) evas_object_inform_call_move(obj); } -/** - * Changes the size of the given evas object. - * @param obj The given evas object. - * @param w The new width of the evas object. - * @param h The new height of the evas object. - * - * @note 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. 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 - * This is more evident in images, but text, textblock, lines - * and polygons will behave similarly. Check their specific APIs - * to know how to achieve your desired behavior. - * - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h) { @@ -620,23 +553,6 @@ evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h) evas_object_inform_call_resize(obj); } -/** - * Retrieves the position and rectangular size of the given evas object. - * - * Note that if any of @p x, @p y, @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param x Pointer to an integer in which to store the X coordinate of - * the object. - * @param y Pointer to an integer in which to store the Y coordinate of - * the object. - * @param w Pointer to an integer in which to store the width of the - * object. - * @param h 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) { @@ -655,11 +571,6 @@ evas_object_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, E if (h) *h = obj->cur.geometry.h; } -/** - * @addtogroup Evas_Object_Group_Size_Hints - * @{ - */ - static void _evas_object_size_hint_alloc(Evas_Object *obj) { @@ -675,19 +586,6 @@ _evas_object_size_hint_alloc(Evas_Object *obj) obj->size_hints->align.y = 0.5; } -/** - * Retrieves the size hint for the minimum size. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param w Pointer to an integer in which to store the minimum width. - * @param h Pointer to an integer in which to store the minimum height. - */ EAPI void evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) { @@ -704,18 +602,6 @@ evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord if (h) *h = obj->size_hints->min.h; } -/** - * Sets the size hint for the minimum size. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Value 0 is considered unset. - * - * @param obj The given evas object. - * @param w Integer to use as the minimum width hint. - * @param h Integer to use as the minimum height hint. - */ EAPI void evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) { @@ -732,19 +618,6 @@ evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size hint for the maximum size. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param w Pointer to an integer in which to store the maximum width. - * @param h Pointer to an integer in which to store the maximum height. - */ EAPI void evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) { @@ -761,18 +634,6 @@ evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord if (h) *h = obj->size_hints->max.h; } -/** - * Sets the size hint for the maximum size. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Value -1 is considered unset. - * - * @param obj The given evas object. - * @param w Integer to use as the maximum width hint. - * @param h Integer to use as the maximum height hint. - */ EAPI void evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) { @@ -789,19 +650,6 @@ evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size request hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param w Pointer to an integer in which to store the requested width. - * @param h Pointer to an integer in which to store the requested height. - */ EAPI void evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) { @@ -818,18 +666,6 @@ evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Co if (h) *h = obj->size_hints->request.h; } -/** - * Sets the requested size hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Value 0 is considered unset. - * - * @param obj The given evas object. - * @param w Integer to use as the preferred width hint. - * @param h Integer to use as the preferred height hint. - */ EAPI void evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) { @@ -846,20 +682,6 @@ evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size aspect control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p aspect, @p w or @p h are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param aspect Returns the hint on how size should be calculated. - * @param w Pointer to an integer in which to store the aspect width. - * @param h Pointer to an integer in which to store the aspect height. - */ EAPI void evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h) { @@ -879,17 +701,6 @@ evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *as if (h) *h = obj->size_hints->aspect.size.h; } -/** - * Sets the size aspect control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * @param obj The given evas object. - * @param aspect Hint on how to calculate size. - * @param w Integer to use as aspect width hint. - * @param h Integer to use as aspect height hint. - */ EAPI void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) { @@ -907,19 +718,6 @@ evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, E evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size align control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p x or @p y are @c NULL, the @c NULL - * parameters are ignored. - * - * @param obj The given evas object. - * @param x Pointer to a double in which to store the align x. - * @param y Pointer to a double in which to store the align y. - */ EAPI void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y) { @@ -936,20 +734,6 @@ evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y) if (y) *y = obj->size_hints->align.y; } -/** - * Sets the size align control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Accepted values are in the 0.0 to 1.0 range, with the special value - * -1.0 used to specify "justify" or "fill" by some users. See - * documentation of possible users. - * - * @param obj The given evas object. - * @param x Double (0.0..1.0 or -1.0) to use as align x hint. - * @param y Double (0.0..1.0 or -1.0) to use as align y hint. - */ EAPI void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y) { @@ -966,23 +750,6 @@ evas_object_size_hint_align_set(Evas_Object *obj, double x, double y) evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size weight control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p x or @p y are @c NULL, the @c NULL - * parameters are ignored. - * - * Accepted values are zero or positive values. Some users might use - * this hint as a boolean, but some might consider it as a proportion, - * see documentation of possible users. - * - * @param obj The given evas object. - * @param x Pointer to a double in which to store the weight x. - * @param y Pointer to a double in which to store the weight y. - */ EAPI void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y) { @@ -999,16 +766,6 @@ evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y) if (y) *y = obj->size_hints->weight.y; } -/** - * Sets the size weight control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * @param obj The given evas object. - * @param x Double (0.0-1.0) to use as weight x hint. - * @param y Double (0.0-1.0) to use as weight y hint. - */ EAPI void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y) { @@ -1025,21 +782,6 @@ evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y) evas_object_inform_call_changed_size_hints(obj); } -/** - * Retrieves the size padding control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * Note that if any of @p l, @p r, @p t or @p b are @c NULL, the @c - * NULL parameters are ignored. - * - * @param obj The given evas object. - * @param l Pointer to an integer in which to store left padding. - * @param r Pointer to an integer in which to store right padding. - * @param t Pointer to an integer in which to store top padding. - * @param b Pointer to an integer in which to store bottom padding. - */ EAPI void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) { @@ -1060,18 +802,6 @@ evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Co if (b) *b = obj->size_hints->padding.b; } -/** - * Sets the size padding control hint. - * - * This is not a size enforcement in any way, it's just a hint that should - * be used whenever appropriate. - * - * @param obj The given evas object. - * @param l Integer to specify left padding. - * @param r Integer to specify right padding. - * @param t Integer to specify top padding. - * @param b Integer to specify bottom padding. - */ EAPI void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b) { @@ -1090,16 +820,6 @@ evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, evas_object_inform_call_changed_size_hints(obj); } - -/** - * @} - */ - -/** - * Makes the given evas object visible. - * @param obj The given evas object. - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_show(Evas_Object *obj) { @@ -1142,17 +862,6 @@ evas_object_show(Evas_Object *obj) evas_object_inform_call_show(obj); } -/** - * Makes the given evas object invisible. - * @param obj The given evas object. - * - * @note the hidden objects will not be checked for changes and will - * not catch events. That is, they are much ligher than an - * object that is invisible due indirect effects, such as - * clipped or out-of-viewport. - * - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_hide(Evas_Object *obj) { @@ -1239,12 +948,6 @@ evas_object_hide(Evas_Object *obj) evas_object_inform_call_hide(obj); } -/** - * Retrieves whether or not the given evas object is visible. - * @param obj The given evas object. - * @return @c 1 if the object is visible. @c 0 otherwise. - * @ingroup Evas_Object_Group_Basic - */ EAPI Eina_Bool evas_object_visible_get(const Evas_Object *obj) { @@ -1255,15 +958,6 @@ evas_object_visible_get(const Evas_Object *obj) return obj->cur.visible; } -/** - * Sets the general colour of the given evas object to the given colour. - * @param obj The given evas object. - * @param r The red component of the given colour. - * @param g The green component of the given colour. - * @param b The blue component of the given colour. - * @param a The alpha component of the given colour. - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a) { @@ -1294,23 +988,6 @@ evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a) evas_object_change(obj); } -/** - * Retrieves the general colour of the given evas object. - * - * Note that if any of @p r, @p g, @p b or @p a are @c NULL, then the - * @c NULL parameters are ignored. - * - * @param obj The given evas object. - * @param r Pointer to an integer in which to store the red component of - * the colour. - * @param g Pointer to an integer in which to store the green component of - * the colour. - * @param b Pointer to an integer in which to store the blue component of - * the colour. - * @param a Pointer to an integer in which to store the alpha component of - * the colour. - * @ingroup Evas_Object_Group_Basic - */ EAPI void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) { @@ -1329,13 +1006,6 @@ evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) if (a) *a = obj->cur.color.a; } -/** - * Sets whether or not the given evas object is to be drawn anti-aliased. - * - * @param obj The given evas object. - * @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise. - * @ingroup Evas_Object_Group_Extras - */ EAPI void evas_object_anti_alias_set(Evas_Object *obj, Eina_Bool anti_alias) { @@ -1349,13 +1019,6 @@ evas_object_anti_alias_set(Evas_Object *obj, Eina_Bool anti_alias) evas_object_change(obj); } - -/** - * Retrieves whether or not the given evas object is to be drawn anti_aliased. - * @param obj The given evas object. - * @return @c 1 if the object is to be anti_aliased. @c 0 otherwise. - * @ingroup Evas_Object_Group_Extras - */ EAPI Eina_Bool evas_object_anti_alias_get(const Evas_Object *obj) { @@ -1366,13 +1029,6 @@ evas_object_anti_alias_get(const Evas_Object *obj) return obj->cur.anti_alias; } -/** - * Sets the scaling factor for an evas object. Does not affect all objects. - * - * @param obj The given evas object. - * @param scale The scaling factor. 1.0 == none. - * @ingroup Evas_Object_Group_Extras - */ EAPI void evas_object_scale_set(Evas_Object *obj, double scale) { @@ -1386,14 +1042,6 @@ evas_object_scale_set(Evas_Object *obj, double scale) if (obj->func->scale_update) obj->func->scale_update(obj); } - -/** - * Retrieves the scaling factor for the given evas object. - * @param obj The given evas object. - * @return The scaling factor. - * - * @ingroup Evas_Object_Group_Extras - */ EAPI double evas_object_scale_get(const Evas_Object *obj) { @@ -1404,12 +1052,6 @@ evas_object_scale_get(const Evas_Object *obj) return obj->cur.scale; } -/** - * Sets the render_op to be used for rendering the evas object. - * @param obj The given evas object. - * @param render_op one of the Evas_Render_Op values. - * @ingroup Evas_Object_Group_Extras - */ EAPI void evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op render_op) { @@ -1423,12 +1065,6 @@ evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op render_op) evas_object_change(obj); } -/** - * Retrieves the current value of the operation used for rendering the evas object. - * @param obj The given evas object. - * @return one of the enumerated values in Evas_Render_Op. - * @ingroup Evas_Object_Group_Extras - */ EAPI Evas_Render_Op evas_object_render_op_get(const Evas_Object *obj) { @@ -1439,12 +1075,6 @@ evas_object_render_op_get(const Evas_Object *obj) return obj->cur.render_op; } -/** - * Retrieves the evas that the given evas object is on. - * @param obj The given evas object. - * @return The evas that the object is on. - * @ingroup Evas_Object_Group_Basic - */ EAPI Evas * evas_object_evas_get(const Evas_Object *obj) { @@ -1455,21 +1085,6 @@ evas_object_evas_get(const Evas_Object *obj) return obj->layer->evas; } -/** - * @addtogroup Evas_Object_Group_Find - * @{ - */ - -/** - * Retrieves the top object at the given position (x,y) - * @param e The given evas object. - * @param x The horizontal coordinate - * @param y The vertical coordinate - * @param include_pass_events_objects Boolean Flag to include or not - * pass events objects - * @param include_hidden_objects Boolean Flag to include or not hidden objects - * @return The evas object that is over all others 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) { @@ -1501,12 +1116,6 @@ evas_object_top_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool i return NULL; } -/** - * Retrieves the top object at mouse pointer position - * @param e The given evas object. - * @return The evas object that is over all others objects at the - * pointer position. - */ EAPI Evas_Object * evas_object_top_at_pointer_get(const Evas *e) { @@ -1514,18 +1123,6 @@ evas_object_top_at_pointer_get(const Evas *e) return evas_object_top_at_xy_get(e, e->pointer.x, e->pointer.y, 1, 1); } -/** - * Retrieves the top object in the given rectangle region - * @param e The given evas object. - * @param x The horizontal coordinate. - * @param y The vertical coordinate. - * @param w The width size. - * @param h The height size. - * @param include_pass_events_objects Boolean Flag to include or not pass events objects - * @param include_hidden_objects Boolean Flag to include or not hidden objects - * @return The evas object that is over all others objects at the pointer position. - * - */ 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) { @@ -1563,17 +1160,6 @@ evas_object_top_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas return NULL; } -/** - * Retrieves the objects at the given position - * @param e The given evas object. - * @param x The horizontal coordinate. - * @param y The vertical coordinate. - * @param include_pass_events_objects Boolean Flag to include or not - * pass events objects - * @param include_hidden_objects Boolean Flag to include or not hidden objects - * @return The list of evas objects at the pointer position. - * - */ 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) { @@ -1606,11 +1192,6 @@ evas_objects_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool incl return in; } -/** - * To be documented. - * - * FIXME: To be fixed. - */ /** * Retrieves the objects in the given rectangle region * @param e The given evas object. @@ -1661,10 +1242,6 @@ evas_objects_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Co return in; } -/** - * @} - */ - /** * Retrieves the name of the type of the given evas object. * @param obj The given object. diff --git a/legacy/evas/src/lib/canvas/evas_object_polygon.c b/legacy/evas/src/lib/canvas/evas_object_polygon.c index dff5cc42a2..44c3f54a60 100644 --- a/legacy/evas/src/lib/canvas/evas_object_polygon.c +++ b/legacy/evas/src/lib/canvas/evas_object_polygon.c @@ -75,18 +75,8 @@ static const Evas_Object_Func object_func = /* the actual api call to add a rect */ /* it has no other api calls as all properties are standard */ -/** - * @addtogroup Evas_Object_Polygon - * @{ - */ - EVAS_MEMPOOL(_mp_obj); -/** - * Adds a new evas polygon object to the given evas. - * @param e The given evas. - * @return A new evas polygon object. - */ EAPI Evas_Object * evas_object_polygon_add(Evas *e) { @@ -101,13 +91,6 @@ evas_object_polygon_add(Evas *e) return obj; } -/** - * Adds the given point to the given evas polygon object. - * @param obj The given evas polygon object. - * @param x The X coordinate of the given point. - * @param 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) { @@ -205,10 +188,6 @@ evas_object_polygon_point_add(Evas_Object *obj, Evas_Coord x, Evas_Coord y) evas_object_inform_call_resize(obj); } -/** - * Removes all of the points from the given evas polygon object. - * @param obj The given polygon object. - */ EAPI void evas_object_polygon_points_clear(Evas_Object *obj) { @@ -252,10 +231,6 @@ evas_object_polygon_points_clear(Evas_Object *obj) evas_object_inform_call_resize(obj); } -/** - * @} - */ - /* all nice and private */ static void evas_object_polygon_init(Evas_Object *obj) diff --git a/legacy/evas/src/lib/canvas/evas_object_rectangle.c b/legacy/evas/src/lib/canvas/evas_object_rectangle.c index 50728ffb1b..74a3d6e19b 100644 --- a/legacy/evas/src/lib/canvas/evas_object_rectangle.c +++ b/legacy/evas/src/lib/canvas/evas_object_rectangle.c @@ -66,19 +66,8 @@ static const Evas_Object_Func object_func = /* the actual api call to add a rect */ /* it has no other api calls as all properties are standard */ - -/** - * @addtogroup Evas_Object_Rectangle - * @{ - */ - EVAS_MEMPOOL(_mp_obj); -/** - * Adds a rectangle to the given evas. - * @param e The given evas. - * @return The new rectangle object. - */ EAPI Evas_Object * evas_object_rectangle_add(Evas *e) { @@ -93,10 +82,6 @@ evas_object_rectangle_add(Evas *e) return obj; } -/** - * @} - */ - /* all nice and private */ static void evas_object_rectangle_init(Evas_Object *obj) diff --git a/legacy/evas/src/lib/canvas/evas_object_smart.c b/legacy/evas/src/lib/canvas/evas_object_smart.c index cdb81d776d..446e37eae3 100644 --- a/legacy/evas/src/lib/canvas/evas_object_smart.c +++ b/legacy/evas/src/lib/canvas/evas_object_smart.c @@ -68,13 +68,6 @@ EVAS_MEMPOOL(_mp_obj); EVAS_MEMPOOL(_mp_cb); /* public funcs */ -/** - * Store a pointer to user data for a smart object. - * - * @param obj The smart object - * @param data A pointer to user data - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_data_set(Evas_Object *obj, void *data) { @@ -90,14 +83,6 @@ evas_object_smart_data_set(Evas_Object *obj, void *data) o->data = data; } -/** - * Retrieve user data stored on a smart object. - * - * @param obj The smart object - * @return A pointer to data stored using evas_object_smart_data_set(), or - * NULL if none has been set. - * @ingroup Evas_Smart_Object_Group - */ EAPI void * evas_object_smart_data_get(const Evas_Object *obj) { @@ -113,13 +98,6 @@ evas_object_smart_data_get(const Evas_Object *obj) return o->data; } -/** - * Get the Evas_Smart from which @p obj was created. - * - * @param obj a smart object - * @return the Evas_Smart - * @ingroup Evas_Smart_Object_Group - */ EAPI Evas_Smart * evas_object_smart_smart_get(const Evas_Object *obj) { @@ -135,20 +113,6 @@ evas_object_smart_smart_get(const Evas_Object *obj) return obj->smart.smart; } -/** - * Set an evas object as a member of a smart object. - * - * @param obj The member object - * @param smart_obj The smart object - * - * Members will automatically be stacked and layered with the smart object. - * The various stacking function will operate on members relative to the - * other members instead of the entire canvas. - * - * Non-member objects can not interleave a smart object's members. - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj) { @@ -209,17 +173,6 @@ evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj) smart_obj->smart.smart->smart_class->member_add(smart_obj, obj); } -/** - * Removes a member object from a smart object. - * - * @param obj the member object - * @ingroup Evas_Smart_Object_Group - * - * This removes a member object from a smart object. The object will still - * be on the canvas, but no longer associated with whichever smart object - * it was associated with. - * - */ EAPI void evas_object_smart_member_del(Evas_Object *obj) { @@ -248,12 +201,6 @@ evas_object_smart_member_del(Evas_Object *obj) evas_object_mapped_clip_across_mark(obj); } -/** - * Gets the smart parent of an Evas_Object - * @param obj the Evas_Object you want to get the parent - * @return Returns the smart parent of @a obj, or NULL if @a obj is not a smart member of another Evas_Object - * @ingroup Evas_Smart_Object_Group - */ EAPI Evas_Object * evas_object_smart_parent_get(const Evas_Object *obj) { @@ -264,13 +211,6 @@ evas_object_smart_parent_get(const Evas_Object *obj) return obj->smart.parent; } -/** - * Checks the Smart type of the object and its parents - * @param obj the Evas_Object to check the type of - * @param type the type to check for - * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise - * @ingroup Evas_Smart_Object_Group - */ EAPI Eina_Bool evas_object_smart_type_check(const Evas_Object *obj, const char *type) { @@ -293,13 +233,6 @@ evas_object_smart_type_check(const Evas_Object *obj, const char *type) return EINA_FALSE; } -/** - * Checks the Smart type of the object and its parents using pointer comparison - * @param obj the Evas_Object to check the type of - * @param type the type to check for. Must be the name pointer in the smart class used to create the object - * @return EINA_TRUE if @a obj or any of its parents if of type @a type, EINA_FALSE otherwise - * @ingroup Evas_Smart_Object_Group - */ EAPI Eina_Bool evas_object_smart_type_check_ptr(const Evas_Object *obj, const char *type) { @@ -322,12 +255,6 @@ evas_object_smart_type_check_ptr(const Evas_Object *obj, const char *type) return EINA_FALSE; } -/** - * Gets the list of the member objects of an Evas_Object - * @param obj the Evas_Object you want to get the list of member objects - * @return Returns the list of the member objects of @a obj. - * The returned list should be freed with eina_list_free() when you no longer need it - */ EAPI Eina_List * evas_object_smart_members_get(const Evas_Object *obj) { @@ -373,14 +300,6 @@ _evas_object_smart_members_all_del(Evas_Object *obj) evas_object_del((Evas_Object *)(o->contained)); } -/** - * Instantiates a new smart object described by @p s. - * - * @param e the evas on which to add the object - * @param s the Evas_Smart describing the smart object - * @return a new Evas_Object - * @ingroup Evas_Smart_Object_Group - */ EAPI Evas_Object * evas_object_smart_add(Evas *e, Evas_Smart *s) { @@ -407,15 +326,6 @@ evas_object_smart_add(Evas *e, Evas_Smart *s) return obj; } -/** - * Add a callback for the smart event specified by @p event. - * - * @param obj a smart object - * @param event the event name - * @param func the callback function - * @param data user data to be passed to the callback function - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_callback_add(Evas_Object *obj, const char *event, void (*func) (void *data, Evas_Object *obj, void *event_info), const void *data) { @@ -441,17 +351,6 @@ evas_object_smart_callback_add(Evas_Object *obj, const char *event, void (*func) o->callbacks = eina_list_prepend(o->callbacks, cb); } -/** - * Remove a smart callback - * - * Removes a callback that was added by evas_object_smart_callback_add() - * - * @param obj a smart object - * @param event the event name - * @param func the callback function - * @return the data pointer - * @ingroup Evas_Smart_Object_Group - */ EAPI void * evas_object_smart_callback_del(Evas_Object *obj, const char *event, void (*func) (void *data, Evas_Object *obj, void *event_info)) { @@ -483,19 +382,6 @@ evas_object_smart_callback_del(Evas_Object *obj, const char *event, void (*func) return NULL; } -/** - * Call any smart callbacks on @p obj for @p event. - * - * @param obj the smart object - * @param event the event name - * @param event_info an event specific struct of info to pass to the callback - * - * This should be called internally in the smart object when some specific - * event has occurred. The documentation for the smart object should include - * a list of possible events and what type of @p event_info to expect. - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_callback_call(Evas_Object *obj, const char *event, void *event_info) { @@ -530,30 +416,6 @@ evas_object_smart_callback_call(Evas_Object *obj, const char *event, void *event evas_object_smart_callbacks_clear(obj); } -/** - * Set smart object instance callbacks descriptions. - * - * These descriptions are hints to be used by introspection and are - * not enforced in any way. - * - * It will not be checked if instance callbacks descriptions have the - * same name as another in class. Both are kept in different arrays - * and users of evas_object_smart_callbacks_descriptions_get() should - * handle this case as they wish. - * - * @param obj The smart object - * @param descriptions NULL terminated (name != NULL) array with - * descriptions. Array elements will not be modified, but - * reference to them and their contents will be made, so this - * array should be kept alive during object lifetime. - * @return 1 on success, 0 on failure. - * @ingroup Evas_Smart_Object_Group - * - * @note while instance callbacks descriptions are possible, they are - * not recommended. Use class callbacks descriptions instead as they - * make user's life simpler and will use less memory as descriptions - * and arrays will be shared among all instances. - */ EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) { @@ -589,35 +451,6 @@ evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_ return 1; } -/** - * Get the callbacks descriptions known by this smart object. - * - * This call retrieves processed callbacks descriptions for both - * instance and class. These arrays are sorted by description's name - * and are @c NULL terminated, so both @a class_count and - * @a instance_count can be ignored, the terminator @c NULL is not - * counted in these values. - * - * @param obj the smart object. - * @param class_descriptions where to store class callbacks - * descriptions array, if any is known. If no descriptions are - * known, @c NULL is returned. This parameter may be @c NULL if - * it is not of interest. - * @param class_count returns how many class callbacks descriptions - * are known. - * @param instance_descriptions where to store instance callbacks - * descriptions array, if any is known. If no descriptions are - * known, @c NULL is returned. This parameter may be @c NULL if - * it is not of interest. - * @param instance_count returns how many instance callbacks - * descriptions are known. - * - * @note if just class descriptions are of interest, try - * evas_smart_callbacks_descriptions_get() instead. - * - * @see evas_smart_callbacks_descriptions_get() - * @ingroup Evas_Smart_Object_Group - */ 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) { @@ -650,22 +483,6 @@ evas_object_smart_callbacks_descriptions_get(const Evas_Object *obj, const Evas_ *instance_count = o->callbacks_descriptions.size; } -/** - * Find callback description for callback called @a name. - * - * @param obj the smart object. - * @param name name of desired callback, must @b not be @c NULL. The - * search have a special case for @a name being the same - * pointer as registered with Evas_Smart_Cb_Description, one - * can use it to avoid excessive use of strcmp(). - * @param class_description pointer to return class description or @c - * NULL if not found. If parameter is @c NULL, no search will - * be done on class descriptions. - * @param instance_description pointer to return instance description - * or @c NULL if not found. If parameter is @c NULL, no search - * will be done on instance descriptions. - * @return reference to description if found, @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) { @@ -699,25 +516,6 @@ evas_object_smart_callback_description_find(const Evas_Object *obj, const char * (&o->callbacks_descriptions, name); } -/** - * Set the need_recalculate flag of given smart object. - * - * If this flag is set then calculate() callback (method) of the given - * smart object will be called, if one is provided, during render phase - * usually evas_render(). After this step, this flag will be automatically - * unset. - * - * If no calculate() is provided, this flag will be left unchanged. - * - * @note just setting this flag will not make scene dirty and evas_render() - * will have no effect. To do that, use evas_object_smart_changed(), - * that will automatically call this function with 1 as parameter. - * - * @param obj the smart object - * @param value if one want to set or unset the need_recalculate flag. - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) { @@ -750,18 +548,6 @@ evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) /* TODO: else, remove from array */ } -/** - * Get the current value of need_recalculate flag. - * - * @note this flag will be unset during the render phase, after calculate() - * is called if one is provided. If no calculate() is provided, then - * the flag will be left unchanged after render phase. - * - * @param obj the smart object - * @return if flag is set or not. - * - * @ingroup Evas_Smart_Object_Group - */ EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) { @@ -777,13 +563,6 @@ evas_object_smart_need_recalculate_get(const Evas_Object *obj) return o->need_recalculate; } -/** - * Call user provided calculate() and unset need_calculate. - * - * @param obj the smart object - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_calculate(Evas_Object *obj) { @@ -803,13 +582,6 @@ evas_object_smart_calculate(Evas_Object *obj) obj->smart.smart->smart_class->calculate(obj); } -/** - * Call user provided calculate() and unset need_calculate on all objects. - * - * @param e The canvas to calculate all objects in - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_smart_objects_calculate(Evas *e) { @@ -855,16 +627,6 @@ evas_call_smarts_calculate(Evas *e) if (in_smart_calc == 0) eina_array_flush(calculate); } -/** - * Mark smart object as changed, dirty. - * - * This will inform the scene that it changed and needs to be redraw, also - * setting need_recalculate on the given object. - * - * @see evas_object_smart_need_recalculate_set(). - * - * @ingroup Evas_Smart_Object_Group - */ EAPI void evas_object_smart_changed(Evas_Object *obj) { diff --git a/legacy/evas/src/lib/canvas/evas_object_smart_clipped.c b/legacy/evas/src/lib/canvas/evas_object_smart_clipped.c index 3357cb4074..9b9fa6d05f 100644 --- a/legacy/evas/src/lib/canvas/evas_object_smart_clipped.c +++ b/legacy/evas/src/lib/canvas/evas_object_smart_clipped.c @@ -1,22 +1,10 @@ #include "evas_common.h" #include "evas_private.h" -/** - * @addtogroup Evas_Smart_Object_Clipped Clipped Smart Object - * @{ - */ - #define CSO_DATA_GET_OR_RETURN(obj, ptr) \ Evas_Object_Smart_Clipped_Data *ptr = evas_object_smart_data_get(obj); \ if (!ptr) return; -/** - * Moves all children objects relative to given offset. - * - * @param obj the smart evas object to use. - * @param dx horizontal offset. - * @param dy vertical offset. - */ EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) { @@ -41,14 +29,6 @@ evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_C } } -/** - * Get the clipper object for the given clipped smart object. - * - * @param obj the clipped smart object to retrieve the associated clipper. - * @return the clipper object. - * - * @see evas_object_smart_clipped_smart_add() - */ EAPI Evas_Object * evas_object_smart_clipped_clipper_get(Evas_Object *obj) { @@ -169,48 +149,6 @@ evas_object_smart_clipped_smart_member_del(Evas_Object *obj, Evas_Object *member evas_object_hide(cso->clipper); } -/** - * Set smart class callbacks so it implements the "Clipped Smart Object". - * - * This call will assign all the required methods of Evas_Smart_Class, - * if one wants to "subclass" it, call this function and later - * override values, if one wants to call the original method, save it - * somewhere, 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 ≻ - * } - * @endcode - * - * Default behavior is: - * - add: creates a hidden clipper with "infinite" size; - * - del: delete all children objects; - * - move: move all objects relative relatively; - * - resize: not defined; - * - show: if there are children objects, show clipper; - * - hide: hides clipper; - * - color_set: set the color of clipper; - * - clip_set: set clipper of clipper; - * - clip_unset: unset the clipper of clipper; - */ EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) { @@ -230,9 +168,6 @@ evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) sc->member_del = evas_object_smart_clipped_smart_member_del; } -/** - * Get a pointer to the Clipped Smart Class to use for proper inheritance - */ EAPI const Evas_Smart_Class * evas_object_smart_clipped_class_get(void) { @@ -246,7 +181,3 @@ evas_object_smart_clipped_class_get(void) class = &_sc; return class; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_object_table.c b/legacy/evas/src/lib/canvas/evas_object_table.c index 0addce1c14..a71efdc7f3 100644 --- a/legacy/evas/src/lib/canvas/evas_object_table.c +++ b/legacy/evas/src/lib/canvas/evas_object_table.c @@ -81,11 +81,6 @@ struct _Evas_Object_Table_Accessor const Evas_Object *table; }; -/** - * @addtogroup Evas_Object_Table - * @{ - */ - #define EVAS_OBJECT_TABLE_DATA_GET(o, ptr) \ Evas_Object_Table_Data *ptr = evas_object_smart_data_get(o) @@ -916,23 +911,12 @@ _evas_object_table_smart_set_user(Evas_Smart_Class *sc) sc->calculate = _evas_object_table_smart_calculate; } -/** - * Create a new table. - * - * It's set to non-homogeneous by default, add children with - * evas_object_table_pack(). - */ EAPI Evas_Object * evas_object_table_add(Evas *evas) { return evas_object_smart_add(evas, _evas_object_table_smart_class_new()); } -/** - * Create a table that is child of a given element @a parent. - * - * @see evas_object_table_add() - */ EAPI Evas_Object * evas_object_table_add_to(Evas_Object *parent) { @@ -945,48 +929,6 @@ evas_object_table_add_to(Evas_Object *parent) return o; } -/** - * Set 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 will - * be 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 will be considered as 0.5. - * - * @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 will get WIDTH / - * COLUMNS pixels. If children have minimum size that is larger - * than this amount (including padding), then it will overflow and be - * aligned respecting the alignment hint, possible overlapping sibling - * cells. @b Weight hint is used as a boolean, if greater than zero it - * will make the child expand in that axis, taking as much space as - * possible (bounded to maximum size hint). Negative alignment will be - * considered as 0.5. - * - * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM - * When homogeneous is relative to item it means the greatest minimum - * cell size will be used. That is, if no element is set to expand, - * the table will have its contents to a minimum size, the bounding - * box of all these children will be 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 will - * keep their size and the bounding box will overflow the box area, - * still respecting the alignment. @b Weight hint is used as a - * boolean, if greater than zero it will make that cell expand in that - * axis, toggling the expand mode, which makes the table behave - * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the - * bounding box will overflow and items will not overlap siblings. If - * no minimum size is provided at all then the table will fallback to - * expand mode as well. - */ EAPI void evas_object_table_homogeneous_set(Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) { @@ -998,11 +940,6 @@ evas_object_table_homogeneous_set(Evas_Object *o, Evas_Object_Table_Homogeneous_ evas_object_smart_changed(o); } -/** - * Get the current layout homogeneous mode. - * - * @see evas_object_table_homogeneous_set() - */ EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get(const Evas_Object *o) { @@ -1010,9 +947,6 @@ evas_object_table_homogeneous_get(const Evas_Object *o) return priv->homogeneous; } -/** - * Set the alignment of the whole bounding box of contents. - */ EAPI void evas_object_table_align_set(Evas_Object *o, double horizontal, double vertical) { @@ -1024,9 +958,6 @@ evas_object_table_align_set(Evas_Object *o, double horizontal, double vertical) evas_object_smart_changed(o); } -/** - * Get alignment of the whole bounding box of contents. - */ EAPI void evas_object_table_align_get(const Evas_Object *o, double *horizontal, double *vertical) { @@ -1043,9 +974,6 @@ evas_object_table_align_get(const Evas_Object *o, double *horizontal, double *ve } } -/** - * Set padding between cells. - */ EAPI void evas_object_table_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) { @@ -1058,9 +986,6 @@ evas_object_table_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord evas_object_smart_changed(o); } -/** - * Get padding between cells. - */ EAPI void evas_object_table_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) { @@ -1077,18 +1002,6 @@ evas_object_table_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas } } -/** - * Add a new child to a table object. - * - * @param o The given table object. - * @param child The child object to add. - * @param col relative-horizontal position to place child. - * @param row relative-vertical position to place child. - * @param colspan how many relative-horizontal position to use for this child. - * @param rowspan how many relative-vertical position to use for this child. - * - * @return 1 on success, 0 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) { @@ -1203,15 +1116,6 @@ _evas_object_table_remove_opt(Evas_Object_Table_Data *priv, Evas_Object_Table_Op } } -/** - * Remove child from table. - * - * @note removing a child will immediately call a walk over children in order - * to recalculate numbers of columns and rows. If you plan to remove - * all children, use evas_object_table_clear() instead. - * - * @return 1 on success, 0 on failure. - */ EAPI Eina_Bool evas_object_table_unpack(Evas_Object *o, Evas_Object *child) { @@ -1242,12 +1146,6 @@ evas_object_table_unpack(Evas_Object *o, Evas_Object *child) return EINA_TRUE; } -/** - * Faster way to remove all child objects from a table object. - * - * @param o The given table object. - * @param clear if true, it will delete just removed children. - */ EAPI void evas_object_table_clear(Evas_Object *o, Eina_Bool clear) { @@ -1270,14 +1168,6 @@ evas_object_table_clear(Evas_Object *o, Eina_Bool clear) evas_object_smart_changed(o); } -/** - * Get the number of columns and rows this table takes. - * - * @note 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 will be - * accounted proportionally. - */ EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) { @@ -1294,11 +1184,6 @@ evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) } } -/** - * Get an iterator to walk the list of children for the table. - * - * @note Do not remove or delete objects while walking the list. - */ EAPI Eina_Iterator * evas_object_table_iterator_new(const Evas_Object *o) { @@ -1323,11 +1208,6 @@ evas_object_table_iterator_new(const Evas_Object *o) return &it->iterator; } -/** - * Get an accessor to get random access to the list of children for the table. - * - * @note Do not remove or delete objects while walking the list. - */ EAPI Eina_Accessor * evas_object_table_accessor_new(const Evas_Object *o) { @@ -1352,14 +1232,6 @@ evas_object_table_accessor_new(const Evas_Object *o) return &it->accessor; } -/** - * Get the list of children for the table. - * - * @note This is a duplicate of the list kept by the table internally. - * It's up to the user to destroy it when it no longer needs it. - * It's possible to remove objects from the table when walking this - * list, but these removals won't be reflected on it. - */ EAPI Eina_List * evas_object_table_children_get(const Evas_Object *o) { @@ -1374,11 +1246,6 @@ evas_object_table_children_get(const Evas_Object *o) return new_list; } -/** - * Get a child from the table using its coordinates - * - * @note This does not take into account col/row spanning - */ Evas_Object * evas_object_table_child_get(const Evas_Object *o, unsigned short col, unsigned short row) { @@ -1393,15 +1260,6 @@ evas_object_table_child_get(const Evas_Object *o, unsigned short col, unsigned s return NULL; } -/** - * Gets the mirrored mode of the table. In mirrored mode the table items go - * from right to left instead of left to right. That is, 1,1 is top right, not - * to left. - * - * @param obj The table object. - * @return EINA_TRUE if it's a mirrored table, EINA_FALSE otherwise. - * @since 1.1.0 - */ EAPI Eina_Bool evas_object_table_mirrored_get(const Evas_Object *obj) { @@ -1410,15 +1268,6 @@ evas_object_table_mirrored_get(const Evas_Object *obj) return priv->is_mirrored; } -/** - * Sets the mirrored mode of the table. In mirrored mode the table items go - * from right to left instead of left to right. That is, 1,1 is top right, not - * to left. - * - * @param obj The table object. - * @param mirrored the mirrored mode to set - * @since 1.1.0 - */ EAPI void evas_object_table_mirrored_set(Evas_Object *obj, Eina_Bool mirrored) { @@ -1429,7 +1278,3 @@ evas_object_table_mirrored_set(Evas_Object *obj, Eina_Bool mirrored) _evas_object_table_smart_calculate_regular(obj, priv); } } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_object_text.c b/legacy/evas/src/lib/canvas/evas_object_text.c index 0c7db47358..81bda1f3f0 100644 --- a/legacy/evas/src/lib/canvas/evas_object_text.c +++ b/legacy/evas/src/lib/canvas/evas_object_text.c @@ -96,14 +96,8 @@ static const Evas_Object_Func object_func = /* the actual api call to add a rect */ /* it has no other api calls as all properties are standard */ -/** - * @addtogroup Evas_Object_Text - * @{ - */ - EVAS_MEMPOOL(_mp_obj); -/* FIXME: doc */ static int _evas_object_text_char_coords_get(const Evas_Object *obj, const Evas_Object_Text *o, @@ -123,7 +117,6 @@ _evas_object_text_char_coords_get(const Evas_Object *obj, return 0; } -/* FIXME: doc */ static void _evas_object_text_item_clean(Evas_Object_Text_Item *it) { @@ -134,7 +127,6 @@ _evas_object_text_item_clean(Evas_Object_Text_Item *it) } } -/* FIXME: doc */ static void _evas_object_text_items_clear(Evas_Object_Text *o) { @@ -165,7 +157,7 @@ _evas_object_text_it_compare_logical(const void *_it1, const void *_it2) } #endif -/* FIXME: doc */ + static int _evas_object_text_last_up_to_pos(const Evas_Object *obj, const Evas_Object_Text *o, Evas_Coord cx, Evas_Coord cy) @@ -219,7 +211,6 @@ _evas_object_text_last_up_to_pos(const Evas_Object *obj, return -1; } -/* FIXME: doc */ static int _evas_object_text_char_at_coords(const Evas_Object *obj, const Evas_Object_Text *o, Evas_Coord cx, Evas_Coord cy, @@ -243,7 +234,6 @@ _evas_object_text_char_at_coords(const Evas_Object *obj, return -1; } -/* FIXME: doc */ static Evas_Coord _evas_object_text_horiz_advance_get(const Evas_Object *obj, const Evas_Object_Text *o) @@ -260,7 +250,6 @@ _evas_object_text_horiz_advance_get(const Evas_Object *obj, return adv; } -/* FIXME: doc */ static Evas_Coord _evas_object_text_vert_advance_get(const Evas_Object *obj __UNUSED__, const Evas_Object_Text *o) @@ -299,17 +288,6 @@ _evas_object_text_string_size_get(const Evas_Object *obj, if (ch) *ch = h; } -/** - * Creates a new text @c Evas_Object on the provided @c Evas canvas. - * - * @param e The @c Evas canvas to create the text object upon. - * - * @see evas_object_text_font_source_set - * @see evas_object_text_font_set - * @see evas_object_text_text_set - * - * @returns NULL on error, A pointer to a new @c Evas_Object on success. - */ EAPI Evas_Object * evas_object_text_add(Evas *e) { @@ -324,12 +302,6 @@ evas_object_text_add(Evas *e) return obj; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_font_source_set(Evas_Object *obj, const char *font_source) { @@ -354,12 +326,6 @@ evas_object_text_font_source_set(Evas_Object *obj, const char *font_source) eina_stringshare_replace(&o->cur.source, font_source); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI const char * evas_object_text_font_source_get(const Evas_Object *obj) { @@ -375,12 +341,6 @@ evas_object_text_font_source_get(const Evas_Object *obj) return o->cur.source; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_font_set(Evas_Object *obj, const char *font, Evas_Font_Size size) { @@ -472,18 +432,6 @@ evas_object_text_font_set(Evas_Object *obj, const char *font, Evas_Font_Size siz evas_object_inform_call_resize(obj); } -/** - * Query evas for font information of a text @c Evas_Object. - * - * This function allows the font name and size of a text @c Evas_Object as - * created with evas_object_text_add() to be queried. Be aware that the font - * name string is still owned by Evas and should NOT have free() called on - * it by the caller of the function. - * - * @param obj The evas text object to query for font information. - * @param font A pointer to the location to store the font name in (may be NULL). - * @param size A pointer to the location to store the font size in (may be NULL). - */ EAPI void evas_object_text_font_get(const Evas_Object *obj, const char **font, Evas_Font_Size *size) { @@ -653,11 +601,6 @@ _evas_object_text_layout(Evas_Object *obj, Evas_Object_Text *o, const Eina_Unico } -/** - * Sets the text to be displayed by the given evas text object. - * @param obj Evas text object. - * @param text Text to display. - */ EAPI void evas_object_text_text_set(Evas_Object *obj, const char *_text) { @@ -719,11 +662,6 @@ evas_object_text_text_set(Evas_Object *obj, const char *_text) if (text) free(text); } -/** - * Retrieves the text currently being displayed by the given evas text object. - * @param obj The given evas text object. - * @return The text currently being displayed. Do not free it. - */ EAPI const char * evas_object_text_text_get(const Evas_Object *obj) { @@ -739,12 +677,6 @@ evas_object_text_text_get(const Evas_Object *obj) return o->cur.utf8_text; } -/** - * Retrieves the direction of the text currently being displayed in the - * text object. - * @param 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) { @@ -764,12 +696,6 @@ evas_object_text_direction_get(const Evas_Object *obj) return EVAS_BIDI_DIRECTION_NATURAL; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_ascent_get(const Evas_Object *obj) { @@ -785,12 +711,6 @@ evas_object_text_ascent_get(const Evas_Object *obj) return o->ascent; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_descent_get(const Evas_Object *obj) { @@ -806,12 +726,6 @@ evas_object_text_descent_get(const Evas_Object *obj) return o->descent; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_max_ascent_get(const Evas_Object *obj) { @@ -827,12 +741,6 @@ evas_object_text_max_ascent_get(const Evas_Object *obj) return o->max_ascent; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_max_descent_get(const Evas_Object *obj) { @@ -848,12 +756,6 @@ evas_object_text_max_descent_get(const Evas_Object *obj) return o->max_descent; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_inset_get(const Evas_Object *obj) { @@ -871,12 +773,6 @@ evas_object_text_inset_get(const Evas_Object *obj) return ENFN->font_inset_get(ENDT, o->engine_data, &o->items->text_props); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) { @@ -894,12 +790,6 @@ evas_object_text_horiz_advance_get(const Evas_Object *obj) return _evas_object_text_horiz_advance_get(obj, o); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Coord evas_object_text_vert_advance_get(const Evas_Object *obj) { @@ -917,24 +807,6 @@ evas_object_text_vert_advance_get(const Evas_Object *obj) return _evas_object_text_vert_advance_get(obj, o); } -/** - * Retrieve position and dimension information of a character within a text @c Evas_Object. - * - * This function is used to obtain the X, Y, width and height of a the character - * located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object - * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx, - * @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that - * parameter. - * - * @param obj The text object to retrieve position information for. - * @param pos The character position to request co-ordinates for. - * @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL). - * @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL). - * @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL). - * @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL). - * - * @returns EINA_FALSE on error, EINA_TRUE on success. - */ 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) { @@ -978,15 +850,6 @@ evas_object_text_char_pos_get(const Evas_Object *obj, int pos, Evas_Coord *cx, E } -/** - * Returns the logical position of the last char in the text - * up to the pos given. this is NOT the position of the last char - * because of the possibility of RTL in the text. - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI int evas_object_text_last_up_to_pos(const Evas_Object *obj, Evas_Coord x, Evas_Coord y) { @@ -1004,12 +867,6 @@ evas_object_text_last_up_to_pos(const Evas_Object *obj, Evas_Coord x, Evas_Coord return _evas_object_text_last_up_to_pos(obj, o, x, y - o->max_ascent); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ 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) { @@ -1052,12 +909,6 @@ evas_object_text_char_coords_get(const Evas_Object *obj, Evas_Coord x, Evas_Coor return ret; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_style_set(Evas_Object *obj, Evas_Text_Style_Type style) { @@ -1084,12 +935,6 @@ evas_object_text_style_set(Evas_Object *obj, Evas_Text_Style_Type style) evas_object_clip_dirty(obj); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI Evas_Text_Style_Type evas_object_text_style_get(const Evas_Object *obj) { @@ -1105,12 +950,6 @@ evas_object_text_style_get(const Evas_Object *obj) return o->cur.style; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_shadow_color_set(Evas_Object *obj, int r, int g, int b, int a) { @@ -1134,12 +973,6 @@ evas_object_text_shadow_color_set(Evas_Object *obj, int r, int g, int b, int a) evas_object_change(obj); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_shadow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) { @@ -1166,12 +999,6 @@ evas_object_text_shadow_color_get(const Evas_Object *obj, int *r, int *g, int *b if (a) *a = o->cur.shadow.a; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_glow_color_set(Evas_Object *obj, int r, int g, int b, int a) { @@ -1195,12 +1022,6 @@ evas_object_text_glow_color_set(Evas_Object *obj, int r, int g, int b, int a) evas_object_change(obj); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_glow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) { @@ -1227,12 +1048,6 @@ evas_object_text_glow_color_get(const Evas_Object *obj, int *r, int *g, int *b, if (a) *a = o->cur.glow.a; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_glow2_color_set(Evas_Object *obj, int r, int g, int b, int a) { @@ -1256,12 +1071,6 @@ evas_object_text_glow2_color_set(Evas_Object *obj, int r, int g, int b, int a) evas_object_change(obj); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_glow2_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) { @@ -1288,12 +1097,6 @@ evas_object_text_glow2_color_get(const Evas_Object *obj, int *r, int *g, int *b, if (a) *a = o->cur.glow2.a; } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) { @@ -1317,12 +1120,6 @@ evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) evas_object_change(obj); } -/** - * To be documented. - * - * FIXME: To be fixed. - * - */ EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) { @@ -1349,16 +1146,6 @@ evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int * if (a) *a = o->cur.outline.a; } -/** - * Gets the text style pad of a text object. - * - * @param obj The given text object. - * @param l The left pad (or NULL). - * @param r The right pad (or NULL). - * @param t The top pad (or NULL). - * @param b The bottom pad (or NULL). - * - */ EAPI void evas_object_text_style_pad_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) { @@ -1389,16 +1176,8 @@ evas_object_text_style_pad_get(const Evas_Object *obj, int *l, int *r, int *t, i } -/** - * @} - */ -/** - * Removes all font paths loaded into memory for the given evas. - * @param e The given evas. - * @ingroup Evas_Font_Path_Group - */ EAPI void evas_font_path_clear(Evas *e) { @@ -1412,12 +1191,6 @@ evas_font_path_clear(Evas *e) } } -/** - * Appends a font path to the list of font paths used by the given evas. - * @param e The given evas. - * @param path The new font path. - * @ingroup Evas_Font_Path_Group - */ EAPI void evas_font_path_append(Evas *e, const char *path) { @@ -1429,12 +1202,6 @@ evas_font_path_append(Evas *e, const char *path) e->font_path = eina_list_append(e->font_path, eina_stringshare_add(path)); } -/** - * Prepends a font path to the list of font paths used by the given evas. - * @param e The given evas. - * @param path The new font path. - * @ingroup Evas_Font_Path_Group - */ EAPI void evas_font_path_prepend(Evas *e, const char *path) { @@ -1446,12 +1213,6 @@ evas_font_path_prepend(Evas *e, const char *path) e->font_path = eina_list_prepend(e->font_path, eina_stringshare_add(path)); } -/** - * Retrieves the list of font paths used by the given evas. - * @param 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) { @@ -1478,14 +1239,6 @@ evas_font_object_rehint(Evas_Object *obj) } } -/** - * Changes the font hinting for the given evas. - * - * @param e The given evas. - * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE, - * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. - * @ingroup Evas_Font_Group - */ EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting) { @@ -1506,14 +1259,6 @@ evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting) } } -/** - * Retrieves the font hinting used by the given evas. - * - * @param e The given evas to query. - * @return The hinting in use, one of #EVAS_FONT_HINTING_NONE, - * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. - * @ingroup Evas_Font_Group - */ EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e) { @@ -1523,15 +1268,6 @@ evas_font_hinting_get(const Evas *e) return e->hinting; } -/** - * Checks if the font hinting is supported by the given evas. - * - * @param e The given evas to query. - * @param hinting The hinting to use, one of #EVAS_FONT_HINTING_NONE, - * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. - * @return @c EINA_TRUE if it is supported, @c EINA_FALSE otherwise. - * @ingroup Evas_Font_Group - */ EAPI Eina_Bool evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) { @@ -1544,12 +1280,6 @@ evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) return EINA_FALSE; } -/** - * Force the given evas and associated engine to flush its font cache. - * - * @param e The given evas to flush font cache. - * @ingroup Evas_Font_Group - */ EAPI void evas_font_cache_flush(Evas *e) { @@ -1560,14 +1290,6 @@ evas_font_cache_flush(Evas *e) e->engine.func->font_cache_flush(e->engine.data.output); } -/** - * Changes the size of font cache of the given evas. - * - * @param e The given evas to flush font cache. - * @param size The size, in bytes. - * - * @ingroup Evas_Font_Group - */ EAPI void evas_font_cache_set(Evas *e, int size) { @@ -1579,14 +1301,6 @@ evas_font_cache_set(Evas *e, int size) e->engine.func->font_cache_set(e->engine.data.output, size); } -/** - * Changes the size of font cache of the given evas. - * - * @param 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) { @@ -1597,20 +1311,6 @@ evas_font_cache_get(const Evas *e) return e->engine.func->font_cache_get(e->engine.data.output); } -/** - * List of available font descriptions known or found by this evas. - * - * 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 e The evas instance to query. - * @return a newly allocated list of strings. Do not change the - * strings. Be sure to call evas_font_available_list_free() - * after you're done. - * - * @ingroup Evas_Font_Group - */ EAPI Eina_List * evas_font_available_list(const Evas *e) { @@ -1621,14 +1321,6 @@ evas_font_available_list(const Evas *e) return evas_font_dir_available_list(e); } -/** - * Free list of font descriptions returned by evas_font_dir_available_list(). - * - * @param e The evas instance that returned such list. - * @param 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) { @@ -1639,25 +1331,6 @@ evas_font_available_list_free(Evas *e, Eina_List *available) evas_font_dir_available_list_free(available); } -/** - * Gets the next character in the string - * - * Given the UTF-8 string in @p str, and starting byte position in @p pos, - * this function will place in @p decoded the decoded code point at @p pos - * and return the byte index for the next character in the string. - * - * The only boundary check done is that @p pos must be >= 0. Other than that, - * no checks are performed, so passing an index value that's not within the - * length of the string will result in undefined behavior. - * - * @param str The UTF-8 string - * @param pos The byte index where to start - * @param decoded Address where to store the decoded code point. Optional. - * - * @return The byte index of the next character - * - * @ingroup Evas_Utils - */ EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) { @@ -1671,25 +1344,6 @@ evas_string_char_next_get(const char *str, int pos, int *decoded) return p; } -/** - * Gets the previous character in the string - * - * Given the UTF-8 string in @p str, and starting byte position in @p pos, - * this function will place in @p decoded the decoded code point at @p pos - * and return the byte index for the previous character in the string. - * - * The only boundary check done is that @p pos must be >= 1. Other than that, - * no checks are performed, so passing an index value that's not within the - * length of the string will result in undefined behavior. - * - * @param str The UTF-8 string - * @param pos The byte index where to start - * @param decoded Address where to store the decoded code point. Optional. - * - * @return The byte index of the previous character - * - * @ingroup Evas_Utils - */ EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) { @@ -1703,12 +1357,6 @@ evas_string_char_prev_get(const char *str, int pos, int *decoded) return p; } -/** - * Get the length in characters of the string. - * @param str The string to get the length of. - * @return The length in characters (not bytes) - * @ingroup Evas_Utils - */ EAPI int evas_string_char_len_get(const char *str) { @@ -1716,14 +1364,6 @@ evas_string_char_len_get(const char *str) return eina_unicode_utf8_get_len(str); } -/** - * Get the minimum padding a style adds to the text. - * @param style The style to determine padding. - * @param l Pointer to the current left padding value - * @param r Pointer to the current right padding value - * @param t Pointer to the current top padding value - * @param b Pointer to the current bottom padding value - */ void evas_text_style_pad_get(Evas_Text_Style_Type style, int *l, int *r, int *t, int *b) { diff --git a/legacy/evas/src/lib/canvas/evas_object_textblock.c b/legacy/evas/src/lib/canvas/evas_object_textblock.c index 84889ba978..e5dffa9cc9 100644 --- a/legacy/evas/src/lib/canvas/evas_object_textblock.c +++ b/legacy/evas/src/lib/canvas/evas_object_textblock.c @@ -1,74 +1,3 @@ -/** - * @addtogroup Evas_Object_Textblock - * - * @{ - */ - -/** - * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial - * - * This part explains about the textblock object's API and proper usage. - * If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal. - * The main user of the textblock object is the edje entry object in Edje, so - * that's a good place to learn from, but I think this document is more than - * enough, if it's not, please request for me info and I'll update it. - * - * @subsection textblock_intro Introduction - * The textblock objects 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. - * - * @subsection textblock_cursors Textblock Object Cursors - * A textblock Cursor @ref Evas_Textblock_Cursor is 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 obj and you can't 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'll - * still point to it even after you change the whole object completely (as long - * as the char was not deleted), this is not possible without updating, because - * as mentioned, each cursor holds a character position. There are many - * functions that handle cursors, just check out the evas_textblock_cursor* - * functions. For creation and deletion of cursors check out: - * @see evas_object_textblock_cursor_new() - * @see evas_textblock_cursor_free() - * @note Cursors are generally the correct way to handle text in the textblock object, and there are enough functions to do everything you need with them (no need to get big chunks of text and processing them yourself). - * - * @subsection textblock_paragraphs Textblock Object Paragraphs - * The textblock object is made out of text splitted 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, i.e formats that - * occupy space, for example: newlines, tabs, items and etc. Some visible items - * are made of two parts, in this case, only the opening tag is visible. - * A closing tag (i.e a tag) should NEVER be visible. - * Invisible: formats that don't occupy space, for example: bold and underline. - * Being able to access format nodes is very important for some uses. For - * example, edje uses the "" 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, take a look at all the evas_textblock_node_format_* - * functions. - * The translation of "" 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 - * This section is not yet written. If you want some info about styles/formats - * and how to use them, expedite's textblock_basic test is a great start. - * @todo Write @textblock_special_formats - */ - /** * @internal * @section Evas_Object_Textblock_Internal Internal Textblock Object Tutorial @@ -3933,11 +3862,6 @@ _find_layout_line_num(const Evas_Object *obj, int line) return NULL; } -/** - * Adds a textblock to the given evas. - * @param e The given evas. - * @return The new textblock object. - */ EAPI Evas_Object * evas_object_textblock_add(Evas *e) { @@ -3952,10 +3876,6 @@ evas_object_textblock_add(Evas *e) return obj; } -/** - * Creates a new textblock style. - * @return The new textblock style. - */ EAPI Evas_Textblock_Style * evas_textblock_style_new(void) { @@ -3965,10 +3885,6 @@ evas_textblock_style_new(void) return ts; } -/** - * Destroys a textblock style. - * @param ts The textblock style to free. - */ EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) { @@ -3982,14 +3898,6 @@ evas_textblock_style_free(Evas_Textblock_Style *ts) free(ts); } -/** - * Sets the style ts to the style passed as text by text. - * Expected a string consisting of many (or none) tag='format' pairs. - * - * @param ts the style to set. - * @param text the text to parse - NOT NULL. - * @return Returns no value. - */ EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) { @@ -4100,11 +4008,6 @@ evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) } } -/** - * Return the text of the style ts. - * @param ts the style to get it's text. - * @return the text of the style or null on error. - */ EAPI const char * evas_textblock_style_get(const Evas_Textblock_Style *ts) { @@ -4113,12 +4016,6 @@ evas_textblock_style_get(const Evas_Textblock_Style *ts) } /* textblock styles */ -/** - * Set the objects style to ts. - * @param obj the evas object to set the style to. - * @param ts the style to set. - * @return Returns no value. - */ EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) { @@ -4149,11 +4046,6 @@ evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) _evas_textblock_invalidate_all(o); } -/** - * Return the style of an object. - * @param 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) { @@ -4161,12 +4053,6 @@ evas_object_textblock_style_get(const Evas_Object *obj) return o->style; } -/** - * @brief Set the "replacement character" to use for the given textblock object. - * - * @param obj The given textblock object. - * @param ch The charset name. - */ EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) { @@ -4178,14 +4064,6 @@ evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) _evas_textblock_invalidate_all(o); } -/** - * @brief Sets newline mode. When true, newline character will behave - * as a paragraph separator. - * - * @param obj The given textblock object. - * @param mode EINA_TRUE for PS mode, EINA_FALSE otherwise. - * @since 1.1.0 - */ EAPI void evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) { @@ -4198,14 +4076,6 @@ evas_object_textblock_newline_mode_set(Evas_Object *obj, Eina_Bool mode) * for new text inserted. */ } -/** - * @brief Gets newline mode. When true, newline character behaves - * as a paragraph separator. - * - * @param obj The given textblock object. - * @return EINA_TRUE if in PS mode, EINA_FALSE otherwise. - * @since 1.1.0 - */ EAPI Eina_Bool evas_object_textblock_newline_mode_get(const Evas_Object *obj) { @@ -4213,18 +4083,6 @@ evas_object_textblock_newline_mode_get(const Evas_Object *obj) return o->newline_is_ps; } -/** - * @brief Sets the vertical alignment of text within the textblock object - * as a whole. - * - * Normally alignment is 0.0 (top of object). Values given should be - * between 0.0 and 1.0 (1.0 bottom of object, 0.5 being vertically centered - * etc.). - * - * @param obj The given textblock object. - * @param align A value between 0.0 and 1.0 - * @since 1.1.0 - */ EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align) { @@ -4236,13 +4094,6 @@ evas_object_textblock_valign_set(Evas_Object *obj, double align) _evas_textblock_changed(o, obj); } -/** - * @brief Gets the vertical alignment of a textblock - * - * @param obj The given textblock object. - * @return The elignment set for the object - * @since 1.1.0 - */ EAPI double evas_object_textblock_valign_get(const Evas_Object *obj) { @@ -4250,13 +4101,6 @@ evas_object_textblock_valign_get(const Evas_Object *obj) return o->valign; } -/** - * @brief Get the "replacement character" for given textblock object. Returns - * NULL if no replacement character is in use. - * - * @param obj The given textblock object - * @return replacement character or NULL - */ EAPI const char * evas_object_textblock_replace_char_get(Evas_Object *obj) { @@ -4371,11 +4215,6 @@ _escaped_char_get(const char *s, const char *s_end) return NULL; } -/** - * Returns the unescaped version of escape. - * @param escape the string to be escaped - * @return the unescaped version of escape - */ EAPI const char * evas_textblock_escape_string_get(const char *escape) { @@ -4383,25 +4222,12 @@ evas_textblock_escape_string_get(const char *escape) return _escaped_char_get(escape, escape + strlen(escape)); } -/** - * Return the unescaped version of the string between start and end. - * - * @param escape_start the start of the string. - * @param 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) { return _escaped_char_get(escape_start, escape_end); } -/** - * Returns the escaped version of the string. - * @param string to escape - * @param len_ret the len of the new escape - * @return the escaped string. - */ EAPI const char * evas_textblock_string_escape_get(const char *string, int *len_ret) { @@ -4448,15 +4274,6 @@ _prepend_escaped_char(Evas_Textblock_Cursor *cur, const char *s, } -/** - * Sets the tetxblock's text to the markup text. - * - * @note assumes text does not include the unicode object replacement char (0xFFFC) - * - * @param obj the textblock object. - * @param text the markup text to use. - * @return Return no value. - */ EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) { @@ -4489,15 +4306,6 @@ evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) } } -/** - * Prepends markup to the cursor cur. - * - * @note assumes text does not include the unicode object replacement char (0xFFFC) - * - * @param cur the cursor to prepend to. - * @param text the markup text to prepend. - * @return Return no value. - */ EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) { @@ -4716,12 +4524,6 @@ _markup_get_text_append(Eina_Strbuf *txt, const Eina_Unicode *text) } free(base); } -/** - * Return the markup of the object. - * - * @param obj the evas object. - * @return the markup text of the object. - */ EAPI const char * evas_object_textblock_text_markup_get(const Evas_Object *obj) { @@ -5043,12 +4845,6 @@ _find_layout_item_match(const Evas_Textblock_Cursor *cur, Evas_Object_Textblock_ return previous_format; } -/** - * Return the object's main cursor. - * - * @param obj the object. - * @return the obj's main cursor. - */ EAPI const Evas_Textblock_Cursor * evas_object_textblock_cursor_get(const Evas_Object *obj) { @@ -5056,16 +4852,6 @@ evas_object_textblock_cursor_get(const Evas_Object *obj) return o->cursor; } -/** - * Create a new cursor, associate it to the obj and init it to point - * to the start of the textblock. Association to the object means the cursor - * will be updated when the object will change. - * - * @note if you need speed and you know what you are doing, it's slightly faster to just allocate the cursor yourself and not associate it. (only people developing the actual object, and not users of the object). - * - * @param obj the object to associate to. - * @return the new cursor. - */ EAPI Evas_Textblock_Cursor * evas_object_textblock_cursor_new(Evas_Object *obj) { @@ -5081,13 +4867,6 @@ evas_object_textblock_cursor_new(Evas_Object *obj) return cur; } -/** - * Free the cursor and unassociate it from the object. - * @note do not use it to free unassociated cursors. - * - * @param cur the cursor to free. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) { @@ -5100,12 +4879,6 @@ evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) free(cur); } -/** - * Returns true if the cursor points to a format. - * - * @param cur the cursor to check. - * @return Returns #EINA_TRUE if a cursor points to a format #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) { @@ -5115,24 +4888,12 @@ evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_TRUE : EINA_FALSE; } -/** - * Returns the first format node. - * - * @param obj The evas, must not be NULL. - * @return Returns the first format node, may be null if there are none. - */ EAPI const Evas_Object_Textblock_Node_Format * evas_textblock_node_format_first_get(const Evas_Object *obj) { TB_HEAD_RETURN(NULL); return o->format_nodes; } -/** - * Returns the last format node. - * - * @param obj The evas textblock, must not be NULL. - * @return Returns the first format node, may be null if there are none. - */ EAPI const Evas_Object_Textblock_Node_Format * evas_textblock_node_format_last_get(const Evas_Object *obj) { @@ -5144,38 +4905,18 @@ evas_textblock_node_format_last_get(const Evas_Object *obj) return NULL; } -/** - * Returns the next format node (after n) - * - * @param n the current format node - not null. - * @return Returns the next format node, may be null. - */ EAPI const Evas_Object_Textblock_Node_Format * evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) { return _NODE_FORMAT(EINA_INLIST_GET(n)->next); } -/** - * Returns the prev format node (after n) - * - * @param n the current format node - not null. - * @return Returns the prev format node, may be null. - */ EAPI const Evas_Object_Textblock_Node_Format * evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) { return _NODE_FORMAT(EINA_INLIST_GET(n)->prev); } -/** - * Remove a format node and it's match. i.e, removes a pair. - * Assumes the node is the first part of i.e, this won't work if - * n is a closing tag. - * - * @param obj the evas object of the textblock - not null. - * @param n the current format node - not null. - */ EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) @@ -5234,12 +4975,6 @@ evas_textblock_node_format_remove_pair(Evas_Object *obj, _evas_textblock_changed(o, obj); } -/** - * Sets the cursor to the start of the first text node. - * - * @param cur the cursor to update. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) { @@ -5251,12 +4986,6 @@ evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) } -/** - * sets the cursor to the end of the last text node. - * - * @param cur the cursor to set. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) { @@ -5282,12 +5011,6 @@ evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) } } -/** - * Advances to the the start of the next text node - * - * @param cur the cursor to update - * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) { @@ -5310,12 +5033,6 @@ evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) return EINA_FALSE; } -/** - * Advances to the the end of the previous text node - * - * @param cur the cursor to update - * @return #EINA_TRUE if it managed to advance a paragraph, #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) { @@ -5342,12 +5059,6 @@ evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) return EINA_FALSE; } -/** - * Sets the cursor to point to the place where format points to. - * - * @param cur the cursor to update. - * @param n the format node to update according. - */ EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) { @@ -5356,12 +5067,6 @@ evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Objec cur->pos = _evas_textblock_node_format_pos_get(n); } -/** - * Advances to the next format node - * - * @param cur the cursor to be updated. - * @return #EINA_TRUE on success #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) { @@ -5399,12 +5104,6 @@ evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) return EINA_FALSE; } -/** - * Advances to the previous format node. - * - * @param cur the cursor to update. - * @return #EINA_TRUE on success #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) { @@ -5441,12 +5140,6 @@ evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) return EINA_FALSE; } -/** - * Advances 1 char forward. - * - * @param cur the cursor to advance. - * @return #EINA_TRUE on success #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) { @@ -5485,12 +5178,6 @@ evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) } } -/** - * Advances 1 char backward. - * - * @param cur the cursor to advance. - * @return #EINA_TRUE on success #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) { @@ -5505,12 +5192,6 @@ evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) return evas_textblock_cursor_paragraph_prev(cur); } -/** - * Go to the first char in the node the cursor is pointing on. - * - * @param cur the cursor to update. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) { @@ -5519,12 +5200,6 @@ evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) } -/** - * Go to the last char in a text node. - * - * @param cur the cursor to update. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) { @@ -5540,12 +5215,6 @@ evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) } -/** - * Go to the start of the current line - * - * @param cur the cursor to update. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) { @@ -5580,12 +5249,6 @@ evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) } } -/** - * Go to the end of the current line. - * - * @param cur the cursor to update. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) { @@ -6094,12 +5757,6 @@ _evas_textblock_node_format_pos_get(const Evas_Object_Textblock_Node_Format *fmt return position + fmt->offset; } -/** - * Return the current cursor pos. - * - * @param cur the cursor to take the position from. - * @return the position or -1 on error - */ EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) { @@ -6118,12 +5775,6 @@ evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) return npos + cur->pos; } -/** - * Set the cursor pos. - * - * @param cur the cursor to be set. - * @param pos the pos to set. - */ EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int _pos) { @@ -6170,13 +5821,6 @@ evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int _pos) } -/** - * Go to the start of the line passed - * - * @param cur cursor to update. - * @param line numer to set. - * @return #EINA_TRUE on success, #EINA_FALSE on error. - */ EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) { @@ -6205,13 +5849,6 @@ evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) return EINA_TRUE; } -/** - * Compare two cursors. - * - * @param cur1 the first cursor. - * @param cur2 the second cursor. - * @return -1 if cur1 < cur2, 0 if cur1 == cur2 and 1 otherwise. - */ EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) { @@ -6240,14 +5877,6 @@ evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Text return 0; } -/** - * Make cur_dest point to the same place as cur. Does not work if they don't - * point to the same object. - * - * @param cur the source cursor. - * @param cur_dest destination cursor. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) { @@ -6505,15 +6134,6 @@ _evas_textblock_invalidate_all(Evas_Object_Textblock *o) } } -/** - * Adds text to the current cursor position and set the cursor to *before* - * the start of the text just added. - * - * @param cur the cursor to where to add text at. - * @param _text the text to add. - * @return Returns the len of the text added. - * @see evas_textblock_cursor_text_prepend() - */ EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *_text) { @@ -6581,15 +6201,6 @@ evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *_text) return len; } -/** - * Adds text to the current cursor position and set the cursor to *after* - * the start of the text just added. - * - * @param cur the cursor to where to add text at. - * @param _text the text to add. - * @return Returns the len of the text added. - * @see evas_textblock_cursor_text_append() - */ EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *_text) { @@ -6634,14 +6245,6 @@ _evas_textblock_node_format_new(const char *format) return n; } -/** - * Check if the current cursor position points to the terminating null of the - * last paragraph. (shouldn't be allowed to point to the terminating null of - * any previous paragraph anyway. - * - * @param cur the cursor to look at. - * @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise. - */ static Eina_Bool _evas_textblock_cursor_is_at_the_end(const Evas_Textblock_Cursor *cur) { @@ -6654,20 +6257,6 @@ _evas_textblock_cursor_is_at_the_end(const Evas_Textblock_Cursor *cur) EINA_TRUE : EINA_FALSE; } -/** - * Adds format to the current cursor position. 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. - * - * This function works with native formats, that means that style defined - * tags like
won't work here. For those kind of things use markup prepend. - * - * @param cur the cursor to where to add format at. - * @param 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) { @@ -6793,21 +6382,6 @@ evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *form return is_visible; } -/** - * Adds format to the current cursor position. 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. - * - * This function works with native formats, that means that style defined - * tags like
won't work here. For those kind of things use markup prepend. - * - * @param cur the cursor to where to add format at. - * @param 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_prepend(Evas_Textblock_Cursor *cur, const char *format) { @@ -6824,13 +6398,6 @@ evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *for } -/** - * Delete the character at the location of the cursor. If there's a format - * pointing to this position, delete it as well. - * - * @param cur the cursor pointing to the current location. - * @return Returns no value. - */ EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) { @@ -6906,13 +6473,6 @@ evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) cur->node->dirty = EINA_TRUE; } -/** - * Delete the range between cur1 and cur2. - * - * @param cur1 one side of the range. - * @param cur2 the second side of the range - * @return Returns no value. - */ EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) { @@ -7010,12 +6570,6 @@ evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_C } -/** - * Return the content of the cursor. - * - * @param cur the cursor - * @return the text in the range - */ EAPI char * evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) { @@ -7040,17 +6594,6 @@ evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) return s; } -/** - * Return the text in the range between cur1 and cur2 - * - * FIXME: format is currently unused, you always get markup back. - * - * @param cur1 one side of the range. - * @param cur2 the other side of the range - * @param format to be documented - * @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 __UNUSED__) { @@ -7173,12 +6716,6 @@ evas_textblock_cursor_range_text_get(const Evas_Textblock_Cursor *cur1, const Ev } } -/** - * Return the text of the paragraph cur points to - returns the text in markup.. - * - * @param cur the cursor pointing to the paragraph. - * @return the text on success, NULL otherwise. - */ EAPI const char * evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) { @@ -7199,12 +6736,6 @@ evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) return cur->node->utf8; } -/** - * Return the length of the paragraph, cheaper the eina_unicode_strlen() - * - * @param cur the position of the paragraph. - * @return the length of the paragraph on success, -1 otehrwise. - */ EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) { @@ -7213,13 +6744,6 @@ evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur return eina_ustrbuf_length_get(cur->node->unicode); } -/** - * Return the format node at the position pointed by cur. - * - * @param cur the position to look at. - * @return the format node if found, NULL otherwise. - * @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) { @@ -7227,12 +6751,6 @@ evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) if (!cur->node) return NULL; return _evas_textblock_cursor_node_format_at_pos_get(cur); } -/** - * Get the text format representation of the format node. - * - * @param fmt 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 *fmt) { @@ -7240,12 +6758,6 @@ evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fmt return eina_strbuf_string_get(fmt->format); } -/** - * Set the cursor to point to the position of fmt. - * - * @param cur the cursor to update - * @param 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) { @@ -7254,15 +6766,6 @@ evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Objec cur->pos = _evas_textblock_node_format_pos_get(fmt); } -/** - * Check if the current cursor position is a visible format. This way is more - * efficient than evas_textblock_cursor_format_get() to check for the existence - * of a visible format. - * - * @param cur the cursor to look at. - * @return #EINA_TRUE if the cursor points to a visible format, #EINA_FALSE otherwise. - * @see evas_textblock_cursor_format_get() - */ EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) { @@ -7275,28 +6778,6 @@ evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_TRUE : EINA_FALSE; } -/** - * Returns the geometry of the cursor. 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. - * in '_' cursor mode (i.e a line below the char) it's the same as char_geometry - * get, except for the case of the last char of a line which depends on the - * paragraph direction. - * - * in '|' cursor mode (i.e a line between two chars) it is very varyable. - * 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 cur the cursor. - * @param cx the x of the cursor - * @param cy the y of the cursor - * @param cw the width of the cursor - * @param ch the height of the cursor - * @param dir the direction of the cursor, can be NULL. - * @param ctype the type of the cursor. - * @return line number of the char on success, -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) { @@ -7540,16 +7021,6 @@ _evas_textblock_cursor_char_pen_geometry_common_get(int (*query_func) (void *dat return ln->par->line_no + ln->line_no; } -/** - * Returns the geometry of the char at cur. - * - * @param cur the position of the char. - * @param cx the x of the char. - * @param cy the y of the char. - * @param cw the w of the char. - * @param ch the h of the char. - * @return line number of the char on success, -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) { @@ -7557,16 +7028,6 @@ evas_textblock_cursor_char_geometry_get(const Evas_Textblock_Cursor *cur, Evas_C cur->ENFN->font_char_coords_get, cur, cx, cy, cw, ch); } -/** - * Returns the geometry of the pen at cur. - * - * @param cur the position of the char. - * @param cpen_x the pen_x of the char. - * @param cy the y of the char. - * @param cadv the adv of the char. - * @param ch the h of the char. - * @return line number of the char on success, -1 on error. - */ EAPI int evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) { @@ -7574,16 +7035,6 @@ evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Co cur->ENFN->font_pen_coords_get, cur, cx, cy, cw, ch); } -/** - * Returns the geometry of the line at cur. - * - * @param cur the position of the line. - * @param cx the x of the line. - * @param cy the y of the line. - * @param cw the width of the line. - * @param ch the height of the line. - * @return line number of the line on success, -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) { @@ -7615,14 +7066,6 @@ evas_textblock_cursor_line_geometry_get(const Evas_Textblock_Cursor *cur, Evas_C return ln->par->line_no + ln->line_no; } -/** - * Set the position of the cursor according to the X and Y coordinates. - * - * @param cur the cursor to set. - * @param x coord to set by. - * @param y coord to set by. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) { @@ -7714,13 +7157,6 @@ evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, E return EINA_FALSE; } -/** - * Set the cursor position according to the y coord. - * - * @param cur the cur to be set. - * @param y the coord to set by. - * @return the line number found, -1 on error. - */ EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) { @@ -8050,13 +7486,6 @@ _evas_textblock_cursor_range_in_line_geometry_get( } return rects; } -/** - * Get the geometry of a range. - * - * @param cur1 one side of the range. - * @param cur2 other side 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) { @@ -8130,15 +7559,6 @@ evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, cons return rects; } -/** - * to be documented. - * @param cur to be documented. - * @param cx to be documented. - * @param cy to be documented. - * @param cw to be documented. - * @param ch to be documented. - * @return to be documented. - */ 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) { @@ -8166,12 +7586,6 @@ evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, return EINA_TRUE; } -/** - * Checks if the cursor points to the end of the line. - * - * @param cur the cursor to check. - * @return #EINA_TRUE if true, #EINA_FALSE otherwise. - */ EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) { @@ -8189,17 +7603,6 @@ evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) } /* general controls */ -/** - * Get the geometry of a line number. - * - * @param obj the object. - * @param line the line number. - * @param cx x coord of the line. - * @param cy y coord of the line. - * @param cw w coord of the line. - * @param ch h coord of the line. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - */ 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) { @@ -8215,13 +7618,6 @@ evas_object_textblock_line_number_geometry_get(const Evas_Object *obj, int line, return EINA_TRUE; } -/** - * Clear the textblock object. - * @note Does *NOT* free the evas object itself. - * - * @param obj the object to clear. - * @return nothing. - */ EAPI void evas_object_textblock_clear(Evas_Object *obj) { @@ -8246,27 +7642,6 @@ evas_object_textblock_clear(Evas_Object *obj) _evas_textblock_changed(o, obj); } -/** - * Get the formatted width and height. 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 wrapping into account - * it just calculates the real width of the object if it was placed on an - * infinite canvas, while this function gives the size after wrapping - * according to the size restrictions of the object. - * - * For example for 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 obj the evas object. - * @param w[out] the width of the object. - * @param h[out] the height of the object - * @return Returns no value. - * @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) { @@ -8276,25 +7651,6 @@ evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, if (h) *h = o->formatted.h; } -/** - * Get the native width and height. This calculates the actual size without taking 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 was placed on an - * infinite canvas, while the "formatted" function gives the size after - * wrapping text according to the size restrictions of the object. - * - * For example for 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 obj the evas object of the textblock - * @param w[out] the width returned - * @param h[out] the height returned - * @return Returns no value. - */ EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) { @@ -8312,15 +7668,6 @@ evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Eva if (h) *h = o->native.h; } -/** - * to be documented. - * @param obj to be documented. - * @param l to be documented. - * @param r to be documented. - * @param t to be documented. - * @param b to be documented. - * @return Returns no value. - */ EAPI void evas_object_textblock_style_insets_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) { diff --git a/legacy/evas/src/lib/canvas/evas_render.c b/legacy/evas/src/lib/canvas/evas_render.c index 5d497a0993..013c189016 100644 --- a/legacy/evas/src/lib/canvas/evas_render.c +++ b/legacy/evas/src/lib/canvas/evas_render.c @@ -46,20 +46,6 @@ rend_dbg(const char *txt) static Eina_List * evas_render_updates_internal(Evas *e, unsigned char make_updates, unsigned char do_draw); -/** - * Add a damage rectangle. - * - * @param e The given canvas pointer. - * @param x The rectangle's left position. - * @param y The rectangle's top position. - * @param w The rectangle's width. - * @param h The rectangle's height. - * - * This is the function by which one tells evas that a part of the - * canvas has to be repainted. - * - * @ingroup Evas_Canvas - */ EAPI void evas_damage_rectangle_add(Evas *e, int x, int y, int w, int h) { @@ -74,23 +60,6 @@ evas_damage_rectangle_add(Evas *e, int x, int y, int w, int h) e->changed = 1; } -/** - * Add an obscured region. - * - * @param e The given canvas pointer. - * @param x The rectangle's left position. - * @param y The rectangle's top position - * @param w The rectangle's width. - * @param h The rectangle's height. - * - * This is the function by which one tells evas that a part of the - * canvas has not to be repainted. To make this region one that have - * to be repainted, call the function evas_obscured_clear(). - * - * @see evas_obscured_clear(). - * - * @ingroup Evas_Canvas - */ EAPI void evas_obscured_rectangle_add(Evas *e, int x, int y, int w, int h) { @@ -104,18 +73,6 @@ evas_obscured_rectangle_add(Evas *e, int x, int y, int w, int h) e->obscures = eina_list_append(e->obscures, r); } -/** - * Remove all obscured region rectangles from the canvas. - * - * @param e The given canvas pointer. - * - * This function removes all the rectangles from the obscured list of - * the canvas. It takes obscured areas added with - * evas_obscured_rectangle_add() and makes it a region that have to be - * repainted. - * - * @ingroup Evas_Canvas - */ EAPI void evas_obscured_clear(Evas *e) { @@ -1512,16 +1469,6 @@ evas_render_updates_internal(Evas *e, return updates; } -/** - * Free the rectangles returned by evas_render_updates(). - * - * @param updates The list of updated rectangles of the canvas. - * - * This function removes the region from the render updates list. It - * makes the region doesn't be render updated anymore. - * - * @ingroup Evas_Canvas - */ EAPI void evas_render_updates_free(Eina_List *updates) { @@ -1531,18 +1478,6 @@ evas_render_updates_free(Eina_List *updates) eina_rectangle_free(r); } -/** - * Force immediate renderization of the given canvas. - * - * @param e The given canvas pointer. - * @return A newly allocated list of updated rectangles of the canvas. - * Free this list with evas_render_updates_free(). - * - * This function forces an immediate renderization update of the given - * given canvas. - * - * @ingroup Evas_Canvas - */ EAPI Eina_List * evas_render_updates(Evas *e) { @@ -1558,13 +1493,6 @@ evas_render_updates(Evas *e) return evas_render_updates_internal(e, 1, 1); } -/** - * Force renderization of the given canvas. - * - * @param e The given canvas pointer. - * - * @ingroup Evas_Canvas - */ EAPI void evas_render(Evas *e) { @@ -1580,20 +1508,6 @@ evas_render(Evas *e) evas_render_updates_internal(e, 0, 1); } -/** - * Update the canvas internal objects but not triggering immediate - * renderization. - * - * @param e The given canvas pointer. - * - * This function updates the canvas internal objects not triggering - * renderization. To force renderization function evas_render() should - * be used. - * - * @see evas_render. - * - * @ingroup Evas_Canvas - */ EAPI void evas_norender(Evas *e) { @@ -1605,17 +1519,6 @@ evas_norender(Evas *e) evas_render_updates_internal(e, 0, 0); } -/** - * Make the canvas discard internally cached data used for rendering. - * - * @param e The given canvas pointer. - * - * This function flushes the arrays of delete, active and render objects. - * Other things it may also discard are: shared memory segments, - * temporary scratch buffers, cached data to avoid re-compute of that data etc. - * - * @ingroup Evas_Canvas - */ EAPI void evas_render_idle_flush(Evas *e) { @@ -1652,20 +1555,6 @@ evas_sync(Evas *e) #endif } -/** - * Make the canvas discard as much data as possible used by the engine at - * runtime. - * - * @param e The given canvas pointer. - * - * This function will unload images, delete 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. - * - * @ingroup Evas_Canvas - */ static void _evas_render_dump_map_surfaces(Evas_Object *obj) { diff --git a/legacy/evas/src/lib/canvas/evas_smart.c b/legacy/evas/src/lib/canvas/evas_smart.c index 6d48905fe5..44cf9a0c04 100644 --- a/legacy/evas/src/lib/canvas/evas_smart.c +++ b/legacy/evas/src/lib/canvas/evas_smart.c @@ -6,20 +6,6 @@ static void _evas_smart_class_callbacks_create(Evas_Smart *s); /* all public */ -/** - * @addtogroup Evas_Smart_Group - * @{ - */ - -/** - * Free an Evas_Smart - * - * If this smart was created using evas_smart_class_new(), the associated - * Evas_Smart_Class will not be freed. - * - * @param s the Evas_Smart to free - * - */ EAPI void evas_smart_free(Evas_Smart *s) { @@ -33,12 +19,6 @@ evas_smart_free(Evas_Smart *s) free(s); } -/** - * Creates an Evas_Smart from an Evas_Smart_Class. - * - * @param sc the smart class definition - * @return an Evas_Smart - */ EAPI Evas_Smart * evas_smart_class_new(const Evas_Smart_Class *sc) { @@ -60,12 +40,6 @@ evas_smart_class_new(const Evas_Smart_Class *sc) return s; } -/** - * Get the Evas_Smart_Class of an Evas_Smart - * - * @param s the Evas_Smart - * @return the Evas_Smart_Class - */ EAPI const Evas_Smart_Class * evas_smart_class_get(const Evas_Smart *s) { @@ -75,15 +49,6 @@ evas_smart_class_get(const Evas_Smart *s) return s->smart_class; } -/** - * @brief Get the data pointer set on an Evas_Smart. - * - * @param s Evas_Smart - * - * This data pointer is set either as the final parameter to - * evas_smart_new or as the data field in the Evas_Smart_Class passed - * in to evas_smart_class_new - */ EAPI void * evas_smart_data_get(const Evas_Smart *s) { @@ -93,37 +58,6 @@ evas_smart_data_get(const Evas_Smart *s) return (void *)s->smart_class->data; } -/** - * Get the callbacks known by this Evas_Smart. - * - * This is likely different from Evas_Smart_Class::callbacks as it - * will contain the callbacks of all class hierarchy sorted, while the - * direct smart class member refers only to that specific class and - * should not include parent's. - * - * If no callbacks are known, this function returns @c NULL. - * - * The array elements and thus their contents will be reference to - * original values given to evas_smart_new() as - * Evas_Smart_Class::callbacks. - * - * The array is sorted by name. The last array element is the @c NULL - * pointer and is not counted in @a count. Loop iterations can check - * any of these cases. - * - * @param s the Evas_Smart. - * @param count returns the number of elements in returned array. - * @return the array with callback descriptions known by this class, - * its size is returned in @a count parameter. It should not - * be modified anyhow. If no callbacks are known, @c NULL is - * returned. The array is sorted by name and elements refer to - * the original value given to evas_smart_new(). - * - * @note objects may provide per-instance callbacks, use - * evas_object_smart_callbacks_descriptions_get() to get those - * as well. - * @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) { @@ -136,16 +70,6 @@ evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) return s->callbacks.array; } -/** - * Find callback description for callback called @a name. - * - * @param s the Evas_Smart. - * @param name name of desired callback, must @b not be @c NULL. The - * search have a special case for @a name being the same - * pointer as registered with Evas_Smart_Cb_Description, one - * can use it to avoid excessive use of strcmp(). - * @return reference to description if found, @c NULL if not found. - */ EAPI const Evas_Smart_Cb_Description * evas_smart_callback_description_find(const Evas_Smart *s, const char *name) { @@ -156,23 +80,6 @@ evas_smart_callback_description_find(const Evas_Smart *s, const char *name) return evas_smart_cb_description_find(&s->callbacks, name); } -/** - * Sets one class to inherit from the other. - * - * Copy all function pointers, set @c parent to @a parent_sc and copy - * everything after sizeof(Evas_Smart_Class) present in @a parent_sc, - * using @a parent_sc_size as reference. - * - * This is recommended instead of a single memcpy() since it will take - * care to not modify @a sc name, version, callbacks and possible - * other members. - * - * @param sc child class. - * @param parent_sc parent class, will provide attributes. - * @param parent_sc_size size of parent_sc structure, child should be at least - * this size. 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) { @@ -205,10 +112,6 @@ evas_smart_class_inherit_full(Evas_Smart_Class *sc, const Evas_Smart_Class *pare return 1; } -/** - * @} - */ - /* internal funcs */ void evas_object_smart_use(Evas_Smart *s) diff --git a/legacy/evas/src/lib/canvas/evas_stack.c b/legacy/evas/src/lib/canvas/evas_stack.c index 8369705d8d..bf7aa21bf0 100644 --- a/legacy/evas/src/lib/canvas/evas_stack.c +++ b/legacy/evas/src/lib/canvas/evas_stack.c @@ -37,16 +37,6 @@ evas_object_below_get_internal(const Evas_Object *obj) return NULL; } -/** - * @addtogroup Evas_Object_Group_Basic - * @{ - */ - -/** - * Raise @p obj to the top of its layer. - * - * @param obj the object to raise - */ EAPI void evas_object_raise(Evas_Object *obj) { @@ -96,11 +86,6 @@ evas_object_raise(Evas_Object *obj) } } -/** - * Lower @p obj to the bottom of its layer. - * - * @param obj the object to lower - */ EAPI void evas_object_lower(Evas_Object *obj) { @@ -150,18 +135,6 @@ evas_object_lower(Evas_Object *obj) } } -/** - * Stack @p obj immediately above @p above - * - * If @p obj is a member of a smart object, then @p above must also be - * a member of the same smart object. - * - * Similarly, if @p obj is not a member of smart object, @p above may - * not either. - * - * @param obj the object to stack - * @param above the object above which to stack - */ EAPI void evas_object_stack_above(Evas_Object *obj, Evas_Object *above) { @@ -242,18 +215,6 @@ evas_object_stack_above(Evas_Object *obj, Evas_Object *above) } } -/** - * Stack @p obj immediately below @p below - * - * If @p obj is a member of a smart object, then @p below must also be - * a member of the same smart object. - * - * Similarly, if @p obj is not a member of smart object, @p below may - * not either. - * - * @param obj the object to stack - * @param below the object below which to stack - */ EAPI void evas_object_stack_below(Evas_Object *obj, Evas_Object *below) { @@ -334,12 +295,6 @@ evas_object_stack_below(Evas_Object *obj, Evas_Object *below) } } -/** - * Get the evas object above @p obj - * - * @param obj an Evas_Object - * @return the Evas_Object directly above - */ EAPI Evas_Object * evas_object_above_get(const Evas_Object *obj) { @@ -365,12 +320,6 @@ evas_object_above_get(const Evas_Object *obj) return NULL; } -/** - * Get the evas object below @p obj - * - * @param obj an Evas_Object - * @return the Evas_Object directly below - */ EAPI Evas_Object * evas_object_below_get(const Evas_Object *obj) { @@ -396,21 +345,8 @@ evas_object_below_get(const Evas_Object *obj) return NULL; } -/** - * @} - */ -/** - * @addtogroup Evas_Object_Group_Find - * @{ - */ -/** - * Get the lowest evas object on the Evas @p e - * - * @param e an Evas - * @return the lowest object - */ EAPI Evas_Object * evas_object_bottom_get(const Evas *e) { @@ -431,12 +367,6 @@ evas_object_bottom_get(const Evas *e) return NULL; } -/** - * Get the highest evas object on the Evas @p e - * - * @param e an Evas - * @return the highest object - */ EAPI Evas_Object * evas_object_top_get(const Evas *e) { @@ -468,7 +398,3 @@ evas_object_top_get(const Evas *e) return obj; } - -/** - * @} - */ diff --git a/legacy/evas/src/lib/canvas/evas_stats.c b/legacy/evas/src/lib/canvas/evas_stats.c index 94cb27b606..e141cae5c1 100644 --- a/legacy/evas/src/lib/canvas/evas_stats.c +++ b/legacy/evas/src/lib/canvas/evas_stats.c @@ -2,11 +2,6 @@ #include "evas_private.h" #include "evas_cs.h" -/** - * Retrieves if the system wants to share bitmaps using the server. - * @return @c EINA_TRUE if wants, @c EINA_FALSE otherwise. - * @ingroup Evas_Cserve - */ EAPI Eina_Bool evas_cserve_want_get(void) { @@ -16,11 +11,6 @@ evas_cserve_want_get(void) return 0; } -/** - * Retrieves if the system is connected to the server used to shae bitmaps. - * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise. - * @ingroup Evas_Cserve - */ EAPI Eina_Bool evas_cserve_connected_get(void) { @@ -30,14 +20,6 @@ evas_cserve_connected_get(void) return 0; } -/** - * Retrieves if the system wants to share bitmaps using the server. - * @param stats pointer to structure to fill with statistics about - * cache server. - * @return @c EINA_TRUE if @p stats were filled with data, - * @c EINA_FALSE otherwise and @p stats is untouched. - * @ingroup Evas_Cserve - */ EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) { @@ -155,13 +137,6 @@ evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache) #endif } -/** - * Retrieves the current configuration of the server. - * @param config where to store current server configuration. - * @return @c EINA_TRUE if @p config were filled with data, - * @c EINA_FALSE otherwise and @p config is untouched. - * @ingroup Evas_Cserve - */ EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) { @@ -179,13 +154,6 @@ evas_cserve_config_get(Evas_Cserve_Config *config) #endif } -/** - * Changes the configuration of the server. - * @param config where to store current server configuration. - * @return @c EINA_TRUE if @p config were successfully applied, - * @c EINA_FALSE otherwise. - * @ingroup Evas_Cserve - */ EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) { @@ -202,10 +170,6 @@ evas_cserve_config_set(const Evas_Cserve_Config *config) #endif } -/** - * Force system to disconnect from cache server. - * @ingroup Evas_Cserve - */ EAPI void evas_cserve_disconnect(void) { diff --git a/legacy/evas/src/lib/canvas/evas_transform.c b/legacy/evas/src/lib/canvas/evas_transform.c deleted file mode 100644 index b28c2ccfff..0000000000 --- a/legacy/evas/src/lib/canvas/evas_transform.c +++ /dev/null @@ -1,2 +0,0 @@ -#include "evas_common.h" -#include "evas_private.h"