diff options
| author | the81.kim@samsung.com <ohpowel@gmail.com> | 2014-11-21 14:55:46 +0900 |
|---|---|---|
| committer | Tae-Hwan Kim <ohpowel@gmail.com> | 2014-11-21 14:55:46 +0900 |
| commit | 2853f0221716603dc8241b52e111e65d4017d84e (patch) | |
| tree | 3a7b6f8bc51cc25901ce6a86c30cc59ef61395fe | |
| parent | 3b59913b9abc4e5c9a164970b0c99c5c13e0451f (diff) | |
| download | efl-devs/bluezery/doc.tar.gz | |
Documentation from Tizendevs/bluezery/doc
74 files changed, 38398 insertions, 22459 deletions
diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h index a6ac338cab..efd2bf95f6 100644 --- a/src/lib/ecore/Ecore.h +++ b/src/lib/ecore/Ecore.h @@ -1,103 +1,60 @@ /** - @brief Ecore Library Public API Calls - - These routines are used for Ecore Library interaction - */ - -/** - - @page ecore_main Ecore - - @date 2000 (created) - - @section toc Table of Contents - - @li @ref ecore_main_intro - @li @ref ecore_main_compiling - @li @ref ecore_main_next_steps - @li @ref ecore_main_intro_example - - @section ecore_main_intro Introduction - - Ecore is a library of convenience functions. A brief explanation of how to use - it can be found in @ref Ecore_Main_Loop_Page. - - The Ecore library provides the following modules: - @li @ref Ecore_Init_Group - @li @ref Ecore_Getopt_Group - @li @ref Ecore_Main_Loop_Group - @li @ref Ecore_System_Events - @li @ref Ecore_Time_Group - @li @ref Ecore_Thread_Group - @li @ref Ecore_Pipe_Group - @li @ref Ecore_Application_Group - @li @ref Ecore_Throttle_Group - @li @ref Ecore_Job_Group - @li @ref Ecore_File_Group - @li @ref Ecore_Con_Group - @li @ref Ecore_Evas_Group - @li @ref Ecore_FB_Group - @li @ref Ecore_Input_Group - @li @ref Ecore_IMF_Lib_Group - @li @ref Ecore_IPC_Group - @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink - @li @ref Ecore_Win32_Group - @li @ref Ecore_Audio_Group - @li @ref Ecore_Avahi_Group - @li @ref Ecore_Drm_Group - @li @ref Ecore_Wl_Group - - - - For more info on Ecore usage, there are these @ref ecore_examples. - - @section ecore_main_compiling How to compile - - Ecore 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. Note that each module is separate in pkg-config. For - example using @ref Ecore_Evas_Group: - - Compiling C or C++ files into object files: - - @verbatim - gcc -c -o main.o main.c `pkg-config --cflags ecore ecore-evas` - @endverbatim - - Linking object files into a binary executable: - - @verbatim - gcc -o my_application main.o `pkg-config --libs ecore ecore-evas` - @endverbatim - - See @ref pkgconfig - - @section ecore_main_next_steps Next Steps - - After you understood what Ecore is and installed it in your system - you should proceed understanding the programming interface. We'd - recommend you to take a while to learn @ref Eina as it is very - convenient and optimized, and Ecore uses it extensively. - - Recommended reading: - - @li @ref Ecore_Timer_Group - @li @ref Ecore_Idle_Group - @li @ref Ecore_FD_Handler_Group - @li @ref Ecore_Event_Group - @li @ref Ecore_Exe_Group - @li @ref Ecore_Animator_Group - @li @ref Ecore_Poller_Group - - - @section ecore_main_intro_example Introductory Examples - - @include ecore_timer_example.c - - More examples can be found at @ref ecore_examples. - - + * @defgroup Ecore_Group Ecore + * @ingroup EFL_Group + * + * @brief Ecore Library Public API Calls + * + * @remarks These routines are used for Ecore Library interaction. + * + * See @ref ecore_main for more details + * + * @page ecore_main Ecore + * + * @date 2000 (created) + * + * @section toc Table of Contents + * + * @li @ref ecore_main_intro + * @li @ref ecore_main_next_steps + * + * @section ecore_main_intro Introduction + * + * Ecore is a library of convenience functions. A brief explanation of how to use + * it can be found in @ref Ecore_Main_Loop_Page. + * + * The Ecore library provides the following modules: + * @li @ref Ecore_Main_Loop_Group + * @internal + * @li @ref Ecore_File_Group + * @li @ref Ecore_Con_Group + * @li @ref Ecore_Evas_Group + * @li @ref Ecore_FB_Group + * @li @ref Ecore_IMF_Group + * @li @ref Ecore_IMF_Context_Group + * @li @ref Ecore_IMF_Evas_Group + * @endinternal + * @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink + * @internal + * @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink + * @endinternal + * + * @section ecore_main_next_steps Next Steps + * + * After you understood what Ecore is and installed it in your system + * you should proceed understanding the programming interface. We'd + * recommend you to take a while to learn @ref Eina_Group as it is very + * convenient and optimized, and Ecore uses it extensively. + * + * Recommended reading: + * + * @li @ref Ecore_Timer_Group + * @li @ref Ecore_Idle_Group + * @li @ref Ecore_FD_Handler_Group + * @li @ref Ecore_Event_Group + * @internal + * @li @ref Ecore_Exe_Group + * @endinternal + * */ /** @@ -106,7 +63,7 @@ * @section Ecore_Main_Loop_Page_intro What is Ecore? * * Ecore is a clean and tiny event loop library with many modules to do lots of - * convenient things for a programmer, to save time and effort. It's small and + * convenient things for a programmer as well as to save time and effort. It's small and * lean, designed to work from embedded systems all the way up to large and * powerful multi-cpu workstations. The main loop has a number of primitives to * be used with its main loop. It serializes all the primitives and allows for @@ -120,7 +77,7 @@ * * @subsection pollers Pollers * - * Pollers allow for polling to be centralized into a single place therefore + * Pollers allow for polling to be centralized into a single place. Therefore, * alleviating the need for different parts of the program to wake up at * different times to do polling, thereby making the code simpler and more * efficient. @@ -128,30 +85,30 @@ * * @subsection idler Idlers * - * There are three types of idlers, enterers, idlers(proper) and exiters, they - * are called, respectively, when the program is about to enter an idle state, - * when the program is idle and when the program is leaving an idle state. Idler + * There are three types of idlers: enterers, idlers(proper), and exiters, they + * are called respectively when the program is about to enter an idle state, + * when the program is idle, and when the program is leaving an idle state. Idler * enterers are usually a good place to update the program state. Proper idlers * are the appropriate place to do heavy computational tasks thereby using what * would otherwise be wasted CPU cycles. Exiters are the perfect place to do - * anything your program should do just before processing events (also timers, - * pollers, file descriptor handlers and animators) + * anything that your program should do just before processing events(also timers, + * poolers, file descriptor handlers, and animators) * @see Ecore_Idle_Group * * @subsection fd_handler File descriptor handlers * * File descriptor handlers allow you to monitor when there is data available to - * read on file descriptors, when writing will not block or if there was an - * error. Any valid file descriptor can be used with this API, regardless of if - * was gotten with an OS specific API or from ecore. + * read on file descriptors, when writing is not blocked or when there is an + * error. Any valid file descriptor can be used with this API, regardless of whether + * it is obtained with an OS specific API or from ecore. * @see Ecore_FD_Handler_Group * * @subsection animators Animators * * Ecore provides a facility called animators, so named since the intended use - * was in animations, that facilitates knowing what percentage of a given + * is in animations, that facilitates knowing what percentage of a given * interval has elapsed. This is perfect for performing animations, but is not - * limited to that use, it can, for example, also be used to create a progress + * limited to that use. It can, for example, also be used to create a progress * bar. * @see Ecore_Animator_Group * @@ -159,25 +116,23 @@ * * Event handlers are, arguably, the most important feature of the ecore main * loop, they are what allows the programmer to easily handle user interaction. - * Events however are not only things the user does, events can represent + * Events, however, are not the only things that the user does. Events can represent * anything for which a type is created. * @see Ecore_Event_Group * * All of these primitives are discussed in more detail in their respective - * pages linked above. + * pages that are linked above. * * Here is a diagram of the main loop flow of a simple program: * * @image html prog_flow.png - * @image latex prog_flow.eps width=\textwidth - * - * + * @image latex prog_flow.eps "prog flow" width=\textwidth * * @section Ecore_Main_Loop_Page_work How does Ecore work? * * Ecore is very easy to learn and use. All the function calls are designed to * be easy to remember, explicit in describing what they do, and heavily - * name-spaced. Ecore programs can start and be very simple. + * name-spaced. Ecore programs can start easily and are very simple. * * For example: * @@ -196,7 +151,7 @@ * @endcode * * This program is very simple and doesn't check for errors, but it does start up - * and begin a main loop waiting for events or timers to tick off. This program + * and begin a main loop that is waiting for events or timers to tick off. This program * doesn't set up any, but now we can expand on this simple program a little * more by adding some event handlers and timers. * @@ -242,14 +197,14 @@ * @endcode * * In the previous example, we initialize our application and get the time at - * which our program has started so we can calculate an offset. We set - * up a timer to tick off in 0.5 seconds, and since it returns 1, will - * keep ticking off every 0.5 seconds until it returns 0, or is deleted + * which our program has started so that we can calculate an offset. We set + * up a timer to tick off in @c 0.5 seconds, and since it returns @c 1, it + * keeps ticking off every @c 0.5 seconds until it returns @c 0, or is deleted * by hand. An event handler is set up to call a function - * exit_func(), * whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C - * on the command line will cause such an event to happen). If this event - * occurs it tells you what kind of exit signal was received, and asks + * on the command line causes such an event to happen). If this event + * occurs it tells you what kind of exit signal is received, and asks * the main loop to quit when it is finished by calling * ecore_main_loop_quit(). * @@ -257,11 +212,11 @@ * ecore_event_handler_add() are * only stored here as an example. If you don't need to address the timer or * event handler again you don't need to store the result, so just call the - * function, and don't assign the result to any variable. + * function and don't assign the result to any variable. * * This program looks slightly more complex than needed to do these simple * things, but in principle, programs don't get any more complex. You add more - * event handlers, for more events, will have more timers and such, BUT it all + * event handlers for more events, you have more timers, BUT it all * follows the same principles as shown in this example. * */ @@ -275,34 +230,19 @@ To use the library, you: @li Set the default values of your properties. - @li Load the configuration from a file. You must set the default values + @li Load the configuration from a file. You must set the default values first, so that the library knows the correct type of each argument. - The following examples show how to use the Enlightened Property Library: - @li @link config_basic_example.c config_basic_example.c @endlink - @li @link config_listener_example.c config_listener_example.c @endlink - - */ - -/** - @page X_Window_System_Page X Window System - - The Ecore library includes a wrapper for handling the X window system. - This page briefly explains what the X window system is and various terms - that are used. */ #ifndef _ECORE_H #define _ECORE_H -#include <Efl_Config.h> - #ifdef _MSC_VER # include <Evil.h> #endif #include <Eina.h> -#include <Eo.h> #ifdef EAPI # undef EAPI @@ -350,13 +290,3172 @@ extern "C" { #endif -#include "Ecore_Common.h" -#ifndef EFL_NOLEGACY_API_SUPPORT -#include "Ecore_Legacy.h" +/** + * @internal + * @defgroup Ecore_Init_Group Ecore initialization, shutdown functions and reset on fork. + * @ingroup Ecore_Group + * + * @{ + */ + +/** + * @brief Initialize the Ecore library. + * + * @details This function sets up connections, sockets, all singal handlers and + * the basic event loop, etc. If it succeeds, 1 or greater will be + * returned, otherwise 0 will be returned. + * + * @remarks This function initializes the Ecore library, making the proper calls + * to internal initialization functions. It will also initialize its + * @b dependencies, making calls to @c eina_init(). + * So, there is no need to call those functions again, in your code. + * To shutdown Ecore, there is the function ecore_shutdown(). + * + * @code + * #include <Ecore.h> + * + * int main(int argc, char **argv) + * { + * if (!ecore_init()) + * { + * printf("ERROR: Cannot init Ecore!\n"); + * return -1; + * } + * ecore_main_loop_begin(); + * ecore_shutdown(); + * } + * @endcode + * + * @return 1 or greater on success, 0 otherwise + * + * @see ecore_shutdown() + * @see eina_init() + */ +EAPI int ecore_init(void); + +/** + * @brief Shutdown the Ecore library. + * + * @details Shut down connections, signal handlers sockets etc. + * + * @remarks This function shuts down all things set up in ecore_init() and + * cleans up all event queues, handlers, filters, timers, idlers, + * idle enterers/exiters etc. set up after ecore_init() was called. + * + * @remarks Do not call this function from any callback that may be called + * from the main loop, as the main loop will then fall over and not + * function properly. + * + * @details This function shuts down the Edje library. It will also call the + * shutdown functions of its @b dependencies, which is @c + * eina_shutdown(). + * so there is no need to call these functions again in your code. + * This returns The number of times the library has been initialised + * without being shutdown. + * + * @return 0 if ecore shuts down, greater than 0 otherwise. + * + * @see ecore_init() + * @see eina_shutdown() + */ +EAPI int ecore_shutdown(void); + +/** + * @} + */ + +/** + * @internal + * @defgroup Ecore_Application_Group Ecore Application + * @ingroup Ecore_Group + * + * @{ + */ + +EAPI void ecore_app_args_set(int argc, const char **argv); +EAPI void ecore_app_args_get(int *argc, char ***argv); +EAPI void ecore_app_restart(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Main_Loop_Group Ecore Main Loop + * @ingroup Ecore_Group + * + * @brief This group discusses functions that are acting on Ecore's main loop itself or + * on events and infrastructure directly linked to it. Most programs only need + * to start and end the main loop, the rest of the function discussed here is + * meant to be used in special situations, and with great care. + * + * For details on the usage of ecore's main loop and how it interacts with other + * ecore facilities see: @ref Ecore_Main_Loop_Page. + * + * @{ + */ + +#define ECORE_VERSION_MAJOR 1 +#define ECORE_VERSION_MINOR 8 + +typedef struct _Ecore_Version +{ + int major; + int minor; + int micro; + int revision; +} Ecore_Version; + +EAPI extern Ecore_Version *ecore_version; + +#define ECORE_CALLBACK_CANCEL EINA_FALSE /**< Return value to remove a callback */ +#define ECORE_CALLBACK_RENEW EINA_TRUE /**< Return value to keep a callback */ + +#define ECORE_CALLBACK_PASS_ON EINA_TRUE /**< Return value to pass an event to the next handler */ +#define ECORE_CALLBACK_DONE EINA_FALSE /**< Return value to stop event handling */ + +/** + * @typedef Ecore_Task_Cb Ecore_Task_Cb + * @brief The boolean type for a callback that is run for a task (timer, idler, poller, animator, and so on). + */ +typedef Eina_Bool (*Ecore_Task_Cb)(void *data); + +/** + * @typedef Ecore_Cb Ecore_Cb + * @brief Called as a hook when a certain point in the execution is reached. + */ +typedef void (*Ecore_Cb)(void *data); + +/** + * @typedef Ecore_Data_Cb Ecore_Data_Cb + * @brief Called to return data to the main function. + */ +typedef void *(*Ecore_Data_Cb)(void *data); + +/** + * @typedef Ecore_Select_Function + * @brief The integer type for a function that can be used to replace select() in the main loop. + */ +typedef int (*Ecore_Select_Function)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); + +/** + * @brief Adds a function to be called by ecore_fork_reset(). + * + * @details This queues @a func to be called (and passes @a data as its argument) when + * ecore_fork_reset() is called. This allows other libraries and subsystems + * to also reset their internal state after a fork. + * + * @param[in] func The function to be called + * @param[in] data A data pointer to pass to the called function @a func + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE. + * + * @since 1.7 + * @since_tizen 2.3 + */ +EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); + +/** + * @brief Removes the specified callback. + * + * @details This deletes the callback added by ecore_fork_reset_callback_add() using + * the function and data pointer to specify which callback to remove. + * + * @param[in] func The function to be called + * @param[in] data A data pointer to pass to the called function @a func + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE. + * + * @since 1.7 + * @since_tizen 2.3 + */ +EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data); + +/** + * @brief Resets the ecore's internal state after a fork. + * + * @since 1.7 + * @since_tizen 2.3 + * + * @remarks Ecore maintains the internal data that can be affected by the fork() system call, + * which creates a duplicate of the current process. This also duplicates + * file descriptors, which is problematic as these file descriptors still + * point to their original sources. This function makes ecore's reset internal + * state (e.g. pipes used for signalling between threads) so they function + * correctly afterwards. + * + * @remarks It is highly suggested that you call this function after any fork() + * system call inside the child process. If you intend to use ecore features + * after this point and not call exec() family functions. Not doing so + * causes a possible misbehaviour. + */ +EAPI void ecore_fork_reset(void); + +/** + * @brief Runs a single iteration of the main loop to process everything on the + * queue. + * + * @details It does everything that is already done inside an @c Ecore main loop, + * like checking for expired timers, idlers, etc. But it will do it + * only once and return, instead of keep watching for new events. + * + * @remarks DO NOT use this function unless you are the person God comes to ask + * for advice when He has trouble managing the Universe. + * + * @see ecore_main_loop_iterate_may_block() + */ +EAPI void ecore_main_loop_iterate(void); + +/** + * @brief Sets the function to use when monitoring multiple file descriptors, + * and waiting until one of more of the file descriptors before ready + * for some class of I/O operation. + * + * @remarks This function will be used instead of the system call select and + * could possible be used to integrate the Ecore event loop with an + * external event loop. + * + * @remarks you don't know how to use, don't even try to use it. + * + * @param func The function to be used. + * + * @see ecore_main_loop_select_func_get() + */ +EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func); + +/** + * @brief Gets the select function set by ecore_select_func_set(), + * or the native select function if none was set. + * + * @return The select function + * + * @see ecore_main_loop_select_func_get() + */ +EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void); + +/** + * @brief Request ecore to integrate GLib's main loop. + * + * @details This will add a small overhead during every main loop interaction + * by checking glib's default main context (used by its main loop). If + * it have events to be checked (timers, file descriptors or idlers), + * then these will be polled alongside with Ecore's own events, then + * dispatched before Ecore's. This is done by calling + * ecore_main_loop_select_func_set(). + * + * @remarks This will cooperate with previously set + * ecore_main_loop_select_func_set() by calling the old function. + * Similarly, if you want to override + * ecore_main_loop_select_func_set() after main loop is integrated, + * call the new select function set by this call (get it by calling + * ecore_main_loop_select_func_get() right after + * ecore_main_loop_glib_integrate()). + * + * @remarks This is useful to use GMainLoop libraries, like GTK, GUPnP, + * LibSoup, GConf and more. Adobe Flash plugin and other plugins + * systems depend on this as well. + * + * @remarks Once initialized/integrated, it will be valid until Ecore is + * completely shut down. + * + * Example of use: + * @code + * + * int main(void) + * { + * ecore_init(); + * ecore_main_loop_glib_integrate(); + * + * // some code here + * + * ecore_main_loop_begin(); + * + * ecore_shutdown(); + * + * return 0; + * } + * + * @endcode + * + * @remarks This is only available if Ecore was compiled with GLib support. + * @remarks You don't need to call this function if Ecore was compiled with + * --with-glib=always. + * + * @return #EINA_TRUE on success of @c EINA_FALSE if it failed, + * likely no GLib support in Ecore. + */ +EAPI Eina_Bool ecore_main_loop_glib_integrate(void); + +/** + * @brief Disable always integrating glib + * + * @remarks If ecore is compiled with --with-glib=always (to always call + * ecore_main_loop_glib_integrate() when ecore_init() is called), + * then calling this before calling ecore_init() will disable the + * integration. This is for apps that explicitly do not want this + * to happen for whatever reasons they may have. + */ +EAPI void ecore_main_loop_glib_always_integrate_disable(void); + +/** + * @brief Runs the application main loop. + * + * @details This function will not return until @ref ecore_main_loop_quit is + * called. It will check for expired timers, idlers, file descriptors + * being watched by fd handlers, etc. Once everything is done, before + * entering again on idle state, any callback set as @c Idle_Enterer + * will be called. + * + * @remarks Each main loop iteration is done by calling + * ecore_main_loop_iterate() internally. + * + * @remarks The polling (select) function used can be changed with + * ecore_main_loop_select_func_set(). + * + * @remarks The function used to check for file descriptors, events, and that + * has a timeout for the timers can be changed using + * ecore_main_loop_select_func_set(). + */ +EAPI void ecore_main_loop_begin(void); + +/** + * @brief Quits the main loop once all the events currently on the queue have + * been processed. + * + * @details This function returns immediately, but will mark the + * ecore_main_loop_begin() function to return at the end of the + * current main loop iteration. + */ +EAPI void ecore_main_loop_quit(void); + +/** + * @brief Called asynchronously in the main loop. + * + * @since 1.1.0 + * + * @remarks For all calls that need to happen in the main loop (most EFL functions do), + * this helper function provides the infrastructure needed to do it safely + * by avoiding a dead lock, race condition, and by properly waking up the main loop. + * + * @remarks Remember that after the function call, you should never touch the @a data + * in the thread again, it is owned by the main loop and your callback should take + * care of freeing it, if necessary. + * + * @param callback The callback to call in the main loop + * @param data The data to give to that call + */ +EAPI void ecore_main_loop_thread_safe_call_async(Ecore_Cb callback, void *data); + +/** + * @brief Called synchronously in the main loop. + * + * @since 1.1.0 + * + * @remarks For all calls that need to happen in the main loop (most EFL functions do), + * this helper function provides the infrastructure needed to do it safely + * by avoiding a dead lock, race condition, and by properly waking up the main loop. + * + * @remarks Remember that this function blocks until the callback is executed in the + * main loop. It can take time and you have no guarantee about the timeline. + * + * @param callback The callback to call in the main loop + * @param data The data to give to that call + * @return The value returned by the callback in the main loop + */ +EAPI void *ecore_main_loop_thread_safe_call_sync(Ecore_Data_Cb callback, void *data); + +/** + * @brief Suspends the main loop in the know state. + * + * @details This function suspends the main loop in the know state. This lets you + * use any EFL call that you want after it returns. Be careful, the main loop + * is blocked until you call ecore_thread_main_loop_end(). This is + * the only way to achieve pseudo thread safety. + * + * @since 1.1.0 + * + * @remarks Notice that till the main loop is blocked, the thread is blocked + * and there is no way around that. + * + * @remarks We still advise you, if possible, to use ecore_main_loop_thread_safe_call_async() + * as it does not block the thread or the main loop. + * + * @return The number of times ecore_thread_main_loop_begin() has been called + * in this thread, if the main loop is suspended correctly \n + * If not, it returns @c -1. + */ +EAPI int ecore_thread_main_loop_begin(void); + +/** + * @brief Unlocks the main loop. + * + * @since 1.1.0 + * + * @remarks After a call to ecore_thread_main_loop_begin(), you need to absolutely + * call ecore_thread_main_loop_end(), or your application stays frozen. + * + * @return The number of times ecore_thread_main_loop_end() needs to be called before + * the main loop is unlocked again \n + * @c -1 is retured if you are trying to unlock + * when there aren't enough calls to ecore_thread_main_loop_begin(). + * + */ +EAPI int ecore_thread_main_loop_end(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Event_Group Ecore Event + * @ingroup Ecore_Main_Loop_Group + * + * @brief Ecore event are a helper to create events are being notified of events. + * + * Ecore events provide two main features that are of use to those using ecore: + * creating events and being notified of events. Those two are usually used + * in different contexts, creating events is mainly done by libraries wrapping + * some system functionality while being notified of events is mainly a + * necessity of applications. + * + * For a program to be notified of events it's interested in, it needs to have a + * function to process the event and to register that function as the callback + * to the event, that's all: + * @code + * ecore_event_handler_add(EVENT_TYPE, _my_event_handler, some_data); + * ... + * static Eina_Bool + * _my_event_handler(void *data, int type, void *event) + * { + * //Data is some_data + * //Event is provided by whoever created the event + * //Do really cool stuff with the event + * } + * @endcode + * + * One very important thing to note here is the @c EVENT_TYPE. To register a + * handler for an event, you must know its type before hand. Ecore provides + * the following events that are emitted in response to POSIX + * signals(https://en.wikipedia.org/wiki/Signal_%28computing%29): + * @li @b ECORE_EVENT_SIGNAL_USER + * @li @b ECORE_EVENT_SIGNAL_HUP + * @li @b ECORE_EVENT_SIGNAL_POWER + * @li @b ECORE_EVENT_SIGNAL_EXIT + * + * Don't override these using the @c signal or @c sigaction calls. + * These, however, aren't the only signals one can handle. Many + * libraries(including ecore modules) have their own signals that can be + * listened to and handled. To do that one only needs to know the type of the + * event. This information can be found on the documentation of the library + * emitting the signal. + * @internal + * So, for example, for events related to windowing one + * would use @ref Ecore_Evas_Group. + * + * Examples of libraries that integrate into ecore's main loop by providing + * events are @ref Ecore_Con_Group, @ref Ecore_Evas_Group, and @ref + * Ecore_Exe_Group, amongst others. + * @endinternal + * + * This usage can be divided into two parts, + * setup and adding events. The setup is very simple, all that needs to be done is + * getting a type ID for the event: + * @code + * int MY_EV_TYPE = ecore_event_type_new(); + * @endcode + * This variable should be declared in the header since it is needed by + * anyone wishing to register a handler to your event. + * + * The complexity of adding an event to the queue depends on whether that + * event sends or uses @a event, if it doesn't it is a one-liner: + * @code + * ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL); + * @endcode + * The usage when an @c event is needed is not that complex and can be + * seen in @ref ecore_event_add. + * + * @{ + */ + +#define ECORE_EVENT_NONE 0 +#define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */ +#define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */ +#define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */ +#define ECORE_EVENT_SIGNAL_POWER 4 /**< Power signal event */ +#define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */ +#define ECORE_EVENT_COUNT 6 + +typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< @internal @brief A handle for HANDLE handlers on Windows */ +typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< @brief A handle for an event handler */ +typedef struct _Ecore_Event_Filter Ecore_Event_Filter; /**< @brief A handle for an event filter */ +typedef struct _Ecore_Event Ecore_Event; /**< @brief A handle for an event */ +typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User; /**< @brief User signal event */ +typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup; /**< @brief Hup signal event */ +typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit; /**< @brief Exit signal event */ +typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power; /**< @brief Power signal event */ +typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime; /**< @brief Realtime signal event */ + +/** + * @typedef Ecore_Filter_Cb + * @brief The boolean type for a callback used for filtering events from the main loop. + */ +typedef Eina_Bool (*Ecore_Filter_Cb)(void *data, void *loop_data, int type, void *event); + +/** + * @typedef Ecore_End_Cb Ecore_End_Cb + * @brief Called at the end of a function, usually for cleanup purposes. + */ +typedef void (*Ecore_End_Cb)(void *user_data, void *func_data); + +/** + * @typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb + * @brief The boolean type used by the main loop to handle events of a specified type. + */ +typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event); + +struct _Ecore_Event_Signal_User /** User signal event */ +{ + int number; /**< The signal number. Either 1 or 2 */ + void *ext_data; /**< Extension data - not used */ + +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ +#endif +}; + +struct _Ecore_Event_Signal_Hup /** Hup signal event */ +{ + void *ext_data; /**< Extension data - not used */ + +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ +#endif +}; + +struct _Ecore_Event_Signal_Exit /** Exit request event */ +{ + Eina_Bool interrupt : 1; /**< Set if the exit request is an interrupt signal*/ + Eina_Bool quit : 1; /**< Set if the exit request is a quit signal */ + Eina_Bool terminate : 1; /**< Set if the exit request is a terminate signal */ + void *ext_data; /**< Extension data - not used */ + +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ #endif -#ifdef EFL_EO_API_SUPPORT -#include "Ecore_Eo.h" +}; + +struct _Ecore_Event_Signal_Power /** Power event */ +{ + void *ext_data; /**< Extension data - not used */ + +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ +#endif +}; + +struct _Ecore_Event_Signal_Realtime /** Realtime event */ +{ + int num; /**< The realtime signal's number */ + +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ +#endif +}; + +/** + * @brief Adds an event handler. + * + * @details This adds an event handler to the list of handlers. This, on success, returns + * a handle to the event handler object that is created, that can be used + * later to remove the handler using ecore_event_handler_del(). The @a type + * parameter is the integer of the event type that triggers this callback + * to be called. The callback @a func is called when this event is processed + * and is passed the event type, a pointer to the private event + * structure that is specific to that event type, and a data pointer that is + * provided in this call as the @a data parameter. + * + * @since_tizen 2.3 + * + * @remarks When the callback @a func is called, it must return @c 1 or @c 0. If it returns + * @c 1 (or @c ECORE_CALLBACK_PASS_ON), it keeps being called as per normal, for + * each handler set up for that event type. If it returns @c 0 (or + * @c ECORE_CALLBACK_DONE), it ceases processing handlers for that particular + * event, so all handlers set to handle that event type that have not already + * been called, are not called. + * + * @param[in] type The type of the event that this handler gets called for + * @param[in] func The function to call when the event is found in the queue + * @param[in] data A data pointer to pass to the called function @a func + * @return A new Event handler, + * otherwise @c NULL on failure + */ +EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); + +/** + * @brief Deletes an event handler. + * + * @details This deletes a specified event handler from the handler list. On success, this + * deletes the event handler and returns the pointer passed as @a data when the + * handler is added by ecore_event_handler_add(). On failure, @c NULL is + * returned. Once a handler is deleted it is no longer called. + * + * @since_tizen 2.3 + * + * @param[in] event_handler The event handler handle to delete + * @return The data passed to the handler + */ +EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); + +/** + * @brief Adds an event to the event queue. + * + * @remarks If it succeeds, an event of type @a type is added to the queue for + * processing by event handlers added by ecore_event_handler_add(). The @a ev + * parameter is passed as the @a event parameter of the handler. When the + * event is no longer needed, @a func_free is called and it passes @a ev for + * cleaning up. If @a func_free is @c NULL, free() is called with the private + * structure pointer. + * + * @since_tizen 2.3 + * + * @param[in] type The event type to add to the end of the event queue + * @param[in] ev The data structure passed as @a event to event handlers + * @param[in] func_free The function to be called to free @a ev + * @param[in] data The data pointer to be passed to the free function + * @return A Handle for that event on success, + * otherwise @c NULL on failure + */ +EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data); + +/** + * @brief Deletes an event from the queue. + * + * @details This deletes the event @a event from the event queue, and returns the + * @a data parameter originally set when adding it using ecore_event_add(). This + * does not immediately call the free function, and it may be called later for + * cleanup, and so if the free function depends on the data pointer to work, + * you should defer cleaning of this till the free function is called later. + * + * @since_tizen 2.3 + * + * @param[in] event The event handle to delete + * @return The data pointer originally set for the event free function + */ +EAPI void *ecore_event_del(Ecore_Event *event); + +/** + * @brief Gets the data associated with an #Ecore_Event_Handler. + * + * @details This function returns the data previously associated with @a eh by + * ecore_event_handler_add(). + * + * @since_tizen 2.3 + * + * @param[in] eh The event handler + * @return The data + */ +EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); + +/** + * @brief Sets the data associated with an #Ecore_Event_Handler. + * + * @details This function sets @a data to @a eh and returns the old data pointer + * that had been previously associated with @a eh by ecore_event_handler_add(). + * + * @since_tizen 2.3 + * + * @param[in] eh The event handler + * @param[in] data The data to associate + * @return The previous data + */ +EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); + +/** + * @brief Allocates a new event type ID sensibly and returns the new ID. + * + * @details This function allocates a new event type ID and returns it. Once an event + * type has been allocated it can never be de-allocated during the life of + * the program. There is no guarantee of the contents of this event ID, or how + * it is calculated, except that the ID is unique to the current instance + * of the process. + * + * @since_tizen 2.3 + * + * @return A new event type ID + * + */ +EAPI int ecore_event_type_new(void); + +/** + * @brief Adds a filter to the current event queue. + * + * @details This adds a callback to filter events from the event queue. Filters are called on + * the queue just before Event handler processing to try and remove redundant + * events. Just when processing is about to start @a func_start is called and + * passed the @a data pointer. The return value of this function is passed to + * @a func_filter as loop_data. @a func_filter is also passed @a data, the + * event type, and the event structure. If this @a func_filter returns + * @c EINA_FALSE, the event is removed from the queue. If it returns + * #EINA_TRUE, the event is kept. When processing is finished @a func_end is + * called and is passed the loop_data(returned by @a func_start) and @a data + * pointer to clean up. + * + * @since_tizen 2.3 + * + * @param[in] func_start The function to call just before filtering and returning data + * @param[in] func_filter The function to call on each event + * @param[in] func_end The function to call after the queue has been filtered + * @param[in] data The data to pass to the filter functions + * @return A filter handle on success, + * otherwise @c NULL on failure + * + */ +EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data); + +/** + * @brief Deletes an event filter. + * + * @details This deletes a filter that has been added by its @a ef handle. + * + * @since_tizen 2.3 + * + * @param[in] ef The event filter handle + * @return The data set for the filter on success, + * otherwise @c NULL + */ +EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); + +/** + * @brief Returns the current event type being handled. + * + * @since_tizen 2.3 + * + * @remarks If the program is currently inside an Ecore event handler callback this + * returns the type of the current event being processed. + * + * This is useful when certain Ecore modules such as Ecore_Evas "swallow" + * events and not all the original information is passed on. In special cases, + * this extra information may be useful or needed and using this call can let + * the program know if the event type being handled is the one about which it wants to get more + * information. + * + * @return The current event type being handled if inside a handler callback, + * otherwise @c ECORE_EVENT_NONE + */ +EAPI int ecore_event_current_type_get(void); +/** + * @brief Returns the current event type pointer handled. + * + * @since_tizen 2.3 + * + * @remarks If the program is currently inside an Ecore event handler callback this + * returns the pointer of the current event being processed. + * + * @remarks This is useful when certain Ecore modules such as Ecore_Evas "swallow" + * events and not all the original information is passed on. In special cases, + * this extra information may be useful or needed and using this call can let + * the program access the event data if the type of the event is handled by + * the program. + * + * @return The current event pointer being handled if inside a handler callback, + * otherwise @c NULL + */ +EAPI void *ecore_event_current_event_get(void); + +/** + * @} + */ + +/** + * @internal + * @defgroup Ecore_Exe_Group Process Spawning + * @ingroup Ecore_Main_Loop_Group + * + * This module is responsible for managing portable processes using Ecore. + * With this module you're able to spawn processes and you can also pause and + * quit your spawned processes. + * An interaction between your process and those spawned is possible + * using pipes or signals. + * + * @{ + */ + +/** Inherit priority from the parent process */ +#define ECORE_EXE_PRIORITY_INHERIT 9999 + +EAPI extern int ECORE_EXE_EVENT_ADD; /**< @brief A child process has been added */ +EAPI extern int ECORE_EXE_EVENT_DEL; /**< @brief A child process has been deleted (it exited, naming is consistent with the rest of ecore) */ +EAPI extern int ECORE_EXE_EVENT_DATA; /**< @brief Data from a child process */ +EAPI extern int ECORE_EXE_EVENT_ERROR; /**< @brief Errors from a child process */ + +/** + * @internal + * @enum _Ecore_Exe_Flags + * @brief Enumeration that defines the flags for executing a child with its stdin and/or stdout piped back. + */ +enum _Ecore_Exe_Flags /* Flags for executing a child with its stdin and/or stdout piped back */ +{ + ECORE_EXE_NONE = 0, /**< No exe flags at all */ + ECORE_EXE_PIPE_READ = 1, /**< Exe Pipe Read mask */ + ECORE_EXE_PIPE_WRITE = 2, /**< Exe Pipe Write mask */ + ECORE_EXE_PIPE_ERROR = 4, /**< Exe Pipe error mask */ + ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8, /**< Reads are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */ + ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, /**< Errors are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */ + ECORE_EXE_PIPE_AUTO = 32, /**< stdout and stderr are buffered automatically */ + ECORE_EXE_RESPAWN = 64, /**< FIXME: Exe is restarted if it dies */ + ECORE_EXE_USE_SH = 128, /**< Use /bin/sh to run the command */ + ECORE_EXE_NOT_LEADER = 256, /**< Do not use setsid() to make the executed process its own session leader */ + ECORE_EXE_TERM_WITH_PARENT = 512 /**< Makes a child receive SIGTERM when the parent dies */ +}; +typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags; + +/** + * @internal + * @enum _Ecore_Exe_Win32_Priority + * @brief Enumeration that defines the priority of the proccess. + */ +enum _Ecore_Exe_Win32_Priority +{ + ECORE_EXE_WIN32_PRIORITY_IDLE, /**< Idle priority, for monitoring the system */ + ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL, /**< Below default priority */ + ECORE_EXE_WIN32_PRIORITY_NORMAL, /**< Default priority */ + ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL, /**< Above default priority */ + ECORE_EXE_WIN32_PRIORITY_HIGH, /**< High priority, use with care as other threads in the system do not get processor time */ + ECORE_EXE_WIN32_PRIORITY_REALTIME /**< Realtime priority, should be almost never used as it can interrupt system threads that manage mouse input, keyboard input, and background disk flushing */ +}; +typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority; + +typedef struct _Ecore_Exe Ecore_Exe; /**< @brief A handle for spawned processes */ + +/** + * @typedef Ecore_Exe_Cb Ecore_Exe_Cb + * @brief Called to run with the associated @ref Ecore_Exe, usually + * for cleanup purposes. + */ +typedef void (*Ecore_Exe_Cb)(void *data, const Ecore_Exe *exe); + +typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add; /**< @brief Spawned Exe add event */ +typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< @brief Spawned Exe exit event */ +typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< @brief Lines from a child process */ +typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< @brief Data from a child process */ + +/** +* @internal +* @brief Structure of Ecore Exe Event Add +*/ +struct _Ecore_Exe_Event_Add /** Process add event */ +{ + Ecore_Exe *exe; /**< The handle to the added process */ + void *ext_data; /**< Extension data - not used */ +}; + +struct _Ecore_Exe_Event_Del /** Process exit event */ +{ + pid_t pid; /**< The process ID of the process that exited */ + int exit_code; /**< The exit code of the process */ + Ecore_Exe *exe; /**< The handle to the exited process, otherwise @c NULL if not found */ + int exit_signal; /** < The signal that caused the process to exit */ + Eina_Bool exited : 1; /** < Set to @c 1 if the process exited on its own */ + Eina_Bool signalled : 1; /** < Set to @c 1 if the process exited due to an uncaught signal */ + void *ext_data; /**< Extension data - not used */ +#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL) + siginfo_t data; /**< Signal info */ +#endif +}; + +struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */ +{ + char *line; /**< The bytes of a line of buffered data */ + int size; /**< The size of the line buffer in bytes */ +}; + +struct _Ecore_Exe_Event_Data /** Data from a child process event */ +{ + Ecore_Exe *exe; /**< The handle to the process */ + void *data; /**< The raw binary data from the child process that is received */ + int size; /**< The size of this data in bytes */ + Ecore_Exe_Event_Data_Line *lines; /**< An array of line data if line buffered, the last one has its line member set to @c NULL */ +}; + +EAPI void ecore_exe_run_priority_set(int pri); +EAPI int ecore_exe_run_priority_get(void); +EAPI Ecore_Exe *ecore_exe_run(const char *exe_cmd, const void *data); +EAPI Ecore_Exe *ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, const void *data); +EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func); +EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, int size); +EAPI void ecore_exe_close_stdin(Ecore_Exe *exe); +EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines); +EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags); +EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data); +EAPI void *ecore_exe_free(Ecore_Exe *exe); +EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe); +EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag); +EAPI const char *ecore_exe_tag_get(const Ecore_Exe *exe); +EAPI const char *ecore_exe_cmd_get(const Ecore_Exe *exe); +EAPI void *ecore_exe_data_get(const Ecore_Exe *exe); +EAPI void *ecore_exe_data_set(Ecore_Exe *exe, void *data); +EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe); +EAPI void ecore_exe_pause(Ecore_Exe *exe); +EAPI void ecore_exe_continue(Ecore_Exe *exe); +EAPI void ecore_exe_interrupt(Ecore_Exe *exe); +EAPI void ecore_exe_quit(Ecore_Exe *exe); +EAPI void ecore_exe_terminate(Ecore_Exe *exe); +EAPI void ecore_exe_kill(Ecore_Exe *exe); +EAPI void ecore_exe_signal(Ecore_Exe *exe, int num); +EAPI void ecore_exe_hup(Ecore_Exe *exe); + +/** + * @} + */ + +/** + * @defgroup Ecore_FD_Handler_Group Ecore File Descriptor Handling + * @ingroup Ecore_Main_Loop_Group + * + * @brief This group discusses functions that deal with file descriptor handlers. + * + * File descriptor handlers facilitate reading, writing, and checking for errors + * without blocking the program or doing expensive pooling. This can be used to + * monitor a socket, pipe, or some other stream for which an FD can be present. + * + * File descriptor handlers can't be used to monitor file creation, + * modification, or deletion, + * @internal + * see @ref Ecore_File_Group for this. + * @endinternal + * + * One common FD to be monitored is the standard input(stdin), monitoring it for + * reading requires a single call: + * @code + * static Eina_Bool + * _my_cb_func(void *data, Ecore_Fd_Handler *handler) + * { + * char c; + * scanf("%c", &c); //Guaranteed not to block + * ... do stuff with c ... + * } + * ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL); + * @endcode + * + * When using a socket, pipe, or some other stream it's important to remember that + * errors may occur and we must monitor not only for reading/writing, but also + * for errors using the @ref ECORE_FD_ERROR flag. + * + * @{ + */ + +/** + * @brief typedef to struct _Ecore_Fd_Handler + */ +typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for FD handlers */ + +/** + * @enum _Ecore_Fd_Handler_Flags + * @brief Enumeration that defines the handler flags to monitor the file descriptor for: reading, writing, or error. + */ +enum _Ecore_Fd_Handler_Flags +{ + ECORE_FD_READ = 1, /**< FD Read mask */ + ECORE_FD_WRITE = 2, /**< FD Write mask */ + ECORE_FD_ERROR = 4 /**< FD Error mask */ +}; + +/** + * @brief typedef to enum _Ecore_Fd_Handler_Flags + */ +typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags; + +/** + * @typedef Ecore_Fd_Cb Ecore_Fd_Cb + * @brief The boolean type for a callback used by an @ref Ecore_Fd_Handler. + */ +typedef Eina_Bool (*Ecore_Fd_Cb)(void *data, Ecore_Fd_Handler *fd_handler); + +/** + * @typedef Ecore_Fd_Prep_Cb Ecore_Fd_Prep_Cb + * @brief Called to be used by an @ref Ecore_Fd_Handler. + */ +typedef void (*Ecore_Fd_Prep_Cb)(void *data, Ecore_Fd_Handler *fd_handler); + +/** + * @internal + * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb + * @brief The boolean type for a callback used by an @ref Ecore_Win32_Handler. + */ +typedef Eina_Bool (*Ecore_Win32_Handle_Cb)(void *data, Ecore_Win32_Handler *wh); + +/** + * @brief Adds a callback for activity on the given file descriptor. + * + * @since_tizen 2.3 + * + * @remarks @a func is called during the execution of @ref Ecore_Main_Loop_Page + * when the file descriptor is available for reading, writing, or there has been + * an error(depending on the given @a flags). + * + * @remarks When @a func returns @c ECORE_CALLBACK_CANCEL, it indicates that the + * handler should be marked for deletion (identical to calling @ref + * ecore_main_fd_handler_del). + * + * @remarks @a buf_func is meant for @b internal use only and should be @b + * avoided. + * + * @remarks The return value of @a buf_func has a different meaning, when it returns + * @c ECORE_CALLBACK_CANCEL, it indicates that @a func @b shouldn't be called, and + * when it returns @c ECORE_CALLBACK_RENEW it indicates @a func should be called. + * The return value of @a buf_func does not cause the FD handler to get deleted. + * + * @remarks @a buf_func is called during event loop handling to check if data that has + * been read from the file descriptor is in a buffer and is available to read. + * Some systems, notably xlib, handle their own buffering, and would otherwise + * not work with select(). These systems should use a @a buf_func. This is the + * most annoying hack, only ecore_x uses it, so refer to that for an example. + * + * @remarks This function should @b not be used for monitoring "normal" files, like text files. + * + * @param[in] fd The file descriptor to watch + * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c + * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n + * Values by |(ored). + * @param[in] func The callback function + * @param[in] data The data to pass to the callback + * @param[in] buf_func The function to call to check if any data has been buffered + * and already read from the fd \n + * May be @c NULL. + * @param[in] buf_data The data to pass to the @a buf_func function + * @return An fd handler handle on success, + * otherwise @c NULL on failure + * + */ +EAPI Ecore_Fd_Handler *ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data); + +/** + * @brief Adds a callback for activity on the given file descriptor. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @remarks This function is identical to ecore_main_fd_handler_add, except that it supports regular files. + * + * @remarks This function should ONLY be called with @c ECORE_FD_ERROR, otherwise it calls the fd + * handler constantly. + * @remarks Do not use this function unless you know what you are doing. + * + * @param[in] fd The file descriptor to watch + * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c + * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n + * Values by |(ored). + * @param[in] func The callback function + * @param[in] data The data to pass to the callback + * @param[in] buf_func The function to call to check if any data has been buffered + * and already read from the fd \n + * May be @c NULL. + * @param[in] buf_data The data to pass to the @a buf_func function. + * @return An fd handler handle on success, + * otherwise @c NULL on failure + */ +EAPI Ecore_Fd_Handler *ecore_main_fd_handler_file_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data); + +/** + * @brief Sets the prepare callback with data for a given #Ecore_Fd_Handler. + * + * @since_tizen 2.3 + * + * @remarks This function is called prior to any fd handler's callback function + * (even the other fd handlers), before entering the main loop select function. + * + * @remarks Once a prepare callback is set for an fd handler, it cannot be changed. + * You need to delete the fd handler and create a new one, to set another + * callback. + * + * @remarks You probably don't need this function. It is only necessary for very + * uncommon cases that need special behavior. + * + * @param[in] fd_handler The fd handler + * @param[in] func The prep function + * @param[in] data The data to pass to the prep function + */ +EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data); + +/** + * @brief Marks an FD handler for deletion. + * + * @since_tizen 2.3 + * + * @details This function marks an fd handler to be deleted during an iteration of the + * main loop. It does NOT close the associated fd. + * + * @remarks If the underlying fd is already closed ecore may complain if the + * main loop is using epoll internally, and also in some rare cases this may + * cause crashes and instability. Remember to delete your fd handlers before the + * fds they listen to are closed. + * + * @param[in] fd_handler The fd handler + * @return The data pointer set using @ref ecore_main_fd_handler_add, for + * @a fd_handler on success, + * otherwise @c NULL on failure + */ +EAPI void *ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler); + +/** + * @brief Retrieves the file descriptor that the given handler is handling. + * + * @since_tizen 2.3 + * + * @param[in] fd_handler The given fd handler + * @return The file descriptor that the handler is watching + */ +EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler); + +/** + * @brief Gets which flags are active on an FD handler. + * + * @since_tizen 2.3 + * + * @param[in] fd_handler The given fd handler + * @param[in] flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE, or + * @c ECORE_FD_ERROR to query + * @return #EINA_TRUE if any of the given flags are active, + * otherwise @c EINA_FALSE + */ +EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); + +/** + * @brief Sets what active streams the given FD handler should be monitoring. + * + * @since_tizen 2.3 + * + * @param[in] fd_handler The given fd handler + * @param[in] flags The flags to be watching + */ +EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); + +/** + * @internal + */ +EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); + +/** + * @internal + */ +EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); + +/** + * @} + */ + +/** + * @defgroup Ecore_Time_Group Ecore Time + * @ingroup Ecore_Main_Loop_Group + * + * @brief This group discusses the functions to retrieve time in a given format. + * + * @{ + */ + +/** + * @brief Retrieves the current system time as a floating point value in seconds. + * + * @details This uses a monotonic clock and thus never goes back in time while + * machine is live (even if user changes time or timezone changes, + * however it may be reset whenever the machine is restarted). + * + * @since_tizen 2.3 + * + * @return The number of seconds. Start time is not defined (it may be + * when the machine was booted, unix time, etc), all it is + * defined is that it never goes backwards (unless you got big critical + * messages when the application started). + * + * @see ecore_loop_time_get(). + * @see ecore_time_unix_get(). + */ +EAPI double ecore_time_get(void); + +/** + * @brief Retrieves the current UNIX time as a floating point value in seconds. + * + * @since_tizen 2.3 + * + * @return The number of seconds since 12.00AM 1st January 1970. + * + * @see ecore_time_get(). + * @see ecore_loop_time_get(). + */ +EAPI double ecore_time_unix_get(void); + +/** + * @brief Retrieves the time at which the last loop stopped waiting for + * timeouts or events. + * + * @since_tizen 2.3 + * + * @remarks This gets the time that the main loop ceased waiting for timouts + * and/or events to come in or for signals or any other interrupt + * source. This should be considered a reference point for all time + * based activity that should calculate its timepoint from the return + * of ecore_loop_time_get(). Use this UNLESS you absolutely must get + * the current actual timepoint - then use ecore_time_get(). + * Note that this time is meant to be used as relative to other times + * obtained on this run. If you need absolute time references, use + * ecore_time_unix_get() instead. + * + * @remarks This function can be called before any loop has ever been run, but + * either ecore_init() or ecore_time_get() must have been called once. + * + * @return The number of seconds. Start time is not defined (it may be + * when the machine was booted, unix time, etc), all it is + * defined is that it never goes backwards (unless you got big critical + * messages when the application started). + */ +EAPI double ecore_loop_time_get(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Thread_Group Ecore Thread + * @ingroup Ecore_Main_Loop_Group + * + * @brief Facilities to run heavy tasks in different threads to avoid blocking + * the main loop. + * + * The EFL is, for the most part, not thread safe. This means that if you + * have some task running in another thread and you have, for example, an + * Evas object to show the status progress of this task, you cannot update + * the object from within the thread. This can only be done from the main + * thread, the one running the main loop. This problem can be solved + * by running a thread that sends messages to the main one using an + * @ref Ecore_Pipe_Group "Ecore_Pipe", but when you need to handle other + * things like cancelling the thread, your code grows in complexity and gets + * much harder to maintain. + * + * Ecore Thread is here to solve that problem. It is not a simple wrapper + * around standard POSIX threads (or an equivalent in other systems) and + * it's not meant to be used to run parallel tasks throughout the entire + * duration of the program, especially when these tasks are performance + * critical, as Ecore manages these tasks using a pool of threads based on + * system configuration. + * + * What Ecore Thread does is it makes it a lot easier to dispatch a worker + * function to perform some heavy tasks and then get the result once it + * completes, without blocking the application's UI. In addition, cancelling + * and rescheduling comes practically for free and the developer need not + * worry about how many threads are launched, since Ecore schedules + * them according to the number of processors the system has and the maximum + * amount of concurrent threads set for the application. + * + * At the system level, Ecore starts a new thread on an as-needed basis + * until the maximum set is reached. When no more threads can be launched, + * new worker functions are queued in a waiting list until a thread + * becomes available. This way, system threads are shared throughout + * different worker functions, but running only one at a time. At the same + * time, a worker function that is rescheduled may be run on a different + * thread the next time. + * + * The ::Ecore_Thread handler has two meanings, depending on what context + * it is on. The one returned when starting a worker with any of the + * functions ecore_thread_run() or ecore_thread_feedback_run() is an + * identifier of that specific instance of the function and can be used from + * the main loop with the ecore_thread_cancel() and ecore_thread_check() + * functions. This handler must not be shared with the worker function + * running in the thread. This same handler is the one received + * on the @c end, @c cancel, and @c feedback callbacks. + * + * The worker function, that's the one running in the thread, also receives + * an ::Ecore_Thread handler that can be used with ecore_thread_cancel() and + * ecore_thread_check(), sharing the flag with the main loop. But this + * handler is also associated with the thread where the function is running. + * This has strong implications when working with thread local data. + * + * There are two kinds of worker threads that Ecore handles: simple or short, + * workers, and feedback workers. + * + * The first kind is for simple functions that perform a + * usually small but time consuming task. Ecore runs this function in + * a thread as soon as one becomes available and notifies the calling user of + * its completion once the task is done. + * + * The following image shows the flow of a program running four tasks on + * a pool of two threads. + * + * @image html ecore_thread.png + * @image rtf ecore_thread.png + * @image latex ecore_thread.eps "ecore thread" width=\textwidth + * + * For larger tasks that may require continuous communication with the main + * program, the feedback workers provide the same functionality plus a way + * for the function running in the thread to send messages to the main + * thread. + * + * The next diagram omits some details shown in the previous one regarding + * how threads are spawned and tasks are queued, but illustrates how feedback + * jobs communicate with the main loop and the special case of threads + * running out of the pool. + * + * @image html ecore_thread_feedback.png + * @image rtf ecore_thread_feedback.png + * @image latex ecore_thread_feedback.eps "ecore thread feedback" width=\textwidth + * + * @{ + */ + +typedef struct _Ecore_Thread Ecore_Thread; /**< @brief A handle for threaded jobs */ + +/** + * @typedef Ecore_Thread_Cb Ecore_Thread_Cb + * @brief Called to be used by Ecore_Thread helper. + */ +typedef void (*Ecore_Thread_Cb)(void *data, Ecore_Thread *thread); +/** + * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb + * @brief Called to be used by the main loop to receive data sent by an + * @ref Ecore_Thread_Group. + */ +typedef void (*Ecore_Thread_Notify_Cb)(void *data, Ecore_Thread *thread, void *msg_data); + +/** + * @brief Schedules a task to run in a parallel thread to avoid locking the main loop. + * + * @details This function tries to create a new thread to run @a func_blocking in, + * or if the maximum number of concurrent threads has been reached it + * adds it to the pending list, where it waits until a thread becomes + * available. The return value is an ::Ecore_Thread handle that can + * be used to cancel the thread before its completion. + * + * @since_tizen 2.3 + * + * @remarks This function should always return immediately, but in the rare + * case that Ecore is built with no thread support, @a func_blocking is + * be called here, actually blocking the main loop. + * + * @remarks Once a thread becomes available, @a func_blocking is run in it until + * it finishes, then @a func_end is called from the thread containing the + * main loop to inform the user of its completion. While in @a func_blocking, + * no functions from the EFL can be used, except for those from Eina that are + * marked to be thread-safe. Even for the latter, caution needs to be taken + * if the data is shared across several threads. + * + * @remarks @a func_end is called from the main thread when @a func_blocking ends, + * so here it's safe to use anything from the EFL freely. + * + * @remarks The thread can also be cancelled before its completion by calling + * ecore_thread_cancel(), either from the main thread or @a func_blocking. + * In this case, @a func_cancel is called, also from the main thread + * to inform of this happening. If the thread could not be created, this + * function is called and its @c thread parameter is @c NULL. It's + * also safe to call any EFL function here, as it is running in the + * main thread. + * + * @remarks Inside @a func_blocking, it's possible to call ecore_thread_reschedule() + * to tell Ecore that this function should be called again. + * + * @remarks Be aware that no assumptions can be made about the order in which the + * @a func_end callbacks for each task are called. Once the function is + * running in a different thread, it's the OS that handles its running + * schedule, and different functions may take longer to finish than others. + * Also remember that just starting several tasks together doesn't mean they + * are going to run at the same time. Ecore schedules them based on the + * number of threads available for the particular system it's running in, + * so some of the jobs started may be waiting until another one finishes + * before it can execute its own @a func_blocking. + * + * @param[in] func_blocking The function that should run in another thread + * @param[in] func_end The function to call from the main loop when @a func_blocking + * completes its task successfully (may be @c NULL) + * @param[in] func_cancel The function to call from the main loop if the thread running + * @a func_blocking is cancelled or fails to start (may be @c NULL) + * @param[in] data The user context data to pass to all callbacks + * @return A new thread handler, + * otherwise @c NULL on failure + * + * @see ecore_thread_feedback_run() + * @see ecore_thread_cancel() + * @see ecore_thread_reschedule() + * @see ecore_thread_max_set() + */ +EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data); + +/** + * @brief Launches a thread to run a task that can talk back to the main thread. + * + * @since_tizen 2.3 + * + * @remarks The difference in the above is that ecore_thread_run() is meant for + * tasks that don't need to communicate anything until they finish, while + * this function is provided with a new callback, @a func_notify, that is + * called from the main thread for every message sent from @a func_heavy + * with ecore_thread_feedback(). + * + * @remarks Like with ecore_thread_run(), a new thread is launched to run + * @a func_heavy unless the maximum number of simultaneous threads has been + * reached, in which case the function is scheduled to run whenever a + * running task ends and a thread becomes free. But if @a try_no_queue is + * set, Ecore first tries to launch a thread outside of the pool to run + * the task. If it fails, it reverts to the normal behaviour of using a + * thread from the pool as if @a try_no_queue had not been set. + * + * @remarks Keep in mind that Ecore handles the thread pool based on the number of + * CPUs available, but running a thread outside of the pool doesn't count for + * this, so having too many of them may have drastic effects over the + * program's performance. + * + * @remarks See ecore_thread_run() for a general description of this function. + * + * @param[in] func_heavy The function that should run in another thread + * @param[in] func_notify the function that receives the data sent from the thread + * @param[in] func_end The function to call from the main loop when @a func_heavy + * completes its task successfully + * @param[in] func_cancel The function to call from the main loop if the thread running + * @a func_heavy is cancelled or fails to start + * @param[in] data The user context data to pass to all callbacks + * @param[in] try_no_queue The boolean value that indicates whether to run outside the thread pool + * @return A new thread handler, + * otherwise @c NULL on failure + * + * @see ecore_thread_feedback() + * @see ecore_thread_run() + * @see ecore_thread_cancel() + * @see ecore_thread_reschedule() + * @see ecore_thread_max_set() + */ +EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify, + Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, + const void *data, Eina_Bool try_no_queue); + +/** + * @brief Cancels a running thread. + * + * @details This function cancels a running thread. If @a thread can be immediately + * cancelled (its still pending execution after creation or rescheduling), + * then the @a cancel callback is called, @a thread is freed and + * the function returns #EINA_TRUE. + * + * @since_tizen 2.3 + * + * @remarks If the thread is already running, then this function returns @c EINA_FALSE + * after marking the @a thread as pending cancellation. For the thread to + * actually be terminated, it needs to return from the user function back + * into Ecore control. This can happen in several ways: + * @li The function ends and returns normally. If it hadn't been cancelled, + * @a func_end would be called here, but instead @a func_cancel happens. + * @li The function returns after requesting to be rescheduled with + * ecore_thread_reschedule(). + * @li The function is prepared to leave early by checking if + * ecore_thread_check() returns #EINA_TRUE. + * + * @remarks The user function can cancel itself by calling ecore_thread_cancel(), but + * it should always use the ::Ecore_Thread handle passed to it and never + * share it with the main loop thread by means of shared user data or in any + * other way. + * + * @remarks @a thread is freed and should not be used again if this function + * returns #EINA_TRUE or after the @a func_cancel callback returns. + * + * @remarks This function can be called both in the main loop and in the running thread. + * + * @param[in] thread The thread to cancel + * @return #EINA_TRUE if the thread has been cancelled, + * otherwise @c EINA_FALSE if it is pending + * + * @see ecore_thread_check() + */ +EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread); + +/** + * @brief Checks whether a thread is in pending cancellation. + * + * @details This function can be called both in the main loop and in the running thread. + * + * @since_tizen 2.3 + * + * @remarks When ecore_thread_cancel() is called on an already running task, the + * thread is marked as pending cancellation. This function returns #EINA_TRUE + * if this mark is set for the given @a thread and can be used from the + * main loop thread to check if a still active thread has been cancelled, + * or from the user function running in the thread to check if it should + * stop doing what it's doing and return early, effectively cancelling the + * task. + * + * @param[in] thread The thread to test + * @return #EINA_TRUE if the thread is in pending cancellation, + * otherwise @c EINA_FALSE if it is not + * + * @see ecore_thread_cancel() + */ +EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread); + +/** + * @brief Sends data from the worker thread to the main loop. + * + * @since_tizen 2.3 + * + * @remarks You should use this function only in the @a func_heavy call. + * + * @remarks Only the address to @a msg_data is sent and once this function + * returns #EINA_TRUE, the job running in the thread should never touch the + * contents of it again. The data sent should be malloc()'ed or something + * similar, as long as it's not the memory that is local to the thread that risks being + * overwritten or deleted once it goes out of scope or the thread finishes. + * + * @remarks Care must be taken that @a msg_data is properly freed in the @a func_notify + * callback set when creating the thread. + * + * @param[in] thread The current ::Ecore_Thread context to send data from + * @param[in] msg_data The data to be transmitted to the main loop + * @return #EINA_TRUE if @a msg_data is successfully sent to the main loop, + * otherwise @c EINA_FALSE if anything goes wrong + * + * @see ecore_thread_feedback_run() + */ +EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data); + +/** + * @brief Asks for the function in the thread to be called again at a later period. + * + * @since_tizen 2.3 + * + * @remarks This function should be called only from the function represented + * by @a thread. + * + * Calling this function marks the thread for a reschedule, so as soon + * as it returns, it is added to the end of the list of pending tasks. + * If no other tasks are waiting or there are sufficient threads available, + * the rescheduled task is launched again immediately. + * + * This should never return @c EINA_FALSE, unless it is called from the wrong + * thread or with the wrong arguments. + * + * @remarks The @a func_end callback set when the thread is created is not + * called until the function in the thread returns without being rescheduled. + * Similarly, if the @a thread is cancelled, the reschedule does not take + * effect. + * + * @param[in] thread The current ::Ecore_Thread context to reschedule + * @return #EINA_TRUE if the task is successfully rescheduled, + * otherwise @c EINA_FALSE if anything goes wrong + * + */ +EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread); + +/** + * @brief Gets the number of active threads running jobs. + * + * @details This returns the number of threads currently running jobs of any type + * through the Ecore_Thread API. + * + * @since_tizen 2.3 + * + * @remarks Jobs started through the ecore_thread_feedback_run() function with + * the @a try_no_queue parameter set to #EINA_TRUE are not accounted for + * in the return of this function unless the thread creation fails and it + * falls back to using one from the pool. + * + * @return The number of active threads running jobs + * + */ +EAPI int ecore_thread_active_get(void); + +/** + * @brief Gets the number of short jobs waiting for a thread to run. + * + * @details This returns the number of tasks started with ecore_thread_run() that are + * pending and waiting for a thread to become available to run them. + * + * @since_tizen 2.3 + * + * @return The number of pending threads running "short" jobs + * + */ +EAPI int ecore_thread_pending_get(void); + +/** + * @brief Gets the number of feedback jobs waiting for a thread to run. + * + * @details This returns the number of tasks started with ecore_thread_feedback_run() + * that are pending and waiting for a thread to become available to run them. + * + * @since_tizen 2.3 + * + * @return The number of pending threads running "feedback" jobs + * + */ +EAPI int ecore_thread_pending_feedback_get(void); + +/** + * @brief Gets the total number of pending jobs. + * + * @since_tizen 2.3 + * + * @remarks This is same as the sum of ecore_thread_pending_get() and + * ecore_thread_pending_feedback_get(). + * + * @return The number of pending threads running jobs + * + */ +EAPI int ecore_thread_pending_total_get(void); + +/** + * @brief Gets the maximum number of threads that can run simultaneously. + * + * @details This returns the maximum number of Ecore_Thread's that may be running at + * the same time. If this number is reached, new jobs started by either + * ecore_thread_run() or ecore_thread_feedback_run() are added to the + * respective pending queues until one of the running threads finishes its + * task and becomes available to run a new one. + * + * @since_tizen 2.3 + * + * @remarks By default, this is the number of available CPUs for the + * running program (as returned by eina_cpu_count()), or @c 1 if this value + * could not be fetched. + * + * @return The maximum possible number of Ecore_Thread's running concurrently + * + * @see ecore_thread_max_set() + * @see ecore_thread_max_reset() + */ +EAPI int ecore_thread_max_get(void); + +/** + * @brief Sets the maximum number of threads allowed to run simultaneously. + * + * @details This sets a new value for the maximum number of concurrently running + * Ecore_Thread's. It @b must be an integer between @c 1 and (@c 16 * @c x), where @c x + * is the number for CPUs available. + * + * @since_tizen 2.3 + * + * @param[in] num The new maximum + * + * @see ecore_thread_max_get() + * @see ecore_thread_max_reset() + */ +EAPI void ecore_thread_max_set(int num); + +/** + * @brief Resets the maximum number of concurrently running threads to the default. + * + * @details This resets the value returned by ecore_thread_max_get() back to its + * default. + * + * @since_tizen 2.3 + * + * @see ecore_thread_max_get() + * @see ecore_thread_max_set() + */ +EAPI void ecore_thread_max_reset(void); + +/** + * @brief Gets the number of threads available for running tasks. + * + * @since_tizen 2.3 + * + * @remarks This is same as doing ecore_thread_max_get() - ecore_thread_active_get(). + * + * @remarks This function may return a negative number only in the case when the user + * changes the maximum number of running threads while other tasks are + * running. + * + * @return The number of available threads + * + */ +EAPI int ecore_thread_available_get(void); + +/** + * @brief Adds some data present in the hash local to the thread. + * + * @since_tizen 2.3 + * + * @remarks Ecore Thread has a mechanism to share data across several worker functions + * that run on the same system thread. That is, the data is stored per + * thread and for a worker function to have access to it, it must be run + * by the same thread that stored the data. + * + * @remarks When there are no more workers pending, the thread is destroyed + * along with the internal hash and any data left in it is freed with + * the given @a cb function. + * + * @ This set of functions is useful to share things around several instances + * of a function when that thing is costly to create and can be reused, but + * may only be used by one function at a time. + * + * For example, if you have a program doing requisitions to a database, + * these requisitions can be done in threads so that waiting for the + * database to respond doesn't block the UI. Each of these threads + * run a function, and each function is dependent on a connection to + * the database, which may not be able to handle more than one request at + * a time so for each running function you need one connection handle. + * + * The options then are: + * @li Each function opens a connection when it's called, does the work and + * closes the connection when it finishes. This may be costly, wasting a lot + * of time on resolving hostnames, negotiating permissions, and allocating + * memory. + * @li Open the connections in the main loop and pass it to the threads + * using the data pointer. Even worse, it's just as costly as before and now + * it may even be kept with connections open doing nothing until a thread + * becomes available to run the function. + * @li Have a way to share connection handles, so that each instance of the + * function can check if an available connection exists, and if it doesn't, + * create one and add it to the pool. When no more connections are needed, + * they are all closed. + * + * The last option is the most efficient, but it requires a lot of work to + * be implemented properly. Using thread local data helps to achieve the same + * result while avoiding all the tracking work on your code. The way + * to use it would be at the worker function, to ask for the connection + * using ecore_thread_local_data_find() and if it doesn't exist, then open + * a new one and save it with ecore_thread_local_data_add(). Complete the work and + * forget about the connection handle, when everything is done the function + * just ends. The next worker to run on that thread checks if a + * connection exists and finds that it does, so the process of opening a + * new one has been spared. When no more workers exist, the thread is + * destroyed and the callback used when saving the connection is called + * to close it. + * + * @remarks This function adds the data @a value to the thread data under the given + * @a key. No other value in the hash may have the same @a key. If you need to + * change the value under a @a key, or you don't know if one exists already, + * you can use ecore_thread_local_data_set(). + * + * Neither @a key nor @a value may be @c NULL and @a key gets copied in the + * hash, unless @a direct is set, in which case the string used should not + * be freed until the data is removed from the hash. + * + * @remarks The @a cb function is called when the data in the hash needs to be + * freed, be it because it got deleted by ecore_thread_local_data_del() or + * because @a thread got terminated and the hash got destroyed. This parameter + * may be @c NULL, in which case @a value needs to be manually freed after + * removing it from the hash with either ecore_thread_local_data_del() or + * ecore_thread_local_data_set(), but it's very unlikely that this is what + * you want. + * + * This function, and all of the others in the @a ecore_thread_local_data + * family of functions, can only be called within the worker function running + * in the thread. Do not call them from the main loop or from a thread + * other than the one represented by @a thread. + * + * @param[in] thread The thread context the data belongs to + * @param[in] key The name under which the data is stored + * @param[in] value The data to add + * @param[in] cb The function to free the data when removed from the hash + * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()), + * otherwise @c false + * @return #EINA_TRUE on success, + * otherwise @c EINA_FALSE on failure + * + * @see ecore_thread_local_data_set() + * @see ecore_thread_local_data_find() + * @see ecore_thread_local_data_del() + */ +EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key, void *value, + Eina_Free_Cb cb, Eina_Bool direct); + +/** + * @brief Sets some data present in the hash local to the given thread. + * + * @since_tizen 2.3 + * + * @remarks If no data exists in the hash under the @a key, this function adds + * @a value in the hash under the given @a key and returns @c NULL. + * The key itself is copied. + * + * If the hash already contains something under @a key, the data is + * replaced by @a value and the old value is returned. + * + * @c NULL is also returned if either @a key or @a value are @c NULL, or + * if an error occurs. + * + * @remarks This function, and all of the others in the @a ecore_thread_local_data + * family of functions, can only be called within the worker function running + * in the thread. Do not call them from the main loop or from a thread + * other than the one represented by @a thread. + * + * @param[in] thread The thread context the data belongs to + * @param[in] key The name under which the data is stored + * @param[in] value The data to add + * @param[in] cb The function to free the data when removed from the hash + * + * @see ecore_thread_local_data_add() + * @see ecore_thread_local_data_del() + * @see ecore_thread_local_data_find() + */ +EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb); + +/** + * @brief Gets data stored in the hash local to the given thread. + * + * @since_tizen 2.3 + * + * @details This finds and returns the data stored in the shared hash under the key @a key. + * + * @remarks This function, and all the others in the @a ecore_thread_local_data + * family of functions, can only be called within the worker function running + * in the thread. Do not call them from the main loop or from a thread + * other than the one represented by @a thread. + * + * @param[in] thread The thread context the data belongs to + * @param[in] key The name under which the data is stored + * @return The value under the given key, + * otherwise @c NULL on an error + * + * @see ecore_thread_local_data_add() + * @see ecore_thread_local_data_wait() + */ +EAPI void *ecore_thread_local_data_find(Ecore_Thread *thread, const char *key); + +/** + * @brief Deletes the data corresponding to the given key from the thread's hash. + * + * @since_tizen 2.3 + * + * @remarks If there's any data associated with @a key that is stored in the global hash, + * this function removes it from the hash and returns #EINA_TRUE. If no data + * exists or an error occurs, it returns @c EINA_FALSE. + * + * @remarks If the data is added to the hash with a free function, then it is + * also freed after removing it from the hash, otherwise it requires + * to be manually freed by the user, which means that if no other reference + * to it exists before calling this function, it results in a memory + * leak. + * + * @remarks This function, and all the others in the @a ecore_thread_local_data + * family of functions, can only be called within the worker function running + * in the thread. Do not call them from the main loop or from a thread + * other than the one represented by @a thread. + * + * @param[in] thread The thread context the data belongs to + * @param[in] key The name under which the data is stored + * @return #EINA_TRUE on success, + * otherwise @c EINA_FALSE on failure + * + * @see ecore_thread_local_data_add() + */ +EAPI Eina_Bool ecore_thread_local_data_del(Ecore_Thread *thread, const char *key); + +/** + * @brief Adds some data to a hash shared by all threads. + * + * @since_tizen 2.3 + * + * @remarks Ecore Thread keeps a hash that can be used to share data across several + * threads, including the main loop thread, without having to manually handle + * mutexes to do it safely. + * + * @remarks This function adds the data @a value to this hash under the given @a key. + * No other value in the hash may have the same @a key. If you need to + * change the value under a @a key, or you don't know if one exists already, + * you can use ecore_thread_global_data_set(). + * + * Neither @a key nor @a value may be @c NULL and @a key gets copied in the + * hash, unless @a direct is set, in which case the string used should not + * be freed until the data is removed from the hash. + * + * @remarks The @a cb function is called when the data in the hash needs to be + * freed, be it because it got deleted with ecore_thread_global_data_del() or + * because Ecore Thread got shut down and the hash got destroyed. This parameter + * may be @c NULL, in which case @a value needs to be manually freed after + * removing it from the hash with either by ecore_thread_global_data_del() or + * ecore_thread_global_data_set(). + * + * Manually freeing any data that is added to the hash with the @a cb function + * is likely to produce a segmentation fault, or any other strange + * happening at a later stage in the program. + * + * @param[in] key The name under which the data is stored + * @param[in] value The data to add + * @param[in] cb The function to free the data when removed from the hash + * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()), + * otherwise @c false + * @return #EINA_TRUE on success, + * otherwise @c EINA_FALSE on failure + * + * @see ecore_thread_global_data_del() + * @see ecore_thread_global_data_set() + * @see ecore_thread_global_data_find() + */ +EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct); + +/** + * @brief Sets some data in the hash shared by all threads. + * + * @since_tizen 2.3 + * + * @remarks If no data exists in the hash under the @a key, this function adds + * @a value in the hash under the given @a key and returns @c NULL. + * The key itself is copied. + * + * If the hash already contains something under @a key, the data is + * replaced by @a value and the old value is returned. + * + * @c NULL is also returned if either @a key or @a value is @c NULL, or + * if an error occurs. + * + * + * @param[in] key The name under which the data is stored + * @param[in] value The data to add + * @param[in] cb The function to free the data when removed from the hash + * + * @see ecore_thread_global_data_add() + * @see ecore_thread_global_data_del() + * @see ecore_thread_global_data_find() + */ +EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_Cb cb); + +/** + * @brief Gets data stored in the hash shared by all threads. + * + * @since_tizen 2.3 + * + * @details This finds and returns the data stored in the shared hash under the key @a key. + * + * @remarks Keep in mind that the data returned may be used by more than one thread + * at the same time and no reference counting is done on it by Ecore. + * Freeing the data or modifying its contents may require additional + * precautions to be considered, depending on the application's design. + * + * @param[in] key The name under which the data is stored + * @return The value under the given key, + * otherwise @c NULL on an error + * + * @see ecore_thread_global_data_add() + * @see ecore_thread_global_data_wait() + */ +EAPI void *ecore_thread_global_data_find(const char *key); + +/** + * @brief Deletes the data corresponding to the given key from the shared hash. + * + * @since_tizen 2.3 + * + * @remarks If there's any data associated with @p key that is stored in the global hash, + * this function removes it from the hash and returns #EINA_TRUE. If no data + * exists or an error occurs, it returns @c EINA_FALSE. + * + * @remarks If the data is added to the hash with a free function, then it is + * also freed after removing it from the hash, otherwise it requires + * to be manually freed by the user, which means that if no other reference + * to it exists before calling this function, it results in a memory + * leak. + * + * Note, also, that freeing data that other threads may be using results + * in a crash, so appropriate care must be taken by the application when + * that possibility exists. + * + * @param[in] key The name under which the data is stored + * @return #EINA_TRUE on success, + * otherwise @c EINA_FALSE on failure + * + * @see ecore_thread_global_data_add() + */ +EAPI Eina_Bool ecore_thread_global_data_del(const char *key); + +/** + * @brief Gets data stored in the shared hash or waits for it if it doesn't exist. + * + * @since_tizen 2.3 + * + * @remarks This finds and returns the data stored in the shared hash under the key @a key. + * + * If there's nothing in the hash under the given @a key, the function + * blocks and waits for @a seconds seconds for some other thread to + * add it with either ecore_thread_global_data_add() or + * ecore_thread_global_data_set(). If after waiting there's still no data + * to obtain, @c NULL is returned. + * + * If @a seconds is @c 0, then no waiting happens and this function works + * like ecore_thread_global_data_find(). If @a seconds is less than @c 0, then + * the function waits indefinitely. + * + * @remarks Keep in mind that the data returned may be used by more than one thread + * at the same time and no reference counting is done on it by Ecore. + * Freeing the data or modifying its contents may require additional + * precautions to be considered, depending on the application's design. + * + * @param[in] key The name under which the data is stored + * @param[in] seconds The amount of time in seconds to wait for the data + * @return The value under the given key, + * otherwise @c NULL on an error + * + * @see ecore_thread_global_data_add() + * @see ecore_thread_global_data_find() + */ +EAPI void *ecore_thread_global_data_wait(const char *key, double seconds); + +/** + * @} + */ + +/** + * @defgroup Ecore_Timer_Group Ecore Timer + * @ingroup Ecore_Main_Loop_Group + * + * @brief Ecore provides very flexible timer functionality. + * + * The basic usage of timers is to call a certain function at a certain + * interval, which can be achieved with a single line: + * @code + * Eina_Bool my_func(void *data) { + * do_funky_stuff_with_data(data); + * return ECORE_CALLBACK_RENEW; + * } + * ecore_timer_add(interval_in_seconds, my_func, data_given_to_function); + * @endcode + * If the function is to be executed only once simply return + * @c CORE_CALLBACK_CANCEL instead. + * + * @{ + */ + +typedef struct _Ecore_Timer Ecore_Timer; /**< @brief A handle for timers */ + +/** + * @brief Creates a timer to call the given function in the given period of time. + * + * @details This function adds a timer and returns its handle on success and NULL on + * failure. The function @p func will be called every @p in seconds. The + * function will be passed the @p data pointer as its parameter. + * + * @since_tizen 2.3 + * + * @remarks When the timer @p func is called, it must return a value of either 1 + * (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL). + * If it returns 1, it will be called again at the next tick, or if it returns + * 0 it will be deleted automatically making any references/handles for it + * invalid. + * + * @param[in] in The interval in seconds. + * @param[in] func The given function. If @p func returns 1, the timer is + * rescheduled for the next interval @p in. + * @param[in] data Data to pass to @p func when it is called. + * @return A timer object on success. @c NULL on failure. + */ +EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data); + +/** + * @brief Creates a timer to call the given function in the given period of time. + * + * @since_tizen 2.3 + * + * @remarks This is same as ecore_timer_add(), but "now" is the time from + * ecore_loop_time_get(), not ecore_time_get(), as ecore_timer_add() uses it. See + * ecore_timer_add() for more details. + * + * @param[in] in The interval in seconds from the current loop time + * @param[in] func The given function \n + * If @a func returns @c 1, the timer is + * rescheduled for the next interval @a in. + * @param[in] data The data to pass to @a func when it is called + * @return A timer object on success, + * otherwise @c NULL on failure + */ +EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data); + +/** + * @brief Deletes the specified timer from the timer list. + * + * @details This deletes the specified @a timer from the set of timer that are + * executed during main loop execution. This function returns the data + * parameter that is being passed to the callback on success, otherwise @c NULL on + * failure. + * + * @since_tizen 2.3 + * + * @param[in] timer The timer to delete + * @return The data pointer set for the timer on add + * + */ +EAPI void *ecore_timer_del(Ecore_Timer *timer); + +/** + * @brief Change the interval the timer ticks off. + * + * @since_tizen 2.3 + * + * @param[in] timer The timer to change. + * @param[in] in The interval in seconds. + */ +EAPI void ecore_timer_interval_set(Ecore_Timer *timer, double in); + +/** + * @brief Get the interval the timer ticks on. + * + * @since_tizen 2.3 + * + * @param[in] timer The timer to retrieve the interval from + * @return The interval on success. -1 on failure. + */ +EAPI double ecore_timer_interval_get(Ecore_Timer *timer); + +/** + * @brief Pauses a running timer. + * + * @since_tizen 2.3 + * + * @remarks The timer callback won't be called while the timer is paused. The remaining + * time until the timer expires will be saved, so the timer can be resumed with + * that same remaining time to expire, instead of expiring instantly. Use + * ecore_timer_thaw() to resume it. + * + * @remarks Nothing happens if the timer was already paused. + * + * @param[in] timer The timer to be paused. + * + * @see ecore_timer_thaw() + */ +EAPI void ecore_timer_freeze(Ecore_Timer *timer); + +/** + * @brief Resumes a frozen (paused) timer. + * + * @since_tizen 2.3 + * + * @remarks The timer will be resumed from its previous relative position in time. That + * means, if it had X seconds remaining until expire when it was paused, it will + * be started now with those same X seconds remaining to expire again. But + * notice that the interval time won't be touched by this call or by + * ecore_timer_freeze(). + * + * @param[in] timer The timer to be resumed. + * + * @see ecore_timer_freeze() + */ +EAPI void ecore_timer_thaw(Ecore_Timer *timer); + +/** + * @brief Add some delay for the next occurrence of a timer. + * + * @since_tizen 2.3 + * + * @remarks This doesn't affect the interval of a timer. + * + * @param[in] timer The timer to change. + * @param[in] add The delay to add to the next iteration. + */ +EAPI void ecore_timer_delay(Ecore_Timer *timer, double add); + +/** + * @brief Reset a timer to its full interval. This effectively makes + * the timer start ticking off from zero now. + * + * @param[in] timer The timer + * + * @since_tizen 2.3 + */ +EAPI void ecore_timer_reset(Ecore_Timer *timer); + +/** + * @brief Get the pending time regarding a timer. + * + * @param[in] timer The timer + * @return The pending time + * + * @since_tizen 2.3 + */ +EAPI double ecore_timer_pending_get(Ecore_Timer *timer); + +/** + * @brief Retrieves the current precision used by timer infrastructure. + * + * @since_tizen 2.3 + * + * @return Current precision. + * + * @see ecore_timer_precision_set() + */ +EAPI double ecore_timer_precision_get(void); + +/** + * @brief Sets the precision to be used by timer infrastructure. + * + * @since_tizen 2.3 + * + * @remarks This sets the precision for @b all timers. The precision determines how much + * of an difference from the requested interval is acceptable. One common reason + * to use this function is to @b increase the allowed timeout and thus @b + * decrease precision of the timers, this is because less precise the timers + * result in the system waking up less often and thus consuming less resources. + * + * @remarks Be aware that kernel may delay delivery even further, these delays + * are always possible due other tasks having higher priorities or + * other scheduler policies. + * + * @remarks Example: + * We have 2 timers, one that expires in a 2.0s and another that + * expires in 2.1s, if precision is 0.1s, then the Ecore will request + * for the next expire to happen in 2.1s and not 2.0s and another one + * of 0.1 as it would before. + * + * @remarks Ecore is smart enough to see if there are timers in the + * precision range, if it does not, in our example if no second timer + * in (T + precision) existed, then it would use the minimum timeout. + + * @param[in] precision difference from the requested internval. + */ +EAPI void ecore_timer_precision_set(double precision); + +/** + * @brief Dump the all timers. + * + * @since_tizen 2.3 + * + * @return The information of all timers + */ +EAPI char *ecore_timer_dump(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Idle_Group Ecore Idle + * @ingroup Ecore_Main_Loop_Group + * + * @brief The idler functionality in Ecore allows for callbacks to be called when the + * program isn't handling @ref Ecore_Event_Group "events", @ref Ecore_Timer_Group + * "timers", or @ref Ecore_FD_Handler_Group "fd handlers". + * + * There are three types of idlers: Enterers, Idlers(proper), and Exiters. They + * are called respectively when the program is about to enter an idle state, + * when the program is in an idle state and when the program has just left an + * idle state and begins processing @ref Ecore_Event_Group "events", @ref + * Ecore_Timer_Group "timers", or @ref Ecore_FD_Handler_Group "fd handlers". + * + * Enterer callbacks are good for updating your program's state, if + * it has a state engine. Once all of the enterer handlers are + * called, the program enters a "sleeping" state. + * + * Idler callbacks are called when the main loop has called all + * enterer handlers. They are useful for interfaces that require + * polling and timers without which they would be too slow to use. + * + * Exiter callbacks are called when the main loop wakes up from an idle state. + * + * If no idler callbacks are specified, then the process literally + * goes to sleep. Otherwise, the idler callbacks are called + * continuously while the loop is "idle", using as much CPU as is + * available to the process. + * + * Idle state doesn't mean that the @b program is idle, but + * that the <b>main loop</b> is idle. It doesn't have any timers, + * events, fd handlers, or anything else to process (which in most + * <em>event driven</em> programs also means that the @b program is + * idle too, but it's not a rule). The program itself may be doing + * a lot of processing in the idler, or in another thread, for + * example. + * + * @{ + */ + +typedef struct _Ecore_Idler Ecore_Idler; /**< @brief A handle for idlers */ +typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer; /**< @brief A handle for idle enterers */ +typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter; /**< @brief A handle for idle exiters */ + +/** + * @brief Adds an idler handler. + * + * @details This adds an idler handle to the event loop, returning a handle on + * success and @c NULL otherwise. The function @a func is called + * repeatedly while no other events are ready to be processed, as + * long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0 + * (or @c ECORE_CALLBACK_CANCEL) deletes the idler. + * + * @since_tizen 2.3 + * + * @remarks Idlers are useful for progressively processing data without blocking. + * + * @param[in] func The function to call when idling + * @param[in] data The data to be passed to this @a func call + * @return A idler handle if successfully added, + * otherwise @c NULL + * + */ +EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data); + +/** + * @brief Deletes an idler callback from the list to be executed. + * + * @since_tizen 2.3 + * + * @param[in] idler The handle of the idler callback to delete + * @return The data pointer passed to the idler callback on success, + * otherwise @c NULL + */ +EAPI void *ecore_idler_del(Ecore_Idler *idler); + +/** + * @brief Add an idle enterer handler. + * + * @since_tizen 2.3 + * + * @remarks The function func will be called every time the main loop is entering + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. + * + * @param[in] func The function to call when entering an idle state. + * @param[in] data The data to be passed to the @p func call + * @return A handle to the idle enterer callback if successful. Otherwise, + * NULL is returned. + */ +EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data); + +/** + * @brief Add an idle enterer handler at the start of the list so it gets called earlier than others. + * + * @since_tizen 2.3 + * + * @remarks The function func will be called every time the main loop is entering + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer. + * + * @param[in] func The function to call when entering an idle state. + * @param[in] data The data to be passed to the @p func call + * @return A handle to the idle enterer callback if successful. Otherwise, + * NULL is returned. + */ +EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data); + +/** + * @brief Delete an idle enterer callback. + * + * @since_tizen 2.3 + * + * @param[in] idle_enterer The idle enterer to delete + * @return The data pointer passed to the idler enterer callback on success. + * NULL otherwise. + */ +EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); + +/** + * @brief Add an idle exiter handler. + * + * @since_tizen 2.3 + * + * @remarks The function func will be called every time the main loop is exiting + * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idle exiter. + * + * @param[in] func The function to call when exiting an idle state. + * @param[in] data The data to be passed to the @p func call + * @return A handle to the idle exiter callback on success. NULL otherwise. + */ +EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data); + +/** + * @brief Delete an idle exiter handler from the list to be run on exiting idle state. + * + * @since_tizen 2.3 + * + * @param[in] idle_exiter The idle exiter to delete + * @return The data pointer that was being being passed to the handler if + * successful. NULL otherwise. + */ +EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); + +/** + * @} + */ + +/** + * @defgroup Ecore_Pipe_Group Ecore Pipe Wrapper + * @ingroup Ecore_Main_Loop_Group + * + * @brief This group discusses the functions that wrap the write / read functions of the pipe to easily + * integrate its use into ecore's main loop. + * + * @remarks The ecore_pipe_add() function creates file descriptors (sockets + * on Windows) and attaches a handle to the ecore main loop. That + * handle is called when data is read in the pipe. To write data in + * the pipe, just call ecore_pipe_write(). When you are done, just + * call ecore_pipe_del(). + * + * @{ + */ + +typedef struct _Ecore_Pipe Ecore_Pipe; /**< @brief A handle for pipes */ + +/** + * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb + * @brief Called to send data written to the pipe. + */ +typedef void (*Ecore_Pipe_Cb)(void *data, void *buffer, unsigned int nbyte); + +/** + * @brief Create two file descriptors (sockets on Windows). + * + * @details Add a callback that will be called when the file descriptor that + * is listened receives data. An event is also put in the event + * queue when data is received. + * + * @since_tizen 2.3 + * + * @param[in] handler The handler called when data is received. + * @param[in] data Data to pass to @p handler when it is called. + * @return A newly created Ecore_Pipe object if successful. + * @c NULL otherwise. + */ +EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); + +/** + * @brief Free an Ecore_Pipe object created with ecore_pipe_add(). + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object to be freed. + * @return The pointer to the private data + */ +EAPI void *ecore_pipe_del(Ecore_Pipe *p); + +/** + * @brief Write on the file descriptor the data passed as parameter. + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object. + * @param[in] buffer The data to write into the pipe. + * @param[in] nbytes The size of the @p buffer in bytes + * @return #EINA_TRUE on a successful write, @c EINA_FALSE on error. + */ +EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes); + +/** + * @brief Close the write end of an Ecore_Pipe object created with ecore_pipe_add(). + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object. + */ +EAPI void ecore_pipe_write_close(Ecore_Pipe *p); + +/** + * @brief Close the read end of an Ecore_Pipe object created with + * ecore_pipe_add(). + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object. + */ +EAPI void ecore_pipe_read_close(Ecore_Pipe *p); + +/** + * @brief Start monitoring again the pipe for reading. See ecore_pipe_freeze() + * for stopping the monitoring activity. This will not work if + * ecore_pipe_read_close() was previously called on the same pipe. + * + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object. + */ +EAPI void ecore_pipe_thaw(Ecore_Pipe *p); + +/** + * @brief Stop monitoring if necessary the pipe for reading. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] p The Ecore_Pipe object. + * + * @see ecore_pipe_thaw() for monitoring it again. + * + */ +EAPI void ecore_pipe_freeze(Ecore_Pipe *p); + +/** + * @brief Wait from another thread on the read side of a pipe. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Negative value for @p wait means infite wait. + * + * @param[in] p The pipe to watch on. + * @param[in] message_count The minimal number of message to wait before exiting. + * @param[in] wait The amount of time in second to wait before exiting. + * @return the number of message catched during that wait call. + * + */ +EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); + +/** + * @} + */ + +/** + * @internal + * @defgroup Ecore_Throttle_Group Ecore Throttle + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + +/** + * @brief Increase throttle amount + * + * @details This will increase or decrease (if @p amount is positive or negative) the + * amount of "voluntary throttling" ecore will do to its main loop while + * running. This is intended to be used to limit animations and wakeups when + * in a strict power management state. The higher the current throttle value + * (which can be retrieved by ecore_throttle_get() ), the more throttling + * takes place. If the current throttle value is 0, then no throttling takes + * place at all. + * + * @remarks The value represents how long the ecore main loop will sleep (in seconds) + * before it goes into a fully idle state waiting for events, input or + * timing events to wake it up. For example, if the current throttle level + * is 0.5, then after every time the main loop cycles and goes into idle + * affter processing all events, the main loop will explicitly sleep for 0.5 + * seconds before sitting and waiting for incoming events or timeouts, thus + * preventing animation, async IO and network handling etc. for that period + * of time. Of course these events, data and timeouts will be buffered, + * thus not losing anything, simply delaying when they get handled by the + * throttle value. + * + * Example: + * @code + * void enter_powersave(void) { + * ecore_throttle_adjust(0.2); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void enter_deep_powersave(void) { + * ecore_throttle_adjust(0.5); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void exit_powersave(void) { + * ecore_throttle_adjust(-0.2); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * + * void exit_deep_powersave(void) { + * ecore_throttle_adjust(-0.5); + * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); + * } + * @endcode + * + * @param[in] amount Amount (in seconds) to adjust by + */ + +EAPI void ecore_throttle_adjust(double amount); + +/** + * @brief Get current throttle level + * + * @remarks This gets the current throttling level, which can be adjusted by + * ecore_throttle_adjust(). The value is in seconds. + * + * @return The current throttle level + * + * @see ecore_throttle_adjust() for more information. + * + */ +EAPI double ecore_throttle_get(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Poller_Group Ecore Poller + * @ingroup Ecore_Main_Loop_Group + * + * @brief Ecore poller provides infrastructure for the creation of pollers. + * + * Pollers are, in essence, callbacks that share a single timer per type. Because not + * all pollers need to be called at the same frequency the user may specify the + * frequency in ticks(each expiration of the shared timer is called a tick, in + * ecore poller parlance) for each added poller. Ecore pollers should only be + * used when the poller doesn't have specific requirements on the exact times + * to poll. + * + * This architecture means that the main loop is only woken up once to handle + * all pollers of that type, this saves power as the CPU has more of a + * chance to go into a low power state the longer it is asleep, so this + * should be used in situations where power usage is a concern. + * + * For now only 1 core poller type is supported: @c ECORE_POLLER_CORE. + * The default interval for @c ECORE_POLLER_CORE is @c 0.125(or 1/8th) second. + * + * The creation of a poller is extremely simple and only requires one line: + * @code + * ecore_poller_add(ECORE_POLLER_CORE, 1, my_poller_function, NULL); + * @endcode + * This sample creates a poller to call @a my_poller_function at every tick with + * @c NULL as data. + * + * @{ + */ + +/** + * @enum _Ecore_Poller_Type + * @brief Enumeration that defines the frequency of ticks for the poller. + */ +enum _Ecore_Poller_Type /* Poller types */ +{ + ECORE_POLLER_CORE = 0, /**< The core poller interval */ +#ifdef __linux + ECORE_POLLER_LAZY = 1, /**< Core poller based on timerfd, + timer is deferrable in case the kernel supports it (no fire at IDLE time) */ #endif + ECORE_POLLER_TYPE_MAX +}; + +/** + * @brief typedef to enum _Ecore_Poller_Type + */ +typedef enum _Ecore_Poller_Type Ecore_Poller_Type; + +typedef struct _Ecore_Poller Ecore_Poller; /**< @brief A handle for pollers */ + +/** + * @brief Sets the time(in seconds) between ticks for the given poller type. + * + * @details This adjusts the time between ticks of the given timer type defined by + * @a type to the time period defined by @a poll_time. + * + * @since_tizen 2.3 + * + * @param[in] type The poller type to adjust + * @param[in] poll_time The time(in seconds) between ticks of the timer + * + */ +EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time); + +/** + * @brief Gets the time(in seconds) between ticks for the given poller type. + * + * @details This gets the time between ticks of the specified poller timer. + * + * @since_tizen 2.3 + * + * @param[in] type The poller type to query + * @return The time in seconds between ticks of the poller timer + * + */ +EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type); + +/** + * @brief Changes the polling interval rate of @a poller. + * + * @details This allows the changing of a poller's polling interval. It is useful when + * you want to alter a poll rate without deleting and re-creating a poller. + * + * @since_tizen 2.3 + * + * @param[in] poller The Ecore_Poller to change the interval of + * @param[in] interval The tick interval to set, must be a power of 2 and <= 32768 + * @return @c true on success, otherwise @c false on failure + * + */ +EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *poller, int interval); + +/** + * @brief Gets the polling interval rate of @a poller. + * + * @details This returns a poller's polling interval, otherwise @c 0 on error. + * + * @since_tizen 2.3 + * + * @param[in] poller The Ecore_Poller to change the interval of + * @return The interval, in ticks, that @a poller polls at + * + */ +EAPI int ecore_poller_poller_interval_get(Ecore_Poller *poller); + +/** + * @brief Creates a poller to call the given function at a particular tick interval. + * + * @details This function adds @a func as a poller callback that is called every @a + * interval ticks together with other pollers of type @a type. @a func is + * passed the @a data pointer as a parameter. + * + * @since_tizen 2.3 + * + * @remarks The @a interval must be between @c 1 and @c 32768 inclusive, and must be a power of + * @c 2 (i.e. 1, 2, 4, 8, 16, ... 16384, 32768). The exact tick in which @a func + * is called is undefined, as only the interval between calls can be + * defined. Ecore endeavors to keep pollers synchronized and calls as + * many in 1 wakeup event as possible. If @a interval is not a power of @c 2, the + * closest power of @c 2 greater than @a interval is used. + * + * @remarks When the poller @a func is called, it must return a value of either + * @c ECORE_CALLBACK_RENEW(or @c 1) or @c ECORE_CALLBACK_CANCEL(or @c 0). If it + * returns @c 1, it is called again at the next tick, or if it returns + * @c 0 it is deleted automatically making any references/handles for it + * invalid. + * + * @param[in] type The ticker type to attach the poller to \n + * Must be @c ECORE_POLLER_CORE. + * @param[in] interval The poll interval + * @param[in] func The poller function + * @param[in] data The data to pass to @a func when it is called + * @return A poller object on success, + * otherwise @c NULL on failure + * + */ +EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data); + +/** + * @brief Deletes the specified poller from the timer list. + * + * @since_tizen 2.3 + * + * @remarks @a poller must be a valid handle. If the poller function has already + * returned @c 0, the handle is no longer valid (and does not need to be deleted). + * + * @param[in] poller The poller to delete + * @return The data pointer set for the timer when @ref ecore_poller_add is called on success, + * otherwise @c NULL on failure + */ +EAPI void *ecore_poller_del(Ecore_Poller *poller); + +/** + * @} + */ + +/** + * @defgroup Ecore_Animator_Group Ecore Animator + * @ingroup Ecore_Main_Loop_Group + * + * @brief Ecore animators are a helper to simplify creating animations. + * + * Creating an animation is as simple as saying for how long it + * should be run and having a callback that does the animation, + * something like this: + * @code + * static Eina_Bool + * _do_animation(void *data, double pos) + * { + * evas_object_move(data, 100 * pos, 100 * pos); + * ... do some more animating ... + * } + * ... + * ecore_animator_timeline_add(2, _do_animation, my_evas_object); + * @endcode + * + * In the sample above we create an animation to move + * @c my_evas_object from position (0,0) to (100,100) in @c 2 seconds. + * + * If your animation runs for an unspecified amount of time you + * can use ecore_animator_add(), which is like using + * ecore_timer_add() with the interval being the + * @ref ecore_animator_frametime_set "framerate". Note that this has + * tangible benefits of creating a timer for each animation in terms + * of performance. + * + * @{ + */ + +/** + * @brief handle for ecore animator. + */ +typedef struct _Ecore_Animator Ecore_Animator; + +/** + * @enum _Ecore_Pos_Map + * @brief Enumeration that defines the position mappings for the animation. + */ +enum _Ecore_Pos_Map /* Position mappings */ +{ + ECORE_POS_MAP_LINEAR, /**< Linear 0.0 -> 1.0 */ + ECORE_POS_MAP_ACCELERATE, /**< Start slow then speed up */ + ECORE_POS_MAP_DECELERATE, /**< Start fast then slow down */ + ECORE_POS_MAP_SINUSOIDAL, /**< Start slow, speed up then slow down at the end */ + ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal accelerate, @c 2.0 being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on */ + ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal decelerate, @c 2.0 being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on */ + ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal sinusoidal, @c 2.0 being much more pronounced sinusoidal (squared), @c 3.0 being cubed, and so on */ + ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via power of v2 curve */ + ECORE_POS_MAP_BOUNCE, /**< Start at @c 0.0 then "drop" like a ball bouncing to the ground at @c 1.0, and bounce v2 times, with decay factor of v1 */ + ECORE_POS_MAP_SPRING /**< Start at @c 0.0 then "wobble" like a spring with rest position @c 1.0, and wobble v2 times, with decay factor of v1 */ +}; + +/** + * @brief typedef to enum _Ecore_Pos_Map + */ +typedef enum _Ecore_Pos_Map Ecore_Pos_Map; + +/** + * @enum _Ecore_Animator_Source + * @brief Enumeration that defines the timing sources for animators. + */ +enum _Ecore_Animator_Source /* Timing sources for animators */ +{ + ECORE_ANIMATOR_SOURCE_TIMER, /**< The default system clock/timer based animator that ticks every "frametime" seconds */ + ECORE_ANIMATOR_SOURCE_CUSTOM /**< A custom animator trigger which ticks when you call ecore_animator_trigger() */ +}; + +/** + * @brief typedef to enum _Ecore_Animator_Source + */ +typedef enum _Ecore_Animator_Source Ecore_Animator_Source; + +/** + * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb + * @brief The boolean type for a callback run for a task (animators with runtimes) + */ +typedef Eina_Bool (*Ecore_Timeline_Cb)(void *data, double pos); + +/** + * @brief Adds an animator to call @a func at every animation tick during main + * loop execution. + * + * @details This function adds an animator and returns its handle on success, and @c NULL + * on failure. The function @a func is called every N seconds where N is + * the @a frametime interval set by ecore_animator_frametime_set(). The + * function is passed the @a data pointer as its parameter. + * + * @since_tizen 2.3 + * + * @remarks When the animator @a func is called, it must return a value of either @c 1 or + * @c 0. If it returns @c 1 (or @c ECORE_CALLBACK_RENEW), it is called again at + * the next tick, or if it returns @c 0 (or @c ECORE_CALLBACK_CANCEL) it is + * deleted automatically making any references/handles for it invalid. + * + * @remarks The default @a frametime value is 1/30th of a second. + * + * @param[in] func The function to call when it ticks off + * @param[in] data The data to pass to the function + * @return A handle to the new animator + * + * @see ecore_animator_timeline_add() + * @see ecore_animator_frametime_set() + */ +EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); + +/** + * @brief Adds an animator that runs for a limited time. + * + * @details This function is just like ecore_animator_add() except that the animator only + * runs for a limited time specified in seconds by @a runtime. Once the + * runtime of the animator has elapsed (animator finished) it is automatically + * deleted. The callback function @a func can return @c ECORE_CALLBACK_RENEW + * to keep the animator running or @c ECORE_CALLBACK_CANCEL to stop it and have + * it deleted automatically at any time. + * + * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @remarks The @a func is ALSO passed a position parameter that has a value + * from @c 0.0 to @c 1.0 to indicate where along the timeline (@c 0.0 for start, @c 1.0 for end) + * is the animator run at. If the callback wishes not to have a linear + * transition it can "map" this value to one of the several curves and mappings + * via ecore_animator_pos_map(). + * + * @remarks The default @a frametime value is 1/30th of a second. + * + * @param[in] runtime The time to run in seconds + * @param[in] func The function to call when it ticks off + * @param[in] data The data to pass to the function + * @return A handle to the new animator + * + * @see ecore_animator_add() + * @see ecore_animator_pos_map() + */ +EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data); + +/** + * @brief Deletes the specified animator from the animator list. + * + * @details This deletes the specified @a animator from the set of animators that are + * executed during main loop execution. This function returns the data + * parameter that is being passed to the callback on success, otherwise @c NULL on + * failure. After this call returns the specified animator object @a animator + * is invalid and should not be used again. It does not get called again after + * deletion. + * + * @since_tizen 2.3 + * + * @param[in] animator The animator to delete + * @return The data pointer set for the animator on add + * + */ +EAPI void *ecore_animator_del(Ecore_Animator *animator); + +/** + * @brief Suspends the specified animator. + * + * @since_tizen 2.3 + * + * @remarks The specified @a animator is temporarily removed from the set of + * animators that are executed during the main loop. + * + * @remarks Freezing an animator doesn't freeze accounting of how long that + * animator has been running. Therefore if the animator is created with + * ecore_animator_timeline_add() the @a pos argument given to the callback + * increases as if the animator hadn't been frozen and the animator may + * have its execution halted if @a runtime elapses. + * + * @param[in] animator The animator to delete + * + */ +EAPI void ecore_animator_freeze(Ecore_Animator *animator); + +/** + * @brief Restores execution of the specified animator. + * + * @since_tizen 2.3 + * + * @remarks The specified @a animator is put back in the set of animators that are + * executed during the main loop. + * + * @param[in] animator The animator to delete + * + */ +EAPI void ecore_animator_thaw(Ecore_Animator *animator); + +/** + * @brief Sets the animator call interval in seconds. + * + * @details This function sets the time interval (in seconds) between animator ticks. + * At every tick the callback of every existing animator is called. + * + * @since_tizen 2.3 + * + * @remarks Too small a value may cause performance issues and too high a + * value may cause your animation to look "jerky". + * + * @remarks The default @a frametime value is 1/30th of a second. + * + * @param[in] frametime The time in seconds between animator ticks + * + */ +EAPI void ecore_animator_frametime_set(double frametime); + +/** + * @brief Gets the animator call interval in seconds. + * + * @details This function retrieves the time in seconds between animator ticks. + * + * @since_tizen 2.3 + * + * @return The time in seconds between animator ticks + * + * @see ecore_animator_frametime_set() + */ +EAPI double ecore_animator_frametime_get(void); + +/** + * @brief Maps an input position from @c 0.0 to @c 1.0 along a timeline to a + * position in a different curve. + * + * @details This takes an input position (@c 0.0 to @c 1.0) and maps it to a new position (normally + * between @c 0.0 and @c 1.0, but it may go above/below @c 0.0 or @c 1.0 to show that it + * has "overshot" the mark) using some interpolation (mapping) algorithm. + * + * @since_tizen 2.3 + * + * @remarks This function is useful to create non-linear animations. It offers a variety + * of possible animation curves to be used: + * @li ECORE_POS_MAP_LINEAR - Linear, returns @a pos. + * @li ECORE_POS_MAP_ACCELERATE - Start slow then speed up. + * @li ECORE_POS_MAP_DECELERATE - Start fast then slow down. + * @li ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at the end. + * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a + * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_ACCELERATE, @c 2.0 + * being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on. + * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a + * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_DECELERATE, @c 2.0 + * being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on. + * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down + * at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being + * @c ECORE_POS_MAP_SINUSOIDAL, @c 2.0 being much more pronounced sinusoidal + * (squared), @c 3.0 being cubed, and so on. + * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via + * power of v2 curve. + * @li ECORE_POS_MAP_BOUNCE - Start at @c 0.0 then "drop" like a ball bouncing to + * the ground at @c 1.0, and bounce v2 times, with decay factor of v1. + * @li ECORE_POS_MAP_SPRING - Start at @c 0.0 then "wobble" like a spring with rest + * position @c 1.0, and wobble v2 times, with decay factor of v1 + * @remarks When not listed v1 and v2 have no effect. + * + * @image html ecore-pos-map.png + * @image latex ecore-pos-map.eps "ecore pos map" width=\textwidth + * + * @remarks One way to use this would be: + * @code + * double pos; // input position in a timeline from 0.0 to 1.0 + * double out; // output position after mapping + * int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position + * int x, y; // x & y are the calculated position + * + * out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7); + * x = (x1 * out) + (x2 * (1.0 - out)); + * y = (y1 * out) + (y2 * (1.0 - out)); + * move_my_object_to(myobject, x, y); + * @endcode + * This makes an animation that bounces @c 7 diminish each time by a + * factor of @c 1.8. + * + * @param[in] pos The input position to map + * @param[in] map The mapping to use + * @param[in] v1 A parameter used by the mapping (pass @c 0.0 if not used) + * @param[in] v2 A parameter used by the mapping (pass @c 0.0 if not used) + * @return The mapped value + * + * @see _Ecore_Pos_Map + * + * @since 1.1.0 + */ +EAPI double ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2); + +/** + * @brief Sets the source of the animator ticks for the mainloop. + * + * @details This sets the source of the animator ticks. When an animator is active the + * mainloop will "tick" over frame by frame calling all animators that are + * registered until none are left. The mainloop ticks at a given rate based + * on the animator source. The default source is the system clock timer + * source - @c ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock + * to tick over every N seconds (specified by ecore_animator_frametime_set(), + * with the default being 1/30th of a second unless set otherwise). You can + * set a custom tick source by setting the source to + * @c ECORE_ANIMATOR_SOURCE_CUSTOM and then driving it yourself based on some input + * tick source (like another application via ipc, some vertical blanking + * interrupt and so on) using ecore_animator_custom_source_tick_begin_callback_set() and + * ecore_animator_custom_source_tick_end_callback_set() to set the functions + * that are called to start and stop the ticking source, which when + * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over @c 1 + * frame. + * + * @since_tizen 2.3 + * + * @param[in] source The source of the animator ticks to use + * + */ +EAPI void ecore_animator_source_set(Ecore_Animator_Source source); + +/** + * @brief Gets the animator source currently set. + * + * @details This gets the current animator source. + * + * @since_tizen 2.3 + * + * @return The current animator source + * + * @see ecore_animator_source_set() + */ +EAPI Ecore_Animator_Source ecore_animator_source_get(void); + +/** + * @brief Sets the function that begins a custom animator tick source. + * + * @since_tizen 2.3 + * + * @remarks The Ecore Animator infrastructure handles tracking of whether animators are needed + * and which ones need to be called and when, but when the tick source + * is custom, you have to provide a tick source by calling + * ecore_animator_custom_tick() to indicate that a frame tick happened. In order + * to allow the source of ticks to be dynamically enabled or disabled as + * needed, @a func when set is called to enable the tick source to + * produce tick events that call ecore_animator_custom_tick(). If @a func + * is @c NULL then no function is called to begin custom ticking. + * + * @param[in] func The function to call when ticking is to begin + * @param[in] data The data passed to the tick begin function as its parameter + * + * @see ecore_animator_source_set() + * @see ecore_animator_custom_source_tick_end_callback_set() + * @see ecore_animator_custom_tick() + */ +EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data); + +/** + * @brief Sets the function that ends a custom animator tick source. + * + * @since_tizen 2.3 + * + * @remarks This function is a matching pair to the function set by + * ecore_animator_custom_source_tick_begin_callback_set() and is called + * when ticking is to stop. If @a func is @c NULL then no function is + * called to stop ticking. For more information see + * ecore_animator_custom_source_tick_begin_callback_set(). + * + * @param[in] func The function to call when ticking is to end + * @param[in] data The data passed to the tick end function as its parameter + * + * @see ecore_animator_source_set() + * @see ecore_animator_custom_source_tick_begin_callback_set() + * @see ecore_animator_custom_tick() + */ +EAPI void ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data); + +/** + * @brief Triggers a custom animator tick. + * + * @since_tizen 2.3 + * + * @remarks When animator source is set to @c ECORE_ANIMATOR_SOURCE_CUSTOM, then calling + * this function triggers a run of all animators currently registered with + * Ecore as this indicates that a "frame tick" happened. This does nothing if + * the animator source(set by ecore_animator_source_set()) is not set to + * @c ECORE_ANIMATOR_SOURCE_CUSTOM. + * + * @see ecore_animator_source_set() + * @see ecore_animator_custom_source_tick_begin_callback_set + * @see ecore_animator_custom_source_tick_end_callback_set()() + */ +EAPI void ecore_animator_custom_tick(void); + +/** + * @} + */ + +/** + * @defgroup Ecore_Job_Group Ecore Job + * @ingroup Ecore_Main_Loop_Group + * + * @brief You can queue jobs that are to be done by the main loop when the + * current event is dealt with. + * + * Jobs are processed by the main loop in a manner which is similar to events. They + * are also executed in the order in which they are added. + * + * A good use for them is when you don't want to execute an action + * immediately, but want to give the control back to the main loop + * so that it calls your job callback when jobs start being + * processed (and if there are other jobs added before yours, they + * are processed first). This also gives a chance to other + * actions in your program to cancel the job before it is started. + * + * @{ + */ + +typedef struct _Ecore_Job Ecore_Job; /**< @brief A job handle */ + +/** + * @brief Add a job to the event queue. + * + * @since_tizen 2.3 + * + * @remarks Once the job has been executed, the job handle is invalid. + * + * @param[in] func The function to call when the job gets handled. + * @param[in] data Data pointer to be passed to the job function when the job is + * handled. + * @return The handle of the job. @c NULL is returned if the job could not be + * added to the queue. + */ +EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data); + +/** + * @brief Delete a queued job that has not yet been executed. + * + * @since_tizen 2.3 + * + * @param[in] job Handle of the job to delete. + * @return The data pointer that was to be passed to the job. + */ +EAPI void *ecore_job_del(Ecore_Job *job); + +/** + * @} + */ #ifdef __cplusplus } diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h index a20cc98e02..33661e4e90 100644 --- a/src/lib/ecore/Ecore_Getopt.h +++ b/src/lib/ecore/Ecore_Getopt.h @@ -31,168 +31,121 @@ #endif /* ! _WIN32 */ /** - * @defgroup Ecore_Getopt_Group Ecore Getopt - * @ingroup Ecore - * - * This group contains powerful getopt replacement. + * @internal + * @file Ecore_Getopt.h + * @brief Contains powerful getopt replacement. * * This replacement handles both short (-X) or long options (--ABC) * options, with various actions supported, like storing one value and * already converting to required type, counting number of - * occurrences, setting true or false values, show help, license, - * copyright and even support user-defined callbacks. + * occurrences, setting true or false values, showing help, license, + * copyright, and even supporting user-defined callbacks. * - * It is provided a set of C Pre Processor macros so definition is + * It is provided a set of C Pre Processor macros. So definition is * straightforward. * - * Values will be stored elsewhere indicated by an array of pointers - * to values, it is given in separate to parser description so you can + * Values are stored elsewhere indicated by an array of pointers + * to values. It is given separately to parser description. So you can * use multiple values with the same parser. - * - * @{ */ #ifdef __cplusplus extern "C" { #endif -/** - * @typedef Ecore_Getopt_Action - * @brief Enumeration that defines the actions to do when parsing command line - * parameters. - */ typedef enum { - ECORE_GETOPT_ACTION_STORE, /**< Store a value */ - ECORE_GETOPT_ACTION_STORE_CONST, /**< Store a const */ - ECORE_GETOPT_ACTION_STORE_TRUE, /**< Store TRUE */ - ECORE_GETOPT_ACTION_STORE_FALSE, /**< Store FALSE */ - ECORE_GETOPT_ACTION_CHOICE, /**< Store a choice between several values */ - ECORE_GETOPT_ACTION_APPEND, /**< Allocate and store a new value of type Ecore_Getopt_Type */ - ECORE_GETOPT_ACTION_COUNT, /**< Store a count number */ - ECORE_GETOPT_ACTION_CALLBACK, /**< Call a callback */ - ECORE_GETOPT_ACTION_HELP, /**< Show help text */ - ECORE_GETOPT_ACTION_VERSION, /**< Show version */ - ECORE_GETOPT_ACTION_COPYRIGHT, /**< Show copyright */ - ECORE_GETOPT_ACTION_LICENSE, /**< Show license */ - ECORE_GETOPT_ACTION_BREAK, /**< Stop parsing options */ - ECORE_GETOPT_ACTION_CATEGORY + ECORE_GETOPT_ACTION_STORE, + ECORE_GETOPT_ACTION_STORE_CONST, + ECORE_GETOPT_ACTION_STORE_TRUE, + ECORE_GETOPT_ACTION_STORE_FALSE, + ECORE_GETOPT_ACTION_CHOICE, + ECORE_GETOPT_ACTION_APPEND, + ECORE_GETOPT_ACTION_COUNT, + ECORE_GETOPT_ACTION_CALLBACK, + ECORE_GETOPT_ACTION_HELP, + ECORE_GETOPT_ACTION_VERSION, + ECORE_GETOPT_ACTION_COPYRIGHT, + ECORE_GETOPT_ACTION_LICENSE } Ecore_Getopt_Action; -/** - * @typedef Ecore_Getopt_Type - * @brief Enumeration that defines the type of the values to store when using - * append action. - */ typedef enum { - ECORE_GETOPT_TYPE_STR, /**< Value of type string */ - ECORE_GETOPT_TYPE_BOOL, /**< Value of type boolean */ - ECORE_GETOPT_TYPE_SHORT, /**< Value of type short */ - ECORE_GETOPT_TYPE_INT, /**< Value of type int */ - ECORE_GETOPT_TYPE_LONG, /**< Value of type long */ - ECORE_GETOPT_TYPE_USHORT, /**< Value of type unsigned short */ - ECORE_GETOPT_TYPE_UINT, /**< Value of type unsigned int */ - ECORE_GETOPT_TYPE_ULONG, /**< Value of type unsigned long */ - ECORE_GETOPT_TYPE_DOUBLE /**< Value of type double */ + ECORE_GETOPT_TYPE_STR, + ECORE_GETOPT_TYPE_BOOL, + ECORE_GETOPT_TYPE_SHORT, + ECORE_GETOPT_TYPE_INT, + ECORE_GETOPT_TYPE_LONG, + ECORE_GETOPT_TYPE_USHORT, + ECORE_GETOPT_TYPE_UINT, + ECORE_GETOPT_TYPE_ULONG, + ECORE_GETOPT_TYPE_DOUBLE } Ecore_Getopt_Type; -/** - * @typedef Ecore_Getopt_Desc_Arg_Requirement - * @brief Enumeration that defines if the command line options require an - * argument. - */ typedef enum { - ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, /**< Argument is not required */ - ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, /**< Argument is required */ - ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 /**< Argument is optional */ + ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, + ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, + ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 } Ecore_Getopt_Desc_Arg_Requirement; +typedef union _Ecore_Getopt_Value Ecore_Getopt_Value; + typedef struct _Ecore_Getopt_Desc_Store Ecore_Getopt_Desc_Store; typedef struct _Ecore_Getopt_Desc_Callback Ecore_Getopt_Desc_Callback; +typedef struct _Ecore_Getopt_Desc Ecore_Getopt_Desc; +typedef struct _Ecore_Getopt Ecore_Getopt; -#ifndef _ECORE_GETOPT_PREDEF -typedef struct _Ecore_Getopt Ecore_Getopt; -#define _ECORE_GETOPT_PREDEF 1 -#endif -#ifndef _ECORE_GETOPT_DESC_PREDEF -typedef struct _Ecore_Getopt_Desc Ecore_Getopt_Desc; -#define _ECORE_GETOPT_DESC_PREDEF 1 -#endif -#ifndef _ECORE_GETOPT_VALUE_PREDEF -typedef union _Ecore_Getopt_Value Ecore_Getopt_Value; -#define _ECORE_GETOPT_VALUE_PREDEF 1 -#endif - -/** - * @union _Ecore_Getopt_Value - * @brief Union listing the types of parameters that can take Getopt values. - */ union _Ecore_Getopt_Value { - char **strp; /**< String pointer */ - unsigned char *boolp; /**< Boolean pointer */ - short *shortp; /**< Short pointer */ - int *intp; /**< Int pointer */ - long *longp; /**< Long pointer */ - unsigned short *ushortp; /**< Unsigned short pointer */ - unsigned int *uintp; /**< Unsigned int pointer */ - unsigned long *ulongp; /**< Unsigned long pointer */ - double *doublep; /**< Double pointer */ - Eina_List **listp; /**< List pointer */ - void **ptrp; /**< Void pointer */ + char **strp; + unsigned char *boolp; + short *shortp; + int *intp; + long *longp; + unsigned short *ushortp; + unsigned int *uintp; + unsigned long *ulongp; + double *doublep; + Eina_List **listp; + void **ptrp; }; -/** - * @struct _Ecore_Getopt_Desc_Store - * @brief Structure used when action is ECORE_GETOPT_ACTION_STORE. It contains - * information about the value to store. - */ struct _Ecore_Getopt_Desc_Store { - Ecore_Getopt_Type type; /**< type of data being handled */ - Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ + Ecore_Getopt_Type type; /**< Type of data being handled */ + Ecore_Getopt_Desc_Arg_Requirement arg_req; union { - const char *strv; /**< String value */ - Eina_Bool boolv; /**< Boolean value */ - short shortv; /**< Short value */ - int intv; /**< Int value */ - long longv; /**< Long value */ - unsigned short ushortv; /**< Unsigned short value */ - unsigned int uintv; /**< Unsigned int value */ - unsigned long ulongv; /**< Unsigned long value */ - double doublev; /**< Double value */ - } def; /**< value of data being handled */ + const char *strv; + Eina_Bool boolv; + short shortv; + int intv; + long longv; + unsigned short ushortv; + unsigned int uintv; + unsigned long ulongv; + double doublev; + } def; }; -/** - * @struct _Ecore_Getopt_Desc_Callback - * @brief Structure used when action is ECORE_GETOPT_ACTION_CALLBACK. It - * contains information about the callback to call. - */ struct _Ecore_Getopt_Desc_Callback { Eina_Bool (*func)(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, - Ecore_Getopt_Value *storage); /**< function to call as a callback */ - const void *data; /**< data to pass to the callback */ - Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ + Ecore_Getopt_Value *storage); + const void *data; + Ecore_Getopt_Desc_Arg_Requirement arg_req; const char *def; }; -/** - * @struct _Ecore_Getopt_Desc - * @brief Structure that describe an option of the command line. - */ struct _Ecore_Getopt_Desc { - char shortname; /**< used with a single dash */ - const char *longname; /**< used with double dashes */ - const char *help; /**< used by --help/ecore_getopt_help() */ - const char *metavar; /**< used by ecore_getopt_help() with nargs > 0 */ + char shortname; /**< Used with a single dash */ + const char *longname; /**< Used with double dashes */ + const char *help; /**< Used by -- help/ecore_getopt_help() */ + const char *metavar; /**< Used by ecore_getopt_help() with nargs > 0 */ - Ecore_Getopt_Action action; /**< define how to handle it */ + Ecore_Getopt_Action action; /**< Define how to handle it */ union { const Ecore_Getopt_Desc_Store store; @@ -201,1018 +154,267 @@ struct _Ecore_Getopt_Desc const Ecore_Getopt_Type append_type; const Ecore_Getopt_Desc_Callback callback; const void *dummy; - } action_param; /**< Action parameter */ + } action_param; }; -/** - * @struct _Ecore_Getopt - * @brief Structure that contains information on all command line options. - */ struct _Ecore_Getopt { - const char *prog; /**< to be used when ecore_app_args_get() fails */ - const char *usage; /**< usage example, %prog is replaced */ - const char *version; /**< if exists, --version will work */ - const char *copyright; /**< if exists, --copyright will work */ - const char *license; /**< if exists, --license will work */ - const char *description; /**< long description, possible multiline */ - Eina_Bool strict : 1; /**< fail on errors */ - const Ecore_Getopt_Desc descs[]; /**< A table that contains the description of all the other options (NULL terminated).*/ - + const char *prog; /**< To be used when ecore_app_args_get() fails */ + const char *usage; /**< Usage example, %prog is replaced */ + const char *version; /**< If exists, --version works */ + const char *copyright; /**< If exists, --copyright works */ + const char *license; /**< If exists, --license works */ + const char *description; /**< Long description, possible multiline */ + Eina_Bool strict : 1; /**< Fail on errors */ + const Ecore_Getopt_Desc descs[]; /**< @c NULL terminated */ }; -/** - * @brief Macro that helps to fill the Ecore_Getopt_Desc table. - */ #define ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, arg_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_STORE, \ {.store = {type, arg_requirement, default_value}}} -/** - * @brief Macro that fills an option in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param type The option value type. - */ #define ECORE_GETOPT_STORE(shortname, longname, help, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type string. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ + #define ECORE_GETOPT_STORE_STR(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_STR) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type boolean. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_BOOL(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_BOOL) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type short. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_SHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_SHORT) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type int. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_INT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_INT) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type long. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_LONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_LONG) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ushort. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_USHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_USHORT) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type uint. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_UINT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_UINT) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ulong. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_ULONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_ULONG) - -/** - * @brief Macro that fill Ecore_Getopt_Desc table with an option of type double. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_DOUBLE(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_DOUBLE) -/** - * Macro that helps to fill the Ecore_Getopt_Desc table with a metavar after - * the description of the option. - */ #define ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type string and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_STR(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_STR) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_BOOL(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_BOOL) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type short and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_SHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_SHORT) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type int and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_INT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_INT) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type long and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_LONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_LONG) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_USHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_USHORT) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_UINT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_UINT) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_ULONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_ULONG) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type double and metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - */ #define ECORE_GETOPT_STORE_METAVAR_DOUBLE(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_DOUBLE) -/** - * Macro that helps to fill the Ecore_Getopt_Desc table with a default value. - */ #define ECORE_GETOPT_STORE_DEF(shortname, longname, help, type, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL, \ default_value) -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type string and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_STR(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_STR, \ {.strv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_BOOL(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_BOOL, \ {.boolv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type short and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_SHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_SHORT, \ {.shortv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type int and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_INT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_INT, \ {.intv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type long and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_LONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_LONG, \ {.longv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_USHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_USHORT, \ {.ushortv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_UINT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_UINT, \ {.uintv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_ULONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_ULONG, \ {.ulongv = default_value}) - -/** - * @brief Fill Ecore_Getopt_Desc table with an option of type double and default value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_DEF_DOUBLE(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_DOUBLE, \ {.doublev = default_value}) -/** - * @brief Fill full string type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_STR(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_STR, \ arg_requirement, \ {.strv = default_value}) - -/** - * @brief Fill full boolean type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_BOOL(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_BOOL, \ arg_requirement, \ {.boolv = default_value}) - -/** - * @brief Fill full short type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_SHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_SHORT, \ arg_requirement, \ {.shortv = default_value}) - -/** - * @brief Fill full int type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_INT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_INT, \ arg_requirement, \ {.intv = default_value}) - -/** - * @brief Fill full long type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_LONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_LONG, \ arg_requirement, \ {.longv = default_value}) - -/** - * @brief Fill full unsigned short type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_USHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_USHORT, \ arg_requirement, \ {.ushortv = default_value}) - -/** - * @brief Fill full unsigned int type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_UINT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_UINT, \ arg_requirement, \ {.uintv = default_value}) - -/** - * @brief Fill full unsigned long type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_ULONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_ULONG, \ arg_requirement, \ {.ulongv = default_value}) - -/** - * @brief Fill full double type option description in Ecore_Getopt_Desc table. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param arg_requirement The option argument requirements. - * @param default_value The default value for the parameter of the option. - */ #define ECORE_GETOPT_STORE_FULL_DOUBLE(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_DOUBLE, \ arg_requirement, \ {.doublev = default_value}) -/** - * @brief Fill Ecore_Getopt_Desc table with a constant value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param value The constant value to store. - */ #define ECORE_GETOPT_STORE_CONST(shortname, longname, help, value) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_CONST, \ {.store_const = value}} - -/** - * @brief Fill Ecore_Getopt_Desc table with a true boolean value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_TRUE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_TRUE, \ {.dummy = NULL}} - -/** - * @brief Fill Ecore_Getopt_Desc table with a false boolean value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_STORE_FALSE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_FALSE, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with a true boolean value. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param choices_array An string array of different choices. - */ #define ECORE_GETOPT_CHOICE(shortname, longname, help, choices_array) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} - -/** - * @brief Fill Ecore_Getopt_Desc table with a choice. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param choices_array An string array of different choices. - */ #define ECORE_GETOPT_CHOICE_METAVAR(shortname, longname, help, metavar, choices_array) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} -/** - * @brief Fill Ecore_Getopt_Desc table with an append action. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param sub_type The type of the new value to store. - */ #define ECORE_GETOPT_APPEND(shortname, longname, help, sub_type) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = sub_type}} - -/** - * @brief Fill Ecore_Getopt_Desc table with an append action and a metavar. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param type The type of the new value to store. - */ #define ECORE_GETOPT_APPEND_METAVAR(shortname, longname, help, metavar, type) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = type}} -/** - * @brief Fill Ecore_Getopt_Desc table with an count action. - * - * This will store the number of time the option has been passed to the command - * line. - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ #define ECORE_GETOPT_COUNT(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_COUNT, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with an callback action and argument requirements. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param callback_func The callback function to call. - * @param callback_data The data to pass to the callback. - * @param argument_requirement the required arguments to this option. - * @param default_value The default values for these arguments. - */ #define ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, callback_func, callback_data, argument_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CALLBACK, \ {.callback = {callback_func, callback_data, \ argument_requirement, default_value}}} - -/** - * @brief Fill Ecore_Getopt_Desc table with an callback action and no arguments. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param callback_func The callback function to call. - * @param callback_data The data to pass to the callback. - */ #define ECORE_GETOPT_CALLBACK_NOARGS(shortname, longname, help, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, NULL, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO, \ NULL) - -/** - * @brief Fill Ecore_Getopt_Desc table with an callback action. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - * @param metavar The metavar message concerning the parameter of the option. - * @param callback_func The callback function to call. - * @param callback_data The data to pass to the callback. - */ #define ECORE_GETOPT_CALLBACK_ARGS(shortname, longname, help, metavar, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, \ NULL) -/** - * @brief Fill Ecore_Getopt_Desc table with a help action. - * - * @param shortname The help option short name. - * @param longname The help option long name. - */ -#define ECORE_GETOPT_HELP(shortname, longname) \ - {shortname, longname, "show this message.", "CATEGORY", \ - ECORE_GETOPT_ACTION_HELP, \ +#define ECORE_GETOPT_HELP(shortname, longname) \ + {shortname, longname, "show this message.", NULL, \ + ECORE_GETOPT_ACTION_HELP, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with a version action. - * - * @param shortname The version option short name. - * @param longname The version option long name. - */ #define ECORE_GETOPT_VERSION(shortname, longname) \ {shortname, longname, "show program version.", NULL, \ ECORE_GETOPT_ACTION_VERSION, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with a copyright action. - * - * @param shortname The copyright option short name. - * @param longname The copyright option long name. - */ #define ECORE_GETOPT_COPYRIGHT(shortname, longname) \ {shortname, longname, "show copyright.", NULL, \ ECORE_GETOPT_ACTION_COPYRIGHT, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with a license action. - * - * @param shortname The license option short name. - * @param longname The license option long name. - */ #define ECORE_GETOPT_LICENSE(shortname, longname) \ {shortname, longname, "show license.", NULL, \ ECORE_GETOPT_ACTION_LICENSE, \ {.dummy = NULL}} -/** - * @brief Fill Ecore_Getopt_Desc table with a break action. - * - * @param shortname The option short name. - * @param longname The option long name. - */ -#define ECORE_GETOPT_BREAK(shortname, longname) \ - {shortname, longname, "stop parsing options.", NULL, \ - ECORE_GETOPT_ACTION_BREAK, \ - {.dummy = NULL}} - -/** - * @brief Fill Ecore_Getopt_Desc table with a break action with help message. - * - * @param shortname The option short name. - * @param longname The option long name. - * @param help The help message concerning this option. - */ -#define ECORE_GETOPT_BREAK_STR(shortname, longname, help) \ - {shortname, longname, help, NULL, \ - ECORE_GETOPT_ACTION_BREAK, \ - {.dummy = NULL}} - -#define ECORE_GETOPT_CATEGORY(name, help) \ - {0, name, help, NULL, ECORE_GETOPT_ACTION_CATEGORY, {.dummy = NULL}} - -/** - * @brief Fill Ecore_Getopt_Desc table with a sentinel to indicate the end of descriptions. - * - */ #define ECORE_GETOPT_SENTINEL {0, NULL, NULL, NULL, 0, {.dummy = NULL}} -/** - * @brief options that store a single value in a variable of type string. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_STR(val) {.strp = &(val)} - -/** - * @brief options that store a single value in a variable of type boolean. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_BOOL(val) {.boolp = &(val)} - -/** - * @brief options that store a single value in a variable of type short. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_SHORT(val) {.shortp = &(val)} - -/** - * @brief options that store a single value in a variable of type int. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_INT(val) {.intp = &(val)} - -/** - * @brief options that store a single value in a variable of type long. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_LONG(val) {.longp = &(val)} - -/** - * @brief options that store a single value in a variable of type unsigned short. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_USHORT(val) {.ushortp = &(val)} - -/** - * @brief options that store a single value in a variable of type unsigned int. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_UINT(val) {.uintp = &(val)} - -/** - * @brief options that store a single value in a variable of type unsigned long. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_ULONG(val) {.ulongp = &(val)} - -/** - * @brief options that store a single value in a variable of type double. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_DOUBLE(val) {.doublep = &(val)} - -/** - * @brief options that store a single value in a variable of type pointer. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_PTR(val) {.ptrp = &(val)} - -/** - * @brief options that store a single value in a variable of type pointer casted. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_PTR_CAST(val) {.ptrp = (void **)&(val)} - -/** - * @brief options that store a single value in a variable of type list. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_LIST(val) {.listp = &(val)} - -/** - * @brief options that store a NULL value. - * - * @param val The value to store. - */ #define ECORE_GETOPT_VALUE_NONE {.ptrp = NULL} -/** - * Show nicely formatted help message for the given parser. - * - * @param fp The file the message will be printed on. - * @param info The structure containing information about command line options. - * - * @see ecore_getopt_help_category() - */ -EAPI void ecore_getopt_help(FILE *fp, const Ecore_Getopt *info); - -/** - * Show help for a single category (along with program usage and description). - * - * @param fp The file the message will be printed on. - * @param info The structure containing information about command line options. - * @param category The category to print. - * - * @return @c EINA_TRUE when the category exists, @c EINA_FALSE otherwise. - * - * @see ecore_getopt_help() - */ -EAPI Eina_Bool ecore_getopt_help_category(FILE *fp, const Ecore_Getopt *info, const char *category); - -/** - * Check parser for duplicate entries, print them out. - * - * @return @c EINA_TRUE if there are duplicates, @c EINA_FALSE otherwise. - * @param parser The parser to be checked. - */ -EAPI Eina_Bool ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser); - -/** - * Parse command line parameters. - * - * Walks the command line parameters and parse them based on @a parser - * description, doing actions based on @c parser->descs->action, like - * showing help text, license, copyright, storing values in values and - * so on. - * - * It is expected that values is of the same size than @c parser->descs, - * options that do not need a value it will be left untouched. - * - * All values are expected to be initialized before use. Options with - * action @c ECORE_GETOPT_ACTION_STORE and non required arguments - * (others than @c ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES), are expected - * to provide a value in @c def to be used. - * - * The following actions will store @c 1 on value as a boolean - * (@c value->boolp) if it's not @c NULL to indicate these actions were - * executed: - * - @c ECORE_GETOPT_ACTION_HELP - * - @c ECORE_GETOPT_ACTION_VERSION - * - @c ECORE_GETOPT_ACTION_COPYRIGHT - * - @c ECORE_GETOPT_ACTION_LICENSE - * - * Just @c ECORE_GETOPT_ACTION_APPEND will allocate memory and thus - * need to be freed. For consistency between all of appended subtypes, - * @c eina_list->data will contain an allocated memory with the value, - * that is, for @c ECORE_GETOPT_TYPE_STR it will contain a copy of the - * argument, @c ECORE_GETOPT_TYPE_INT a pointer to an allocated - * integer and so on. - * - * If parser is in strict mode (see @c Ecore_Getopt->strict), then any - * error will abort parsing and @c -1 is returned. Otherwise it will try - * to continue as far as possible. - * - * This function may reorder @a argv elements. - * - * Translation of help strings (description), metavar, usage, license - * and copyright may be translated, standard/global gettext() call - * will be applied on them if ecore was compiled with such support. - * - * This function will @b not parse positional arguments! If these are - * declared (metavar is defined with both shortname and longname being - * empty), then you must call ecore_getopt_parse_positional() with the - * last argument (@c start) being the result of this function. This is - * done so you can have "quit options", those that once called you - * want to exit without doing further parsing, as is the case with - * help, license, copyright, version and eventually others you may - * define. - * - * @param parser description of how to work. - * @param values where to store values, it is assumed that this is a vector - * of the same size as @c parser->descs. Values should be previously - * initialized. - * @param argc how many elements in @a argv. If not provided it will be - * retrieved with ecore_app_args_get(). - * @param argv command line parameters. - * - * @return index of first non-option parameter or -1 on error. - * - * @see ecore_getopt_parse_positional() - */ -EAPI int ecore_getopt_parse(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv); - -/** - * Parse command line positional parameters. - * - * Walks the command line positional parameters (those that do not - * start with "-" or "--") and parse them based on @a parser - * description, doing actions based on @c parser->descs->action, like - * storing values of some type. - * - * It is expected that @a values is of the same size than @c - * parser->descs, same as with ecore_getopt_parse(). - * - * All values are expected to be initialized before use. - * - * Unlike the ecore_getopt_parse(), only the following options are - * supported: - * - @c ECORE_GETOPT_ACTION_STORE - * - @c ECORE_GETOPT_ACTION_CHOICE - * - @c ECORE_GETOPT_ACTION_APPEND - * - @c ECORE_GETOPT_ACTION_CALLBACK - * - * There is a special case for @c ECORE_GETOPT_ACTION_APPEND as it - * will consume all remaining elements. It is also special in the - * sense that it will allocate memory and thus need to be freed. For - * consistency between all of appended subtypes, @c eina_list->data - * will contain an allocated memory with the value, that is, for @c - * ECORE_GETOPT_TYPE_STR it will contain a copy of the argument, @c - * ECORE_GETOPT_TYPE_INT a pointer to an allocated integer and so on. - * - * If parser is in strict mode (see @c Ecore_Getopt->strict), then any - * error will abort parsing and @c -1 is returned. Otherwise it will try - * to continue as far as possible. - * - * Translation of help strings (description) and metavar may be done, - * standard/global gettext() call will be applied on them if ecore was - * compiled with such support. - * - * @param parser description of how to work. - * @param values where to store values, it is assumed that this is a vector - * of the same size as @c parser->descs. Values should be previously - * initialized. - * @param argc how many elements in @a argv. If not provided it will be - * retrieved with ecore_app_args_get(). - * @param argv command line parameters. - * @param start the initial position argument to look at, usually the - * return of ecore_getopt_parse(). If less than 1, will try to - * find it automatically. - * - * @return index of first non-option parameter or -1 on error. If the - * last positional argument is of action @c - * ECORE_GETOPT_ACTION_APPEND then it will be the same as @a argc. - */ -EAPI int ecore_getopt_parse_positional(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv, int start); +EAPI void +ecore_getopt_help(FILE *fp, + const Ecore_Getopt *info); +EAPI Eina_Bool + ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser); +EAPI int + ecore_getopt_parse(const Ecore_Getopt *parser, + Ecore_Getopt_Value *values, + int argc, + char **argv); -/** - * Utility to free list and nodes allocated by @a ECORE_GETOPT_ACTION_APPEND. - * - * @param list pointer to list to be freed. - * @return always @c NULL, so you can easily make your list head @c NULL. - */ EAPI Eina_List *ecore_getopt_list_free(Eina_List *list); -/** - * Helper ecore_getopt callback to parse geometry (x:y:w:h). - * - * @param parser This parameter isn't in use. - * @param desc This parameter isn't in use. - * @param str Geometry value - * @param data This parameter isn't in use. - * @param storage must be a pointer to @c Eina_Rectangle and will be used to - * store the four values passed in the given string. - * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect geometry value. - * - * This is a helper functions to be used with ECORE_GETOPT_CALLBACK_*(). - * - * @c callback_data value is ignored, you can safely use @c NULL. - */ -EAPI Eina_Bool ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage); - -/** - * Helper ecore_getopt callback to parse geometry size (WxH). - * - * @param parser This parameter isn't in use. - * @param desc This parameter isn't in use. - * @param str size value - * @param data This parameter isn't in use. - * @param storage must be a pointer to @c Eina_Rectangle and will be used to - * store the two values passed in the given string and @c 0 in the x and y - * fields. - * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect size value. - * - * @c callback_data value is ignored, you can safely use @c NULL. - */ -EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage); +/* Helper functions to be used with ECORE_GETOPT_CALLBACK_*() */ +EAPI Eina_Bool +ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser, + const Ecore_Getopt_Desc *desc, + const char *str, + void *data, + Ecore_Getopt_Value *storage); +EAPI Eina_Bool +ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, + const Ecore_Getopt_Desc *desc, + const char *str, + void *data, + Ecore_Getopt_Value *storage); #ifdef __cplusplus } #endif - -/** - * @} - */ - #endif /* _ECORE_GETOPT_H */ diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h index 6cfea2eff3..a299c033a4 100644 --- a/src/lib/ecore_con/Ecore_Con.h +++ b/src/lib/ecore_con/Ecore_Con.h @@ -9,7 +9,6 @@ # include <netdb.h> #endif #include <Eina.h> -#include <Eo.h> #ifdef EAPI # undef EAPI @@ -38,12 +37,13 @@ #endif /** + * @internal * @defgroup Ecore_Con_Group Ecore_Con - Connection functions - * @ingroup Ecore + * @ingroup Ecore_Group * * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms - * for communications between programs using reliable sockets. It saves - * the programmer from having to worry about file descriptors and waiting + * for communications between programs using reliable sockets. It saves + * you from having to worry about file descriptors and waiting * for incoming connections. * * There are two main objects in the @c Ecore_Con library: the @c @@ -70,138 +70,140 @@ /** + * @internal * @defgroup Ecore_Con_Events_Group Ecore Connection Events Functions * @ingroup Ecore_Con_Group * * @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an * @c Ecore_Con_Server, an event of this type is emitted, allowing the - * retrieval of the client's ip with @ref ecore_con_client_ip_get and + * retrieval of the client's IP with @ref ecore_con_client_ip_get and * associating data with the client using ecore_con_client_data_set. * @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an - * @c Ecore_Con_Server, an event of this type is emitted. The contents of + * @c Ecore_Con_Server, an event of this type is emitted. The contents of * the data with this event are variable, but if the client object in the data * is non-null, it must be freed with @ref ecore_con_client_del. * @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created * with @ref ecore_con_server_connect, an event of this type is emitted, * allowing for data to be serialized and sent to the server using - * @ref ecore_con_server_send. At this point, the http handshake has + * @ref ecore_con_server_send. At this point, the HTTP handshake has * occurred. * @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed, * usually by the server connection being refused or dropped, an event of this - * type is emitted. The contents of the data with this event are variable, + * type is emitted. The contents of the data with this event are variable, * but if the server object in the data is non-null, it must be freed * with @ref ecore_con_server_del. * @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server - * object and sends data, an event of this type is emitted. The data will contain both - * the size and contents of the message sent by the client. It should be noted that + * object and sends data, an event of this type is emitted. The data contains both + * the size and contents of the message sent by the client. It should be noted that * data within this object is transient, so it must be duplicated in order to be - * retained. This event will continue to occur until the client has stopped sending its - * message, so a good option for storing this data is an Eina_Strbuf. Once the message has + * retained. This event continues to occur until the client has stopped sending its + * message, so a good option for storing this data is an Eina_Strbuf. Once the message has * been received in full, the client object must be freed with ecore_con_client_free. * @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination - * and receives data, an event of this type is emitted. The data will contain both - * the size and contents of the message sent by the server. It should be noted that + * and receives data, an event of this type is emitted. The data contains both + * the size and contents of the message sent by the server. It should be noted that * data within this object is transient, so it must be duplicated in order to be - * retained. This event will continue to occur until the server has stopped sending its - * message, so a good option for storing this data is an Eina_Strbuf. Once the message has + * retained. This event continues to occur until the server has stopped sending its + * message, so a good option for storing this data is an Eina_Strbuf. Once the message has * been received in full, the server object must be freed with ecore_con_server_free. * */ /** + * @internal * @defgroup Ecore_Con_Buffer Ecore Connection Buffering * @ingroup Ecore_Con_Group - * - * As Ecore_Con works on an event driven design, as data arrives, events will - * be produced containing the data that arrived. It is up to the user of + * + * As Ecore_Con works on an event driven design, as data arrives, events are + * produced containing the data that arrived. It is up to the user of * Ecore_Con to either parse as they go, append to a file to later parse the - * whole file in one go, or append to memory to parse or handle later. - * - * To help with this Eina has some handy API's. The Eina_Binbuf and - * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial - * to handle buffers at runtime, without having to manage them. Eina_Binbuf - * makes it possible to create, expand, reset and slice a blob of memory - - * all via API. No system calls, no pointer manipulations and no size + * whole file in one go, or append to memory to parse or handle leter. + * + * To help with this, Eina has some handy API's. The Eina_Binbuf and + * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial + * to handle buffers at runtime, without having to manage them. Eina_Binbuf + * makes it possible to create, expand, reset and slice a blob of memory - + * all via API. No system calls, no pointer manipulations and no size * calculation. - * - * Additional functions include adding content at specified byte positions in - * the buffer, escaping the inputs, find and replace strings. This provides + * + * Additional functions include adding content at specified byte positions in + * the buffer, escaping the inputs, find and replace strings. This provides * extreme flexibility to play around, with a dynamic blob of memory. - * + * * It is good to free it (using eina_binbuf_free()) after using it. - * + * * Eina_Binbuf compliments Ecore_Con use cases, where dynamic sizes of data * arrive from the network (think http download in chunks). Using * Eina_Binbuf provides enough flexibility to handle data as it arrives and * to defer its processing until desired, without having to think about * where to store the temporary data and how to manage its size. - * + * * An example of how to use these with Ecore_Con follows. - * + * * @code * #include <Eina.h> * #include <Ecore.h> * #include <Ecore_Con.h> - * + * * static Eina_Bool * data_callback(void *data, int type, void *event) * { * Ecore_Con_Event_Url_Data *url_data = event; * if ( url_data->size > 0) * { - * // append data as it arrives - don't worry where or how it gets stored. - * // Also don't worry about size, expanding, reallocing etc. - * // just keep appending - size is automatically handled. - * + * // Append data as it arrives - do not worry where or how it gets stored. + * // Also do not worry about size, expanding, reallocing etc. + * // Just keep appending - size is automatically handled. + * * eina_binbuf_append_length(data, url_data->data, url_data->size); - * + * * fprintf(stderr, "Appended %d \n", url_data->size); * } * return EINA_TRUE; * } - * - * - * + * + * + * * static Eina_Bool * completion_callback(void *data, int type, void *event) * { * Ecore_Con_Event_Url_Complete *url_complete = event; * printf("download completed with status code: %d\n", url_complete->status); - * - * // get the data back from Eina_Binbuf + * + * // Get the data back from Eina_Binbuf * char *ptr = eina_binbuf_string_get(data); * size_t size = eina_binbuf_length_get(data); - * - * // process data as required (write to file) + * + * // Process data as required (write to file) * fprintf(stderr, "Size of data = %d bytes\n", size); * int fd = open("./elm.png", O_CREAT); * write(fd, ptr, size); * close(fd); - * - * // free it when done. + * + * // Free it when done. * eina_binbuf_free(data); - * + * * ecore_main_loop_quit(); - * + * * return EINA_TRUE; * } - * - * + * + * * int * main(int argc, char **argv) * { - * + * * const char *url = "http://www.enlightenment.org/p/index/d/logo.png"; - * + * * ecore_init(); * ecore_con_init(); * ecore_con_url_init(); - * - * + * + * * // This is single additional line to manage dynamic network data. * Eina_Binbuf *data = eina_binbuf_new(); * Ecore_Con_Url *url_con = ecore_con_url_new(url); - * + * * ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE, * completion_callback, * data); @@ -209,7 +211,7 @@ * data_callback, * data); * ecore_con_url_get(url_con); - * + * * ecore_main_loop_begin(); * return 0; * } @@ -222,376 +224,341 @@ extern "C" { #define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2 #define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP -typedef Eo Ecore_Con; /** - * @typedef Ecore_Con_Socks - * An object representing a SOCKS proxy - * @ingroup Ecore_Con_Socks_Group - * @since 1.2 + * @typedef Ecore_Con_Server + * @brief The structure type containing a connection handle to a server. + * @ingroup Ecore_Con_Server_Group */ -typedef struct Ecore_Con_Socks Ecore_Con_Socks; +typedef struct _Ecore_Con_Server Ecore_Con_Server; /** - * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions - * @ingroup Ecore_Con_Group - * - * Utility functions that set up and shut down the Ecore Connection - * library. - * - * There's also ecore_con_lookup() that can be used to make simple asynchronous - * DNS lookups. + * @typedef Ecore_Con_Client + * @brief The structure type containing a connection handle to a client. + * @ingroup Ecore_Con_Client_Group + */ +typedef struct _Ecore_Con_Client Ecore_Con_Client; + +/** + * @typedef Ecore_Con_Socks + * @brief The structure type containing an object representing a SOCKS proxy. * - * A simple example of how to use these functions: - * @li @ref ecore_con_lookup_example_c + * @since 1.2 * - * @{ + * @ingroup Ecore_Con_Socks_Group */ +typedef struct Ecore_Con_Socks Ecore_Con_Socks; /** - * @typedef Ecore_Con_Type - * @enum _Ecore_Con_Type - * Types for an ecore_con client/server object. A correct way to set this type is - * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired, - * and LOAD_CERT if the previously loaded certificate should be used. - * @code - * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT - * @endcode - * @ingroup Ecore_Con_Server_Group + * @typedef Ecore_Con_Url + * @brief The structure type containing a handle to an HTTP upload/download object. + * @ingroup Ecore_Con_Url_Group */ -typedef enum _Ecore_Con_Type -{ - /** Socket in ~/.ecore */ - ECORE_CON_LOCAL_USER = 0, - /** Socket in /tmp */ - ECORE_CON_LOCAL_SYSTEM = 1, - /** Abstract socket */ - ECORE_CON_LOCAL_ABSTRACT = 2, - /** Remote server using TCP */ - ECORE_CON_REMOTE_TCP = 3, - /** Remote multicast server */ - ECORE_CON_REMOTE_MCAST = 4, - /** Remote server using UDP */ - ECORE_CON_REMOTE_UDP = 5, - /** Remote broadcast using UDP */ - ECORE_CON_REMOTE_BROADCAST = 6, - /** Remote connection sending packets immediately */ - ECORE_CON_REMOTE_NODELAY = 7, - /** Remote connection sending data in large chunks - * @note Only available on Linux - * @since 1.2 - */ - ECORE_CON_REMOTE_CORK = 8, - /** Use SSL2: UNSUPPORTED. **/ - ECORE_CON_USE_SSL2 = (1 << 4), - /** Use SSL3 */ - ECORE_CON_USE_SSL3 = (1 << 5), - /** Use TLS */ - ECORE_CON_USE_TLS = (1 << 6), - /** Use both TLS and SSL3 */ - ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS, - /** Attempt to use the loaded certificate */ - ECORE_CON_LOAD_CERT = (1 << 7), - /** Disable all types of proxy on the server - * @note Only functional for clients - * @since 1.2 - */ - ECORE_CON_NO_PROXY = (1 << 8), - ECORE_CON_SOCKET_ACTIVATE = (1 << 9) -} Ecore_Con_Type; - -/** @} */ +typedef struct _Ecore_Con_Url Ecore_Con_Url; -#ifndef EFL_NOLEGACY_API_SUPPORT -#include "Ecore_Con_Legacy.h" -#endif -#ifdef EFL_EO_API_SUPPORT -#include "Ecore_Con_Eo.h" -#endif /** + * @internal * @addtogroup Ecore_Con_Events_Group + * * @{ */ /** * @typedef Ecore_Con_Event_Client_Add - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event */ typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add; /** * @typedef Ecore_Con_Event_Client_Upgrade - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Client_Upgrade Ecore_Con_Event_Client_Upgrade; /** * @typedef Ecore_Con_Event_Client_Del - * Used as the @p data param for the corresponding event + * @brief The structure type containing a connection used as the @a data param for the corresponding event. */ typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del; /** * @typedef Ecore_Con_Event_Client_Error - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error; /** * @typedef Ecore_Con_Event_Server_Add - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. */ typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add; /** * @typedef Ecore_Con_Event_Server_Upgrade - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Server_Upgrade Ecore_Con_Event_Server_Upgrade; /** * @typedef Ecore_Con_Event_Server_Del - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. */ typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del; /** * @typedef Ecore_Con_Event_Server_Error - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error; /** * @typedef Ecore_Con_Event_Client_Data - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. */ typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data; /** * @typedef Ecore_Con_Event_Server_Data - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. */ typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data; /** * @typedef Ecore_Con_Event_Client_Write - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Client_Write Ecore_Con_Event_Client_Write; /** * @typedef Ecore_Con_Event_Server_Write - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.1 */ typedef struct _Ecore_Con_Event_Server_Write Ecore_Con_Event_Server_Write; /** * @typedef Ecore_Con_Event_Proxy_Bind - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @since 1.2 */ typedef struct _Ecore_Con_Event_Proxy_Bind Ecore_Con_Event_Proxy_Bind; /** * @typedef Ecore_Con_Event_Url_Data - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @ingroup Ecore_Con_Url_Group */ typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data; /** * @typedef Ecore_Con_Event_Url_Complete - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @ingroup Ecore_Con_Url_Group */ typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete; /** * @typedef Ecore_Con_Event_Url_Progress - * Used as the @p data param for the corresponding event + * @brief The structure type used as the @a data param for the corresponding event. * @ingroup Ecore_Con_Url_Group */ typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress; /** + * @internal * @struct _Ecore_Con_Event_Client_Add - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event. */ struct _Ecore_Con_Event_Client_Add { - Ecore_Con_Client *client; /**< the client that connected */ + Ecore_Con_Client *client; /** the client that connected */ }; /** + * @internal * @struct _Ecore_Con_Event_Client_Upgrade - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event. * @since 1.1 */ struct _Ecore_Con_Event_Client_Upgrade { - Ecore_Con_Client *client; /**< the client that completed handshake */ + Ecore_Con_Client *client; /** The client that completed handshake */ }; /** + * @internal * @struct _Ecore_Con_Event_Client_Del - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event. */ struct _Ecore_Con_Event_Client_Del { - Ecore_Con_Client *client; /**< the client that was lost */ + Ecore_Con_Client *client; /** The client that was lost */ }; /** + * @internal * @struct _Ecore_Con_Event_Client_Error - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event. */ struct _Ecore_Con_Event_Client_Error { - Ecore_Con_Client *client; /**< the client for which an error occurred */ - char *error; /**< the error string describing what happened */ + Ecore_Con_Client *client; /** The client for which an error occurred */ + char *error; /**< The error string describing what happened */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Add - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ADD event. */ struct _Ecore_Con_Event_Server_Add { - Ecore_Con_Server *server; /**< the server that was connected to */ + Ecore_Con_Server *server; /** The server that is connected to */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Upgrade - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event. * @since 1.1 */ struct _Ecore_Con_Event_Server_Upgrade { - Ecore_Con_Server *server; /**< the server that was connected to */ + Ecore_Con_Server *server; /** The server that is connected to */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Del - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DEL event. */ struct _Ecore_Con_Event_Server_Del { - Ecore_Con_Server *server; /**< the client that was lost */ + Ecore_Con_Server *server; /** The client that is lost */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Error - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event. */ struct _Ecore_Con_Event_Server_Error { - Ecore_Con_Server *server; /**< the server for which an error occurred */ - char *error; /**< the error string describing what happened */ + Ecore_Con_Server *server; /** The server for which an error occurred */ + char *error; /**< The error string describing what happened */ }; /** + * @internal * @struct _Ecore_Con_Event_Client_Data - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event. */ struct _Ecore_Con_Event_Client_Data { - Ecore_Con_Client *client; /**< the client that connected */ - void *data; /**< the data that the client sent */ - int size; /**< the length of the data sent */ + Ecore_Con_Client *client; /**< The client that connected */ + void *data; /**< The data that the client sent */ + int size; /**< The length of the data sent */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Data - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DATA event. */ struct _Ecore_Con_Event_Server_Data { - Ecore_Con_Server *server; /**< the server that was connected to */ - void *data; /**< the data that the server sent */ - int size; /**< the length of the data sent */ + Ecore_Con_Server *server; /**< The server that is connected to */ + void *data; /**< The data that the server sent */ + int size; /**< The length of the data sent */ }; /** + * @internal * @struct _Ecore_Con_Event_Client_Write - * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event. */ struct _Ecore_Con_Event_Client_Write { - Ecore_Con_Client *client; /**< the client that connected */ - int size; /**< the length of the data sent */ + Ecore_Con_Client *client; /**< The client that connected */ + int size; /**< The length of the data sent */ }; /** + * @internal * @struct _Ecore_Con_Event_Server_Write - * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event. */ struct _Ecore_Con_Event_Server_Write { - Ecore_Con_Server *server; /**< the server that was connected to */ - int size; /**< the length of the data sent */ + Ecore_Con_Server *server; /**< The server that is connected to */ + int size; /**< The length of the data sent */ }; /** + * @internal * @struct _Ecore_Con_Event_Proxy_Bind - * Used as the @p data param for the @ref ECORE_CON_EVENT_PROXY_BIND event - * @ingroup Ecore_Con_Socks_Group + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_PROXY_BIND event. + * * @since 1.2 + * @ingroup Ecore_Con_Socks_Group */ struct _Ecore_Con_Event_Proxy_Bind { - Ecore_Con_Server *server; /**< the server object connected to the proxy */ - const char *ip; /**< the proxy-bound ip address */ - int port; /**< the proxy-bound port */ + Ecore_Con_Server *server; /**< The server object connected to the proxy */ + const char *ip; /**< The proxy-bound ip address */ + int port; /**< The proxy-bound port */ }; /** + * @internal * @struct _Ecore_Con_Event_Url_Data - * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_DATA event. * @ingroup Ecore_Con_Url_Group */ struct _Ecore_Con_Event_Url_Data { - Ecore_Con_Url *url_con; /**< a pointer to the connection object */ - int size; /**< the size of the current received data (in bytes) */ - unsigned char data[1]; /**< the data received on this event */ + Ecore_Con_Url *url_con; /**< A pointer to the connection object */ + int size; /**< The size of the current received data (in bytes) */ + unsigned char data[1]; /**< The data received on this event */ }; /** + * @internal * @struct _Ecore_Con_Event_Url_Complete - * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event. * @ingroup Ecore_Con_Url_Group */ struct _Ecore_Con_Event_Url_Complete { - Ecore_Con_Url *url_con; /**< a pointer to the connection object */ + Ecore_Con_Url *url_con; /**< A pointer to the connection object */ int status; /**< HTTP status code of the operation (200, 404, 401, etc.) */ }; /** + * @internal * @struct _Ecore_Con_Event_Url_Progress - * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event + * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event. * @ingroup Ecore_Con_Url_Group */ struct _Ecore_Con_Event_Url_Progress { - Ecore_Con_Url *url_con; /**< a pointer to the connection object */ + Ecore_Con_Url *url_con; /**< A pointer to the connection object */ struct { - double total; /**< total size of the downloading data (in bytes) */ - double now; /**< current size of the downloading data (in bytes) */ - } down; /**< download info */ + double total; /**< Total size of the downloading data (in bytes) */ + double now; /**< Current size of the downloading data (in bytes) */ + } down; /**< Download info */ struct { - double total; /**< total size of the uploading data (in bytes) */ - double now; /**< current size of the uploading data (in bytes) */ - } up; /**< upload info */ + double total; /**< Total size of the uploading data (in bytes) */ + double now; /**< Current size of the uploading data (in bytes) */ + } up; /**< Upload info */ }; /** A client has connected to the server */ @@ -606,9 +573,9 @@ EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR; * @since 1.1 */ EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE; -/** A server was created */ +/** A server is created */ EAPI extern int ECORE_CON_EVENT_SERVER_ADD; -/** A server connection was lost */ +/** A server connection is lost */ EAPI extern int ECORE_CON_EVENT_SERVER_DEL; /** A server experienced an error * @since 1.1 @@ -646,36 +613,127 @@ EAPI extern int ECORE_CON_EVENT_URL_PROGRESS; */ /** - * @addtogroup Ecore_Con_Events_Group Ecore_Con_Lib_Group + * @internal + * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions * @ingroup Ecore_Con_Group * + * @brief This group provides utility functions that set up and shut down the Ecore Connection + * library. + * + * There is also ecore_con_lookup() that can be used to make simple asynchronous + * DNS lookups. + * * @{ */ /** - * Initialises the Ecore_Con library. - * @return Number of times the library has been initialised without being - * shut down. + * @typedef Ecore_Con_Dns_Cb + * A callback type for use with @ref ecore_con_lookup. + */ +typedef void (*Ecore_Con_Dns_Cb)(const char *canonname, + const char *ip, + struct sockaddr *addr, + int addrlen, + void *data); + +/** + * @typedef Ecore_Con_Type + * @enum _Ecore_Con_Type + * @brief Enumeration of the types for an ecore_con client/server object. A correct way to set this type is + * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired, + * and LOAD_CERT if the previously loaded certificate should be used. + * @code + * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT + * @endcode + * @ingroup Ecore_Con_Server_Group + */ +typedef enum _Ecore_Con_Type +{ + /** Socket in ~/.ecore */ + ECORE_CON_LOCAL_USER = 0, + /** Socket in /tmp */ + ECORE_CON_LOCAL_SYSTEM = 1, + /** Abstract socket */ + ECORE_CON_LOCAL_ABSTRACT = 2, + /** Remote server using TCP */ + ECORE_CON_REMOTE_TCP = 3, + /** Remote multicast server */ + ECORE_CON_REMOTE_MCAST = 4, + /** Remote server using UDP */ + ECORE_CON_REMOTE_UDP = 5, + /** Remote broadcast using UDP */ + ECORE_CON_REMOTE_BROADCAST = 6, + /** Remote connection sending packets immediately */ + ECORE_CON_REMOTE_NODELAY = 7, + /** Remote connection sending data in large chunks + * @note Only available on Linux + * @since 1.2 + */ + ECORE_CON_REMOTE_CORK = 8, + /** Use SSL2: UNSUPPORTED. **/ + ECORE_CON_USE_SSL2 = (1 << 4), + /** Use SSL3 */ + ECORE_CON_USE_SSL3 = (1 << 5), + /** Use TLS */ + ECORE_CON_USE_TLS = (1 << 6), + /** Use both TLS and SSL3 */ + ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS, + /** Attempt to use the loaded certificate */ + ECORE_CON_LOAD_CERT = (1 << 7), + /** Disable all types of proxy on the server + * @note Only functional for clients + * @since 1.2 + */ + ECORE_CON_NO_PROXY = (1 << 8) +} Ecore_Con_Type; + +/** + * @brief Initialises the Ecore_Con library. * - * @note This function already calls ecore_init() internally, so you don't need - * to call it explicitly. + * @remarks This function already calls ecore_init() internally. So you do not need + * to call it explicitly. + * @return The number of times the library has been initialised without being shut down */ EAPI int ecore_con_init(void); /** - * Shuts down the Ecore_Con library. - * @return Number of times the library has been initialised without being - * shut down. - * @note This function already calls ecore_shutdown() internally, so you don't - * need to call it explicitly unless you called ecore_init() explicitly too. + * @brief Shuts down the Ecore_Con library. + * + * @remarks This function already calls ecore_shutdown() internally. So you do not + * need to call it explicitly unless you called ecore_init() explicitly too. + * + * @return The number of times the library has been initialised without being shut down */ EAPI int ecore_con_shutdown(void); /** + * @brief Does an asynchronous DNS lookup. + * + * @details This function performs a DNS lookup on the hostname specified by @a name, + * then calls @a done_cb with the result and the @a data given as parameter. + * The result is given to the @a done_cb as follows: + * @li @c canonname - the canonical name of the address + * @li @c ip - the resolved IP address + * @li @c addr - a pointer to the socket address + * @li @c addrlen - the length of the socket address, in bytes + * @li @c data - the data pointer given as parameter to ecore_con_lookup() + * + * @param[in] name The IP address or server name to translate + * @param[in] done_cb The callback to notify when done + * @param[in] data The user data to be given to done_cb + * @return @c EINA_TRUE if the request did not fail to be set up, \n + * otherwise @c EINA_FALSE if it failed + */ +EAPI Eina_Bool ecore_con_lookup(const char *name, + Ecore_Con_Dns_Cb done_cb, + const void *data); + +/** * @} */ /** + * @internal * @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions * @ingroup Ecore_Con_Group * @@ -713,18 +771,19 @@ EAPI void ecore_con_socks_apply_once(Ecore_Con_Socks *ecs); EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs); /** + * @internal * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions * @ingroup Ecore_Con_Group * - * This group of functions is applied to an @ref Ecore_Con_Server object. It - * doesn't mean that they should be used in the server application, but on the - * server object. In fact, most of them should be used in the client - * application, when retrieving information or sending data. + * @brief This group of functions is applied to an @ref Ecore_Con_Server object. It + * does not mean that they should be used in the server application, but on the + * server object. In fact, most of them should be used in the client + * application, when retrieving information or sending data. * * Setting up a server is very simple: you just need to start it with * ecore_con_server_add() and setup some callbacks to the events * @ref ECORE_CON_EVENT_CLIENT_ADD, @ref ECORE_CON_EVENT_CLIENT_DEL and - * @ref ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is + * @ref ECORE_CON_EVENT_CLIENT_DATA, that is called when a client is * communicating with the server: * * @code @@ -739,7 +798,7 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs); * @endcode * * The function ecore_con_server_connect() can be used to write a client that - * connects to a server. The resulting code will be very similar to the server + * connects to a server. The resulting code is very similar to the server * code: * * @code @@ -754,180 +813,194 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs); * @endcode * * After these two pieces of code are executed, respectively, in the server and - * client code, the server will be up and running and the client will try to + * client code, the server is up and running and the client tries to * connect to it. The connection, with its subsequent messages being sent from * server to client and client to server, can be represented in the following * sequence diagram: * * @htmlonly - * <img src="ecore_con-client-server.png" style="max-width: 400px"/> * <a href="ecore_con-client-server.png">Full size</a> * @endhtmlonly * + * @image html ecore_con-client-server.png * @image rtf ecore_con-client-server.png - * @image latex ecore_con-client-server.eps width=\textwidth + * @image latex ecore_con-client-server.eps "ecore con client server" width=\textwidth * - * Please notice the important difference between these two codes: the first is + * Note the important difference between these two codes: the first is * used for writing a @b server, while the second should be used for writing a * @b client. * * A reference for the @c client functions can be found at @ref * Ecore_Con_Client_Group. * - * Examples of usage for this API can be found here: - * @li @ref ecore_con_server_simple_example_c - * @li @ref ecore_con_client_simple_example_c - * * @{ */ /** - * Creates a server to listen for connections. + * @brief Creates a server to listen for connections. * - * @param type The connection type. - * @param name Name to associate with the socket. It is used when - * generating the socket name of a Unix socket, or for - * determining what host to listen on for TCP sockets. - * @c NULL will not be accepted. - * @param port Number to identify socket. When a Unix socket is used, - * it becomes part of the socket name. When a TCP socket - * is used, it is used as the TCP port. - * @param data Data to associate with the created Ecore_Con_Server - * object. - * @return A new Ecore_Con_Server. + * @remarks The socket on which the server listens depends on the connection type: + * @li If @a type is @c ECORE_CON_LOCAL_USER, the server listens on + * the Unix socket "~/.ecore/[name]/[port]". + * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server listens + * on Unix socket "/tmp/.ecore_service|[name]|[port]". + * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server listens + * on TCP port @c port. * - * The socket on which the server listens depends on the connection - * type: - * @li If @a type is @c ECORE_CON_LOCAL_USER, the server will listen on - * the Unix socket "~/.ecore/[name]/[port]". - * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen - * on Unix socket "/tmp/.ecore_service|[name]|[port]". - * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server will listen - * on TCP port @c port. + * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type. * - * More information about the @p type can be found at @ref _Ecore_Con_Type. + * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get() + * or changed with ecore_con_server_data_set(). * - * The @p data parameter can be fetched later using ecore_con_server_data_get() - * or changed with ecore_con_server_data_set(). + * @param[in] type The connection type + * @param[in] name The name to associate with the socket \n + * It is used when generating the socket name of a Unix socket, or for + * determining what host to listen on for TCP sockets. + * @c NULL is not accepted. + * @param[in] port The number to identify socket \n + * When a Unix socket is used, it becomes part of the socket name. + * When a TCP socket is used, it is used as the TCP port. + * @param[in] data The data to associate with the created Ecore_Con_Server object + * @return A new Ecore_Con_Server */ EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type, const char *name, int port, const void *data); /** - * Creates a connection to the specified server and returns an associated object. + * @brief Creates a connection to the specified server and returns an associated object. * - * @param type The connection type. - * @param name Name used when determining what socket to connect to. - * It is used to generate the socket name when the socket - * is a Unix socket. It is used as the hostname when - * connecting with a TCP socket. - * @param port Number to identify the socket to connect to. Used when - * generating the socket name for a Unix socket, or as the - * TCP port when connecting to a TCP socket. - * @param data Data to associate with the created Ecore_Con_Server - * object. - * @return A new Ecore_Con_Server. + * @remarks The socket to which the connection is made depends on the connection type: + * @li If @a type is @c ECORE_CON_LOCAL_USER, the function + * connects to the server at the Unix socket + * "~/.ecore/[name]/[port]". + * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function + * connects to the server at the Unix socket + * "/tmp/.ecore_service|[name]|[port]". + * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function + * connects to the server at the TCP port "[name]:[port]". * - * The socket to which the connection is made depends on the connection type: - * @li If @a type is @c ECORE_CON_LOCAL_USER, the function will - * connect to the server at the Unix socket - * "~/.ecore/[name]/[port]". - * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function will - * connect to the server at the Unix socket - * "/tmp/.ecore_service|[name]|[port]". - * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function will - * connect to the server at the TCP port "[name]:[port]". + * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type. * - * More information about the @p type can be found at @ref _Ecore_Con_Type. + * @remarks This function does not block. It either succeeds, or fails due to invalid + * parameters, failed memory allocation, etc., returning @c NULL in that case. * - * This function won't block. It will either succeed, or fail due to invalid - * parameters, failed memory allocation, etc., returning @c NULL on that case. + * @remarks However, even if this call returns a valid @ref Ecore_Con_Server, the + * connection is only successfully completed if an event of type + * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an + * @ref ECORE_CON_EVENT_SERVER_DEL is received. * - * However, even if this call returns a valid @ref Ecore_Con_Server, the - * connection will only be successfully completed if an event of type - * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an - * @ref ECORE_CON_EVENT_SERVER_DEL will be received. + * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get() + * or changed with ecore_con_server_data_set(). * - * The @p data parameter can be fetched later using ecore_con_server_data_get() - * or changed with ecore_con_server_data_set(). + * @param[in] type The connection type + * @param[in] name The name used when determining what socket to connect to \n + * It is used to generate the socket name when the socket + * is a Unix socket. It is used as the hostname when + * connecting with a TCP socket. + * @param[in] port The number to identify the socket to connect to \n + * It is used when generating the socket name for a Unix socket, + * or as the TCP port when connecting to a TCP socket. + * @param[in] data The data to associate with the created Ecore_Con_Server object + * @return A new Ecore_Con_Server */ EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type, const char *name, int port, const void *data); /** - * Closes the connection and frees the given server. + * @brief Closes the connection and frees the given server. * - * @param svr The given server. - * @return Data associated with the server when it was created. + * @remarks All the clients connected to this server is disconnected. * - * All the clients connected to this server will be disconnected. + * @param[in] svr The given server + * @return The data associated with the server when it is created * * @see ecore_con_server_add, ecore_con_server_connect */ EAPI void * ecore_con_server_del(Ecore_Con_Server *svr); /** - * Retrieves the data associated with the given server. + * @brief Gets the data associated with the given server. * - * @param svr The given server. - * @return The associated data. + * @param[in] svr The given server + * @return The associated data * * @see ecore_con_server_data_set() */ EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr); /** - * Sets the data associated with the given server. + * @brief Sets the data associated with the given server. * - * @param svr The given server. - * @param data The data to associate with @p svr - * @return The previously associated data, if any. + * @param[in] svr The given server + * @param[in] data The data to associate with @a svr + * @return The previously associated data, if any * * @see ecore_con_server_data_get() */ EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr, void *data); /** - * Retrieves whether the given server is currently connected. + * @brief Checks whether the given server is currently connected. + * + * @param[in] svr The given server + * @return @c EINA_TRUE if the server is connected, \n + * otherwise @c EINA_FALSE if the server is not connected + */ +EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr); +/** + * @brief Gets the current list of clients. + * + * @remarks Each node in the returned list points to an @ref Ecore_Con_Client. This list + * cannot be modified or freed. It can also change if new clients are connected + * or disconnected, and becomes invalid when the server is deleted or freed. + * + * @param[in] svr The given server + * @return The list of clients on this server + */ +EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr); + +/** + * @brief Gets the name of server. + * + * @remarks The name returned is the name used to connect on this server. * - * @param svr The given server. - * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise. + * @param[in] svr The given server + * @return The name of the server */ -EAPI Eina_Bool ecore_con_server_connected_get(const Ecore_Con_Server *svr); +EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr); /** - * Retrieves the server port in use. + * @brief Gets the server port in use. * - * @param svr The given server. - * @return The server port in use. + * @remarks The port where the server is listening for connections. * - * The port where the server is listening for connections. + * @param[in] svr The given server + * @return The server port in use */ -EAPI int ecore_con_server_port_get(const Ecore_Con_Server *svr); +EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr); /** - * @brief Check how long a server has been connected + * @brief Checks how long a server has been connected. * - * @param svr The server to check - * @return The total time, in seconds, that the server has been - * connected/running + * @details This function is used to find out the time that has been elapsed since + * ecore_con_server_add() succeeded. * - * This function is used to find out the time that has been elapsed since - * ecore_con_server_add() succeeded. + * @param[in] svr The server to check + * @return The total time, in seconds, that the server has been connected or running */ -EAPI double ecore_con_server_uptime_get(const Ecore_Con_Server *svr); +EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr); /** - * Sends the given data to the given server. + * @brief Sends the given data to the given server. * - * @param svr The given server. - * @param data The given data. - * @param size Length of the data, in bytes, to send. - * @return The number of bytes sent. @c 0 will be returned if there is an - * error. + * @details This function sends the given data to the server as soon as the program + * is back to the main loop. Thus, this function returns immediately + * (non-blocking). If the data needs to be sent @b now, call + * ecore_con_server_flush() after this one. * - * This function will send the given data to the server as soon as the program - * is back to the main loop. Thus, this function returns immediately - * (non-blocking). If the data needs to be sent @b now, call - * ecore_con_server_flush() after this one. + * @param[in] svr The given server + * @param[in] data The given data + * @param[in] size The length of the data, in bytes, to send + * @return The number of bytes sent, \n + * otherwise @c 0 if there is an error * * @see ecore_con_client_send() * @see ecore_con_server_flush() @@ -936,120 +1009,121 @@ EAPI int ecore_con_server_send(Ecore_Con_Server *svr, const void *data, int size); /** - * Sets a limit on the number of clients that can be handled concurrently - * by the given server, and a policy on what to do if excess clients try to - * connect. - * - * @param svr The given server. - * @param client_limit The maximum number of clients to handle - * concurrently. -1 means unlimited (default). 0 - * effectively disables the server. - * @param reject_excess_clients Set to 1 to automatically disconnect - * excess clients as soon as they connect if you are - * already handling client_limit clients. Set to 0 - * (default) to just hold off on the "accept()" - * system call until the number of active clients - * drops. This causes the kernel to queue up to 4096 - * connections (or your kernel's limit, whichever is - * lower). - * - * Beware that if you set this once ecore is already running, you may - * already have pending CLIENT_ADD events in your event queue. Those - * clients have already connected and will not be affected by this call. - * Only clients subsequently trying to connect will be affected. + * @brief Sets a limit on the number of clients that can be handled concurrently + * by the given server, and a policy on what to do if excess clients try to + * connect. + * + * @remarks Beware that if you set this once, ecore is already running. You may + * already have pending CLIENT_ADD events in your event queue. Those + * clients have already connected and is not affected by this call. + * Only clients subsequently trying to connect is affected. + * + * @param[in] svr The given server + * @param[in] client_limit The maximum number of clients to handle concurrently \n + * @c -1 means unlimited (default), @c 0 effectively disables the server. + * @param[in] reject_excess_clients Set to @c 1 to automatically disconnect excess clients + * as soon as they connect if you are already handling client_limit clients \n + * otherwise set to @c 0 (default) to just hold off on the "accept()" + * system call until the number of active clients drops \n + * This causes the kernel to queue up to 4096 + * connections (or your kernel's limit, whichever is lower). */ EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr, int client_limit, char reject_excess_clients); /** - * Gets the IP address of a server that has been connected to. + * @brief Gets the IP address of a server that has been connected to. * - * @param svr The given server. + * @param[in] svr The given server * @return A pointer to an internal string that contains the IP address of - * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation. + * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation \n * This string should not be modified or trusted to stay valid after - * deletion for the @p svr object. If no IP is known @c NULL is - * returned. + * deletion for the @a svr object. If no IP is known, @c NULL is returned. */ -EAPI const char * ecore_con_server_ip_get(const Ecore_Con_Server *svr); +EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr); /** - * Flushes all pending data to the given server. + * @brief Flushes all pending data to the given server. * - * @param svr The given server. + * @details This function blocks until all data is sent to the server. * - * This function will block until all data is sent to the server. + * @param[in] svr The given server * * @see ecore_con_server_send() * @see ecore_con_client_flush() */ EAPI void ecore_con_server_flush(Ecore_Con_Server *svr); /** - * Set the default time after which an inactive client will be disconnected + * @brief Sets the default time after which an inactive client is disconnected. * - * @param svr The server object - * @param timeout The timeout, in seconds, to disconnect after + * @details This function is used by the server to set the default idle timeout on + * clients. If the any of the clients becomes idle for a time higher than this + * value, it is disconnected. A value of < @c 1 disables the idle timeout. * - * This function is used by the server to set the default idle timeout on - * clients. If the any of the clients becomes idle for a time higher than this - * value, it will be disconnected. A value of < 1 disables the idle timeout. + * @remarks This timeout is not affected by the one set by + * ecore_con_client_timeout_set(). A client is disconnected whenever the + * client or the server timeout is reached. That means, the lower timeout value + * is used for that client if ecore_con_client_timeout_set() is used on it. * - * This timeout is not affected by the one set by - * ecore_con_client_timeout_set(). A client will be disconnected whenever the - * client or the server timeout is reached. That means, the lower timeout value - * will be used for that client if ecore_con_client_timeout_set() is used on it. + * @param[in] svr The server object + * @param[in] timeout The timeout, in seconds, to disconnect after * * @see ecore_con_server_timeout_get() * @see ecore_con_client_timeout_set() */ EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout); /** - * Get the default time after which an inactive client will be disconnected + * @brief Gets the default time after which an inactive client is disconnected. * - * @param svr The server object - * @return The timeout, in seconds, to disconnect after + * @details This function is used to get the idle timeout for clients. A value of < @c 1 + * means the idle timeout is disabled. * - * This function is used to get the idle timeout for clients. A value of < 1 - * means the idle timeout is disabled. + * @param[in] svr The server object + * @return The timeout, in seconds, to disconnect after * * @see ecore_con_server_timeout_set() * @see ecore_con_client_timeout_get() */ -EAPI double ecore_con_server_timeout_get(const Ecore_Con_Server *svr); +EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr); /** - * Get the fd that the server is connected to + * @brief Get the fd that the server is connected to. * - * @param svr The server object - * @return The fd, or -1 on failure + * @details This function returns the fd which is used by the underlying server connection. + * It should not be tampered with unless you REALLY know what you are doing. + * @since 1.1 * - * This function returns the fd which is used by the underlying server connection. - * It should not be tampered with unless you REALLY know what you are doing. - * @note This function is only valid for servers created with ecore_con_server_connect() - * @warning Seriously. Don't use this unless you know what you are doing. - * @since 1.1 + * @remarks This function is only valid for servers created with ecore_con_server_connect() + * @remarks Do not use this unless you know what you are doing. + * + * @param[in] svr The server object + * @return The fd, \n + * otherwise @c -1 on failure */ -EAPI int ecore_con_server_fd_get(const Ecore_Con_Server *svr); +EAPI int ecore_con_server_fd_get(Ecore_Con_Server *svr); /** - * Get the fd that the client is connected to + * @brief Gets the fd that the client is connected to. * - * @param cl The client object - * @return The fd, or -1 on failure + * @details This function returns the fd which is used by the underlying client connection. + * It should not be tampered with unless you REALLY know what you are doing. + * + * @since 1.1 * - * This function returns the fd which is used by the underlying client connection. - * It should not be tampered with unless you REALLY know what you are doing. - * @since 1.1 + * @param[in] cl The client object + * @return The fd, \n + * otherwise @c -1 on failure */ -EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl); +EAPI int ecore_con_client_fd_get(Ecore_Con_Client *cl); /** * @} */ /** + * @internal * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions * @ingroup Ecore_Con_Group * - * Functions to communicate with and/or set options on a client. + * @brief This group provides functions to communicate with and/or set options on a client. * * This set of functions, as explained in @ref Ecore_Con_Server_Group, is used * to send data to a client, or to set options and get information about this @@ -1059,25 +1133,22 @@ EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl); * If you need to implement a client, the way to connect to a server is * described in @ref Ecore_Con_Server_Group. * - * An example of usage of these functions can be found at: - * @li @ref ecore_con_client_simple_example_c - * * @{ */ /** - * Sends the given data to the given client. + * @brief Sends the given data to the given client. * - * @param cl The given client. - * @param data The given data. - * @param size Length of the data, in bytes, to send. - * @return The number of bytes sent. @c 0 will be returned if there is an - * error. + * @details This function sends the given data to the client as soon as the program + * is back to the main loop. Thus, this function returns immediately + * (non-blocking). If the data needs to be sent @b now, call + * ecore_con_client_flush() after this one. * - * This function will send the given data to the client as soon as the program - * is back to the main loop. Thus, this function returns immediately - * (non-blocking). If the data needs to be sent @b now, call - * ecore_con_client_flush() after this one. + * @param[in] cl The given client + * @param[in] data The given data + * @param[in] size The length of the data, in bytes, to send + * @return The number of bytes sent, \n + * otherwise @c 0 if there is an error * * @see ecore_con_server_send() * @see ecore_con_client_flush() @@ -1086,126 +1157,139 @@ EAPI int ecore_con_client_send(Ecore_Con_Client *cl, const void *data, int size); /** - * Closes the connection and frees memory allocated to the given client. + * @brief Gets the server representing the socket the client has connected to. * - * @param cl The given client. - * @return Data associated with the client. + * @param[in] cl The given client + * @return The server that the client connected to + */ +EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl); + +/** + * @brief Closes the connection and frees the memory allocated to the given client. + * + * @param[in] cl The given client + * @return The data associated with the client */ EAPI void * ecore_con_client_del(Ecore_Con_Client *cl); + /** - * Sets the data associated with the given client to @p data. + * @brief Sets the data associated with the given client to @a data. * - * @param cl The given client. - * @param data What to set the data to. + * @param[in] cl The given client + * @param[in] data The data to set */ EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data); /** - * Retrieves the data associated with the given client. + * @brief Gets the data associated with the given client. * - * @param cl The given client. - * @return The data associated with @p cl. + * @param[in] cl The given client + * @return The data associated with @a cl */ EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl); /** - * Gets the IP address of a client that has connected. + * @brief Gets the IP address of a client that has connected. * - * @param cl The given client. - * @return A pointer to an internal string that contains the IP address of - * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation. + * @remarks The returned string should not be modified, freed or trusted to stay valid + * after deletion for the @a cl object. If no IP is known @c NULL is returned. * - * The returned string should not be modified, freed or trusted to stay valid - * after deletion for the @p cl object. If no IP is known @c NULL is returned. + * @param[in] cl The given client + * @return A pointer to an internal string that contains the IP address of + * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation */ -EAPI const char * ecore_con_client_ip_get(const Ecore_Con_Client *cl); +EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl); + /** - * Flushes all pending data to the given client. + * @brief Flushes all pending data to the given client. * - * @param cl The given client. + * @details This function blocks until all data is sent to the server. * - * This function will block until all data is sent to the server. + * @param[in] cl The given client * * @see ecore_con_client_send() * @see ecore_con_server_flush() */ EAPI void ecore_con_client_flush(Ecore_Con_Client *cl); + /** - * @brief Check how long a client has been connected + * @brief Checks how long a client has been connected. * - * @param cl The client to check - * @return The total time, in seconds, that the client has been connected to - * the server + * @details This function is used to find out how long a client has been connected for. * - * This function is used to find out how long a client has been connected for. + * @param[in] cl The client to check + * @return The total time, in seconds, that the client has been connected to the server */ -EAPI double ecore_con_client_uptime_get(const Ecore_Con_Client *cl); +EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl); + /** - * Get the default time after which the client will be disconnected when - * inactive + * @brief Gets the default time after which the client is disconnected when inactive. * - * @param cl The client object - * @return The timeout, in seconds, to disconnect after + * @details This function is used to get the idle timeout for a client. A value of < @c 1 + * means the idle timeout is disabled. * - * This function is used to get the idle timeout for a client. A value of < 1 - * means the idle timeout is disabled. + * @param[in] cl The client object + * @return The timeout, in seconds, to disconnect after * * @see ecore_con_client_timeout_set() */ -EAPI double ecore_con_client_timeout_get(const Ecore_Con_Client *cl); +EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl); + /** - * Set the time after which the client will be disconnected when inactive + * @brief Sets the time after which the client is disconnected when inactive. * - * @param cl The client object - * @param timeout The timeout, in seconds, to disconnect after + * @details This function is used by the server to set the idle timeout on a specific + * client. If the client becomes idle for a time higher than this value, it is + * disconnected. A value of < @c 1 disables the idle timeout. * - * This function is used by the server to set the idle timeout on a specific - * client. If the client becomes idle for a time higher than this value, it will - * be disconnected. A value of < 1 disables the idle timeout. + * @details This timeout is not affected by the one set by + * ecore_con_server_timeout_set(). A client is disconnected whenever the + * client or the server timeout is reached. That means, the lower timeout value + * is used for that client if ecore_con_server_timeout_set() is used on the server. * - * This timeout is not affected by the one set by - * ecore_con_server_timeout_set(). A client will be disconnected whenever the - * client or the server timeout is reached. That means, the lower timeout value - * will be used for that client if ecore_con_server_timeout_set() is used on the - * server. + * @param[in] cl The client object + * @param[in] timeout The timeout, in seconds, to disconnect after * * @see ecore_con_client_timeout_get() * @see ecore_con_server_timeout_set() */ EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout); + /** - * Returns whether the client is still connected + * @brief Checks whether the client is still connected. * - * @param cl The given client. - * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise. + * @param[in] cl The given client + * @return @c EINA_TRUE if connected, \n + * otherwise @c EINA_FALSE if it is not connected */ -EAPI Eina_Bool ecore_con_client_connected_get(const Ecore_Con_Client *cl); +EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl); /** - * @brief Return the port that the client has connected to + * @brief Gets the port that the client has connected to. * - * @param cl The client - * @return The port that @p cl has connected to, or -1 on error - * Use this function to return the port on which a given client has connected. + * @remarks Use this function to return the port on which a given client has connected. + * + * @param[in] cl The client + * @return The port that @a cl has connected to, \n + * otherwise @c -1 on error */ -EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl); - - +EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl); /** * @} */ /** + * @internal * @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions * @ingroup Ecore_Con_Group * - * Utility functions that set up, use and shut down the Ecore URL - * Connection library. + * @brief This group provides utility functions that set up, use and shut down the Ecore URL + * Connection library. * - * These functions are a shortcut to make it easy to perform http requests + * These functions are shortcuts to make it easy to perform HTTP requests * (POST, GET, etc). * - * Brief usage: + * Brief usage details: * 1. Create an Ecore_Con_Url object with ecore_con_url_new(url); * 2. Register to receive the #ECORE_CON_EVENT_URL_COMPLETE event * (and optionally the #ECORE_CON_EVENT_URL_DATA and @@ -1218,7 +1302,7 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl); * need to wait for the #ECORE_CON_EVENT_URL_COMPLETE event before re-using or * destroying the object. * - * If it's necessary to change the @ref Ecore_Con_Url object url, use + * If it is necessary to change the @ref Ecore_Con_Url object url, use * ecore_con_url_url_set(). * * Simple Usage 1 (HTTP GET): @@ -1253,18 +1337,14 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl); * ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir"); * @endcode * - * These are complete examples for the API: - * @li @ref ecore_con_url_download_example.c "Downloading a file" - * @li @ref ecore_con_url_headers_example.c "Setting many options for the connection" - * * @{ */ /** * @typedef Ecore_Con_Url_Time * @enum _Ecore_Con_Url_Time - * The type of condition to use when making an HTTP request dependent on time, - * so that headers such as "If-Modified-Since" are used. + * @brief Enumeration for the type of condition to use when making an HTTP request dependent on time, + * so that headers such as "If-Modified-Since" are used. */ typedef enum _Ecore_Con_Url_Time { @@ -1289,7 +1369,7 @@ typedef enum _Ecore_Con_Url_Time /** * @typedef Ecore_Con_Url_Http_Version * @enum _Ecore_Con_Url_Http_Version - * The http version to use + * @brief Enumeration of the HTTP version to use. * @since 1.2 */ typedef enum _Ecore_Con_Url_Http_Version @@ -1307,84 +1387,87 @@ typedef enum _Ecore_Con_Url_Http_Version } Ecore_Con_Url_Http_Version; /** - * Change the HTTP version used for the request - * @param url_con Connection object through which the request will be sent. - * @param version The version to be used - * @return @c EINA_TRUE on success, @c EINA_FALSE on failure to change version. - * @since 1.2 + * @brief Changes the HTTP version used for the request. + * @since 1.2 + * + * @param[in] url_con The connection object through which the request is sent + * @param[in] version The version to be used + * @return @c EINA_TRUE if the version is changed successfully, \n + * otherwise @c EINA_FALSE on failure to change version * @see ecore_con_url_pipeline_get() */ EAPI Eina_Bool ecore_con_url_http_version_set(Ecore_Con_Url *url_con, Ecore_Con_Url_Http_Version version); - + /** - * Initialises the Ecore_Con_Url library. - * @return Number of times the library has been initialised without being - * shut down. + * @brief Initialises the Ecore_Con_Url library. * - * @note This function doesn't call ecore_con_init(). You still need to call it - * explicitly before calling this one. + * @remarks This function does not call ecore_con_init(). You still need to call it + * explicitly before calling this one. + * @return The number of times the library has been initialised without being shut down */ EAPI int ecore_con_url_init(void); /** - * Shuts down the Ecore_Con_Url library. - * @return Number of calls that still uses Ecore_Con_Url + * @brief Shuts down the Ecore_Con_Url library. * - * @note This function doesn't call ecore_con_shutdown(). You still need to call - * it explicitly after calling this one. + * @remarks This function does not call ecore_con_shutdown(). You still need to call + * it explicitly after calling this one. + * @return The number of calls that still uses Ecore_Con_Url */ EAPI int ecore_con_url_shutdown(void); /** - * Enable or disable HTTP 1.1 pipelining. - * @param enable @c EINA_TRUE will turn it on, @c EINA_FALSE will disable it. + * @brief Enables or disables HTTP 1.1 pipelining. * - * Pipelining allows to send one request after another one, without having to - * wait for the reply of the first request. The respective replies are received - * in the order that the requests were sent. + * @remarks Pipelining allows to send one request after another one, without having to + * wait for the reply of the first request. The respective replies are received + * in the order that the requests were sent. * - * Enabling this feature will be valid for all requests done using @c - * ecore_con_url. + * @remarks Enabling this feature is valid for all requests done using @c ecore_con_url. * - * See http://en.wikipedia.org/wiki/HTTP_pipelining for more info. + * @remarks See http://en.wikipedia.org/wiki/HTTP_pipelining for more info. * + * @param[in] enable Set @c EINA_TRUE to turn it on, \n + * otherwise @c EINA_FALSE to disable it * @see ecore_con_url_pipeline_get() */ EAPI void ecore_con_url_pipeline_set(Eina_Bool enable); /** - * Is HTTP 1.1 pipelining enable ? - * @return @c EINA_TRUE if it is enable. + * @brief Checks whether HTTP 1.1 pipelining is enabled. + * + * @return @c EINA_TRUE if it is enabled, \n + * otherwise @c EINA_FALSE if it is not enabled * * @see ecore_con_url_pipeline_set() */ EAPI Eina_Bool ecore_con_url_pipeline_get(void); /** - * Creates and initializes a new Ecore_Con_Url connection object. + * @brief Creates and initializes a new Ecore_Con_Url connection object. * - * @param url URL that will receive requests. Can be changed using - * ecore_con_url_url_set. + * @details This function creates and initializes a new Ecore_Con_Url connection object that can be + * used for sending requests. * - * @return @c NULL on error, a new Ecore_Con_Url on success. - * - * Creates and initializes a new Ecore_Con_Url connection object that can be - * used for sending requests. + * @param[in] url The URL that receives requests \n + * This can be changed using ecore_con_url_url_set. + * @return A new Ecore_Con_Url, \n + * otherwise @c NULL on error * * @see ecore_con_url_custom_new() * @see ecore_con_url_url_set() */ EAPI Ecore_Con_Url * ecore_con_url_new(const char *url); /** - * Creates a custom connection object. - * - * @param url URL that will receive requests - * @param custom_request Custom request (e.g. GET, POST, HEAD, PUT, etc) + * @brief Creates a custom connection object. * - * @return @c NULL on error, a new Ecore_Con_Url on success. + * @details This function creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD, + * SUBSCRIBE and other obscure HTTP requests). This object should be used like + * the one created with ecore_con_url_new(). * - * Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD, - * SUBSCRIBE and other obscure HTTP requests). This object should be used like - * one created with ecore_con_url_new(). + * @param[in] url The URL that receives requests + * @param[in] custom_request The custom request (e.g. GET, POST, HEAD, PUT, etc) + * @return A new Ecore_Con_Url, \n + * otherwise @c NULL on error * * @see ecore_con_url_new() * @see ecore_con_url_url_set() @@ -1392,52 +1475,74 @@ EAPI Ecore_Con_Url * ecore_con_url_new(const char *url); EAPI Ecore_Con_Url * ecore_con_url_custom_new(const char *url, const char *custom_request); /** - * Destroys a Ecore_Con_Url connection object. + * @brief Destroys an Ecore_Con_Url connection object. * - * @param url_con Connection object to free. + * @param[in] url_con The connection object to free * * @see ecore_con_url_new() */ EAPI void ecore_con_url_free(Ecore_Con_Url *url_con); /** - * Associates data with a connection object. + * @brief Sets the URL to send the request to. + * + * @param[in] url_con The connection object through which the request is sent + * @param[in] url The URL that receives the request + * + * @return @c EINA_TRUE if the URL is set successfully, \n + * otherwise @c EINA_FALSE on error + */ +EAPI Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con, + const char *url); +/** + * @brief Gets the URL to send the request to. + * @since 1.1 + * + * @param[in] url_con The connection object through which the request is sent + * @return The URL that receives the request, \n + * otherwise @c NULL on failure \n + * URL is stringshared. + */ +EAPI const char *ecore_con_url_url_get(Ecore_Con_Url *url_con); + +/** + * @brief Associates data with a connection object. * - * @param url_con Connection object to associate data. - * @param data Data to be set. + * @remarks Associates data with a connection object, which can be retrieved later with + * ecore_con_url_data_get()). * - * Associates data with a connection object, which can be retrieved later with - * ecore_con_url_data_get()). + * @param[in] url_con The connection object to associate data + * @param[in] data The data to be set * * @see ecore_con_url_data_get() */ EAPI void ecore_con_url_data_set(Ecore_Con_Url *url_con, void *data); /** - * Retrieves data associated with a Ecore_Con_Url connection object. + * @brief Gets data associated with a Ecore_Con_Url connection object. * - * @param url_con Connection object to retrieve data from. + * @details This function gets data associated with a Ecore_Con_Url connection object (previously + * set with ecore_con_url_data_set()). * - * @return Data associated with the given object. - * - * Retrieves data associated with a Ecore_Con_Url connection object (previously - * set with ecore_con_url_data_set()). + * @param[in] url_con The connection object to retrieve data from + * @return The data associated with the given object * * @see ecore_con_url_data_set() */ EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con); + /** - * Adds an additional header to the request connection object. + * @brief Adds an additional header to the request connection object. * - * @param url_con Connection object - * @param key Header key - * @param value Header value + * @details This function adds an additional header (User-Agent, Content-Type, etc.) to the request + * connection object. This addition is valid for only one + * ecore_con_url_get() or ecore_con_url_post() call. * - * Adds an additional header (User-Agent, Content-Type, etc.) to the request - * connection object. This addition will be valid for only one - * ecore_con_url_get() or ecore_con_url_post() call. + * @remarks Some functions like ecore_con_url_time() also add headers to the request. * - * Some functions like ecore_con_url_time() also add headers to the request. + * @param[in] url_con The connection object + * @param[in] key The header key + * @param[in] value The header value * * @see ecore_con_url_get() * @see ecore_con_url_post() @@ -1446,88 +1551,92 @@ EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con); EAPI void ecore_con_url_additional_header_add(Ecore_Con_Url *url_con, const char *key, const char *value); + /** - * Cleans additional headers. + * @brief Cleans additional headers. * - * @param url_con Connection object to clean additional headers. + * @details This function cleans additional headers associated with a connection object (previously + * added with ecore_con_url_additional_header_add()). * - * Cleans additional headers associated with a connection object (previously - * added with ecore_con_url_additional_header_add()). + * @param[in] url_con The connection object to clean additional headers * * @see ecore_con_url_additional_header_add() * @see ecore_con_url_get() * @see ecore_con_url_post() */ EAPI void ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con); + /** - * Retrieves headers from last request sent. + * @brief Gets headers from last request sent. * - * @param url_con Connection object to retrieve response headers from. + * @details This function retrieves a list containing the response headers. This function should be + * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be + * ready at that time). * - * Retrieves a list containing the response headers. This function should be - * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be - * ready at that time). - * - * @return List of response headers. This list must not be modified by the user. + * @param[in] url_con The connection object to retrieve response headers from + * @return The list of response headers \n + * This list must not be modified by the user. */ EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con); + /** - * Setup a file for receiving response data. + * @brief Sets up a file for receiving response data. * - * @param url_con Connection object to set file - * @param fd File descriptor associated with the file. A negative value will - * unset any previously set fd. + * @details This function sets up a file to have response data written into. Note that + * ECORE_CON_EVENT_URL_DATA events are not emitted if a file has been set to + * receive the response data. * - * Sets up a file to have response data written into. Note that - * ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to - * receive the response data. + * @remarks This function can be used to easily setup a file where the downloaded data + * is saved. * - * This call can be used to easily setup a file where the downloaded data will - * be saved. + * @param[in] url_con The connection object to set file + * @param[in] fd The file descriptor associated with the file \n + * A negative value unsets any previously set @a fd. */ EAPI void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd); + /** - * Retrieves the number of bytes received. - * - * Retrieves the number of bytes received on the last request of the given - * connection object. + * @brief Gets the number of bytes received. * - * @param url_con Connection object which the request was sent on. + * @details This function retrieves the number of bytes received on the last request of the given + * connection object. * - * @return Number of bytes received on request. + * @param[in] url_con The connection object which the request is sent on + * @return The number of bytes received on request * * @see ecore_con_url_get() * @see ecore_con_url_post() */ EAPI int ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con); + /** - * Sets url_con to use http auth, with given username and password, "safely" or not. - * - * @param url_con Connection object to perform a request on, previously created - * with ecore_con_url_new() or ecore_con_url_custom_new(). - * @param username Username to use in authentication - * @param password Password to use in authentication - * @param safe Whether to use "safer" methods (eg, NOT http basic auth) + * @brief Sets @a url_con to use http auth, with the given @a username and @a password, "safely" or not. * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. + * @remarks This function requires libcurl >= 7.19.1 to work. Otherwise it always returns @c 0. * - * @attention Requires libcurl >= 7.19.1 to work, otherwise will always return - * @c 0. + * @param[in] url_con The connection object to perform a request on, previously created + * with ecore_con_url_new() or ecore_con_url_custom_new(). + * @param[in] username The username to use in authentication + * @param[in] password The password to use in authentication + * @param[in] safe Set @c EINA_TRUE to use "safer" methods (eg, NOT http basic auth), \n + * otherwise set @c EINA_FALSE to not use it + * @return @c EINA_TRUE if it is set successfully, + * otherwise @c EINA_FALSE on error */ EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con, const char *username, const char *password, Eina_Bool safe); /** - * Sends a get request. + * @brief Sends a get request. * - * @param url_con Connection object to perform a request on, previously created + * @remarks The request is performed immediately, but you need to setup event handlers + * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or + * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result. * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. - * - * The request is performed immediately, but you need to setup event handlers - * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or - * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result. + * @param[in] url_con The connection object to perform a request on, previously created + * @return @c EINA_TRUE if the request is sent successfully, \n + * otherwise @c EINA_FALSE on error * * @see ecore_con_url_custom_new() * @see ecore_con_url_additional_headers_clear() @@ -1539,24 +1648,27 @@ EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con, * @see ecore_con_url_post() */ EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con); + /** - * Sends a post request. + * @brief Sends a post request. * - * @param url_con Connection object to perform a request on, previously created - * with ecore_con_url_new() or ecore_con_url_custom_new(). - * @param data Payload (data sent on the request). Can be @c NULL. - * @param length Payload length. If @c -1, rely on automatic length - * calculation via @c strlen() on @p data. - * @param content_type Content type of the payload (e.g. text/xml). Can be @c - * NULL. + * @remarks The request starts immediately, but you need to setup event handlers + * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or + * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result. * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. + * @remarks This call does not block your main loop. * - * The request starts immediately, but you need to setup event handlers - * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or - * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result. - * - * This call won't block your main loop. + * @param[in] url_con The connection object to perform a request on, previously created + * with ecore_con_url_new() or ecore_con_url_custom_new(). + * @param[in] data The payload (data sent on the request) \n + * This can be @c NULL. + * @param[in] length The payload length \n + * If this is @c -1, it relies on automatic length + * calculation via @c strlen() on @a data. + * @param[in] content_type The content type of the payload (e.g. text/xml) \n + * This can be @c NULL. + * @return @c EINA_TRUE if the request is sent successfully, + * otherwise @c EINA_FALSE on error * * @see ecore_con_url_custom_new() * @see ecore_con_url_additional_headers_clear() @@ -1570,37 +1682,39 @@ EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con); EAPI Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con, const void *data, long length, const char *content_type); + /** - * Sets whether HTTP requests should be conditional, dependent on - * modification time. + * @brief Sets whether HTTP requests should be conditional, dependent on + * modification time. * - * @param url_con Ecore_Con_Url to act upon. - * @param time_condition Condition to use for HTTP requests. - * @param timestamp Time since 1 Jan 1970 to use in the condition. + * @details This function may set the header "If-Modified-Since" or + * "If-Unmodified-Since", depending on the value of @a time_condition, with the + * value @a timestamp. * - * This function may set the header "If-Modified-Since" or - * "If-Unmodified-Since", depending on the value of @p time_condition, with the - * value @p timestamp. + * @param[in] url_con The Ecore_Con_Url to act upon + * @param[in] time_condition The condition to use for HTTP requests + * @param[in] timestamp The time since 1 Jan 1970 to use in the condition * - * @sa ecore_con_url_get() - * @sa ecore_con_url_post() + * @see ecore_con_url_get() + * @see ecore_con_url_post() */ EAPI void ecore_con_url_time(Ecore_Con_Url *url_con, Ecore_Con_Url_Time time_condition, double timestamp); /** - * @brief Uploads a file to an ftp site. + * @brief Uploads a file to an FTP site. * - * @param url_con The Ecore_Con_Url object to send with - * @param filename The path to the file to send - * @param user The username to log in with - * @param pass The password to log in with - * @param upload_dir The directory to which the file should be uploaded - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * @remarks Upload @a filename to an FTP server set in @a url_con using @a user + * and @a pass to directory @a upload_dir * - * Upload @p filename to an ftp server set in @p url_con using @p user - * and @p pass to directory @p upload_dir + * @param[in] url_con The Ecore_Con_Url object to send with + * @param[in] filename The path to the file to send + * @param[in] user The username to log in with + * @param[in] pass The password to log in with + * @param[in] upload_dir The directory to which the file should be uploaded + * @return @c EINA_TRUE if the file is uploaded successfully, \n + * otherwise @c EINA_FALSE on error */ EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con, const char *filename, @@ -1608,173 +1722,178 @@ EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con, const char *pass, const char *upload_dir); /** - * Toggle libcurl's verbose output. + * @brief Toggles libcurl's verbose output. * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param verbose Whether or not to enable libcurl's verbose output. + * @remarks If @a verbose is @c EINA_TRUE, libcurl outputs a lot of verbose + * information about its operations, which is useful for + * debugging. The verbose information is sent to stderr. * - * If @p verbose is @c EINA_TRUE, libcurl will output a lot of verbose - * information about its operations, which is useful for - * debugging. The verbose information will be sent to stderr. + * @param[in] url_con The Ecore_Con_Url instance which is acted upon + * @param[in] verbose Set @c EINA_TRUE to enable libcurl's verbose output, \n + * otherwise @c EINA_FALSE to disable verbose output */ EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con, Eina_Bool verbose); + /** - * Enable or disable EPSV extension - * @param url_con The Ecore_Con_Url instance which will be acted upon. - * @param use_epsv Boolean to enable/disable the EPSV extension. + * @brief Enables or disables EPSV extension. + * + * @param[in] url_con The Ecore_Con_Url instance which is acted upon + * @param[in] use_epsv Set @c EINA_TRUE to enable the EPSV extension, \n + * otherwise @c EINA_FALSE to disable it */ EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con, Eina_Bool use_epsv); /** - * Enables the cookie engine for subsequent HTTP requests. + * @brief Enables the cookie engine for subsequent HTTP requests. * - * @param url_con Ecore_Con_Url instance which will be acted upon. + * @remarks After this function is called, cookies set by the server in HTTP responses + * are parsed and stored, as well as sent back to the server in new HTTP requests. * - * After this function is called, cookies set by the server in HTTP responses - * will be parsed and stored, as well as sent back to the server in new HTTP - * requests. + * @remarks Even though this function is called @c ecore_con_url_cookies_init(), + * there is no symmetrical shutdown operation. * - * @note Even though this function is called @c ecore_con_url_cookies_init(), - * there is no symmetrical shutdown operation. + * @param[in] url_con The Ecore_Con_Url instance which is acted upon */ EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con); + /** - * Controls whether session cookies from previous sessions shall be loaded. + * @brief Sets whether session cookies from previous sessions shall be loaded. * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies - * from files. If @c EINA_FALSE, all cookies will be loaded. + * @remarks Session cookies are cookies with no expire date set, which usually means + * they are removed after the current session is closed. * - * Session cookies are cookies with no expire date set, which usually means - * they are removed after the current session is closed. + * @remarks By default, when Ecore_Con_Url loads cookies from a file, all cookies are + * loaded, including session cookies, which, most of the time, were supposed + * to be loaded and valid only for that session. * - * By default, when Ecore_Con_Url loads cookies from a file, all cookies are - * loaded, including session cookies, which, most of the time, were supposed - * to be loaded and valid only for that session. + * @remarks If @a ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from + * the files passed to @c ecore_con_url_cookies_file_add(), session cookies + * are not loaded. * - * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from - * the files passed to @c ecore_con_url_cookies_file_add(), session cookies - * will not be loaded. + * @param[in] url_con The Ecore_Con_Url instance which is acted upon + * @param[in] ignore Set @c EINA_TRUE to ignore session cookies when loading cookies from files, \n + * otherwise set @c EINA_FALSE to load all cookies * * @see ecore_con_url_cookies_file_add() */ EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con, Eina_Bool ignore); + /** - * Clears currently loaded cookies. - * @param url_con Ecore_Con_Url instance which will be acted upon. + * @brief Clears currently loaded cookies. * - * The cleared cookies are removed and will not be sent in subsequent HTTP - * requests, nor will they be written to the cookiejar file set via - * @c ecore_con_url_cookies_jar_file_set(). + * @remarks The cleared cookies are removed and not sent in subsequent HTTP + * requests, nor are they written to the cookiejar file set using + * @c ecore_con_url_cookies_jar_file_set(). * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded - * immediately, just when the request is started. Thus, if you ask to - * clear the cookies, but has a file already set by that function, the - * cookies will then be loaded and you will have old cookies set. In order - * to don't have any old cookie set, you need to don't call - * ecore_con_url_cookies_file_add() ever on the @p url_con handler, and - * call this function to clear any cookie set by a previous request on - * this handler. + * @remarks This function initializes the cookie engine if it has not been + * initialized yet. + * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded + * immediately, just when the request is started. Thus, if you ask to + * clear the cookies, but has a file already set by that function, the + * cookies are then loaded and you have old cookies set. In order + * to not have any old cookie set, you need to not call + * ecore_con_url_cookies_file_add() ever on the @a url_con handler, and + * call this function to clear any cookie set by a previous request on + * this handler. + * + * @param[in] url_con The Ecore_Con_Url instance which are acted upon * * @see ecore_con_url_cookies_session_clear() * @see ecore_con_url_cookies_ignore_old_session_set() */ EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con); + /** - * Clears currently loaded session cookies. + * @brief Clears currently loaded session cookies. * - * @param url_con Ecore_Con_Url instance which will be acted upon. + * @remarks Session cookies are cookies with no expire date set, which usually means + * they are removed after the current session is closed. * - * Session cookies are cookies with no expire date set, which usually means - * they are removed after the current session is closed. + * @remarks The cleared cookies are removed and not sent in subsequent HTTP + * requests, nor are they be written to the cookiejar file set using + * @c ecore_con_url_cookies_jar_file_set(). * - * The cleared cookies are removed and will not be sent in subsequent HTTP - * requests, nor will they be written to the cookiejar file set via - * @c ecore_con_url_cookies_jar_file_set(). + * @remarks This function initializes the cookie engine if it has not been + * initialized yet. + * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded + * immediately, just when the request is started. Thus, if you ask to + * clear the session cookies, but has a file already set by that function, + * the session cookies are then loaded and you have old cookies + * set. In order to not have any old session cookie set, you need to + * not call ecore_con_url_cookies_file_add() ever on the @a url_con + * handler, and call this function to clear any session cookie set by a + * previous request on this handler. An easier way to not use old + * session cookies is by using the function + * ecore_con_url_cookies_ignore_old_session_set(). * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded - * immediately, just when the request is started. Thus, if you ask to - * clear the session cookies, but has a file already set by that function, - * the session cookies will then be loaded and you will have old cookies - * set. In order to don't have any old session cookie set, you need to - * don't call ecore_con_url_cookies_file_add() ever on the @p url_con - * handler, and call this function to clear any session cookie set by a - * previous request on this handler. An easier way to don't use old - * session cookies is by using the function - * ecore_con_url_cookies_ignore_old_session_set(). + * @param[in] url_con The Ecore_Con_Url instance which are acted upon * * @see ecore_con_url_cookies_clear() * @see ecore_con_url_cookies_ignore_old_session_set() */ EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con); + /** - * Adds a file to the list of files from which to load cookies. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param file_name Name of the file that will be added to the list. + * @brief Adds a file to the list of files from which to load cookies. * - * Files must contain cookies defined according to two possible formats: + * @remarks The files must contain cookies defined according to two possible formats: + * @li HTTP-style header ("Set-Cookie: ..."). + * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a> * - * @li HTTP-style header ("Set-Cookie: ..."). - * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a> + * @remarks Cookies are only @b read from this file. If you want to save cookies to a + * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this + * function supports the both types of cookie file cited above, while + * ecore_con_url_cookies_jar_file_set() saves only in the Netscape/Mozilla's format. * - * Cookies will only be @b read from this file. If you want to save cookies to a - * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this - * function supports the both types of cookie file cited above, while - * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's - * format. + * @remarks Please notice that the file is not read immediately, but rather added + * to a list of files that is loaded and parsed at a later time. * - * Please notice that the file will not be read immediately, but rather added - * to a list of files that will be loaded and parsed at a later time. + * @remarks This function initializes the cookie engine if it has not been + * initialized yet. * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. + * @param[in] url_con The Ecore_Con_Url instance which is acted upon + * @param[in] file_name The name of the file that is added to the list * * @see ecore_con_url_cookies_ignore_old_session_set() * @see ecore_con_url_cookies_jar_file_set() */ EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con, const char * const file_name); + /** - * Sets the name of the file to which all current cookies will be written when - * either cookies are flushed or Ecore_Con is shut down. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param cookiejar_file File to which the cookies will be written. + * @brief Sets the name of the file to which all current cookies are written when + * either cookies are flushed or Ecore_Con is shut down. * - * @return @c EINA_TRUE is the file name has been set successfully, - * @c EINA_FALSE otherwise. + * @remarks Cookies are written following Netscape/Mozilla's data format, also known as + * cookie-jar. * - * Cookies are written following Netscape/Mozilla's data format, also known as - * cookie-jar. + * @remarks Cookies are only @b saved to this file. If you need to read cookies from + * a file, use ecore_con_url_cookies_file_add() instead. * - * Cookies will only be @b saved to this file. If you need to read cookies from - * a file, use ecore_con_url_cookies_file_add() instead. + * @remarks This function initializes the cookie engine if it has not been initialized yet. * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. + * @param[in] url_con The Ecore_Con_Url instance which are acted upon + * @param[in] cookiejar_file The file to which the cookies are written + * @return @c EINA_TRUE is the file name has been set successfully, \n + * otherwise @c EINA_FALSE on failure * * @see ecore_con_url_cookies_jar_write() */ EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con, const char * const cookiejar_file); + /** - * Writes all current cookies to the cookie jar immediately. + * @brief Writes all current cookies to the cookie jar immediately. * - * @param url_con Ecore_Con_Url instance which will be acted upon. + * @remarks A cookie-jar file must have been previously set by + * ecore_con_url_jar_file_set(), otherwise nothing is done. * - * A cookie-jar file must have been previously set by - * @c ecore_con_url_jar_file_set, otherwise nothing will be done. + * @remarks This function initializes the cookie engine if it has not been initialized yet. * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. + * @param[in] url_con The Ecore_Con_Url instance which is acted upon * * @see ecore_con_url_cookies_jar_file_set() */ @@ -1786,81 +1905,86 @@ EAPI int ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con, const char *ca_path); /** - * Set HTTP proxy to use. - * - * The parameter should be a char * to a zero terminated string holding - * the host name or dotted IP address. To specify port number in this string, - * append :[port] to the end of the host name. - * The proxy string may be prefixed with [protocol]:// since any such prefix - * will be ignored. - * The proxy's port number may optionally be specified with the separate option. - * If not specified, libcurl will default to using port 1080 for proxies. + * @brief Sets the HTTP proxy to use. + * @since 1.2 * - * @param url_con Connection object that will use the proxy. - * @param proxy Porxy string or @c NULL to disable + * @remarks The parameter should be a char * to a zero terminated string holding + * the host name or dotted IP address. To specify port number in this string, + * append :[port] to the end of the host name. + * The proxy string may be prefixed with [protocol]:// since any such prefix + * is ignored. + * The proxy's port number may optionally be specified with the separate option. + * If not specified, libcurl defaults to using port 1080 for proxies. * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. - * @since 1.2 + * @param[in] url_con The connection object that uses the proxy + * @param[in] proxy The proxy string, \n + * otherwise set @c NULL to disable + * @return @c EINA_TRUE if the proxy is set successfully, + * otherwise @c EINA_FALSE on error */ EAPI Eina_Bool ecore_con_url_proxy_set(Ecore_Con_Url *url_con, const char *proxy); /** - * Set zero terminated username to use for proxy. + * @brief Sets zero terminated username to use for proxy. + * @since 1.2 * - * if socks protocol is used for proxy, protocol should be socks5 and above. + * @remarks If socks protocol is used for proxy, protocol should be socks5 and above. * - * @param url_con Connection object that will use the proxy. - * @param username Username string. + * @param[in] url_con The connection object that uses the proxy + * @param[in] username The username string * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. + * @return @c EINA_TRUE if the username is set successfully, \n + * otherwise @c EINA_FALSE on error * * @see ecore_con_url_proxy_set() * - * @since 1.2 */ EAPI Eina_Bool ecore_con_url_proxy_username_set(Ecore_Con_Url *url_con, const char *username); /** - * Set zero terminated password to use for proxy. + * @brief Sets zero terminated password to use for proxy. + * @since 1.2 * - * if socks protocol is used for proxy, protocol should be socks5 and above. + * @remarks If socks protocol is used for proxy, protocol should be socks5 and above. * - * @param url_con Connection object that will use the proxy. - * @param password Password string. + * @param[in] url_con The connection object that uses the proxy + * @param[in] password The password string * - * @return @c EINA_TRUE on success, @c EINA_FALSE on error. + * @return @c EINA_TRUE if the password is set successfully, \n + * otherwise @c EINA_FALSE on error * * @see ecore_con_url_proxy_set() * - * @since 1.2 */ EAPI Eina_Bool ecore_con_url_proxy_password_set(Ecore_Con_Url *url_con, const char *password); /** - * Set timeout in seconds. + * @brief Sets timeout in seconds. * - * the maximum time in seconds that you allow the ecore con url transfer - * operation to take. Normally, name lookups can take a considerable time - * and limiting operations to less than a few minutes risk aborting perfectly - * normal operations. + * @since 1.2 * - * @param url_con Connection object that will use the timeout. - * @param timeout time in seconds. + * @remarks The maximum time in seconds that you allow the ecore_con_url_transfer + * operation to take. Normally, name lookups can take a considerable time + * and limiting operations to less than a few minutes risk aborting perfectly + * normal operations. * - * @see ecore_con_url_cookies_jar_file_set() + * @param[in] url_con The connection object that uses the timeout + * @param[in] timeout The time in seconds * - * @since 1.2 + * @see ecore_con_url_cookies_jar_file_set() */ EAPI void ecore_con_url_timeout_set(Ecore_Con_Url *url_con, double timeout); /** - * Get the returned HTTP STATUS code + * @brief Gets the returned HTTP STATUS code. + * @since 1.2 * - * This is used to, at any time, try to return the status code for a transmission. - * @param url_con Connection object - * @return A valid HTTP STATUS code, or 0 on failure + * @remarks This is used to try to return the status code for a transmission. + * + * @param[in] url_con The connection object + * @return A valid HTTP STATUS code, \n + * otherwise @c 0 on failure * - * @since 1.2 */ EAPI int ecore_con_url_status_code_get(Ecore_Con_Url *url_con); /** diff --git a/src/lib/ecore_con/Ecore_Con_Eet.h b/src/lib/ecore_con/Ecore_Con_Eet.h index a6c52bd328..bdf0d2d605 100644 --- a/src/lib/ecore_con/Ecore_Con_Eet.h +++ b/src/lib/ecore_con/Ecore_Con_Eet.h @@ -31,254 +31,43 @@ # endif #endif -/** - * @defgroup Ecore_Con_Eet_Group Eet connection functions - * @ingroup Ecore_Con_Group - * - * The Ecore Connection Eet library ( @c Ecore_Con_Eet) adds @c Eet data - * serialization features to Ecore Connection objects. Its main aim is to - * provide a way to send @c Eet data streams to another program through sockets - * using @c Ecore_Con objects. - * - * @{ - */ - typedef struct _Ecore_Con_Eet Ecore_Con_Eet; typedef struct _Ecore_Con_Reply Ecore_Con_Reply; -/** - * @typedef Ecore_Con_Eet_Data_Cb - * @brief Called when an Ecore_Con_Eet object receives data. - */ typedef void (*Ecore_Con_Eet_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, void *value); - -/** - * @typedef Ecore_Con_Eet_Raw_Data_Cb - * @brief Called when an Ecore_Con_Eet object receives raw data. - */ typedef void (*Ecore_Con_Eet_Raw_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, size_t length); - -/** - * @typedef Ecore_Con_Eet_Client_Cb - * @brief Called when a client connects to the server. - */ typedef Eina_Bool (*Ecore_Con_Eet_Client_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Client *conn); - -/** - * @typedef Ecore_Con_Eet_Server_Cb - * @brief Called when the server has accepted the connection of the client. - */ typedef Eina_Bool (*Ecore_Con_Eet_Server_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Server *conn); -/** - * Create a Ecore_Con_Eet server. - * - * @param server An existing Ecore_Con_Server that have been previously - * created by the server program with @ref - * ecore_con_server_add. - * - * @return A new Ecore_Con_Eet server. - */ EAPI Ecore_Con_Eet *ecore_con_eet_server_new(Ecore_Con_Server *server); - -/** - * Create a Ecore_Con_Eet client. - * - * @param server An existing Ecore_Con_Server that have been previously - * returned by a call to @ref ecore_con_server_connect in the - * client program. - * - * @return A new Ecore_Con_Eet client. - */ EAPI Ecore_Con_Eet *ecore_con_eet_client_new(Ecore_Con_Server *server); - -/** - * Free an existing Ecore_Con_Eet object. - * - * @param server An existing Ecore_Con_Eet object that have been previously - * allocated by a @ref ecore_con_eet_server_new or @ref - * ecore_con_eet_client_new. - * - */ EAPI void ecore_con_eet_server_free(Ecore_Con_Eet *ece); -/** - * Register an @c Eet data descriptor on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param name The name of the Eet stream to connect. - * @param edd A Eet data descriptor that describes the data organization - * in the Eet stream. - * - */ EAPI void ecore_con_eet_register(Ecore_Con_Eet *ece, const char *name, Eet_Data_Descriptor *edd); -/** - * Register a data callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param name The name of the Eet stream to connect. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - * - */ EAPI void ecore_con_eet_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Data_Cb func, const void *data); - -/** - * Remove a data callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param name The name of the Eet stream to remove callback on. - * - */ EAPI void ecore_con_eet_data_callback_del(Ecore_Con_Eet *ece, const char *name); -/** - * Register a raw data callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param name The name of the raw Eet stream to connect. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - * - */ EAPI void ecore_con_eet_raw_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Raw_Data_Cb func, const void *data); - -/** - * Remove a raw data callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param name The name of the raw Eet stream to remove callback on. - * - */ EAPI void ecore_con_eet_raw_data_callback_del(Ecore_Con_Eet *ece, const char *name); -/** - * Register a client connect callback on a Ecore_Con_Eet object. - * @brief This callback can be registered on the server program to know when a - * client connects. - * - * @param ece An Ecore_Con_Eet object. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - */ EAPI void ecore_con_eet_client_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); - -/** - * Remove a client connect callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param func The callback to remove. - * @param data The data passed to this function at the callback registration. - */ EAPI void ecore_con_eet_client_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); -/** - * Register a client disconnect callback on a Ecore_Con_Eet object. - * @brief This callback can be registered on the server program to know when a - * client disconnects. - * - * @param ece An Ecore_Con_Eet object. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - */ EAPI void ecore_con_eet_client_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); - -/** - * Remove a client disconnect callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param func The callback to remove. - * @param data The data passed to this function at the callback registration. - */ EAPI void ecore_con_eet_client_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); -/** - * Register a server connect callback on a Ecore_Con_Eet object. - * @brief This callback can be registered on the client program to be called - * when it has been connected to the server. - * - * @param ece An Ecore_Con_Eet object. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - */ EAPI void ecore_con_eet_server_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); - -/** - * Remove a server connect callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param func The callback to remove. - * @param data The data passed to this function at the callback registration. - */ EAPI void ecore_con_eet_server_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); -/** - * Register a server disconnect callback on a Ecore_Con_Eet object. - * @brief This callback can be registered on the client program to be called - * when it has been disconnected from the server. - * - * @param ece An Ecore_Con_Eet object. - * @param func The function to call as a callback. - * @param data The data to pass to the callback. - */ EAPI void ecore_con_eet_server_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); - -/** - * Remove a server disconnect callback on a Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param func The callback to remove. - * @param data The data passed to this function at the callback registration. - */ EAPI void ecore_con_eet_server_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); -/** - * Attach data to an Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @param data The data to attach to the Ecore_Con_Eet object. - */ EAPI void ecore_con_eet_data_set(Ecore_Con_Eet *ece, const void *data); - -/** - * Get the data attached to an Ecore_Con_Eet object. - * - * @param ece An Ecore_Con_Eet object. - * @return The data attached to the Ecore_Con_Eet object. - */ EAPI void *ecore_con_eet_data_get(Ecore_Con_Eet *ece); -/** - * Get the Ecore_Con_Eet object corresponding to the Ecore_Con_Reply object. - * - * @param reply An Ecore_Con_Reply object. - * @return The corresponding Ecore_Con_Eet object. - */ EAPI Ecore_Con_Eet *ecore_con_eet_reply(Ecore_Con_Reply *reply); - -/** - * Send some data using a protocol type. - * - * @param reply An Ecore_Con_Reply object. - * @param protocol_name The protocol type to use. - * @param value The data to send. - */ EAPI void ecore_con_eet_send(Ecore_Con_Reply *reply, const char *protocol_name, void *value); - -/** - * Send some raw data using a protocol type. - * - * @param reply An Ecore_Con_Reply object. - * @param protocol_name The protocol type to use. - * @param section The section to add to the protocol. - * @param value The data to send. - * @param length The data length. - */ EAPI void ecore_con_eet_raw_send(Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, unsigned int length); -/** - * @} - */ - #endif diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h index 82186e3035..d933203c92 100644..100755 --- a/src/lib/ecore_evas/Ecore_Evas.h +++ b/src/lib/ecore_evas/Ecore_Evas.h @@ -2,7 +2,8 @@ #define _ECORE_EVAS_H #include <Evas.h> -#include <Ecore_Evas_Types.h> +#include <Ecore_Getopt.h> +#include <Ecore_Input.h> #ifdef EAPI # undef EAPI @@ -31,16 +32,9 @@ #endif /* ! _WIN32 */ /** + * @internal * @file Ecore_Evas.h * @brief Evas wrapper functions - * - * The following is a list of example that partially exemplify Ecore_Evas's API: - * @li @ref ecore_evas_callbacks_example_c - * @li @ref ecore_evas_object_example_c - * @li @ref ecore_evas_basics_example_c - * @li @ref Ecore_Evas_Window_Sizes_Example_c - * @li @ref Ecore_Evas_Buffer_Example_01_c - * @li @ref Ecore_Evas_Buffer_Example_02_c */ /* FIXME: @@ -60,13 +54,14 @@ extern "C" { #endif /** + * @internal * @defgroup Ecore_Evas_Group Ecore_Evas wrapper/helper set of functions - * @ingroup Ecore + * @ingroup Ecore_Group * * Ecore evas is a set of functions that makes it easy to tie together ecore's - * main loop and input handling to evas. As such it's a natural base for EFL + * main loop and input handling to evas. As such it is a natural base for EFL * applications. While this combination makes it easy to create the basic - * aspects all applications need, for normal applications(ones with buttons, + * aspects all applications need, for normal applications (ones with buttons, * checkboxes and layouts) one should consider using Elementary. * * Ecore evas is extremely well suited for applications that are not based on @@ -75,35 +70,25 @@ extern "C" { * in conjunction with Edje or if doing custom drawing as, for example, is done * in games. * - * This is a list of examples of these functions: - * @li @ref ecore_evas_basics_example_c - * @li @ref ecore_evas_object_example_c - * @li @ref ecore_evas_callbacks_example_c - * @li @ref Ecore_Evas_Window_Sizes_Example_c - * @li @ref Ecore_Evas_Buffer_Example_01_c - * @li @ref Ecore_Evas_Buffer_Example_02_c - * * @{ */ -/* these are dummy and just tell u what API levels ecore_evas supports - not if +/* These are dummy and just tells you what API levels ecore_evas supports - not * the actual support is compiled in. You need to query for that separately. */ #define HAVE_ECORE_EVAS_X 1 #define HAVE_ECORE_EVAS_FB 1 #define HAVE_ECORE_EVAS_X11_GL 1 -//#define HAVE_ECORE_EVAS_X11_16 1 -//#define HAVE_ECORE_EVAS_DIRECTFB 1 +#define HAVE_ECORE_EVAS_X11_16 1 +#define HAVE_ECORE_EVAS_DIRECTFB 1 #define HAVE_ECORE_EVAS_WIN32 1 #define HAVE_ECORE_EVAS_COCOA 1 #define HAVE_ECORE_EVAS_SDL 1 -//#define HAVE_ECORE_EVAS_WINCE 1 +#define HAVE_ECORE_EVAS_WINCE 1 #define HAVE_ECORE_EVAS_EWS 1 #define HAVE_ECORE_EVAS_PSL1GHT 1 #define HAVE_ECORE_EVAS_WAYLAND_SHM 1 #define HAVE_ECORE_EVAS_WAYLAND_EGL 1 -#define HAVE_ECORE_EVAS_DRM 1 -#define HAVE_ECORE_EVAS_DRM_GL 1 typedef enum _Ecore_Evas_Engine_Type { @@ -129,9 +114,7 @@ typedef enum _Ecore_Evas_Engine_Type ECORE_EVAS_ENGINE_EWS, ECORE_EVAS_ENGINE_PSL1GHT, ECORE_EVAS_ENGINE_WAYLAND_SHM, - ECORE_EVAS_ENGINE_WAYLAND_EGL, - ECORE_EVAS_ENGINE_DRM, - ECORE_EVAS_ENGINE_OPENGL_DRM + ECORE_EVAS_ENGINE_WAYLAND_EGL } Ecore_Evas_Engine_Type; typedef enum _Ecore_Evas_Avoid_Damage_Type @@ -149,26 +132,63 @@ typedef enum _Ecore_Evas_Object_Associate_Flags ECORE_EVAS_OBJECT_ASSOCIATE_DEL = 1 << 2 } Ecore_Evas_Object_Associate_Flags; +#ifndef _ECORE_X_H +#define _ECORE_X_WINDOW_PREDEF +typedef unsigned int Ecore_X_Window; +typedef unsigned int Ecore_X_Pixmap; +#endif + +#ifndef _ECORE_DIRECTFB_H +#define _ECORE_DIRECTFB_WINDOW_PREDEF +typedef struct _Ecore_DirectFB_Window Ecore_DirectFB_Window; +#endif + +#ifndef __ECORE_WIN32_H__ +typedef struct _Ecore_Win32_Window Ecore_Win32_Window; +#endif + +#ifndef __ECORE_WINCE_H__ +typedef struct _Ecore_WinCE_Window Ecore_WinCE_Window; +#endif + +#ifndef __ECORE_COCOA_H__ +typedef struct _Ecore_Cocoa_Window Ecore_Cocoa_Window; +#endif + +#ifndef _ECORE_EVAS_PRIVATE_H +/* Basic data types */ +typedef struct _Ecore_Evas Ecore_Evas; +typedef void (*Ecore_Evas_Event_Cb) (Ecore_Evas *ee); /**< Callback used for several ecore evas events @since 1.2 */ +#endif + +#ifndef _ECORE_WAYLAND_H_ +#define _ECORE_WAYLAND_WINDOW_PREDEF +typedef struct _Ecore_Wl_Window Ecore_Wl_Window; +#endif + /* module setup/shutdown calls */ EAPI int ecore_evas_engine_type_supported_get(Ecore_Evas_Engine_Type engine); /** - * @brief Init the Ecore_Evas system. + * @brief Initializes the Ecore_Evas system. * - * @return How many times the lib has been initialized, 0 indicates failure. + * @details This function sets up the Evas wrapper system - initializes Evas and Ecore libraries. * - * Set up the Evas wrapper system. Init Evas and Ecore libraries. + * @return The number of time the lib has been initialized, \n + * otherwise @c 0 on failure * * @see ecore_evas_shutdown() */ EAPI int ecore_evas_init(void); + /** - * @brief Shut down the Ecore_Evas system. + * @brief Shuts down the Ecore_Evas system. * - * @return 0 if ecore evas is fully shut down, or > 0 if it still being used. + * @details This function closes the Evas wrapper system down - shuts down Evas and Ecore libraries. * - * This closes the Evas wrapper system down. Shut down Evas and Ecore libraries. + * @return @c 0 if ecore evas is fully shut down, \n + * otherwise > @c 0 if it still being used * * @see ecore_evas_init() */ @@ -178,723 +198,716 @@ EAPI void ecore_evas_app_comp_sync_set(Eina_Bool do_sync); EAPI Eina_Bool ecore_evas_app_comp_sync_get(void); /** - * @brief Returns a list of supported engines names. + * @brief Gets a list of supported engines names. * - * @return Newly allocated list with engines names. Engines names - * strings are internal and should be considered constants, do not - * free or modify them, to free the list use ecore_evas_engines_free(). + * @return The newly allocated list with engines names \n + * Engines names strings are internal and should be + * considered constants, do not free or modify them, + * to free the list use ecore_evas_engines_free(). */ EAPI Eina_List *ecore_evas_engines_get(void); + /** - * @brief Free list returned by ecore_evas_engines_get() + * @brief Frees the list returned by ecore_evas_engines_get(). * - * @param engines list with engines names + * @param[in] engines The list with engines names */ EAPI void ecore_evas_engines_free(Eina_List *engines); + /** - * @brief Creates a new Ecore_Evas based on engine name and common parameters. - * - * @param engine_name engine name as returned by - * ecore_evas_engines_get() or @c NULL to use environment variable - * ECORE_EVAS_ENGINE, that can be undefined and in this case - * this call will try to find the first working engine. - * @param x horizontal position of window (not supported in all engines) - * @param y vertical position of window (not supported in all engines) - * @param w width of window - * @param h height of window - * @param extra_options string with extra parameter, dependent on engines - * or @ NULL. String is usually in the form: 'key1=value1;key2=value2'. - * Pay attention that when getting that from shell commands, most - * consider ';' as the command terminator, so you need to escape - * it or use quotes. - * - * @return Ecore_Evas instance or @c NULL if creation failed. + * @brief Creates a new Ecore_Evas based on engine name and common parameters. + * + * @param[in] engine_name The engine name as returned by ecore_evas_engines_get(), \n + * otherwise set @c NULL to use environment variable @a ECORE_EVAS_ENGINE \n + * This can be undefined and in this case this call tries + * to find the first working engine. + * @param[in] x The horizontal position of window (not supported in all engines) + * @param[in] y The vertical position of window (not supported in all engines) + * @param[in] w The width of window + * @param[in] h The height of window + * @param[in] extra_options The string with extra parameter, dependent on engines or @ NULL \n + * The string is usually in the form: 'key1=value1;key2=value2'. + * Pay attention that when getting that from shell commands, most + * consider ';' as the command terminator, so you need to escape + * it or use quotes. + * @return The Ecore_Evas instance, \n + * otherwise @c NULL on failure */ EAPI Ecore_Evas *ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options); + /** - * @brief Set whether an Ecore_Evas has an alpha channel or not. + * @brief Sets whether an Ecore_Evas has an alpha channel or not. * - * @param ee The Ecore_Evas to shape - * @param alpha @c EINA_TRUE to enable the alpha channel, @c EINA_FALSE to - * disable it + * @details This function allows you to make an Ecore_Evas translucent using an + * alpha channel. See ecore_evas_shaped_set() for details. The difference + * between a shaped window and a window with an alpha channel is that an + * alpha channel supports multiple levels of transparency, as opposed to + * the @c 1 bit transparency of a shaped window (a pixel is either opaque, or + * it is transparent). * - * This function allows you to make an Ecore_Evas translucent using an - * alpha channel. See ecore_evas_shaped_set() for details. The difference - * between a shaped window and a window with an alpha channel is that an - * alpha channel supports multiple levels of transparency, as opposed to - * the 1 bit transparency of a shaped window (a pixel is either opaque, or - * it's transparent). + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to shape + * @param[in] alpha Set @c EINA_TRUE to enable the alpha channel, \n + * otherwise @c EINA_FALSE to disable it */ EAPI void ecore_evas_alpha_set(Ecore_Evas *ee, Eina_Bool alpha); + /** - * @brief Query whether an Ecore_Evas has an alpha channel. - * @param ee The Ecore_Evas to query. - * @return @c EINA_TRUE if ee has an alpha channel, @c EINA_FALSE if it does - * not. + * @brief Checks whether an Ecore_Evas has an alpha channel. * - * This function returns @c EINA_TRUE if @p ee has an alpha channel, and - * @c EINA_FALSE if it does not. + * @remarks This function returns @c EINA_TRUE if @a ee has an alpha channel, and + * @c EINA_FALSE if it does not. + * + * @param[in] ee The Ecore_Evas to query + * @return @c EINA_TRUE if @a ee has an alpha channel, \n + * otherwise @c EINA_FALSE if it does not * * @see ecore_evas_alpha_set() */ EAPI Eina_Bool ecore_evas_alpha_get(const Ecore_Evas *ee); + /** - * @brief Set whether an Ecore_Evas has an transparent window or not. + * @brief Sets whether an Ecore_Evas has an transparent window or not. * - * @param ee The Ecore_Evas to shape - * @param transparent @c EINA_TRUE to enable the transparent window, - * @c EINA_FALSE to disable it + * @details This function sets some translucency options. * - * This function sets some translucency options, for more complete support see - * ecore_evas_alpha_set(). + * @remarks For more complete support see ecore_evas_alpha_set(). * - * @warning Support for this depends on the underlying windowing system. + * @remarks Support for this depends on the underlying windowing system. + * + * @param[in] ee The Ecore_Evas to shape + * @param[in] transparent @c EINA_TRUE to enable the transparent window, \n + * otherwise @c EINA_FALSE to disable it * * @see ecore_evas_alpha_set() */ EAPI void ecore_evas_transparent_set(Ecore_Evas *ee, Eina_Bool transparent); + /** - * @brief Query whether an Ecore_Evas is transparent. + * @brief Checks whether an Ecore_Evas is transparent. * - * @param ee The Ecore_Evas to query. - * @return @c EINA_TRUE if ee is transparent, @c EINA_FALSE if it isn't. + * @param[in] ee The Ecore_Evas to query + * @return @c EINA_TRUE if ee is transparent, \n + * otherwise @c EINA_FALSE if it is not * * @see ecore_evas_transparent_set() */ EAPI Eina_Bool ecore_evas_transparent_get(const Ecore_Evas *ee); + /** - * @brief Get the geometry of an Ecore_Evas. + * @brief Gets the geometry of an Ecore_Evas. * - * @param ee The Ecore_Evas whose geometry y - * @param x A pointer to an int to place the x coordinate in - * @param y A pointer to an int to place the y coordinate in - * @param w A pointer to an int to place the w size in - * @param h A pointer to an int to place the h size in - * - * This function takes four pointers to (already allocated) ints, and places - * the geometry of @p ee in them. If any of the parameters is not desired you - * may pass @c NULL on them. + * @details This function takes four pointers to (already allocated) int, and places + * the geometry of @a ee in them. If any of the parameters is not desired, you + * may pass @c NULL on them. * * @code * int x, y, w, h; * ecore_evas_geometry_get(ee, &x, &y, &w, &h); * @endcode * + * @param[in] ee The Ecore_Evas whose geometry y + * @param[out] x A pointer to an int to place the x coordinate in + * @param[out] y A pointer to an int to place the y coordinate in + * @param[out] w A pointer to an int to place the w size in + * @param[out] h A pointer to an int to place the h size in + * * @see ecore_evas_new() * @see ecore_evas_resize() * @see ecore_evas_move() * @see ecore_evas_move_resize() */ EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h); + /** - * @brief Get the geometry which an Ecore_Evas was latest recently requested. + * @brief Gets the geometry recently requested by an Ecore_Evas. * - * @param ee The Ecore_Evas whose geometry y - * @param x A pointer to an int to place the x coordinate in - * @param y A pointer to an int to place the y coordinate in - * @param w A pointer to an int to place the w size in - * @param h A pointer to an int to place the h size in - * - * This function takes four pointers to (already allocated) ints, and places - * the geometry which @p ee was latest recently requested . If any of the - * parameters is not desired you may pass @c NULL on them. - * This function can represent recently requested geometry. - * ecore_evas_geometry_get function returns the value is updated after engine - * finished request. By comparison, ecore_evas_request_geometry_get returns - * recently requested value. + * @details This function takes four pointers to (already allocated) ints, and places + * the geometry which @a ee recently requested. If any of the + * parameters is not desired, you may pass @c NULL on them. + * This function can represent the recently requested geometry. + * The ecore_evas_geometry_get function returns the value that is updated after engine + * finished the request. By comparison, ecore_evas_request_geometry_get returns + * the recently requested value. + * @since 1.1 * * @code * int x, y, w, h; * ecore_evas_request_geometry_get(ee, &x, &y, &w, &h); * @endcode * - * @since 1.1 + * @param[in] ee The Ecore_Evas whose geometry y + * @param[out] x A pointer to an int to place the x coordinate in + * @param[out] y A pointer to an int to place the y coordinate in + * @param[out] w A pointer to an int to place the w size in + * @param[out] h A pointer to an int to place the h size in */ EAPI void ecore_evas_request_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h); + /** - * @brief Set the focus of an Ecore_Evas' window. + * @brief Sets the focus of an Ecore_Evas' window. * - * @param ee The Ecore_Evas - * @param on @c EINA_TRUE for focus, @c EINA_FALSE to defocus. + * @details This function focuses @a ee if @a on is @c EINA_TRUE, + * or unfocuses @a ee if @a on is @c EINA_FALSE. * - * This function focuses @p ee if @p on is @c EINA_TRUE, or unfocuses @p ee if - * @p on is @c EINA_FALSE. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE for focus, \n + * otherwise set @c EINA_FALSE to defocus */ EAPI void ecore_evas_focus_set(Ecore_Evas *ee, Eina_Bool on); + /** - * @brief Query whether an Ecore_Evas' window is focused or not. + * @brief Checks whether an Ecore_Evas' window is focused. * - * @param ee The Ecore_Evas to set - * @return @c EINA_TRUE if @p ee if focused, @c EINA_FALSE if not. + * @param[in] ee The Ecore_Evas to check + * @return @c EINA_TRUE if @a ee is focused, \n + * otherwise @c EINA_FALSE if it is not focused. * * @see ecore_evas_focus_set() */ EAPI Eina_Bool ecore_evas_focus_get(const Ecore_Evas *ee); + /** - * @brief Iconify or uniconify an Ecore_Evas' window. + * @brief Iconifies or uniconifies an Ecore_Evas' window. * - * @param ee The Ecore_Evas - * @param on @c EINA_TRUE to iconify, @c EINA_FALSE to uniconify. + * @details This function iconifies @a ee if @a on is @c EINA_TRUE, or uniconifies @a ee + * if @a on is @c EINA_FALSE. * - * This function iconifies @p ee if @p on is @c EINA_TRUE, or uniconifies @p ee - * if @p on is @c EINA_FALSE. + * @remarks Iconify and minimize are synonyms. * - * @note Iconify and minimize are synonyms. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE to iconify, \n + * otherwise set @c EINA_FALSE to uniconify */ EAPI void ecore_evas_iconified_set(Ecore_Evas *ee, Eina_Bool on); + /** - * @brief Query whether an Ecore_Evas' window is iconified or not. + * @brief Checks whether an Ecore_Evas' window is iconified. * - * @param ee The Ecore_Evas to set - * @return @c EINA_TRUE if @p ee is iconified, @c EINA_FALSE if not. + * @remarks Iconify and minimize are synonyms. * - * @note Iconify and minimize are synonyms. + * @param[in] ee The Ecore_Evas to check + * @return @c EINA_TRUE if @a ee is iconified, \n + * otherwise @c EINA_FALSE if it is not iconified * * @see ecore_evas_iconified_set() */ EAPI Eina_Bool ecore_evas_iconified_get(const Ecore_Evas *ee); + /** - * @brief Set whether an Ecore_Evas' window is borderless or not. + * @brief Sets whether an Ecore_Evas' window is borderless or not. * - * @param ee The Ecore_Evas - * @param on @c EINA_TRUE for borderless, @c EINA_FALSE for bordered. + * @details This function makes @a ee borderless if @a on is @c EINA_TRUE, or bordered + * if @a on is @c EINA_FALSE. * - * This function makes @p ee borderless if @p on is @c EINA_TRUE, or bordered - * if @p on is @c EINA_FALSE. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE for borderless, \n + * otherwise set @c EINA_FALSE for bordered */ EAPI void ecore_evas_borderless_set(Ecore_Evas *ee, Eina_Bool on); + /** - * @brief Query whether an Ecore_Evas' window is borderless or not. + * @brief Checks whether an Ecore_Evas' window is borderless. * - * @param ee The Ecore_Evas to set - * @return @c EINA_TRUE if @p ee is borderless, @c EINA_FALSE if not. + * @param[in] ee The Ecore_Evas to check + * @return @c EINA_TRUE if @a ee is borderless, \n + * otherwise @c EINA_FALSE if it is not borderless * * @see ecore_evas_borderless_set() */ EAPI Eina_Bool ecore_evas_borderless_get(const Ecore_Evas *ee); + /** - * @brief Set whether or not an Ecore_Evas' window is fullscreen. + * @brief Sets whether or not an Ecore_Evas' window is fullscreen. * - * @param ee The Ecore_Evas - * @param on @c EINA_TRUE fullscreen, @c EINA_FALSE not. + * @details This function causes @a ee to be fullscreen if @a on is @c EINA_TRUE, and + * not to be fullscreen if @a on is @c EINA_FALSE. * - * This function causes @p ee to be fullscreen if @p on is @c EINA_TRUE, or - * not if @p on is @c EINA_FALSE. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE for fullscreen, \n + * otherwise set @c EINA_FALSE */ EAPI void ecore_evas_fullscreen_set(Ecore_Evas *ee, Eina_Bool on); + /** - * @brief Query whether an Ecore_Evas' window is fullscreen or not. + * @brief Checks whether an Ecore_Evas' window is fullscreen. * - * @param ee The Ecore_Evas to set - * @return @c EINA_TRUE if @p ee is fullscreen, @c EINA_FALSE if not. + * @param[in] ee The Ecore_Evas to check + * @return @c EINA_TRUE if @a ee is fullscreen, \n + * otherwise @c EINA_FALSE if it is not fullscreen * * @see ecore_evas_fullscreen_set() */ EAPI Eina_Bool ecore_evas_fullscreen_get(const Ecore_Evas *ee); + /** - * @brief Set another window that this window is a group member of + * @brief Sets another window that this window is a group member of. + * @since 1.2 * - * @param ee The Ecore_Evas - * @param ee_group The other group member + * @remarks If @a ee_group is @c NULL, @a ee is removed from the group, otherwise it is + * added. Note that if you free the @a ee_group canvas before @a ee, then + * getting the group canvas with ecore_evas_window_group_get() returns + * an invalid handle. * - * If @p ee_group is @c NULL, @p ee is removed from the group, otherwise it is - * added. Note that if you free the @p ee_group canvas before @p ee, then - * getting the group canvas with ecore_evas_window_group_get() will return - * an invalid handle. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] ee_group The other group member */ EAPI void ecore_evas_window_group_set(Ecore_Evas *ee, const Ecore_Evas *ee_group); + /** - * @brief Get the canvas group set. + * @brief Gets the canvas group that is set. + * @details This returns the handle set by ecore_evas_window_group_set(). * - * This returns the handle set by ecore_evas_window_group_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The Canvas group handle + * @param[in] ee The Ecore_Evas + * @return The Canvas group handle * * @see ecore_evas_window_group_set() - * @since 1.2 */ EAPI const Ecore_Evas *ecore_evas_window_group_get(const Ecore_Evas *ee); + /** - * @brief Set the aspect ratio of a canvas window + * @brief Sets the aspect ratio of a canvas window. * - * @param ee The Ecore_Evas - * @param aspect The aspect ratio (width divided by height), or 0 to disable + * @details This function sets the desired aspect ratio of a canvas window. + * @since 1.2 * - * This sets the desired aspect ratio of a canvas window + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] aspect The aspect ratio (width divided by height), \n + * otherwise set @c 0 to disable */ EAPI void ecore_evas_aspect_set(Ecore_Evas *ee, double aspect); + /** - * @brief Get the aspect ratio of a canvas window + * @brief Gets the aspect ratio of a canvas window. * - * This returns the value set by ecore_evas_aspect_set(). + * @details This function returns the value set by ecore_evas_aspect_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The aspect ratio + * @param[in] ee The Ecore_Evas to set + * @return The aspect ratio * * @see ecore_evas_aspect_set() - * @since 1.2 */ EAPI double ecore_evas_aspect_get(const Ecore_Evas *ee); + /** - * @brief Set The urgent hint flag + * @brief Sets the urgent hint flag. * - * @param ee The Ecore_Evas - * @param urgent The urgent state flag + * @details This function sets the "urgent" state hint on a window so that the desktop environment + * can highlight it somehow. + * @since 1.2 * - * This sets the "urgent" state hint on a window so the desktop environment - * can highlight it somehow. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] urgent Set @c EINA_TRUE to set the urgent state flag, \n + * otherwise set @c EINA_FALSE to not set it */ EAPI void ecore_evas_urgent_set(Ecore_Evas *ee, Eina_Bool urgent); + /** - * @brief Get the urgent state on the cavas window + * @brief Gets the urgent state on the canvas window. * - * This returns the value set by ecore_evas_urgent_set() + * @details This returns the value set by ecore_evas_urgent_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The urgent state set + * @param[in] ee The Ecore_Evas to set + * @return @c EINA_TRUE if the urgent state is set, \n + * otherwise @c EINA_FALSE if it is not set * * @see ecore_evas_urgent_set() - * @since 1.2 */ EAPI Eina_Bool ecore_evas_urgent_get(const Ecore_Evas *ee); + /** - * @brief Set the modal state flag on the canvas window + * @brief Sets the modal state flag on the canvas window. * - * @param ee The Ecore_Evas - * @param modal The modal hint flag + * @details This function hints if the window should be modal (for example, if it is also transient + * for another window, the other window maybe be denied focus by + * the desktop window manager). + * @since 1.2 * - * This hints if the window should be modal (eg if it is also transient - * for another window, the other window will maybe be denied focus by - * the desktop window manager). + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] modal Set @c EINA_TRUE to set the window as modal, \n + * otherwise set @c EINA_FALSE to set the window as not modal */ EAPI void ecore_evas_modal_set(Ecore_Evas *ee, Eina_Bool modal); + /** - * @brief Get The modal flag + * @brief Checks whether the modal flag is set. * - * This returns the value set by ecore_evas_modal_set(). + * @details This returns the value set by ecore_evas_modal_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The modal flag + * @param[in] ee The Ecore_Evas + * @return @c EINA_TRUE if the window is modal, \n + * otherwise @c EINA_FALSE if the window is not modal * * @see ecore_evas_modal_set() - * @since 1.2 */ EAPI Eina_Bool ecore_evas_modal_get(const Ecore_Evas *ee); + /** - * @brief Set the "i demand attention" flag on a canvas window + * @brief Sets the "i demand attention" flag on a canvas window. + * @since 1.2 * - * @param ee The Ecore_Evas - * @param demand The flag state to set + * @remarks A window may demand attention (for example, you must enter a password before + * continuing), and so you may flag a window with this function. * - * A window may demand attention now (eg you must enter a password before - * continuing), and so it may flag a window with this. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] demand Set @c EINA_TRUE to set the flag, \n + * otherwise set @c EINA_FALSE to not set the flag */ EAPI void ecore_evas_demand_attention_set(Ecore_Evas *ee, Eina_Bool demand); + /** - * @brief Get the "i demand attention" flag + * @brief Checks whether the "i demand attention" flag is set. * - * This returns the value set by ecore_evas_demand_attention_set(). + * @details This function returns the value set by ecore_evas_demand_attention_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The "i demand attention" flag. + * @param[in] ee The Ecore_Evas + * @return @c EINA_TRUE if the "i demand attention" flag is set, \n + * otherwise @c EINA_FALSE if the flag is not set * * @see ecore_evas_demand_attention_set() - * @since 1.2 */ EAPI Eina_Bool ecore_evas_demand_attention_get(const Ecore_Evas *ee); + /** - * @brief Set the "focus skip" flag + * @brief Sets the "focus skip" flag. + * @since 1.2 * - * @param ee The Ecore_Evas - * @param skip The "focus skip" state to set. + * @remarks A window may not want to accept focus, be in the taskbar or pager + * sometimes (example for a small notification window that hovers around + * a taskbar or panel, or hovers around a window until some activity + * dismisses it). * - * A window may not want to accept focus, be in the taskbar, pager etc. - * sometimes (example for a small notification window that hovers around - * a taskbar or panel, or hovers around a window until some activity - * dismisses it). + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.2 + * @param[in] ee The Ecore_Evas + * @param[in] skip Set @c EINA_TRUE to set the "focus skip", \n + * otherwise @c EINA_FALSE to not set the flag */ EAPI void ecore_evas_focus_skip_set(Ecore_Evas *ee, Eina_Bool skip); + /** - * @brief Get the "focus skip" flag + * @brief Checks whether the "focus skip" flag is set. * - * This returns the value set by ecore_evas_focus_skip_set(). + * @details This returns the value set by ecore_evas_focus_skip_set(). + * @since 1.2 * - * @param ee The Ecore_Evas to set - * @return The "focus skip" flag. + * @param[in] ee The Ecore_Evas to set + * @return @c EINA_TRUE if the "focus skip" flag is set, \n + * otherwise @c EINA_FALSE if the flag is not set * * @see ecore_evas_focus_skip_set() - * @since 1.2 */ EAPI Eina_Bool ecore_evas_focus_skip_get(const Ecore_Evas *ee); /** - * @brief Set if this evas should ignore @b all events. + * @brief Sets whether this evas should ignore @b all events. * - * @param ee The Ecore_Evas whose window's to ignore events. - * @param ignore The Ecore_Evas new ignore state. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] ignore Set @c EINA_TRUE for Ecore_Evas to ignore events, \n + * otherwise @c EINA_FALSE to not ignore the events */ EAPI void ecore_evas_ignore_events_set(Ecore_Evas *ee, Eina_Bool ignore); + /** - * @brief Returns the ignore state of an Ecore_Evas' window. + * @brief Checks whether the ignore state of the Ecore_Evas window is set. * - * @param ee The Ecore_Evas whose window's ignore events state is returned. - * @return The Ecore_Evas window's ignore state. + * @param[in] ee The Ecore_Evas + * @return @c EINA_TRUE if ignore state is set, \n + * otherwise @c EINA_FALSE if the ignore state is not set * * @see ecore_evas_ignore_events_set() */ EAPI Eina_Bool ecore_evas_ignore_events_get(const Ecore_Evas *ee); + /** - * @brief Query whether an Ecore_Evas' window is visible or not. + * @brief Checks whether an Ecore_Evas window is visible. * - * @param ee The Ecore_Evas to query. - * @return 1 if visible, 0 if not. + * @details This function queries @a ee and returns @c 1 if it is visible, + * and @c 0 if it is not visible. * - * This function queries @p ee and returns 1 if it is visible, and 0 if not. + * @param[in] ee The Ecore_Evas to query + * @return @c 1 if the window visible, \n + * otherwise @c 0 if it is not visible * * @see ecore_evas_show() * @see ecore_evas_hide() */ EAPI int ecore_evas_visibility_get(const Ecore_Evas *ee); + /** - * @brief Set the layer of an Ecore_Evas' window. + * @brief Sets the layer of an Ecore_Evas window. * - * @param ee The Ecore_Evas - * @param layer The layer to put @p ee on. + * @details This function moves @a ee to the layer @a layer. * - * This function moves @p ee to the layer @p layer. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] layer The layer to put @a ee on * * @see ecore_evas_lower() * @see ecore_evas_raise() */ EAPI void ecore_evas_layer_set(Ecore_Evas *ee, int layer); + /** - * @brief Get the layer of an Ecore_Evas' window. + * @brief Gets the layer of an Ecore_Evas window. * - * @param ee The Ecore_Evas to set - * @return the layer @p ee's window is on. + * @param[in] ee The Ecore_Evas to set + * @return The layer @a ee's window is on * * @see ecore_evas_layer_set() * @see ecore_evas_lower() * @see ecore_evas_raise() */ EAPI int ecore_evas_layer_get(const Ecore_Evas *ee); + /** - * @brief Maximize (or unmaximize) an Ecore_Evas' window. + * @brief Maximizes (or unmaximizes) an Ecore_Evas window. * - * @param ee The Ecore_Evas - * @param on @c EINA_TRUE to maximize, @c EINA_FALSE to unmaximize. + * @details This function maximizes @a ee if @a on is @c EINA_TRUE, + * or unmaximizes @a ee if @a on is @c EINA_FALSE. * - * This function maximizes @p ee if @p on is @c EINA_TRUE, or unmaximizes @p ee - * if @p on is @c EINA_FALSE. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE to maximize, \n + * otherwise set @c EINA_FALSE to unmaximize */ EAPI void ecore_evas_maximized_set(Ecore_Evas *ee, Eina_Bool on); + /** - * @brief Query whether an Ecore_Evas' window is maximized or not. + * @brief Checks whether an Ecore_Evas window is maximized. * - * @param ee The Ecore_Evas to set - * @return @c EINA_TRUE if @p ee is maximized, @c EINA_FALSE if not. + * @param[in] ee The Ecore_Evas to set + * @return @c EINA_TRUE if @a ee is maximized, \n + * otherwise @c EINA_FALSE if is not maximized * * @see ecore_evas_maximized_set() */ EAPI Eina_Bool ecore_evas_maximized_get(const Ecore_Evas *ee); + /** - * @brief Query if the underlying windowing system supports the window profile. - * - * @param ee The Ecore_Evas - * @return @c EINA_TRUE if the window profile is supported, @c EINA_FALSE otherwise. - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 - */ -EAPI Eina_Bool ecore_evas_window_profile_supported_get(const Ecore_Evas *ee); -/** - * @brief Set the window profile - * - * @param ee The Ecore_Evas to set - * @param profile The string value of the window profile - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 - */ -EAPI void ecore_evas_window_profile_set(Ecore_Evas *ee, const char *profile); -/** - * @brief Get the window profile - * - * @param ee The Ecore_Evas to get the window profile from. - * @return The string value of the window profile, or NULL if none exists - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 - */ -EAPI const char *ecore_evas_window_profile_get(const Ecore_Evas *ee); -/** - * @brief Set the array of available window profiles - * - * @param ee The Ecore_Evas to set - * @param profiles The string array of available window profiels - * @param count The number of members in profiles - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 - */ -EAPI void ecore_evas_window_available_profiles_set(Ecore_Evas *ee, const char **profiles, const unsigned int count); -/** - * @brief Get the array of available window profiles - * - * @param ee The Ecore_Evas to get available window profiles from. - * @param profiles Where to return the string array of available window profiles - * @param count Where to return the number of members in profiles - * @return EINA_TRUE if available window profiles exist, EINA_FALSE otherwise - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 - */ -EAPI Eina_Bool ecore_evas_window_available_profiles_get(Ecore_Evas *ee, char ***profiles, unsigned int *count); -/** - * @brief Query if the underlying windowing system supports the window manager rotation. - * - * @param ee The Ecore_Evas - * @return @c EINA_TRUE if the window manager rotation is supported, @c EINA_FALSE otherwise. - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.9.0 - */ -EAPI Eina_Bool ecore_evas_wm_rotation_supported_get(const Ecore_Evas *ee); -/** - * @brief Set the preferred rotation hint. - * - * @param ee The Ecore_Evas to set - * @param rotation Value to set the preferred rotation hint - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.9.0 - */ -EAPI void ecore_evas_wm_rotation_preferred_rotation_set(Ecore_Evas *ee, int rotation); -/** - * @brief Get the preferred rotation hint. - * - * @param ee The Ecore_Evas to get the preferred rotation hint from. - * @return The preferred rotation hint, -1 on failure. - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.9.0 - */ -EAPI int ecore_evas_wm_rotation_preferred_rotation_get(const Ecore_Evas *ee); -/** - * @brief Set the array of available window rotations. + * @brief Sets the Ecore_Evas window profile list. + * @since 1.7.0 * - * @param ee The Ecore_Evas to set - * @param rotations The integer array of available window rotations - * @param count The number of members in rotations + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.9.0 + * @param[in] ee The Ecore_Evas + * @param[in] profiles The profile name list + * @param[in] num_profiles The number of profile names */ -EAPI void ecore_evas_wm_rotation_available_rotations_set(Ecore_Evas *ee, const int *rotations, unsigned int count); +EAPI void ecore_evas_profiles_set(Ecore_Evas *ee, const char **profiles, unsigned int num_profiles); + /** - * @brief Get the array of available window rotations. + * @brief Gets the Ecore_Evas window profile name. + * @since 1.7.0 * - * @param ee The Ecore_Evas to get available window rotations from. - * @param rotations Where to return the integer array of available window rotations - * @param count Where to return the number of members in rotations - * @return EINA_TRUE if available window rotations exist, EINA_FALSE otherwise - * - * @warning Support for this depends on the underlying windowing system. - * @since 1.9.0 + * @param[in] ee The Ecore_Evas + * @return The profile name */ -EAPI Eina_Bool ecore_evas_wm_rotation_available_rotations_get(const Ecore_Evas *ee, int **rotations, unsigned int *count); +EAPI const char *ecore_evas_profile_get(const Ecore_Evas *ee); + +EAPI Eina_Bool ecore_evas_wm_rotation_supported_get(const Ecore_Evas *ee); +EAPI void ecore_evas_wm_rotation_preferred_rotation_set(Ecore_Evas *ee, int rotation); +EAPI int ecore_evas_wm_rotation_preferred_rotation_get(const Ecore_Evas *ee); +EAPI void ecore_evas_wm_rotation_available_rotations_set(Ecore_Evas *ee, const int *rotations, unsigned int count); +EAPI Eina_Bool ecore_evas_wm_rotation_available_rotations_get(const Ecore_Evas *ee, int **rotations, unsigned int *count); + /** - * @brief Set manual rotation done mode of Ecore_Evas's window + * @brief Sets manual rotation done mode for Ecore_Evas window. + * @since 1.8.0 * - * @param ee The Ecore_Evas - * @param set If true, the window manager will not rotate the Ecore_Evas's window until - * the rotation done event is received by ecore_evas_wm_rotation_manual_rotation_done. - * If false, the manual rotation mode is disabled. + * @param[in] ee The Ecore_Evas + * @param[in] set Set @c EINA_TRUE if the window manager should not rotate the Ecore_Evas's window until + * the rotation done event is received by ecore_evas_wm_rotation_manual_rotation_done, \n + * otherwise set @c EINA_FALSE if the manual rotation mode should be disabled * - * @since 1.9.0 */ -EAPI void ecore_evas_wm_rotation_manual_rotation_done_set(Ecore_Evas *ee, Eina_Bool set); +EAPI void ecore_evas_wm_rotation_manual_rotation_done_set(Ecore_Evas *ee, Eina_Bool set); /** - * @brief Get manual rotation done mode of Ecore_Evas's window - * - * @param ee The Ecore_Evas - * @return If true, the manual rotation done mode is enabled + * @brief Gets manual rotation done mode of Ecore_Evas's window. + * @since 1.8.0 * - * @since 1.9.0 + * @param[in] ee The Ecore_Evas + * @return @c EINA_TRUE if the manual rotation done mode is enabled, \n + * otherwise @c EINA_FALSE if it is not enabled */ -EAPI Eina_Bool ecore_evas_wm_rotation_manual_rotation_done_get(const Ecore_Evas *ee); +EAPI Eina_Bool ecore_evas_wm_rotation_manual_rotation_done_get(const Ecore_Evas *ee); /** - * @brief Set rotation finish manually + * @brief Sets the rotation finish manually. + * @since 1.8.0 * - * @param ee The Ecore_Evas + * @param[in] ee The Ecore_Evas * - * @since 1.9.0 */ -EAPI void ecore_evas_wm_rotation_manual_rotation_done(Ecore_Evas *ee); +EAPI void ecore_evas_wm_rotation_manual_rotation_done(Ecore_Evas *ee); + /** - * @brief Get the list of supported auxiliary hint strings. + * @brief Gets the list of supported auxiliary hint strings. + * @since 1.8.0 * - * @param ee The Ecore_Evas - * @return List of supported auxiliary hint strings. - * @note Do not change the returned list of its contents. Auxiliary hint - * strings are internal and should be considered constants, do not free or - * modify them. - * @warning Support for this depends on the underlying windowing system. + * @remarks Do not change the returned list of its contents. Auxiliary hint + * strings are internal and should be considered constants, do not free or + * modify them. + * @remarks Support for this depends on the underlying windowing system. * - * The window auxiliary hint is the value which is used to decide which actions should - * be made available to the user by the window manager. If you want to set specific hint - * to your window, then you should check whether it exists in the supported auxiliary - * hints that are registered in the root window by the window manager. Once you've added - * an auxiliary hint, you can get a new ID which is used to change value and delete hint. - * The window manager sends the response message to the application on receiving auxiliary - * hint change event. A list of auxiliary hint within the Ecore_Evas has this format: - * ID:HINT:VALUE,ID:HINT:VALUE,... + * @remarks The window auxiliary hint is the value which is used to decide which actions should + * be made available to the user by the window manager. If you want to set specific hint + * to your window, then you should check whether it exists in the supported auxiliary + * hints that are registered in the root window by the window manager. Once you have added + * an auxiliary hint, you can get a new ID which is used to change value and delete hint. + * The window manager sends the response message to the application on receiving auxiliary + * hint change event. A list of auxiliary hint within the Ecore_Evas has this format: + * ID:HINT:VALUE,ID:HINT:VALUE,... * - * @since 1.10.0 + * @param[in] ee The Ecore_Evas + * @return The list of supported auxiliary hint strings */ EAPI const Eina_List *ecore_evas_aux_hints_supported_get(const Ecore_Evas *ee); + /** - * @brief Get the list of allowed auxiliary hint ID. + * @brief Gets the list of allowed auxiliary hint ID. * - * @param ee The Ecore_Evas - * @return List of allowed auxiliary hint ID. - * @note This function is low level. Instead of using it directly, consider - * using the callback mechanism in Elementary such as "aux,hint,allowed". - * @warning Support for this depends on the underlying windowing system. + * @since 1.8.0 * - * @since 1.10.0 + * @remarks This function is low level. Instead of using it directly, consider + * using the callback mechanism in Elementary such as "aux,hint,allowed". + * @remarks Support for this depends on the underlying windowing system. + * + * @param[in] ee The Ecore_Evas + * @return The list of allowed auxiliary hint ID */ EAPI Eina_List *ecore_evas_aux_hints_allowed_get(const Ecore_Evas *ee); + /** - * @brief Create an auxiliary hint of the Ecore_Evas. + * @brief Creates an auxiliary hint of the Ecore_Evas. * - * @param ee The Ecore_Evas - * @param hint The auxiliary hint string. - * @param val The value string. - * @return The ID of created auxiliary hint, or -1 on failure. - * @warning Support for this depends on the underlying windowing system. + * @since 1.8.0 * - * @since 1.10.0 + * @remarks Support for this depends on the underlying windowing system. + * + * @param[in] ee The Ecore_Evas + * @param[in] hint The auxiliary hint string + * @param[in] val The value string + * @return The ID of created auxiliary hint, \n + * otherwise @c -1 on failure */ EAPI int ecore_evas_aux_hint_add(Ecore_Evas *ee, const char *hint, const char *val); + /** - * @brief Delete an auxiliary hint of the Ecore_Evas. + * @brief Deletes an auxiliary hint of the Ecore_Evas. * - * @param ee The Ecore_Evas - * @param id The ID of the auxiliary hint. - * @return EINA_TRUE if no error occurred, EINA_FALSE otherwise. - * @warning Support for this depends on the underlying windowing system. + * @since 1.8.0 * - * @since 1.10.0 + * @remarks Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] id The ID of the auxiliary hint. + * @return @c EINA_TRUE if the hint is deleted successfully, \n + * otherwise @c EINA_FALSE in case of errors */ EAPI Eina_Bool ecore_evas_aux_hint_del(Ecore_Evas *ee, const int id); + /** - * @brief Change a value of the auxiliary hint. + * @brief Changes a value of the auxiliary hint. * - * @param ee The Ecore_Evas - * @param id The auxiliary hint ID. - * @param val The value string to be set. - * @return EINA_TRUE if no error occurred, EINA_FALSE otherwise. - * @warning Support for this depends on the underlying windowing system. + * @since 1.8.0 + * + * @remarks Support for this depends on the underlying windowing system. * - * @since 1.10.0 + * @param[in] ee The Ecore_Evas + * @param[in] id The auxiliary hint ID + * @param[in] val The value string to be set + * @return @c EINA_TRUE if the value is changed successfully, \n + * otherwise @c EINA_FALSE in case of errors */ EAPI Eina_Bool ecore_evas_aux_hint_val_set(Ecore_Evas *ee, const int id, const char *val); + /** - * @brief Send message to parent ecore + * @brief Sends message to parent ecore. + * @since 1.8.0 * - * @param ee The Ecore_Evas to set - * @param msg_domain The domain of message - * @param msg_id The id of message - * @param data The data of message - * @param size The size of message data + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 + * @param[in] ee The Ecore_Evas to set + * @param[in] msg_domain The domain of message + * @param[in] msg_id The ID of message + * @param[in] data The data of message + * @param[in] size The size of message data * * @see ecore_evas_msg_send() * @see ecore_evas_callback_msg_parent_handle_set() * @see eecore_evas_callback_msg_handle_set() - * - * This is a list of examples of these functions: - * @li @ref ecore_evas_extn_socket_example - * @li @ref ecore_evas_extn_plug_example */ EAPI void ecore_evas_msg_parent_send(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size); + /** - * @brief Send message to child ecore + * @brief Sends message to child ecore. + * @since 1.8.0 * - * @param ee The Ecore_Evas to set - * @param msg_domain The domain of message - * @param msg_id The id of message - * @param data The data of message - * @param size The size of message data + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 + * @param[in] ee The Ecore_Evas to set + * @param[in] msg_domain The domain of message + * @param[in] msg_id The ID of message + * @param[in] data The data of message + * @param[in] size The size of message data * * @see ecore_evas_msg_parent_send() * @see ecore_evas_callback_msg_parent_handle_set() * @see eecore_evas_callback_msg_handle_set() */ EAPI void ecore_evas_msg_send(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size); + /** - * Set a callback for parent Ecore_Evas message. + * @brief Sets a callback for parent Ecore_Evas message. + * @since 1.8.0 * - * @param ee The Ecore_Evas to set callbacks on - * @param func_parent_handle The handle to be called when message arive. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func_parent_handle The handle to be called when message arrives * * @see ecore_evas_msg_parent_send() * @see ecore_evas_msg_send() * @see eecore_evas_callback_msg_handle_set() */ EAPI void ecore_evas_callback_msg_parent_handle_set(Ecore_Evas *ee, void (*func_parent_handle)(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size)); + /** - * Set a callback for child Ecore_Evas message. + * @brief Sets a callback for child Ecore_Evas message. + * @since 1.8.0 * - * @param ee The Ecore_Evas to set callbacks on - * @param func_handle The handle to be called when message arive + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. - * @since 1.8.0 + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func_handle The handle to be called when message arrives * * @see ecore_evas_msg_parent_send() * @see ecore_evas_msg_send() @@ -903,15 +916,15 @@ EAPI void ecore_evas_callback_msg_parent_handle_set(Ecore_Evas *ee, void (*func_ EAPI void ecore_evas_callback_msg_handle_set(Ecore_Evas *ee, void (*func_handle)(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size)); /** - * @brief Move an Ecore_Evas. + * @brief Moves an Ecore_Evas. * - * @param ee The Ecore_Evas to move - * @param x The x coordinate to move to - * @param y The y coordinate to move to + * @details This function moves @a ee to the screen coordinates (@a x, @a y). * - * This moves @p ee to the screen coordinates (@p x, @p y) + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to move + * @param[in] x The x coordinate to move to + * @param[in] y The y coordinate to move to * * @see ecore_evas_new() * @see ecore_evas_resize() @@ -919,162 +932,173 @@ EAPI void ecore_evas_callback_msg_handle_set(Ecore_Evas *ee, void (*func_handle) */ EAPI void ecore_evas_move(Ecore_Evas *ee, int x, int y); /** - * @brief Resize an Ecore_Evas. + * @brief Resizes an Ecore_Evas. * - * @param ee The Ecore_Evas to move - * @param w The w coordinate to resize to - * @param h The h coordinate to resize to + * @details This function resizes @a ee to @a w x @a h. * - * This resizes @p ee to @p w x @p h. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to move + * @param[in] w The w coordinate to resize to + * @param[in] h The h coordinate to resize to * * @see ecore_evas_new() * @see ecore_evas_move() * @see ecore_evas_move_resize() */ EAPI void ecore_evas_resize(Ecore_Evas *ee, int w, int h); + /** - * @brief Move and resize an Ecore_Evas + * @brief Moves and resizes an Ecore_Evas. * - * @param ee The Ecore_Evas to move and resize - * @param x The x coordinate to move to - * @param y The y coordinate to move to - * @param w The w coordinate to resize to - * @param h The h coordinate to resize to + * @details This moves @a ee to the screen coordinates (@a x, @a y) and resizes + * it to @a w x @a h. * - * This moves @p ee to the screen coordinates (@p x, @p y) and resizes - * it to @p w x @p h. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to move and resize + * @param[in] x The x coordinate to move to + * @param[in] y The y coordinate to move to + * @param[in] w The w coordinate to resize to + * @param[in] h The h coordinate to resize to * * @see ecore_evas_new() * @see ecore_evas_move() * @see ecore_evas_resize() */ EAPI void ecore_evas_move_resize(Ecore_Evas *ee, int x, int y, int w, int h); + /** - * @brief Set the rotation of an Ecore_Evas' window. + * @brief Sets the rotation of an Ecore_Evas window. * - * @param ee The Ecore_Evas - * @param rot the angle (in degrees) of rotation. + * @remarks The allowed values of @a rot depend on the engine being used. Most only + * allow multiples of @c 90. * - * The allowed values of @p rot depend on the engine being used. Most only - * allow multiples of 90. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] rot The angle (in degrees) of rotation * * @see ecore_evas_rotation_with_resize_set() */ EAPI void ecore_evas_rotation_set(Ecore_Evas *ee, int rot); + /** - * @brief Set the rotation of an Ecore_Evas' window + * @brief Sets the rotation of an Ecore_Evas window. * - * @param ee The Ecore_Evas - * @param rot the angle (in degrees) of rotation. + * @remarks Like ecore_evas_rotation_set(), but it also resizes the window's contents so + * that they fit inside the current window geometry. * - * Like ecore_evas_rotation_set(), but it also resizes the window's contents so - * that they fit inside the current window geometry. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] rot The angle (in degrees) of rotation * * @see ecore_evas_rotation_set() */ EAPI void ecore_evas_rotation_with_resize_set(Ecore_Evas *ee, int rot); + /** - * @brief Get the rotation of an Ecore_Evas' window + * @brief Gets the rotation of an Ecore_Evas window. * - * @param ee The Ecore_Evas - * @return the angle (in degrees) of rotation. + * @param[in] ee The Ecore_Evas + * @return The angle (in degrees) of rotation * * @see ecore_evas_rotation_set() * @see ecore_evas_rotation_with_resize_set() */ EAPI int ecore_evas_rotation_get(const Ecore_Evas *ee); + /** - * @brief Raise an Ecore_Evas' window. + * @brief Raises an Ecore_Evas window. * - * @param ee The Ecore_Evas to raise. + * @details This functions raises the Ecore_Evas to the front. * - * This functions raises the Ecore_Evas to the front. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to raise * * @see ecore_evas_lower() * @see ecore_evas_layer_set() */ EAPI void ecore_evas_raise(Ecore_Evas *ee); + /** - * @brief Lower an Ecore_Evas' window. + * @brief Lowers an Ecore_Evas window. * - * @param ee The Ecore_Evas to raise. + * @details This functions lowers the Ecore_Evas to the back. * - * This functions lowers the Ecore_Evas to the back. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to raise * * @see ecore_evas_raise() * @see ecore_evas_layer_set() */ EAPI void ecore_evas_lower(Ecore_Evas *ee); + /** - * @brief Set the title of an Ecore_Evas' window. + * @brief Sets the title of an Ecore_Evas window. * - * @param ee The Ecore_Evas whose title you wish to set. - * @param t The title + * @details This function sets the title of @a ee to @a t. * - * This function sets the title of @p ee to @p t. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas whose title you wish to set + * @param[in] t The title */ EAPI void ecore_evas_title_set(Ecore_Evas *ee, const char *t); + /** - * @brief Get the title of an Ecore_Evas' window. + * @brief Gets the title of an Ecore_Evas window. * - * @param ee The Ecore_Evas whose title you wish to get. - * @return The title of @p ee. + * @details This function returns the title of @a ee. * - * This function returns the title of @p ee. + * @param[in] ee The Ecore_Evas whose title you wish to get + * @return The title of @a ee * * @see ecore_evas_title_set() */ EAPI const char *ecore_evas_title_get(const Ecore_Evas *ee); + /** - * @brief Set the name and class of an Ecore_Evas' window. + * @brief Sets the name and class of an Ecore_Evas window. * - * @param ee the Ecore_Evas - * @param n the name - * @param c the class + * @details This function sets the name of @a ee to @a n, and its class to @a c. The + * meaning of @a name and @a class depends on the underlying windowing system. * - * This function sets the name of @p ee to @p n, and its class to @p c. The - * meaning of @p name and @p class depends on the underlying windowing system. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @param[in] n The name + * @param[in] c The class */ EAPI void ecore_evas_name_class_set(Ecore_Evas *ee, const char *n, const char *c); + /** - * @brief Get the name and class of an Ecore_Evas' window + * @brief Gets the name and class of an Ecore_Evas window. * - * This function gets the name of @p ee into @p n, and its class into - * @p c. + * @details This function gets the name of @a ee into @a n, and its class into @a c. * - * @param ee The Ecore_Evas to query. - * @param n A pointer to a string to place the name in. - * @param c A pointer to a string to place the class in. + * @param[in] ee The Ecore_Evas to query + * @param[out] n A pointer to a string to place the name in + * @param[out] c A pointer to a string to place the class in * @see ecore_evas_name_class_set() */ EAPI void ecore_evas_name_class_get(const Ecore_Evas *ee, const char **n, const char **c); + /** - * @brief Returns a pointer to the underlying window. + * @brief Gets a pointer to the underlying window. * - * @param ee The Ecore_Evas whose window is desired. - * @return A pointer to the underlying window. + * @remarks Support for this depends on the underlying windowing system. * - * @warning Support for this depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas + * @return A pointer to the underlying window */ EAPI Ecore_Window ecore_evas_window_get(const Ecore_Evas *ee); -/* engine/target specific init calls */ + +/* Engine/target specific init calls */ EAPI Ecore_Evas *ecore_evas_software_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); EAPI Ecore_X_Window ecore_evas_software_x11_window_get(const Ecore_Evas *ee); EAPI void ecore_evas_software_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on); @@ -1096,7 +1120,12 @@ EAPI Ecore_Evas *ecore_evas_software_x11_pixmap_new(const char *disp_name, E /** * @brief Returns the underlying Ecore_X_Pixmap used in the Ecore_Evas * - * @param ee The Ecore_Evas whose pixmap is desired. + * @param[in] disp_name Display name. + * @param[in] parent X11 parent window. + * @param[in] x X cooridnate. + * @param[in] y Y coordinate. + * @param[in] w Width. + * @param[in] h Height. * @return The underlying Ecore_X_Pixmap * * @warning Support for this depends on the underlying windowing system. @@ -1107,12 +1136,13 @@ EAPI Ecore_Evas *ecore_evas_software_x11_pixmap_new(const char *disp_name, E * * @since 1.8 */ +EAPI Ecore_Evas * ecore_evas_software_x11_pixmap_new_internal(const char *disp_name, Ecore_X_Window parent,int x, int y, int w, int h); EAPI Ecore_X_Pixmap ecore_evas_software_x11_pixmap_get(const Ecore_Evas *ee); #define ECORE_EVAS_GL_X11_OPT_NONE 0 #define ECORE_EVAS_GL_X11_OPT_INDIRECT 1 #define ECORE_EVAS_GL_X11_OPT_VSYNC 2 -#define ECORE_EVAS_GL_X11_OPT_SWAP_MODE 3 +#define ECORE_EVAS_GL_X11_OPT_SWAP_MODE 3 #define ECORE_EVAS_GL_X11_OPT_LAST 4 #define ECORE_EVAS_GL_X11_SWAP_MODE_AUTO 0 @@ -1120,7 +1150,7 @@ EAPI Ecore_X_Pixmap ecore_evas_software_x11_pixmap_get(const Ecore_Evas *ee); #define ECORE_EVAS_GL_X11_SWAP_MODE_COPY 2 #define ECORE_EVAS_GL_X11_SWAP_MODE_DOUBLE 3 #define ECORE_EVAS_GL_X11_SWAP_MODE_TRIPLE 4 - + EAPI Ecore_Evas *ecore_evas_gl_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); EAPI Ecore_Evas *ecore_evas_gl_x11_options_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h, const int *opt); EAPI Ecore_X_Window ecore_evas_gl_x11_window_get(const Ecore_Evas *ee); @@ -1133,18 +1163,31 @@ EAPI void ecore_evas_gl_x11_pre_post_swap_callback_set(const Ecore_Ev * @brief Create a new Ecore_Evas which does not contain an XWindow. It will * only contain an XPixmap to render to * + * @since 1.8 + * * @warning The XPixmap ID can change with every frame after it is rendered, * so you should ALWAYS call ecore_evas_software_x11_pixmap_get when you * need the current pixmap id. * - * @since 1.8 + * @param[in] disp_name Display name. + * @param[in] parent X11 parent window. + * @param[in] x X cooridnate. + * @param[in] y Y coordinate. + * @param[in] w Width. + * @param[in] h Height. + * @return The underlying Ecore_X_Pixmap */ EAPI Ecore_Evas *ecore_evas_gl_x11_pixmap_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); /** * @brief Returns the underlying Ecore_X_Pixmap used in the Ecore_Evas * - * @param ee The Ecore_Evas whose pixmap is desired. + * @param[in] disp_name Display name. + * @param[in] parent X11 parent window. + * @param[in] x X cooridnate. + * @param[in] y Y coordinate. + * @param[in] w Width. + * @param[in] h Height. * @return The underlying Ecore_X_Pixmap * * @warning Support for this depends on the underlying windowing system. @@ -1155,31 +1198,32 @@ EAPI Ecore_Evas *ecore_evas_gl_x11_pixmap_new(const char *disp_name, Ecore_X * * @since 1.8 */ +EAPI Ecore_Evas * ecore_evas_gl_x11_pixmap_new_internal(const char *disp_name, Ecore_X_Window parent,int x, int y, int w, int h); EAPI Ecore_X_Pixmap ecore_evas_gl_x11_pixmap_get(const Ecore_Evas *ee); -EAPI Ecore_Evas *ecore_evas_xrender_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED; -EAPI Ecore_X_Window ecore_evas_xrender_x11_window_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_xrender_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED; -EAPI Eina_Bool ecore_evas_xrender_x11_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_xrender_x11_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED; - -EAPI Ecore_Evas *ecore_evas_software_x11_8_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED; -EAPI Ecore_X_Window ecore_evas_software_x11_8_window_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI Ecore_X_Window ecore_evas_software_x11_8_subwindow_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_software_x11_8_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED; -EAPI Eina_Bool ecore_evas_software_x11_8_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_software_x11_8_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED; - -EAPI Ecore_Evas *ecore_evas_software_x11_16_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED; -EAPI Ecore_X_Window ecore_evas_software_x11_16_window_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_software_x11_16_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED; -EAPI Eina_Bool ecore_evas_software_x11_16_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED; -EAPI void ecore_evas_software_x11_16_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED; +EAPI Ecore_Evas *ecore_evas_xrender_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); +EAPI Ecore_X_Window ecore_evas_xrender_x11_window_get(const Ecore_Evas *ee); +EAPI void ecore_evas_xrender_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on); +EAPI Eina_Bool ecore_evas_xrender_x11_direct_resize_get(const Ecore_Evas *ee); +EAPI void ecore_evas_xrender_x11_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win); + +EAPI Ecore_Evas *ecore_evas_software_x11_8_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); +EAPI Ecore_X_Window ecore_evas_software_x11_8_window_get(const Ecore_Evas *ee); +EAPI Ecore_X_Window ecore_evas_software_x11_8_subwindow_get(const Ecore_Evas *ee); +EAPI void ecore_evas_software_x11_8_direct_resize_set(Ecore_Evas *ee, Eina_Bool on); +EAPI Eina_Bool ecore_evas_software_x11_8_direct_resize_get(const Ecore_Evas *ee); +EAPI void ecore_evas_software_x11_8_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win); + +EAPI Ecore_Evas *ecore_evas_software_x11_16_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h); +EAPI Ecore_X_Window ecore_evas_software_x11_16_window_get(const Ecore_Evas *ee); +EAPI void ecore_evas_software_x11_16_direct_resize_set(Ecore_Evas *ee, Eina_Bool on); +EAPI Eina_Bool ecore_evas_software_x11_16_direct_resize_get(const Ecore_Evas *ee); +EAPI void ecore_evas_software_x11_16_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win); EAPI Ecore_Evas *ecore_evas_fb_new(const char *disp_name, int rotation, int w, int h); -EAPI Ecore_Evas *ecore_evas_directfb_new(const char *disp_name, int windowed, int x, int y, int w, int h) EINA_DEPRECATED; -EAPI Ecore_DirectFB_Window *ecore_evas_directfb_window_get(const Ecore_Evas *ee) EINA_DEPRECATED; +EAPI Ecore_Evas *ecore_evas_directfb_new(const char *disp_name, int windowed, int x, int y, int w, int h); +EAPI Ecore_DirectFB_Window *ecore_evas_directfb_window_get(const Ecore_Evas *ee); EAPI Ecore_Evas *ecore_evas_wayland_shm_new(const char *disp_name, unsigned int parent, int x, int y, int w, int h, Eina_Bool frame); @@ -1191,201 +1235,195 @@ EAPI void ecore_evas_wayland_pointer_set(Ecore_Evas *ee, int hot_x, i EAPI void ecore_evas_wayland_type_set(Ecore_Evas *ee, int type); EAPI Ecore_Wl_Window *ecore_evas_wayland_window_get(const Ecore_Evas *ee); -EAPI Ecore_Evas *ecore_evas_drm_new(const char *device, unsigned int parent, int x, int y, int w, int h); -EAPI Ecore_Evas *ecore_evas_gl_drm_new(const char *device, unsigned int parent, int x, int y, int w, int h); /** @since 1.12 */ - /** - * @brief Create a new @c Ecore_Evas canvas bound to the Evas - * @b buffer engine + * @brief Creates a new @c Ecore_Evas canvas bound to the Evas @b buffer engine. * - * @param w The width of the canvas, in pixels - * @param h The height of the canvas, in pixels - * @return A new @c Ecore_Evas instance or @c NULL, on failure + * @details This function creates a new buffer canvas wrapper, with image data array + * @b bound to the ARGB format, 8 bits per pixel. * - * This creates a new buffer canvas wrapper, with image data array - * @b bound to the ARGB format, 8 bits per pixel. + * @remarks This function allocates the needed pixels array with canonical + * @c malloc(). If you wish a custom function to allocate it, consider + * using ecore_evas_buffer_allocfunc_new(), instead. * - * This function will allocate the needed pixels array with canonical - * @c malloc(). If you wish a custom function to allocate it, consider - * using ecore_evas_buffer_allocfunc_new(), instead. + * @remarks This function actually is a wrapper on + * ecore_evas_buffer_allocfunc_new(), using the same @a w and @a h + * arguments and canonical @c malloc() and @c free() to the memory + * allocation and freeing functions. See the function's documentation + * for more details. * - * @note This function actually is a wrapper on - * ecore_evas_buffer_allocfunc_new(), using the same @a w and @a h - * arguments and canonical @c malloc() and @c free() to the memory - * allocation and freeing functions. See that function's documentation - * for more details. + * @param[in] w The width of the canvas, in pixels + * @param[in] h The height of the canvas, in pixels + * @return A new @c Ecore_Evas instance, \n + * otherwise @c NULL on failure */ EAPI Ecore_Evas *ecore_evas_buffer_new(int w, int h); /** - * @brief Create a new @c Ecore_Evas canvas bound to the Evas - * @b buffer engine, giving custom allocation and freeing functions for - * the canvas memory region + * @brief Creates a new @c Ecore_Evas canvas bound to the Evas + * @b buffer engine, giving custom allocation and freeing functions for + * the canvas memory region. * - * @param w The width of the canvas, in canvas units - * @param h The height of the canvas, in canvas units - * @param alloc_func Function to be called to allocate the memory - * needed for the new buffer canvas. @a data will be passed the same - * value as the @p data of this function, while @a size will be passed - * @p w times @p h times @c sizeof(int). - * @param free_func Function to be called to free the memory used by - * the new buffer canvas. @a data will be passed the same value as the - * @p data of this function, while @a pix will be passed the canvas - * memory pointer. - * @param data Custom data to be passed to the allocation and freeing - * functions - * @return A new @c Ecore_Evas instance or @c NULL, on failure + * @details This function creates a new buffer canvas wrapper, with image data array + * @b bound to the ARGB format, 8 bits per pixel. * - * This creates a new buffer canvas wrapper, with image data array - * @b bound to the ARGB format, 8 bits per pixel. + * @remarks This function is useful when one wants an @c Ecore_Evas buffer + * canvas with a custom allocation function, like one getting memory + * chunks from a memory pool, for example. * - * This function is useful when one wants an @c Ecore_Evas buffer - * canvas with a custom allocation function, like one getting memory - * chunks from a memory pool, for example. + * @remarks On any resizing of this @c Ecore_Evas buffer canvas, its image data + * is @b freed, to be allocated again with the new size. * - * On any resizing of this @c Ecore_Evas buffer canvas, its image data - * will be @b freed, to be allocated again with the new size. + * @remarks @a w and @a h sizes have to greater or equal to @c 1. Otherwise, + * they are interpreted as @c 1, exactly. * - * @note @p w and @p h sizes have to greater or equal to 1. Otherwise, - * they'll be interpreted as 1, exactly. + * @param[in] w The width of the canvas, in canvas units + * @param[in] h The height of the canvas, in canvas units + * @param[in] alloc_func The function to be called to allocate the memory + * needed for the new buffer canvas \n + * @a data is passed the same value as the @a data of this function, + * while @a size is passed @a w times @a h times @c sizeof(int). + * @param[in] free_func The function to be called to free the memory used by + * the new buffer canvas \n + * @a data is passed the same value as the @a data of this function, + * while @a pix is passed the canvas memory pointer. + * @param[in] data The custom data to be passed to the allocation and freeing functions + * @return A new @c Ecore_Evas instance, \n + * otherwise @c NULL on failure * * @see ecore_evas_buffer_new() */ EAPI Ecore_Evas *ecore_evas_buffer_allocfunc_new(int w, int h, void *(*alloc_func) (void *data, int size), void (*free_func) (void *data, void *pix), const void *data); /** - * @brief Grab a pointer to the actual pixels array of a given - * @c Ecore_Evas @b buffer canvas/window. + * @brief Grabs a pointer to the actual pixels array of a given + * @c Ecore_Evas @b buffer canvas/window. * - * @param ee An @c Ecore_Evas handle - * @return A pointer to the internal pixels array of @p ee + * @remarks Besides returning a pointer to the actual pixel array of the given + * canvas, this call forces a <b>rendering update on @a ee</b>, first. * - * Besides returning a pointer to the actual pixel array of the given - * canvas, this call will force a <b>rendering update on @p ee</b>, - * first. + * @remarks A common use case for this call is to create an image object, from + * @b another canvas, to have as data @a ee's contents, thus taking a + * snapshot of the canvas. For that case, one can also use the + * ecore_evas_object_image_new() helper function. * - * A common use case for this call is to create an image object, from - * @b another canvas, to have as data @p ee's contents, thus - * snapshoting the canvas. For that case, one can also use the - * ecore_evas_object_image_new() helper function. + * @param[in] ee An @c Ecore_Evas handle + * @return A pointer to the internal pixels array of @a ee */ EAPI const void *ecore_evas_buffer_pixels_get(Ecore_Evas *ee); /** - * @brief Create a new @c Ecore_Evas canvas bound to the Evas - * @b ews (Ecore + Evas Single Process Windowing System) engine + * @brief Creates a new @c Ecore_Evas canvas bound to the Evas + * @b ews (Ecore + Evas Single Process Windowing System) engine. + * + * @since 1.1 * - * EWS is a simple single process windowing system. The backing store - * is also an @c Ecore_Evas that can be setup with - * ecore_evas_ews_setup() and retrieved with - * ecore_evas_ews_ecore_evas_get(). It will allow window management - * using events prefixed with @c ECORE_EVAS_EVENT_EWS_. + * @remarks EWS is a simple single process windowing system. The backing store + * is also an @c Ecore_Evas that can be setup with + * ecore_evas_ews_setup() and retrieved with + * ecore_evas_ews_ecore_evas_get(). It allows window management + * using events prefixed with @c ECORE_EVAS_EVENT_EWS_. * - * The EWS windows (returned by this function or - * ecore_evas_new("ews"...)) will all be software buffer windows - * automatic rendered to the backing store. + * @remarks The EWS windows (returned by this function or + * ecore_evas_new("ews"...)) is all software buffer windows + * automatic rendered to the backing store. * - * @param x horizontal position of window, in pixels - * @param y vertical position of window, in pixels - * @param w The width of the canvas, in pixels - * @param h The height of the canvas, in pixels - * @return A new @c Ecore_Evas instance or @c NULL, on failure + * @param[in] x The horizontal position of window, in pixels + * @param[in] y The vertical position of window, in pixels + * @param[in] w The width of the canvas, in pixels + * @param[in] h The height of the canvas, in pixels + * @return A new @c Ecore_Evas instance, \n + * otherwise @c NULL on failure * * @see ecore_evas_ews_setup() * @see ecore_evas_ews_ecore_evas_get() - * - * @since 1.1 */ EAPI Ecore_Evas *ecore_evas_ews_new(int x, int y, int w, int h); - /** - * Returns the backing store image object that represents the given - * window in EWS. - * @return The evas object of EWS backing store. + * @brief Gets the backing store image object that represents the given + * window in EWS. + * @since 1.1 + * + * @remarks This should not be modified anyhow, but may be helpful to + * determine stacking and geometry of it for window managers + * that decorate windows. * - * @note This should not be modified anyhow, but may be helpful to - * determine stacking and geometry of it for window managers - * that decorate windows. + * @param[in] ee The Ecore_Evas from which to get the backing store + * @return The evas object of EWS backing store * - * @param ee The Ecore_Evas from which to get the backing store. * @see ecore_evas_ews_manager_set() * @see ecore_evas_ews_evas_get() - * @since 1.1 */ EAPI Evas_Object *ecore_evas_ews_backing_store_get(const Ecore_Evas *ee); /** - * Calls the window to be deleted (freed), but can let user decide to - * forbid it by using ecore_evas_callback_delete_request_set() + * @brief Calls the window to be deleted (freed), but can let user decide to + * forbid it by using ecore_evas_callback_delete_request_set() + * @since 1.1 * - * @param ee The Ecore_Evas for which window will be deleted. - * @since 1.1 + * @param[in] ee The Ecore_Evas for which window is deleted */ EAPI void ecore_evas_ews_delete_request(Ecore_Evas *ee); /** - * @brief Create an Evas image object with image data <b>bound to an - * own, internal @c Ecore_Evas canvas wrapper</b> - * - * @param ee_target @c Ecore_Evas to have the canvas receiving the new - * image object - * @return A handle to the new image object - * - * This will create a @b special Evas image object. The image's pixel - * array will get bound to the same image data array of an @b internal - * @b buffer @c Ecore_Evas canvas. The user of this function is, then, - * supposed to grab that @c Ecore_Evas handle, with - * ecore_evas_object_ecore_evas_get(), and use its canvas to render - * whichever contents he/she wants, @b independently of the contents - * of the canvas owned by @p ee_target. Those contents will reflect on - * the canvas of @p ee, though, being exactly the image data of the - * object returned by this function. - * - * This is a helper function for the scenario of one wanting to grab a - * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be - * used on another canvas, for whichever reason. The most common goal - * of this setup is to @b save an image file with a whole canvas as - * contents, which could not be achieved by using an image file within - * the target canvas. - * - * @warning Always resize the returned image and its underlying - * @c Ecore_Evas handle accordingly. They must be kept with same sizes - * for things to work as expected. Also, you @b must issue - * @c evas_object_image_size_set() on the image with that same size. If - * the image is to be shown in a canvas bound to an engine different - * than the buffer one, then you must also set this image's @b fill - * properties accordingly. - * - * @note The image returned will always be bound to the - * @c EVAS_COLORSPACE_ARGB8888 colorspace, always. - * - * @note Use ecore_evas_object_evas_get() to grab the image's internal - * own canvas directly. - * - * @note If snapshoting this image's internal canvas, remember to - * flush its internal @c Ecore_Evas firstly, with - * ecore_evas_manual_render(). + * @brief Creates an Evas image object with image data <b>bound to an + * own, internal @c Ecore_Evas canvas wrapper</b>. + * + * @remarks This creates a @b special Evas image object. The image's pixel + * array gets bound to the same image data array of an @b internal + * @b buffer @c Ecore_Evas canvas. The user of this function is, then, + * supposed to grab that @c Ecore_Evas handle, with + * ecore_evas_object_ecore_evas_get(), and use its canvas to render + * whichever contents he/she wants, @b independently of the contents + * of the canvas owned by @a ee_target. Those contents reflect on + * the canvas of @a ee, though, being exactly the image data of the + * object returned by this function. + * + * This is a helper function for the scenario of one wanting to grab a + * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be + * used on another canvas, for whichever reason. The most common goal + * of this setup is to @b save an image file with a whole canvas as + * contents, which could not be achieved by using an image file within + * the target canvas. + * + * @remarks Always resize the returned image and its underlying + * @c Ecore_Evas handle accordingly. They must be kept with same sizes + * for things to work as expected. Also, you @b must issue + * @c evas_object_image_size_set() on the image with that same size. If + * the image is to be shown in a canvas bound to an engine different + * than the buffer one, then you must also set this image's @b fill + * properties accordingly. + * + * @remarks The image returned is always bound to the + * @c EVAS_COLORSPACE_ARGB8888 colorspace, always. + * + * @remarks Use ecore_evas_object_evas_get() to grab the image's internal + * own canvas directly. + * + * @remarks If you are taking a snapshot of this image's internal canvas, remember to + * flush its internal @c Ecore_Evas firstly, with + * ecore_evas_manual_render(). + * + * @param[in] ee_target The Ecore_Evas to have the canvas receiving the new image object + * @return A handle to the new image object */ EAPI Evas_Object *ecore_evas_object_image_new(Ecore_Evas *ee_target); /** - * @brief Retrieve the internal @c Ecore_Evas handle of an image - * object created via ecore_evas_object_image_new() + * @brief Gets the internal @c Ecore_Evas handle of an image + * object created using ecore_evas_object_image_new(). * - * @param obj A handle to an image object created via - * ecore_evas_object_image_new() - * @return The underlying @c Ecore_Evas handle in @p obj + * @param[in] obj A handle to an image object created using ecore_evas_object_image_new() + * @return The underlying @c Ecore_Evas handle in @a obj */ EAPI Ecore_Evas *ecore_evas_object_ecore_evas_get(Evas_Object *obj); /** - * @brief Retrieve the canvas bound to the internal @c Ecore_Evas - * handle of an image object created via ecore_evas_object_image_new() + * @brief Gets the canvas bound to the internal @c Ecore_Evas + * handle of an image object created using ecore_evas_object_image_new(). * - * @param obj A handle to an image object created via - * ecore_evas_object_image_new() - * @return A handle to @p obj's underlying @c Ecore_Evas's canvas + * @param[in] obj A handle to an image object created using ecore_evas_object_image_new() + * @return A handle to @a obj's underlying @c Ecore_Evas's canvas */ EAPI Evas *ecore_evas_object_evas_get(Evas_Object *obj); @@ -1429,97 +1467,98 @@ EAPI Ecore_Evas *ecore_evas_software_wince_new(Ecore_WinCE_Window *parent, int x, int y, int width, - int height) EINA_DEPRECATED; + int height); EAPI Ecore_Evas *ecore_evas_software_wince_fb_new(Ecore_WinCE_Window *parent, int x, int y, int width, - int height) EINA_DEPRECATED; + int height); EAPI Ecore_Evas *ecore_evas_software_wince_gapi_new(Ecore_WinCE_Window *parent, int x, int y, int width, - int height) EINA_DEPRECATED; + int height); EAPI Ecore_Evas *ecore_evas_software_wince_ddraw_new(Ecore_WinCE_Window *parent, int x, int y, int width, - int height) EINA_DEPRECATED; + int height); EAPI Ecore_Evas *ecore_evas_software_wince_gdi_new(Ecore_WinCE_Window *parent, int x, int y, int width, - int height) EINA_DEPRECATED; + int height); -EAPI Ecore_WinCE_Window *ecore_evas_software_wince_window_get(const Ecore_Evas *ee) EINA_DEPRECATED; +EAPI Ecore_WinCE_Window *ecore_evas_software_wince_window_get(const Ecore_Evas *ee); EAPI Ecore_Evas *ecore_evas_cocoa_new(Ecore_Cocoa_Window *parent, - int x, - int y, - int w, - int h); + int x, + int y, + int w, + int h); EAPI Ecore_Evas *ecore_evas_psl1ght_new(const char* name, int w, int h); -/* generic manipulation calls */ +/* Generic manipulation calls */ /** - * @brief Get the engine name used by this Ecore_Evas(window). + * @brief Gets the engine name used by this Ecore_Evas(window). * - * @param ee Ecore_Evas whose engine's name is desired. - * @return A string that can(usually) be used in ecore_evas_new() + * @param[in] ee The Ecore_Evas whose engine's name is desired + * @return A string that can(usually) be used in ecore_evas_new() * * @see ecore_evas_free() */ EAPI const char *ecore_evas_engine_name_get(const Ecore_Evas *ee); /** - * @brief Return the Ecore_Evas for this Evas + * @brief Gets the Ecore_Evas for this Evas. * - * @param e The Evas to get the Ecore_Evas from - * @return The Ecore_Evas that holds this Evas, or @c NULL if not held by one. + * @remarks Use this only on Evas created with ecore evas. * - * @warning Only use on Evas' created with ecore evas! + * @param[in] e The Evas to get the Ecore_Evas from + * @return The Ecore_Evas that holds this Evas, \n + * otherwise @c NULL if not held by one */ EAPI Ecore_Evas *ecore_evas_ecore_evas_get(const Evas *e); /** - * @brief Free an Ecore_Evas + * @brief Frees an Ecore_Evas. * - * @param ee The Ecore_Evas to free + * @details This function frees up any memory used by the Ecore_Evas. * - * This frees up any memory used by the Ecore_Evas. + * @param[in] ee The Ecore_Evas to free. */ EAPI void ecore_evas_free(Ecore_Evas *ee); /** - * @brief Retrieve user data associated with an Ecore_Evas. + * @brief Gets user data associated with an Ecore_Evas. * - * @param ee The Ecore_Evas to retrieve the user data from. - * @param key The key which the user data to be retrieved is associated with. + * @details This function retrieves user specific data that has been stored within an + * Ecore_Evas structure with ecore_evas_data_set(). * - * This function retrieves user specific data that has been stored within an - * Ecore_Evas structure with ecore_evas_data_set(). + * @return A pointer to the user data on success, \n + * otherwise @c NULL on error * - * @returns @c NULL on error or no data found, A pointer to the user data on - * success. + * @param[in] ee The Ecore_Evas to retrieve the user data from + * @param[in] key The key which the user data to be retrieved is associated with * * @see ecore_evas_data_set() */ EAPI void *ecore_evas_data_get(const Ecore_Evas *ee, const char *key); /** - * @brief Store user data in an Ecore_Evas structure. + * @brief Stores user data in an Ecore_Evas structure. * - * @param ee The Ecore_Evas to store the user data in. - * @param key A unique string to associate the user data against. Cannot - * be NULL. - * @param data A pointer to the user data to store. + * @details This function associates the @a data with a @a key which is stored by + * the Ecore_Evas @a ee. Be aware that a call to ecore_evas_free() does + * not free any memory for the associated user data. This is the responsibility + * of the caller. * - * This function associates the @p data with a @p key which is stored by - * the Ecore_Evas @p ee. Be aware that a call to ecore_evas_free() will - * not free any memory for the associated user data, this is the responsibility - * of the caller. + * @param[in] ee The Ecore_Evas to store the user data in + * @param[in] key A unique string to associate the user data against \n + * This must not be @c NULL. + * @param[in] data A pointer to the user data to store * * @see ecore_evas_callback_pre_free_set() * @see ecore_evas_free() @@ -1527,563 +1566,505 @@ EAPI void *ecore_evas_data_get(const Ecore_Evas *ee, const char *key); */ EAPI void ecore_evas_data_set(Ecore_Evas *ee, const char *key, const void *data); /** - * Set a callback for Ecore_Evas resize events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee is resized. + * @brief Sets a callback for Ecore_Evas resize events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee is resized. + * + * @remarks If and when this function is called depends on the underlying + * windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_resize_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas move events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee is moved. + * @brief Sets a callback for Ecore_Evas move events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee is moved. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_move_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas show events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee is shown. + * @brief Sets a callback for Ecore_Evas show events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee is shown. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_show_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas hide events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee is hidden. + * @brief Sets a callback for Ecore_Evas hide events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee is hidden. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_hide_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas delete request events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee gets a delete request. + * @brief Sets a callback for Ecore_Evas delete request events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee gets a delete request. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_delete_request_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas destroy events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee is destroyed. + * @brief Sets a callback for Ecore_Evas destroy events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee is destroyed. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_destroy_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas focus in events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee gets focus. + * @brief Sets a callback for Ecore_Evas focus in events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee gets focus. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_focus_in_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); -/** - * Set a callback for Ecore_Evas focus out events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee loses focus. +/** + * @brief Sets a callback for Ecore_Evas focus out events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee loses focus. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param ee The Ecore_Evas to set callbacks on + * @param func The function to call */ EAPI void ecore_evas_callback_focus_out_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas sticky events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee becomes sticky. + * @brief Sets a callback for Ecore_Evas sticky events. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee becomes sticky. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks When this function is called depends on the underlying windowing system. + * @param ee The Ecore_Evas to set callbacks on + * @param func The function to call */ EAPI void ecore_evas_callback_sticky_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); -/** - * Set a callback for Ecore_Evas un-sticky events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee becomes un-sticky. +/** + * @brief Sets a callback for Ecore_Evas focus out events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee becomes un-sticky. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call + */ EAPI void ecore_evas_callback_unsticky_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas mouse in events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever the mouse enters @p ee. + * @brief Sets a callback for Ecore_Evas mouse in events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever the mouse enters @a ee. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_mouse_in_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas mouse out events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever the mouse leaves @p ee. + * @brief Sets a callback for Ecore_Evas mouse out events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever the mouse leaves @a ee. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_mouse_out_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas pre render events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called just before the evas in @p ee is rendered. + * @brief Sets a callback for Ecore_Evas pre render events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called just before the evas in @a ee is rendered. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_pre_render_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas mouse post render events. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called just after the evas in @p ee is rendered. + * @brief Sets a callback for Ecore_Evas mouse post render events. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called just after the evas in @a ee is rendered. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_post_render_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas pre-free event. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call + * @brief Sets a callback for Ecore_Evas pre-free event. * - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called just before the instance @p ee is freed. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called just before the instance @a ee is freed. * - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_pre_free_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Set a callback for Ecore_Evas state changes. - * @param ee The Ecore_Evas to set callbacks on - * @param func The function to call - - * A call to this function will set a callback on an Ecore_Evas, causing - * @p func to be called whenever @p ee changes state. + * @brief Sets a callback for Ecore_Evas state changes. + * @since 1.2 * - * @since 1.2 - * @warning If and when this function is called depends on the underlying - * windowing system. + * @remarks A call to this function sets a callback on an Ecore_Evas, causing + * @a func to be called whenever @a ee changes state. + * + * @remarks When this function is called depends on the underlying windowing system. + * @param[in] ee The Ecore_Evas to set callbacks on + * @param[in] func The function to call */ EAPI void ecore_evas_callback_state_change_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func); /** - * Get an Ecore_Evas's Evas - * @param ee The Ecore_Evas whose Evas you wish to get - * @return The Evas wrapped by @p ee + * @brief Gets an Ecore_Evas's Evas. * - * This function returns the Evas contained within @p ee. + * @details This function returns the Evas contained within @a ee. + * + * @param[in] ee The Ecore_Evas whose Evas you wish to get + * @return The Evas wrapped by @a ee */ EAPI Evas *ecore_evas_get(const Ecore_Evas *ee); /** - * Provide Managed move co-ordinates for an Ecore_Evas - * @param ee The Ecore_Evas to move - * @param x The x coordinate to set as the managed location - * @param y The y coordinate to set as the managed location + * @brief Provides managed move co-ordinates for an Ecore_Evas. + * + * @details This sets the managed geometry position of the @a ee to (@a x, @a y). * - * This sets the managed geometry position of the @p ee to (@p x, @p y) + * @param[in] ee The Ecore_Evas to move + * @param[in] x The x coordinate to set as the managed location + * @param[in] y The y coordinate to set as the managed location */ EAPI void ecore_evas_managed_move(Ecore_Evas *ee, int x, int y); /** - * Set whether an Ecore_Evas is shaped or not. + * @brief Sets whether an Ecore_Evas is shaped or not. * - * @param ee The Ecore_Evas to shape. - * @param shaped @c EINA_TRUE to shape, @c EINA_FALSE to not. + * @remarks This function allows one to make an Ecore_Evas shaped to the contents of the + * evas. If @a shaped is @c EINA_TRUE, @a ee is transparent in parts of + * the evas that contain no objects. If @a shaped is @c EINA_FALSE, then @a ee + * is rectangular, and parts with no data show random framebuffer + * artifacting. For non-shaped Ecore_Evases, it is recommended to cover the + * entire evas with a background object. * - * This function allows one to make an Ecore_Evas shaped to the contents of the - * evas. If @p shaped is @c EINA_TRUE, @p ee will be transparent in parts of - * the evas that contain no objects. If @p shaped is @c EINA_FALSE, then @p ee - * will be rectangular, and parts with no data will show random framebuffer - * artifacting. For non-shaped Ecore_Evases, it is recommended to cover the - * entire evas with a background object. + * @param[in] ee The Ecore_Evas to shape + * @param[in] shaped Set @c EINA_TRUE to shape, \n + * otherwise set @c EINA_FALSE to not shape */ EAPI void ecore_evas_shaped_set(Ecore_Evas *ee, Eina_Bool shaped); /** - * Query whether an Ecore_Evas is shaped or not. + * @brief Checks whether an Ecore_Evas is shaped. * - * @param ee The Ecore_Evas to query. - * @return @c EINA_TRUE if shaped, @c EINA_FALSE if not. + * @details This function returns @c EINA_TRUE if @a ee is shaped, and @c EINA_FALSE if not. * - * This function returns @c EINA_TRUE if @p ee is shaped, and @c EINA_FALSE if not. + * @param[in] ee The Ecore_Evas to query + * @return @c EINA_TRUE if shaped, \n + * otherwise @c EINA_FALSE if is not shaped */ EAPI Eina_Bool ecore_evas_shaped_get(const Ecore_Evas *ee); /** - * @brief Show an Ecore_Evas' window + * @brief Shows an Ecore_Evas window. * - * @param ee The Ecore_Evas to show. + * @details This function makes @a ee visible. * - * This function makes @p ee visible. + * @param[in] ee The Ecore_Evas to show */ EAPI void ecore_evas_show(Ecore_Evas *ee); /** - * @brief Hide an Ecore_Evas' window + * @brief Hides an Ecore_Evas' window. * - * @param ee The Ecore_Evas to hide. + * @details This function makes @a ee hidden (not visible). * - * This function makes @p ee hidden(not visible). + * @param[in] ee The Ecore_Evas to hide */ EAPI void ecore_evas_hide(Ecore_Evas *ee); /** - * Activate (set focus to, via the window manager) an Ecore_Evas' window. - * @param ee The Ecore_Evas to activate. + * @brief Activates (sets focus to, via the window manager) an Ecore_Evas' window. + * + * @details This functions activates the Ecore_Evas. * - * This functions activates the Ecore_Evas. + * @param[in] ee The Ecore_Evas to activate */ EAPI void ecore_evas_activate(Ecore_Evas *ee); /** - * Set the minimum size of a given @c Ecore_Evas window + * @brief Sets the minimum size of a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w The minimum width - * @param h The minimum height + * @details This function sets the minimum size of @a ee to be @a w x @a h. + * You cannot resize that window to dimensions smaller than + * the ones set. * - * This function sets the minimum size of @p ee to be @p w x @p h. - * One won't be able to resize that window to dimensions smaller than - * the ones set. + * @remarks When base sizes are set, using ecore_evas_size_base_set(), + * they are used to calculate a window's minimum size, instead of + * those set by this function. * - * @note When base sizes are set, via ecore_evas_size_base_set(), - * they'll be used to calculate a window's minimum size, instead of - * those set by this function. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[in] w The minimum width + * @param[in] h The minimum height * * @see ecore_evas_size_min_get() */ EAPI void ecore_evas_size_min_set(Ecore_Evas *ee, int w, int h); /** - * Get the minimum size set for a given @c Ecore_Evas window + * @brief Gets the minimum size set for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w A pointer to an int to place the minimum width in. - * @param h A pointer to an int to place the minimum height in. + * @remarks Use @c NULL pointers on the size components that you are not + * interested in: they are ignored by the function. * - * @note Use @c NULL pointers on the size components you're not - * interested in: they'll be ignored by the function. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[out] w A pointer to an int to place the minimum width in + * @param[out] h A pointer to an int to place the minimum height in * * @see ecore_evas_size_min_set() for more details */ EAPI void ecore_evas_size_min_get(const Ecore_Evas *ee, int *w, int *h); /** - * Set the maximum size of a given @c Ecore_Evas window + * @brief Sets the maximum size of a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w The maximum width - * @param h The maximum height + * @details This function sets the maximum size of @a ee to be @a w x @a h. + * You cannot resize that window to dimensions bigger than + * the ones set. * - * This function sets the maximum size of @p ee to be @p w x @p h. - * One won't be able to resize that window to dimensions bigger than - * the ones set. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[in] w The maximum width + * @param[in] h The maximum height * * @see ecore_evas_size_max_get() */ EAPI void ecore_evas_size_max_set(Ecore_Evas *ee, int w, int h); /** - * Get the maximum size set for a given @c Ecore_Evas window + * @brief Gets the maximum size set for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w A pointer to an int to place the maximum width in. - * @param h A pointer to an int to place the maximum height in. + * @remarks Use @c NULL pointers on the size components that you are not + * interested in: they are ignored by the function. * - * @note Use @c NULL pointers on the size components you're not - * interested in: they'll be ignored by the function. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[out] w A pointer to an int to place the maximum width in + * @param[out] h A pointer to an int to place the maximum height in * * @see ecore_evas_size_max_set() for more details */ EAPI void ecore_evas_size_max_get(const Ecore_Evas *ee, int *w, int *h); /** - * Set the base size for a given @c Ecore_Evas window + * @brief Sets the base size for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w The base width - * @param h The base height + * @details This function sets the @b base size of @a ee to be @a w x @a h. + * When base sizes are set, they are used to calculate a window's + * @b minimum size, instead of those set by ecore_evas_size_min_get(). * - * This function sets the @b base size of @p ee to be @p w x @p h. - * When base sizes are set, they'll be used to calculate a window's - * @b minimum size, instead of those set by ecore_evas_size_min_get(). + * @param[in] ee An @c Ecore_Evas window's handle + * @param[in] w The base width + * @param[in] h The base height * * @see ecore_evas_size_base_get() */ EAPI void ecore_evas_size_base_set(Ecore_Evas *ee, int w, int h); /** - * Get the base size set for a given @c Ecore_Evas window + * @brief Gets the base size set for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w A pointer to an int to place the base width in. - * @param h A pointer to an int to place the base height in. + * @remarks Use @c NULL pointers on the size components that you are not + * interested in: they are ignored by the function. * - * @note Use @c NULL pointers on the size components you're not - * interested in: they'll be ignored by the function. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[out] w A pointer to an int to place the base width in + * @param[out] h A pointer to an int to place the base height in * * @see ecore_evas_size_base_set() for more details */ EAPI void ecore_evas_size_base_get(const Ecore_Evas *ee, int *w, int *h); /** - * Set the "size step" for a given @c Ecore_Evas window + * @brief Sets the "size step" for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w The step width - * @param h The step height + * @details This function sets the size steps of @a ee to be @a w x @a h. This + * limits the size of this @c Ecore_Evas window to be @b always an + * integer multiple of the step size, for each axis. * - * This function sets the size steps of @p ee to be @p w x @p h. This - * limits the size of this @c Ecore_Evas window to be @b always an - * integer multiple of the step size, for each axis. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[in] w The step width + * @param[in] h The step height */ EAPI void ecore_evas_size_step_set(Ecore_Evas *ee, int w, int h); /** - * Get the "size step" set for a given @c Ecore_Evas window + * @brief Gets the "size step" set for a given @c Ecore_Evas window. * - * @param ee An @c Ecore_Evas window's handle - * @param w A pointer to an int to place the step width in. - * @param h A pointer to an int to place the step height in. + * @remarks Use @c NULL pointers on the size components that you are not + * interested in: they are ignored by the function. * - * @note Use @c NULL pointers on the size components you're not - * interested in: they'll be ignored by the function. + * @param[in] ee An @c Ecore_Evas window's handle + * @param[out] w A pointer to an int to place the step width in + * @param[out] h A pointer to an int to place the step height in * * @see ecore_evas_size_base_set() for more details */ EAPI void ecore_evas_size_step_get(const Ecore_Evas *ee, int *w, int *h); /** - * @brief Set the cursor of an Ecore_Evas. + * @brief Sets the cursor of an Ecore_Evas. * - * @param ee The Ecore_Evas - * @param file The path to an image file for the cursor. - * @param layer The layer in which the cursor will appear. - * @param hot_x The x coordinate of the cursor's hot spot. - * @param hot_y The y coordinate of the cursor's hot spot. + * @details This function makes the mouse cursor over @a ee be the image specified by + * @a file. The actual point within the image that the mouse is at is specified + * by @a hot_x and @a hot_y, which are coordinates with respect to the top left + * corner of the cursor image. * - * This function makes the mouse cursor over @p ee be the image specified by - * @p file. The actual point within the image that the mouse is at is specified - * by @p hot_x and @p hot_y, which are coordinates with respect to the top left - * corner of the cursor image. Cursor object will be delete with Ecore_Evas. + * @remarks This function creates an object from the image and uses ecore_evas_object_cursor_set(). * - * @note This function creates an object from the image and uses - * ecore_evas_object_cursor_set(). - * - * @warning Previos setted cursor will be delete. + * @param[in] ee The Ecore_Evas + * @param[in] file The path to an image file for the cursor + * @param[in] layer The layer in which the cursor appears + * @param[in] hot_x The x coordinate of the cursor's hot spot + * @param[in] hot_y The y coordinate of the cursor's hot spot * * @see ecore_evas_object_cursor_set() - * @see ecore_evas_cursor_unset() */ EAPI void ecore_evas_cursor_set(Ecore_Evas *ee, const char *file, int layer, int hot_x, int hot_y); /** - * @brief Get information about an Ecore_Evas' cursor + * @brief Gets information about an Ecore_Evas' cursor. * - * @param ee The Ecore_Evas to set - * @param obj A pointer to an Evas_Object to place the cursor Evas_Object. - * @param layer A pointer to an int to place the cursor's layer in. - * @param hot_x A pointer to an int to place the cursor's hot_x coordinate in. - * @param hot_y A pointer to an int to place the cursor's hot_y coordinate in. + * @details This function queries information about an Ecore_Evas' cursor. * - * This function queries information about an Ecore_Evas' cursor. + * @param[in] ee The Ecore_Evas to set + * @param[out] obj A pointer to an Evas_Object to place the cursor Evas_Object + * @param[out] layer A pointer to an int to place the cursor's layer in + * @param[out] hot_x A pointer to an int to place the cursor's hot_x coordinate in + * @param[out] hot_y A pointer to an int to place the cursor's hot_y coordinate in * * @see ecore_evas_cursor_set() * @see ecore_evas_object_cursor_set() - * @see ecore_evas_cursor_unset() */ EAPI void ecore_evas_cursor_get(const Ecore_Evas *ee, Evas_Object **obj, int *layer, int *hot_x, int *hot_y); /** - * @brief Set the cursor of an Ecore_Evas - * - * @param ee The Ecore_Evas + * @brief Sets the cursor of an Ecore_Evas. * - * @param obj The Evas_Object which will be the cursor. - * @param layer The layer in which the cursor will appear. - * @param hot_x The x coordinate of the cursor's hot spot. - * @param hot_y The y coordinate of the cursor's hot spot. + * @details This function makes the mouse cursor over @a ee be the object specified by + * @a obj. The actual point within the object that the mouse is at is specified + * by @a hot_x and @a hot_y, which are coordinates with respect to the top left + * corner of the cursor object. * - * This function makes the mouse cursor over @p ee be the object specified by - * @p obj. The actual point within the object that the mouse is at is specified - * by @p hot_x and @p hot_y, which are coordinates with respect to the top left - * corner of the cursor object. Cursor object will be delete with the Ecore_Evas. + * @param[in] ee The Ecore_Evas + * @param[in] obj The Evas_Object which is the cursor + * @param[in] layer The layer in which the cursor appears + * @param[in] hot_x The x coordinate of the cursor's hot spot + * @param[in] hot_y The y coordinate of the cursor's hot spot * * @see ecore_evas_cursor_set() */ EAPI void ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int hot_x, int hot_y); /** - * @brief Unset the Ecore_Evas cursor - * - * @param ee The Ecore_Evas to unset the cursor. - * - * This function unsets the cursor from the Ecore_Evas, and returns the cursor - * object. If the cursor was set from ecore_evas_cursor_set(), this function - * returns the image. In this case, the image should be deleted when it is - * no longer needed. - * - * @see ecore_evas_cursor_set() - * @see ecore_evas_object_cursor_set() - * @since 1.11 - */ -EAPI Evas_Object* ecore_evas_cursor_unset(Ecore_Evas *ee); - -/** - * Tell the WM whether or not to ignore an Ecore_Evas' window + * @brief Tells the WM whether or not to ignore an Ecore_Evas' window. * - * @param ee The Ecore_Evas. - * @param on @c EINA_TRUE to ignore, @c EINA_FALSE to not. + * @details This function causes the window manager to ignore @a ee if @a on is + * @c EINA_TRUE, or not ignore @a ee if @a on is @c EINA_FALSE. * - * This function causes the window manager to ignore @p ee if @p on is - * @c EINA_TRUE, or not ignore @p ee if @p on is @c EINA_FALSE. + * @param[in] ee The Ecore_Evas + * @param[in] on Set @c EINA_TRUE to ignore, \n + * otherwise set @c EINA_FALSE to not ignore */ EAPI void ecore_evas_override_set(Ecore_Evas *ee, Eina_Bool on); /** - * Query whether an Ecore_Evas' window is overridden or not + * @brief Checks whether an Ecore_Evas window is overridden or not. * - * @param ee The Ecore_Evas to set. - * @return @c EINA_TRUE if @p ee is overridden, @c EINA_FALSE if not. - */ -EAPI Eina_Bool ecore_evas_override_get(const Ecore_Evas *ee); - -/** - * Set whether or not an Ecore_Evas' window should avoid damage - * - * @param ee The Ecore_Evas - * @param on The type of the damage management - * - * This option causes updates of the Ecore_Evas to be done on a pixmap, and - * then copied to the window, or the pixmap used directly on the window, - * depending on the setting. Possible options are: - * - * @li @ref ECORE_EVAS_AVOID_DAMAGE_NONE - every expose event triggers a new - * damage and consequently render of the affected area. The rendering of things - * happens directly on the window; - * - * @li @ref ECORE_EVAS_AVOID_DAMAGE_EXPOSE - there's a pixmap where everything - * is rendered into, and then copied to the window. On expose events, there's - * no need to render things again, just to copy the exposed region to the - * window; - * - * @li @ref ECORE_EVAS_AVOID_DAMAGE_BUILT_IN - there's the same pixmap as the - * previous one, but it is set as a "background pixmap" of the window. The - * rendered things appear directly on the window, with no need to copy - * anything, but would stay stored on the pixmap, so there's no need to render - * things again on expose events. This option can be faster than the previous - * one, but may lead to artifacts during resize of the window. - */ -EAPI void ecore_evas_avoid_damage_set(Ecore_Evas *ee, Ecore_Evas_Avoid_Damage_Type on); - -/** - * Query whether an Ecore_Evas' window avoids damage or not - * @param ee The Ecore_Evas to set - * @return The type of the damage management + * @param[in] ee The Ecore_Evas to set + * @return The type of the damage management * */ EAPI Ecore_Evas_Avoid_Damage_Type ecore_evas_avoid_damage_get(const Ecore_Evas *ee); /** - * Set the withdrawn state of an Ecore_Evas' window. - * @param ee The Ecore_Evas whose window's withdrawn state is set. - * @param withdrawn The Ecore_Evas window's new withdrawn state. + * @brief Sets the withdrawn state of an Ecore_Evas' window. + * + * @param[in] ee The Ecore_Evas whose window's withdrawn state is set + * @param[in] withdrawn Set @c EINA_TRUE to set the withdrawn state, \n + * otherwise set @c EINA_FALSE to not set the state * */ EAPI void ecore_evas_withdrawn_set(Ecore_Evas *ee, Eina_Bool withdrawn); /** - * Returns the withdrawn state of an Ecore_Evas' window. - * @param ee The Ecore_Evas whose window's withdrawn state is returned. - * @return The Ecore_Evas window's withdrawn state. + * @brief Gets the withdrawn state of an Ecore_Evas' window. + * + * @param[in] ee The Ecore_Evas whose window's withdrawn state is returned + * @return @c EINA_TRUE if the Ecore_Evas window's withdrawn state is state, \n + * otherwise @c EINA_FALSE if it is not state * */ EAPI Eina_Bool ecore_evas_withdrawn_get(const Ecore_Evas *ee); /** - * Set the sticky state of an Ecore_Evas window. + * @brief Sets the sticky state of an Ecore_Evas window. * - * @param ee The Ecore_Evas whose window's sticky state is set. - * @param sticky The Ecore_Evas window's new sticky state. + * @param[in] ee The Ecore_Evas whose window's sticky state is set + * @param[in] sticky Set @c EINA_TRUE to set the sticky state, \n + * otherwise set @c EINA_FALSE to not set it * */ EAPI void ecore_evas_sticky_set(Ecore_Evas *ee, Eina_Bool sticky); /** - * Returns the sticky state of an Ecore_Evas' window. + * @brief Gets the sticky state of an Ecore_Evas' window. * - * @param ee The Ecore_Evas whose window's sticky state is returned. - * @return The Ecore_Evas window's sticky state. + * @param[in] ee The Ecore_Evas whose window's sticky state is returned + * @return @c EINA_TRUE if the Ecore_Evas window's sticky state is set, \n + * otherwise @c EINA_FALSE if the state is not set * */ EAPI Eina_Bool ecore_evas_sticky_get(const Ecore_Evas *ee); /** - * Enable/disable manual render + * @brief Enable/disable manual render * - * @param ee An @c Ecore_Evas handle - * @param manual_render Enable/disable manual render. @c EINA_TRUE to enable - * manual render, @c EINA_FALSE to disable manual render. @c EINA_FALSE by - * default + * @details If @p manual_render is true, default ecore_evas render routine would be + * disabled and rendering will be done only manually. If @p manual_render is + * false, rendering will be done by default ecore_evas rendering routine, but + * still manual rendering is available. Call ecore_evas_manual_render() to + * force immediate render. * - * If @p manual_render is true, default ecore_evas render routine would be - * disabled and rendering will be done only manually. If @p manual_render is - * false, rendering will be done by default ecore_evas rendering routine, but - * still manual rendering is available. Call ecore_evas_manual_render() to - * force immediate render. + * @param[in] ee An @c Ecore_Evas handle + * @param[in] manual_render Enable/disable manual render. @c EINA_TRUE to enable + * manual render, @c EINA_FALSE to disable manual render. @c EINA_FALSE by + * default * * @see ecore_evas_manual_render_get() * @see ecore_evas_manual_render() @@ -2091,11 +2072,11 @@ EAPI Eina_Bool ecore_evas_sticky_get(const Ecore_Evas *ee); EAPI void ecore_evas_manual_render_set(Ecore_Evas *ee, Eina_Bool manual_render); /** - * Get enable/disable status of manual render + * @brief Get enable/disable status of manual render * - * @param ee An @c Ecore_Evas handle + * @param[in] ee An @c Ecore_Evas handle * @return @c EINA_TRUE if manual render is enabled, @c EINA_FALSE if manual - * render is disabled + * render is disabled * * @see ecore_evas_manual_render_set() * @see ecore_evas_manual_render() @@ -2103,61 +2084,67 @@ EAPI void ecore_evas_manual_render_set(Ecore_Evas *ee, Eina_Bool manual_r EAPI Eina_Bool ecore_evas_manual_render_get(const Ecore_Evas *ee); /** - * @brief Registers an @c Ecore_Evas to receive events through ecore_input_evas. + * @brief Registers an @c Ecore_Evas to receive events through ecore_input_evas. * - * @param ee The @c Ecore_Evas handle. + * @details This function calls ecore_event_window_register() with the @a ee as its @a + * id argument, @a window argument, and uses its @a Evas too. It is useful when + * no @a window information is available on a given @a Ecore_Evas backend. + * @since 1.1 * - * This function calls ecore_event_window_register() with the @p ee as its @c - * id argument, @c window argument, and uses its @c Evas too. It is useful when - * no @c window information is available on a given @c Ecore_Evas backend. + * @param[in] ee The @c Ecore_Evas handle * * @see ecore_evas_input_event_unregister() - * @since 1.1 */ EAPI void ecore_evas_input_event_register(Ecore_Evas *ee); + /** - * @brief Unregisters an @c Ecore_Evas receiving events through ecore_input_evas. + * @brief Unregisters an @c Ecore_Evas receiving events through ecore_input_evas. + * @since 1.1 * - * @param ee The @c Ecore_Evas handle. + * @param[in] ee The @c Ecore_Evas handle * * @see ecore_evas_input_event_register() - * @since 1.1 */ EAPI void ecore_evas_input_event_unregister(Ecore_Evas *ee); /** - * @brief Force immediate rendering on a given @c Ecore_Evas window - * - * @param ee An @c Ecore_Evas handle + * @brief Forces immediate rendering on a given @c Ecore_Evas window. * - * Use this call to forcefully flush the @p ee's canvas rendering - * pipeline, thus bring its window to an up to date state. + * @remarks Use this call to forcefully flush the @a ee's canvas rendering + * pipeline, thus bringing its window to an up-to-date state. + * @param[in] ee An @c Ecore_Evas handle */ EAPI void ecore_evas_manual_render(Ecore_Evas *ee); EAPI void ecore_evas_comp_sync_set(Ecore_Evas *ee, Eina_Bool do_sync); EAPI Eina_Bool ecore_evas_comp_sync_get(const Ecore_Evas *ee); /** - * @brief Get geometry of screen associated with this Ecore_Evas. + * @brief Gets geometry of screen associated with this Ecore_Evas. * - * @param ee The Ecore_Evas whose window's to query container screen geometry. - * @param x where to return the horizontal offset value. May be @c NULL. - * @param y where to return the vertical offset value. May be @c NULL. - * @param w where to return the width value. May be @c NULL. - * @param h where to return the height value. May be @c NULL. + * @since 1.1 * - * @since 1.1 + * @param[in] ee The Ecore_Evas whose window's to query container screen geometry + * @param[out] x The horizontal offset value that is returned \n + * This may be @c NULL. + * @param[out] y The vertical offset value that is returned \n + * This may be @c NULL. + * @param[out] w The width value that is returned \n + * This may be @c NULL. + * @param[out] h The height value \n + * This may be @c NULL. */ EAPI void ecore_evas_screen_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h); /** - * @brief Get the dpi of the screen the Ecore_Evas is primarily on. + * @brief Gets the DPI of the screen the Ecore_Evas is primarily on. * - * @param ee The Ecore_Evas whose window's to query. - * @param xdpi Pointer to integer to store horizontal DPI. May be @c NULL. - * @param ydpi Pointer to integer to store vertical DPI. May be @c NULL. + * @since 1.7 * - * @since 1.7 + * @param[in] ee The Ecore_Evas whose window's to query + * @param[out] xdpi The pointer to integer to store horizontal DPI \n + * This may be @c NULL. + * @param[out] ydpi The pointer to integer to store vertical DPI \n + * This may be @c NULL. */ EAPI void ecore_evas_screen_dpi_get(const Ecore_Evas *ee, int *xdpi, int *ydpi); @@ -2165,85 +2152,82 @@ EAPI void ecore_evas_draw_frame_set(Ecore_Evas *ee, Eina_Bool draw_frame) EAPI Eina_Bool ecore_evas_draw_frame_get(const Ecore_Evas *ee); /** - * @brief Associate the given object to this ecore evas. - * - * @param ee The Ecore_Evas to associate to @a obj - * @param obj The object to associate to @a ee - * @param flags The association flags. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * Association means that operations on one will affect the other, for - * example moving the object will move the window, resize the object will - * also affect the ecore evas window, hide and show applies as well. - * - * This is meant to simplify development, since you often need to associate - * these events with your "base" objects, background or bottom-most object. - * - * Be aware that some methods might not be what you would like, deleting - * either the window or the object will delete the other. If you want to - * change that behavior, let's say to hide window when it's closed, you - * must use ecore_evas_callback_delete_request_set() and set your own code, - * like ecore_evas_hide(). Just remember that if you override delete_request - * and still want to delete the window/object, you must do that yourself. - * - * Since we now define delete_request, deleting windows will not quit - * main loop, if you wish to do so, you should listen for EVAS_CALLBACK_FREE - * on the object, that way you get notified and you can call - * ecore_main_loop_quit(). - * - * Flags can be OR'ed of: - * @li ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events - * like delete, resize and move, but no stacking or layer are used. - * @li ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations will act - * on the Ecore_Evas, not the object. So evas_object_raise() will - * call ecore_evas_raise(). Relative operations (stack_above, stack_below) - * are still not implemented. - * @li ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations will act - * on the Ecore_Evas, not the object. So evas_object_layer_set() will - * call ecore_evas_layer_set(). - * @li ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete will delete the - * ecore_evas as well as delete_requests on the ecore_evas will delete - * etc. + * @brief Associates the given object to this ecore evas. + * + * @remarks Association means that operations on one affects the other. For + * example, moving the object moves the window, resizing the object + * also affects the ecore evas window, hide and show applies as well. + * + * @remarks This is meant to simplify development, since you often need to associate + * these events with your "base" objects, background or bottom-most object. + * + * @remarks Be aware that some methods might not be what you would like, deleting + * either the window or the object deletes the other. If you want to + * change that behavior, say to hide window when it is closed, you + * must use ecore_evas_callback_delete_request_set() and set your own code, + * like ecore_evas_hide(). Just remember that if you override delete_request + * and still want to delete the window or object, you must do that yourself. + * + * @remarks Since we now define delete_request, deleting windows does not quit + * main loop. If you wish to do so, you should listen for EVAS_CALLBACK_FREE + * on the object, that way you get notified and you can call + * ecore_main_loop_quit(). + * + * @remarks Flags can be OR'ed of: + * @li ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events + * like delete, resize and move, but no stacking or layer are used. + * @li ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations act + * on the Ecore_Evas, not the object. So evas_object_raise() + * calls ecore_evas_raise(). Relative operations (stack_above, stack_below) + * are still not implemented. + * @li ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations act + * on the Ecore_Evas, not the object. So evas_object_layer_set() + * calls ecore_evas_layer_set(). + * @li ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete deletes the + * ecore_evas and the delete_requests on the ecore_evas are also deleted. + * + * @param[in] ee The Ecore_Evas to associate to @a obj + * @param[in] obj The object to associate to @a ee + * @param[in] flags The association flags + * @return @c EINA_TRUE if associated successfully, \n + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_Associate_Flags flags); + /** - * @brief Cancel the association set with ecore_evas_object_associate(). + * @brief Cancels the association set with ecore_evas_object_associate(). * - * @param ee The Ecore_Evas to dissociate from @a obj - * @param obj The object to dissociate from @a ee - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * @param[in] ee The Ecore_Evas to dissociate from @a obj + * @param[in] obj The object to dissociate from @a ee + * @return @c EINA_TRUE if the association is cancelled successfully, + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool ecore_evas_object_dissociate(Ecore_Evas *ee, Evas_Object *obj); + /** - * @brief Get the object associated with @p ee + * @brief Gets the object associated with @a ee. * - * @param ee The Ecore_Evas to get the object from. - * @return The associated object, or @c NULL if there is no associated object. + * @param[in] ee The Ecore_Evas to get the object from. + * @return The associated object, \n + * otherwise @c NULL if there is no associated object */ EAPI Evas_Object *ecore_evas_object_associate_get(const Ecore_Evas *ee); -/* helper function to be used with ECORE_GETOPT_CALLBACK_*() */ +/* Helper function to be used with ECORE_GETOPT_CALLBACK_*() */ EAPI unsigned char ecore_getopt_callback_ecore_evas_list_engines(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage); /** - * @brief Get a list of all the ecore_evases. + * @brief Gets a list of all the ecore_evases. * - * @return A list of ecore_evases. + * @remarks The returned list of ecore evases is only valid until the canvases are + * destroyed (and should not be cached for instance). The list can be freed by + * just deleting the list. * - * The returned list of ecore evases is only valid until the canvases are - * destroyed (and should not be cached for instance). The list can be freed by - * just deleting the list. + * @return A list of ecore_evases */ EAPI Eina_List *ecore_evas_ecore_evas_list_get(void); -/** - * @brief Get a list of all the sub ecore_evases. - * - * @param ee Ecore_Evas to get the list from. - * @return A list of sub ecore_evases, or @c NULL if there is no sub ecore_evases. - */ -EAPI Eina_List *ecore_evas_sub_ecore_evas_list_get(const Ecore_Evas *ee); -/* specific calls to an x11 environment ecore_evas */ +/* Specific calls to an x11 environment ecore_evas */ EAPI void ecore_evas_x11_leader_set(Ecore_Evas *ee, Ecore_X_Window win); EAPI Ecore_X_Window ecore_evas_x11_leader_get(Ecore_Evas *ee); EAPI void ecore_evas_x11_leader_default_set(Ecore_Evas *ee); @@ -2255,6 +2239,7 @@ EAPI void ecore_evas_x11_shape_input_reset(Ecore_Evas *ee); EAPI void ecore_evas_x11_shape_input_apply(Ecore_Evas *ee); /** + * @internal * @defgroup Ecore_Evas_Ews Ecore_Evas Single Process Windowing System. * @ingroup Ecore_Evas_Group * @@ -2266,157 +2251,163 @@ EAPI void ecore_evas_x11_shape_input_apply(Ecore_Evas *ee); */ /** - * Sets the engine to be used by the backing store engine. + * @brief Sets the engine to be used by the backing store engine. + * @since 1.1 * - * @param engine The engine to be set. - * @param options The options of the engine to be set. - * @return @c EINA_TRUE on success, @c EINA_FALSE if ews is already in use. - * @since 1.1 + * @param[in] engine The engine to be set + * @param[in] options The options of the engine to be set + * @return @c EINA_TRUE if the engine is set successfully, \n + * otherwise @c EINA_FALSE if ews is already in use */ EAPI Eina_Bool ecore_evas_ews_engine_set(const char *engine, const char *options); /** - * Reconfigure the backing store used. + * @brief Reconfigures the backing store used. + * @since 1.1 * - * @param x The X coordinate to be used. - * @param y The Y coordinate to be used. - * @param w The width of the Ecore_Evas to setup. - * @param h The height of the Ecore_Evas to setup. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * @since 1.1 + * @param[in] x The X coordinate to be used + * @param[in] y The Y coordinate to be used + * @param[in] w The width of the Ecore_Evas to setup + * @param[in] h The height of the Ecore_Evas to setup + * @return @c EINA_TRUE if the backing store is reconfigured successfully, \n + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool ecore_evas_ews_setup(int x, int y, int w, int h); /** - * Return the internal backing store in use. + * @brief Gets the internal backing store in use. + * @since 1.1 * - * @return The internal backing store in use. - * @note this will forced it to be created, making future calls to - * ecore_evas_ews_engine_set() void. + * @remarks This forces it to be created, making future calls to + * ecore_evas_ews_engine_set() void. * + * @return The internal backing store in use * @see ecore_evas_ews_evas_get() - * @since 1.1 */ EAPI Ecore_Evas *ecore_evas_ews_ecore_evas_get(void); /** - * Return the internal backing store in use. + * @brief Gets the internal backing store in use. + * @since 1.1 * - * @return The internal backing store in use. - * @note this will forced it to be created, making future calls to - * ecore_evas_ews_engine_set() void. + * @remarks This forces it to be created, making future calls to + * ecore_evas_ews_engine_set() void. * + * @return The internal backing store in use * @see ecore_evas_ews_ecore_evas_get() - * @since 1.1 */ EAPI Evas *ecore_evas_ews_evas_get(void); /** - * Get the current background. + * @brief Gets the current background. + * + * @return The background object + * @see ecore_evas_ews_background_set() */ EAPI Evas_Object *ecore_evas_ews_background_get(void); /** - * Set the current background, must be created at evas ecore_evas_ews_evas_get() + * @brief Sets the current background. + * @details This must be created at evas ecore_evas_ews_evas_get(). * - * It will be kept at lowest layer (EVAS_LAYER_MIN) and below - * everything else. You can set any object, default is a black - * rectangle. + * @remarks It is kept at lowest layer (EVAS_LAYER_MIN) and below + * everything else. You can set any object, default is a black + * rectangle. * - * @note previous object will be deleted! - * @param o The Evas_Object for which to set the background. + * @remarks The previous object is deleted + * @param[in] o The Evas_Object for which to set the background */ EAPI void ecore_evas_ews_background_set(Evas_Object *o); /** - * Return all Ecore_Evas* created by EWS. + * @brief Gets all Ecore_Evas* created by EWS. + * @since 1.1 * - * @return An eina list of Ecore_evases. - e @note Do not change the returned list or its contents. - * @since 1.1 + * @remarks Do not change the returned list or its contents. + * + * @return An eina list of Ecore_evases */ EAPI const Eina_List *ecore_evas_ews_children_get(void); /** - * Set the identifier of the manager taking care of internal windows. + * @brief Sets the identifier of the manager taking care of internal windows. + * @since 1.1 * - * The ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE event is issued. Consider - * handling it to know if you should stop handling events yourself - * (ie: another manager took over) + * @remarks The ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE event is issued. Consider + * handling it to know if you should stop handling events yourself + * (that is, another manager took over). * - * @param manager any unique identifier address. + * @param[in] manager A unique identifier address * * @see ecore_evas_ews_manager_get() - * @since 1.1 */ EAPI void ecore_evas_ews_manager_set(const void *manager); /** - * Get the identifier of the manager taking care of internal windows. + * @brief Gets the identifier of the manager taking care of internal windows. + * @since 1.1 * - * @return the value set by ecore_evas_ews_manager_set() - * @since 1.1 + * @return The value set by ecore_evas_ews_manager_set() */ EAPI const void *ecore_evas_ews_manager_get(void); -EAPI extern int ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE; /**< manager was changed @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_ADD; /**< window was created @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_DEL; /**< window was deleted, pointer is already invalid but may be used as reference for further cleanup work. @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_RESIZE; /**< window was resized @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_MOVE; /**< window was moved @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_SHOW; /**< window become visible @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_HIDE; /**< window become hidden @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_FOCUS; /**< window was focused @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_UNFOCUS; /**< window lost focus @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_RAISE; /**< window was raised @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_LOWER; /**< window was lowered @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_ACTIVATE; /**< window was activated @since 1.1 */ - -EAPI extern int ECORE_EVAS_EWS_EVENT_ICONIFIED_CHANGE; /**< window minimized/iconified changed @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_MAXIMIZED_CHANGE; /**< window maximized changed @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_LAYER_CHANGE; /**< window layer changed @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_FULLSCREEN_CHANGE; /**< window fullscreen changed @since 1.1 */ -EAPI extern int ECORE_EVAS_EWS_EVENT_CONFIG_CHANGE; /**< some other window property changed (title, name, class, alpha, transparent, shaped...) @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE; /**< Manager is changed @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_ADD; /**< Window is created @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_DEL; /**< Window is deleted, pointer is already invalid but may be used as reference for further cleanup work. @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_RESIZE; /**< Window is resized @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_MOVE; /**< Window is moved @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_SHOW; /**< Window becomes visible @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_HIDE; /**< Window becomes hidden @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_FOCUS; /**< Window is focused @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_UNFOCUS; /**< Window lost focus @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_RAISE; /**< Window is raised @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_LOWER; /**< Window is lowered @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_ACTIVATE; /**< Window is activated @since 1.1 */ + +EAPI extern int ECORE_EVAS_EWS_EVENT_ICONIFIED_CHANGE; /**< Window minimized or iconified changed @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_MAXIMIZED_CHANGE; /**< Window maximized changed @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_LAYER_CHANGE; /**< Window layer changed @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_FULLSCREEN_CHANGE; /**< Window fullscreen changed @since 1.1 */ +EAPI extern int ECORE_EVAS_EWS_EVENT_CONFIG_CHANGE; /**< Some other window property changed (title, name, class, alpha, transparent, shaped etc) @since 1.1 */ /** * @} */ /** + * @internal * @defgroup Ecore_Evas_Extn External plug/socket infrastructure to remote canvases * @ingroup Ecore_Evas_Group * - * These functions allow 1 process to create a "socket" was pluged into which another + * These functions allow one process to create a "socket" that is plugged into which another * process can create a "plug" remotely to plug into. - * Socket can provides content for several plugs. + * Socket can provide content for several plugs. * This is best for small sized objects (about the size range - * of a small icon up to a few large icons). Sine the plug is actually an - * image object, you can fetch the pixel data + * of a small icon up to a few large icons). Since the plug is actually an + * image object, you can fetch the pixel data. * * @since 1.2 * @{ */ -EAPI extern int ECORE_EVAS_EXTN_CLIENT_ADD; /**< this event is received when a plug has connected to an extn socket @since 1.2 */ -EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< this event is received when a plug has disconnected from an extn socket @since 1.2 */ +EAPI extern int ECORE_EVAS_EXTN_CLIENT_ADD; /**< This event is received when a plug has connected to an extn socket @since 1.2 */ +EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< This event is received when a plug has disconnected from an extn socket @since 1.2 */ /** - * @brief Create a new Ecore_Evas canvas for the new external ecore evas socket + * @brief Creates a new Ecore_Evas canvas for the new external ecore evas socket. * - * @param w The width of the canvas, in pixels - * @param h The height of the canvas, in pixels - * @return A new @c Ecore_Evas instance or @c NULL, on failure + * @since 1.2 * - * This creates a new extn_socket canvas wrapper, with image data array - * @b bound to the ARGB format, 8 bits per pixel. + * @remarks This function creates a new extn_socket canvas wrapper, with image data array + * @b bound to the ARGB format, 8 bits per pixel. * - * If creation is successful, an Ecore_Evas handle is returned or @c NULL if - * creation fails. Also focus, show, hide etc. callbacks will also be called - * if the plug object is shown, or already visible on connect, or if it is - * hidden later, focused or unfocused. + * @remarks If creation is successful, an Ecore_Evas handle is returned or @c NULL if + * creation fails. Also callbacks such as focus, show, and hide are also called + * if the plug object is shown, or already visible on connect, or if it is + * hidden later, focused or unfocused. * - * This function has to be flowed by ecore_evas_extn_socket_listen(), - * for starting ecore ipc service. + * @remarks This function has to be flowed by ecore_evas_extn_socket_listen(), + * for starting ecore ipc service. * * @code * Eina_Bool res = EINA_FALSE; @@ -2437,133 +2428,203 @@ EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< this event is received when a p * if (!res) return; * @endcode * - * When a client(plug) connects, you will get the ECORE_EVAS_EXTN_CLIENT_ADD event - * in the ecore event queue, with event_info being the image object pointer - * passed as a void pointer. When a client disconnects you will get the - * ECORE_EVAS_EXTN_CLIENT_DEL event. + * @remarks When a client(plug) connects, you get the ECORE_EVAS_EXTN_CLIENT_ADD event + * in the ecore event queue, with event_info being the image object pointer + * passed as a void pointer. When a client disconnects you get the + * ECORE_EVAS_EXTN_CLIENT_DEL event. * - * You can set up event handles for these events as follows: + * @remarks You can set up event handles for these events as follows: * * @code - * static Eina_Bool client_add_cb(void *data, int event, void *event_info) + * static void client_add_cb(void *data, int event, void *event_info) * { - * Ecore_Evas *ee = event_info; - * printf("client is connected to external socket %p\n", ee); - * return ECORE_CALLBACK_PASS_ON; + * Evas_Object *obj = event_info; + * printf("client added to image object %p\n", obj); + * evas_object_show(obj); * } * - * static Eina_Bool client_del_cb(void *data, int event, void *event_info) + * static void client_del_cb(void *data, int event, void *event_info) * { - * Ecore_Evas *ee = event_info; - * printf("client is disconnected from external socket %p\n", ee); - * return ECORE_CALLBACK_PASS_ON; + * Evas_Object *obj = event_info; + * printf("client deleted from image object %p\n", obj); + * evas_object_hide(obj); * } * * void setup(void) * { - * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD, + * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD, * client_add_cb, NULL); - * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL, + * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL, * client_del_cb, NULL); * } * @endcode * - * Note that events come in later after the event happened. You may want to be - * careful as data structures you had associated with the image object - * may have been freed after deleting, but the object may still be around - * awating cleanup and thus still be valid.You can change the size with something like: + * @remarks Note that events come in later after the event happened. You may want to be + * careful as data structures you had associated with the image object + * may have been freed after deleting, but the object may still be around + * awaiting cleanup and thus still be valid. + * + * @param[in] w The width of the canvas, in pixels + * @param[in] h The height of the canvas, in pixels + * @return A new @c Ecore_Evas instance, \n + * otherwise @c NULL on failure * * @see ecore_evas_extn_socket_listen() * @see ecore_evas_extn_plug_new() * @see ecore_evas_extn_plug_object_data_lock() - * @see ecore_evas_extn_plug_object_data_unlock() - * - * @since 1.2 + * @see ecore_evas_extn_plug_object_data_unlock() */ EAPI Ecore_Evas *ecore_evas_extn_socket_new(int w, int h); /** - * @brief Create a socket to provide the service for external ecore evas - * socket. + * @brief Creates a socket to provide the service for external ecore evas socket. * - * @param ee The Ecore_Evas. - * @param svcname The name of the service to be advertised. ensure that it is - * unique (when combined with @p svcnum) otherwise creation may fail. - * @param svcnum A number (any value, @c 0 being the common default) to - * differentiate multiple instances of services with the same name. - * @param svcsys A boolean that if true, specifies to create a system-wide - * service all users can connect to, otherwise the service is private to the - * user ide that created the service. - * @return @c EINA_TRUE if creation is successful, @c EINA_FALSE if it does - * not. - * - * This creates socket specified by @p svcname, @p svcnum and @p svcsys. If - * creation is successful, @c EINA_TRUE is returned or @c EINA_FALSE if - * creation fails. + * @details This creates socket specified by @a svcname, @a svcnum and @a svcsys. If + * creation is successful, @c EINA_TRUE is returned or @c EINA_FALSE if + * creation fails. + * + * @since 1.2 + * + * @param[in] ee The Ecore_Evas + * @param[in] svcname The name of the service to be advertised \n + * Ensure that it is unique (when combined with @a svcnum). + * Otherwise creation may fail. + * @param[in] svcnum A number (any value, @c 0 being the common default) to + * differentiate multiple instances of services with the same name + * @param[in] svcsys Set @c EINA_TRUE to create a system-wide service all users can connect to, \n + * otherwise set @c EINA_FALSE if the service should be private to the + * user ID that created the service + * @return @c EINA_TRUE if created successfully, \n + * otherwise @c EINA_FALSE on failure * * @see ecore_evas_extn_socket_new() * @see ecore_evas_extn_plug_new() * @see ecore_evas_extn_plug_object_data_lock() * @see ecore_evas_extn_plug_object_data_unlock() - * - * @since 1.2 */ EAPI Eina_Bool ecore_evas_extn_socket_listen(Ecore_Evas *ee, const char *svcname, int svcnum, Eina_Bool svcsys); /** - * @brief Lock the pixel data so the socket cannot change it + * @brief Grabs a pointer to the actual pixels array of a given + * external ecore evas socket. + * + * @since 1.8 + * + * @param[in] ee The Ecore_Evas + * @return The pixel data + */ +EAPI void *ecore_evas_extn_socket_pixels_get(Ecore_Evas *ee); + +/** + * @brief Marks a region of the extn_socket canvas that has been updated. + * + * @since 1.8 + * + * @param[in] ee The Ecore_Evas + * @param[in] x The X-offset of the region to be updated + * @param[in] y The Y-offset of the region to be updated + * @param[in] w The width of the region to be updated + * @param[in] h The height of the region to be updated + */ +EAPI void ecore_evas_extn_socket_update_add(Ecore_Evas *ee, int x, int y, int w, int h); + +/** + * @brief Lock the pixel data so the plug cannot change it + * + * @param[in] ee The Ecore_Evas. + * + * @see ecore_evas_extn_socket_new() + * @see ecore_evas_extn_socket_unlock() + * + * @since 1.8 + */ +EAPI void ecore_evas_extn_socket_lock(Ecore_Evas *ee); + +/** + * @brief Unlock the pixel data so the plug can change it again + * + * @param[in] ee The Ecore_Evas. + * + * @see ecore_evas_extn_socket_new() + * @see ecore_evas_extn_socket_lock() + * + * @since 1.8 + */ +EAPI void ecore_evas_extn_socket_unlock(Ecore_Evas *ee); + +/** + * @brief Set the blocking about mouse events to Ecore Evas. * - * @param obj The image object returned by ecore_evas_extn_plug_new() to lock + * @param ee The Ecore_Evas. + * @param events_block The blocking about mouse events. * - * You may need to get the image pixel data with evas_object_image_data_get() - * from the image object, but need to ensure that it does not change while - * you are using the data. This function lets you set an advisory lock on the - * image data so the external plug process will not render to it or alter it. + * @see ecore_evas_extn_socket_events_block_get() * - * You should only hold the lock for just as long as you need to read out the - * image data or otherwise deal with it, and then unlock it with - * ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than - * 1 iteration of the main ecore loop will be problematic, so avoid it. Also - * forgetting to unlock may cause the socket process to freeze and thus create - * odd behavior. + * @since 1.11 + */ +EINA_DEPRECATED EAPI void ecore_evas_extn_socket_events_block_set(Ecore_Evas *ee, Eina_Bool events_block); + +/** + * @brief Get the blocking about mouse events to Ecore Evas. + * + * @param ee The Ecore_Evas. + + * @return The blocking about mouse events. + * + * @see ecore_evas_extn_socket_events_block_set() + * + * @since 1.11 + */ +EINA_DEPRECATED EAPI Eina_Bool ecore_evas_extn_socket_events_block_get(Ecore_Evas *ee); + +/** + * @brief Locks the pixel data so the socket cannot change it. + * @since 1.2 + * + * @remarks You may need to get the image pixel data with evas_object_image_data_get() + * from the image object, but need to ensure that it does not change while + * you are using the data. This function lets you set an advisory lock on the + * image data so the external plug process does not render to it or alter it. + * + * @remarks You should only hold the lock for just as long as you need to read out the + * image data or otherwise deal with it, and then unlock it with + * ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than + * one iteration of the main ecore loop is problematic, so avoid it. Also + * forgetting to unlock may cause the socket process to freeze and thus create + * odd behavior. + * + * @param[in] obj The image object returned by ecore_evas_extn_plug_new() to lock * * @see ecore_evas_extn_plug_new() * @see ecore_evas_extn_plug_object_data_unlock() - * - * @since 1.2 */ EAPI void ecore_evas_extn_plug_object_data_lock(Evas_Object *obj); /** - * @brief Unlock the pixel data so the socket can change it again. + * @brief Unlocks the pixel data so the socket can change it again. * - * @param obj The image object returned by ecore_evas_extn_plug_new() to unlock + * @details This function unlocks after an advisor lock has been taken by + * ecore_evas_extn_plug_object_data_lock(). + * @since 1.2 * - * This unlocks after an advisor lock has been taken by - * ecore_evas_extn_plug_object_data_lock(). + * @param[in] obj The image object returned by ecore_evas_extn_plug_new() to unlock * * @see ecore_evas_extn_plug_new() * @see ecore_evas_extn_plug_object_data_lock() - * - * @since 1.2 */ EAPI void ecore_evas_extn_plug_object_data_unlock(Evas_Object *obj); /** - * @brief Create a new external ecore evas plug - * - * @param ee_target The Ecore_Evas containing the canvas in which the new image object will live. - * @return An evas image object that will contain the image output of a socket. - * - * This creates an image object that will contain the output of another - * processes socket canvas when it connects. All input will be sent back to - * this process as well, effectively swallowing or placing the socket process - * in the canvas of the plug process in place of the image object. The image - * object by default is created to be filled (equivalent of - * evas_object_image_filled_add() on creation) so image content will scale - * to fill the image unless otherwise reconfigured. The Ecore_Evas size - * of the plug is the master size and determines size in pixels of the - * plug canvas. You can change the size with something like: + * @brief Creates a new external ecore evas plug. + * @details This creates an image object that contains the output of another + * processes socket canvas when it connects. All input is sent back to + * this process as well, effectively swallowing or placing the socket process + * in the canvas of the plug process in place of the image object. The image + * object by default is created to be filled (equivalent of + * evas_object_image_filled_add() on creation) so image content scales + * to fill the image unless otherwise reconfigured. The Ecore_Evas size + * of the plug is the master size and determines size in pixels of the + * plug canvas. You can change the size with something like: * * @code * Eina_Bool res = EINA_FALSE; @@ -2574,97 +2635,77 @@ EAPI void ecore_evas_extn_plug_object_data_unlock(Evas_Object *obj); * ecore_evas_resize(ee, 240, 400); * @endcode * + * @since 1.2 + * + * @param[in] ee_target The Ecore_Evas containing the canvas in which the new image object lives + * @return An evas image object that contains the image output of a socket + * * @see ecore_evas_extn_socket_new() * @see ecore_evas_extn_plug_connect() - * @since 1.2 */ EAPI Evas_Object *ecore_evas_extn_plug_new(Ecore_Evas *ee_target); /** - * @brief Connect an external ecore evas plug to service provided by external - * ecore evas socket. + * @brief Connects an external ecore evas plug to service provided by external + * ecore evas socket. * - * @param obj The Ecore_Evas containing the canvas in which the new image - * object will live. - * @param svcname The service name to connect to set up by the socket. - * @param svcnum The service number to connect to (set up by socket). - * @param svcsys Boolean to set if the service is a system one or not (set up - * by socket). - * @return @c EINA_TRUE if creation is successful, @c EINA_FALSE if it does - * not. + * @since 1.2 * - * @see ecore_evas_extn_plug_new() + * @param[in] obj The Ecore_Evas containing the canvas in which the new image + * object lives + * @param[in] svcname The service name to connect to set up by the socket + * @param[in] svcnum The service number to connect to (set up by socket) + * @param[in] svcsys Set @c EINA_TRUE to if the service is a system one, \n + * otherwise set @c EINA_FALSE if it is not a system one (set up by socket) + * @return @c EINA_TRUE if created successfully, + * otherwise @c EINA_FALSE on failure * - * @since 1.2 + * @see ecore_evas_extn_plug_new() */ EAPI Eina_Bool ecore_evas_extn_plug_connect(Evas_Object *obj, const char *svcname, int svcnum, Eina_Bool svcsys); /** - * @brief Retrieve the coordinates of the mouse pointer - * - * @param ee The Ecore_Evas containing the pointer - * @param x Pointer to integer to store horizontal coordinate. May be @c NULL. - * @param y Pointer to integer to store vertical coordinate. May be @c NULL. + * @brief Retrieve the Visual used for pixmap creation * * @since 1.8 - */ -EAPI void ecore_evas_pointer_xy_get(const Ecore_Evas *ee, Evas_Coord *x, Evas_Coord *y); - -/** - * @brief Retrieve the coordinates of the mouse pointer - * - * @param ee The Ecore_Evas containing the pointer - * @param x The horizontal coordinate to move the pointer to - * @param y The vertical coordinate to move the pointer to * - * @return @c EINA_TRUE on success, EINA_FALSE on failure. - * - * @since 1.8 - */ -EAPI Eina_Bool ecore_evas_pointer_warp(const Ecore_Evas *ee, Evas_Coord x, Evas_Coord y); - -/** - * @brief Retrieve the Visual used for pixmap creation - * - * @param ee The Ecore_Evas containing the pixmap + * @param[in] ee The Ecore_Evas containing the pixmap * * @return The Visual which was used when creating the pixmap * * @warning If and when this function is called depends on the underlying * windowing system. This function should only be called if the Ecore_Evas was * created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new - * - * @since 1.8 */ EAPI void *ecore_evas_pixmap_visual_get(const Ecore_Evas *ee); /** * @brief Retrieve the Colormap used for pixmap creation * - * @param ee The Ecore_Evas containing the pixmap + * @since 1.8 + * + * @param[in] ee The Ecore_Evas containing the pixmap * * @return The Colormap which was used when creating the pixmap * * @warning If and when this function is called depends on the underlying * windowing system. This function should only be called if the Ecore_Evas was * created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new - * - * @since 1.8 */ EAPI unsigned long ecore_evas_pixmap_colormap_get(const Ecore_Evas *ee); /** * @brief Retrieve the depth used for pixmap creation * - * @param ee The Ecore_Evas containing the pixmap + * @since 1.8 + * + * @param[in] ee The Ecore_Evas containing the pixmap * * @return The depth which was used when creating the pixmap * * @warning If and when this function is called depends on the underlying * windowing system. This function should only be called if the Ecore_Evas was * created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new - * - * @since 1.8 */ EAPI int ecore_evas_pixmap_depth_get(const Ecore_Evas *ee); diff --git a/src/lib/ecore_fb/Ecore_Fb.h b/src/lib/ecore_fb/Ecore_Fb.h index 69d37a49dd..fc73df42f8 100644 --- a/src/lib/ecore_fb/Ecore_Fb.h +++ b/src/lib/ecore_fb/Ecore_Fb.h @@ -18,15 +18,14 @@ #endif /* FIXME: - * maybe a new module? - * - code to get battery info - * - code to get thermal info + * Maybe a new module? + * - Code to get the battery info + * - Code to get the thermal info * ecore evas fb isn't good enough for weird things, like multiple fb's, same happens here. * backlight support using new kernel interface * absolute axis * joystick * ecore_fb_li_device_close_all ? or a shutdown of the subsystem? - * */ #ifdef __cplusplus @@ -34,23 +33,24 @@ extern "C" { #endif /** + * @internal * @defgroup Ecore_FB_Group Ecore_FB - Frame buffer convenience functions. - * @ingroup Ecore + * @ingroup Ecore_Group * - * Functions used to set up and shut down the Ecore_Framebuffer functions. + * @brief This group discusses the functions used to set up and shut down the Ecore_Framebuffer functions. * * @{ */ /** * @typedef Ecore_Fb_Input_Device - * Input device handler. + * @brief The structure type containing the Input device handler. */ typedef struct _Ecore_Fb_Input_Device Ecore_Fb_Input_Device; /** * @enum _Ecore_Fb_Input_Device_Cap - * Device capabilities. + * @brief Enumeration that defines the device capabilities. */ enum _Ecore_Fb_Input_Device_Cap { @@ -62,7 +62,7 @@ enum _Ecore_Fb_Input_Device_Cap /** * @typedef Ecore_Fb_Input_Device_Cap - * Device capabilities. + * @brief Enumeration that defines the device capabilities. */ typedef enum _Ecore_Fb_Input_Device_Cap Ecore_Fb_Input_Device_Cap; diff --git a/src/lib/ecore_file/Ecore_File.h b/src/lib/ecore_file/Ecore_File.h index 806ad87f84..35276ded2d 100644 --- a/src/lib/ecore_file/Ecore_File.h +++ b/src/lib/ecore_file/Ecore_File.h @@ -35,6 +35,7 @@ #endif /* ! _WIN32 */ /** + * @internal * @file Ecore_File.h * @brief Files utility functions */ @@ -44,66 +45,67 @@ extern "C" { #endif /** + * @internal * @defgroup Ecore_File_Group Ecore_File - Files and directories convenience functions - * @ingroup Ecore + * @ingroup Ecore_Group * * @{ */ /** * @typedef Ecore_File_Monitor - * Abstract type used when monitoring a directory. + * @brief The structure type containing the abstract type used to monitor a directory. */ typedef struct _Ecore_File_Monitor Ecore_File_Monitor; /** * @typedef Ecore_File_Download_Job - * Abstract type used when aborting a download. + * @brief The structure type containing the abstract type used to abort a download. */ typedef struct _Ecore_File_Download_Job Ecore_File_Download_Job; /** * @typedef _Ecore_File_Event - * The event type returned when a file or directory is monitored. + * @brief The structure type containing the event type returned when a file or directory is monitored. */ typedef enum _Ecore_File_Event { - ECORE_FILE_EVENT_NONE, /**< No event. */ - ECORE_FILE_EVENT_CREATED_FILE, /**< Created file event. */ - ECORE_FILE_EVENT_CREATED_DIRECTORY, /**< Created directory event. */ - ECORE_FILE_EVENT_DELETED_FILE, /**< Deleted file event. */ - ECORE_FILE_EVENT_DELETED_DIRECTORY, /**< Deleted directory event. */ - ECORE_FILE_EVENT_DELETED_SELF, /**< Deleted monitored directory event. */ - ECORE_FILE_EVENT_MODIFIED, /**< Modified file or directory event. */ + ECORE_FILE_EVENT_NONE, /**< No event */ + ECORE_FILE_EVENT_CREATED_FILE, /**< Created file event */ + ECORE_FILE_EVENT_CREATED_DIRECTORY, /**< Created directory event */ + ECORE_FILE_EVENT_DELETED_FILE, /**< Deleted file event */ + ECORE_FILE_EVENT_DELETED_DIRECTORY, /**< Deleted directory event */ + ECORE_FILE_EVENT_DELETED_SELF, /**< Deleted monitored directory event */ + ECORE_FILE_EVENT_MODIFIED, /**< Modified file or directory event */ ECORE_FILE_EVENT_CLOSED /**< Closed file event */ } Ecore_File_Event; /** * @typedef Ecore_File_Monitor_Cb - * Callback type used when a monitored directory has changes. + * @brief Called to be used when a monitored directory has changed. */ typedef void (*Ecore_File_Monitor_Cb)(void *data, Ecore_File_Monitor *em, Ecore_File_Event event, const char *path); /** * @typedef Ecore_File_Download_Completion_Cb - * Callback type used when a download is finished. + * @brief Called to be used when a download has finished. */ typedef void (*Ecore_File_Download_Completion_Cb)(void *data, const char *file, int status); /** * @typedef _Ecore_File_Progress_Return - * What to do with the download as a return from the - * Ecore_File_Download_Progress_Cb function, if provided. + * @brief Enumeration on what to do with the download as a return from the + * Ecore_File_Download_Progress_Cb function, if provided. */ typedef enum _Ecore_File_Progress_Return { - ECORE_FILE_PROGRESS_CONTINUE = 0, /**< Continue the download. */ - ECORE_FILE_PROGRESS_ABORT = 1 /**< Abort the download. */ + ECORE_FILE_PROGRESS_CONTINUE = 0, /**< Continue the download */ + ECORE_FILE_PROGRESS_ABORT = 1 /**< Abort the download */ } Ecore_File_Progress_Return; /** * @typedef Ecore_File_Download_Progress_Cb - * Callback type used while a download is in progress. + * @brief Called to be used while a download is in progress. */ typedef int (*Ecore_File_Download_Progress_Cb)(void *data, const char *file, @@ -140,6 +142,7 @@ EAPI Eina_Bool ecore_file_can_write (const char *file); EAPI Eina_Bool ecore_file_can_exec (const char *file); EAPI char *ecore_file_readlink (const char *link); EAPI Eina_List *ecore_file_ls (const char *dir); +EAPI Eina_Iterator *ecore_file_ls_iterator (const char *dir); EAPI char *ecore_file_app_exe_get (const char *app); EAPI char *ecore_file_escape_name (const char *filename); EAPI char *ecore_file_strip_ext (const char *file); diff --git a/src/lib/ecore_imf/Ecore_IMF.h b/src/lib/ecore_imf/Ecore_IMF.h index 5618f3130d..1615374872 100644 --- a/src/lib/ecore_imf/Ecore_IMF.h +++ b/src/lib/ecore_imf/Ecore_IMF.h @@ -34,68 +34,57 @@ extern "C" { #endif /** - * @defgroup Ecore_IMF_Lib_Group Ecore_IMF - Ecore Input Method Library Functions - * @ingroup Ecore + * @internal + * @defgroup Ecore_IMF_Group Ecore_IMF - Ecore Input Method Library Functions + * @ingroup Ecore_Group * * Utility functions that set up and shut down the Ecore Input Method * library. + * + * @{ */ /** + * @internal * @defgroup Ecore_IMF_Context_Group Ecore Input Method Context Functions - * @ingroup Ecore_IMF_Lib_Group + * @ingroup Ecore_IMF_Group * - * Functions that operate on Ecore Input Method Context objects. + * @brief This group discusses the functions that operate on Ecore Input Method Context objects. - * Ecore Input Method Context Function defines the interface for EFL input methods. - * An input method is used by EFL text input widgets like elm_entry - * (based on edje_entry) to map from key events to Unicode character strings. - * - * The default input method can be set through setting the ECORE_IMF_MODULE environment variable. - * eg) export ECORE_IMF_MODULE=xim (or scim or ibus) + * @remarks Ecore Input Method Context Function defines the interface for EFL input methods. + * An input method is used by EFL text input widgets like elm_entry + * (based on edje_entry) to map from key events to Unicode character strings. * - * An input method may consume multiple key events in sequence and finally output the composed result. - * This is called preediting, and an input method may provide feedback about - * this process by displaying the intermediate composition states as preedit text. + * @remarks The default input method can be set through setting the ECORE_IMF_MODULE environment variable. + * eg: export ECORE_IMF_MODULE=xim (or scim or ibus) * - * Immodule is plugin to connect your application and input method framework such as SCIM, ibus, and so on.@n - * ecore_imf_init() should be called to initialize and load immodule.@n - * ecore_imf_shutdown() is used for shutdowning and unloading immodule. + * @remarks An input method may consume multiple key events in sequence and finally give the composed result as output. + * This is called preediting, and an input method may provide feedback about + * this process by displaying the intermediate composition states as preedit text. * - * An example of usage of these functions can be found at: - * @li @ref ecore_imf_example_c - */ - -/** - * @addtogroup Ecore_IMF_Context_Group + * @remarks Immodule is a plugin to connect your application and input method framework such as SCIM, ibus, and so on. \n + * ecore_imf_init() should be called to initialize and load immodule. \n + * ecore_imf_shutdown() is used to shutdown and unload immodule. * * @{ */ /** - * @example ecore_imf_example.c - * Show how to write simple editor using the Ecore_IMF library - */ - -/* ecore_imf_context_input_panel_event_callback_add() flag */ - -/** - * @typedef Ecore_IMF_Input_Panel_Event - * Enum containing input panel events. + * @brief Enumeration of Ecore IMF Input Panel State type + * @see ecore_imf_context_input_panel_event_callback_add */ typedef enum { - ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< called when the state of the input panel is changed. @since 1.7 */ - ECORE_IMF_INPUT_PANEL_LANGUAGE_EVENT, /**< called when the language of the input panel is changed. @since 1.7 */ - ECORE_IMF_INPUT_PANEL_SHIFT_MODE_EVENT, /**< called when the shift key state of the input panel is changed @since 1.7 */ - ECORE_IMF_INPUT_PANEL_GEOMETRY_EVENT, /**< called when the size of the input panel is changed. @since 1.7 */ - ECORE_IMF_CANDIDATE_PANEL_STATE_EVENT, /**< called when the state of the candidate word panel is changed. @since 1.7 */ - ECORE_IMF_CANDIDATE_PANEL_GEOMETRY_EVENT /**< called when the size of the candidate word panel is changed. @since 1.7 */ + ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< Called when the state of the input panel is changed @since 1.7 */ + ECORE_IMF_INPUT_PANEL_LANGUAGE_EVENT, /**< Called when the language of the input panel is changed @since 1.7 */ + ECORE_IMF_INPUT_PANEL_SHIFT_MODE_EVENT, /**< Called when the shift key state of the input panel is changed @since 1.7 */ + ECORE_IMF_INPUT_PANEL_GEOMETRY_EVENT, /**< Called when the size of the input panel is changed @since 1.7 */ + ECORE_IMF_CANDIDATE_PANEL_STATE_EVENT, /**< Called when the state of the candidate word panel is changed @since 1.7 */ + ECORE_IMF_CANDIDATE_PANEL_GEOMETRY_EVENT /**< Called when the size of the candidate word panel is changed @since 1.7 */ } Ecore_IMF_Input_Panel_Event; /** - * @typedef Ecore_IMF_Input_Panel_State - * Enum containing input panel state notifications. + * @brief Enumeration of Ecore IMF Input Panel State type */ typedef enum { @@ -105,8 +94,7 @@ typedef enum } Ecore_IMF_Input_Panel_State; /** - * @typedef Ecore_IMF_Input_Panel_Shift_Mode - * Enum containing input shift mode states. + * @brief Enumeration of Ecore IMF Input Panel Shift Mode type */ typedef enum { @@ -115,8 +103,7 @@ typedef enum } Ecore_IMF_Input_Panel_Shift_Mode; /** - * @typedef Ecore_IMF_Candidate_Panel_State - * Enum containing candidate word panel state notifications. + * @brief Enumeration of Ecore IMF Candidate Panel type */ typedef enum { @@ -132,7 +119,7 @@ typedef struct _Ecore_IMF_Event_Commit Ecore_IMF_Event_Commit; typedef struct _Ecore_IMF_Event_Delete_Surrounding Ecore_IMF_Event_Delete_Surrounding; typedef struct _Ecore_IMF_Event_Selection Ecore_IMF_Event_Selection; -/* Events to filter */ +/* Events to the filter */ typedef struct _Ecore_IMF_Event_Mouse_Down Ecore_IMF_Event_Mouse_Down; typedef struct _Ecore_IMF_Event_Mouse_Up Ecore_IMF_Event_Mouse_Up; typedef struct _Ecore_IMF_Event_Mouse_In Ecore_IMF_Event_Mouse_In; @@ -145,7 +132,7 @@ typedef union _Ecore_IMF_Event Ecore_IMF_Event; typedef struct _Ecore_IMF_Context Ecore_IMF_Context; /**< An Input Method Context */ typedef struct _Ecore_IMF_Context_Class Ecore_IMF_Context_Class; /**< An Input Method Context class */ -typedef struct _Ecore_IMF_Context_Info Ecore_IMF_Context_Info; /**< An Input Method Context info */ +typedef struct _Ecore_IMF_Context_Info Ecore_IMF_Context_Info; /**< Input Method Context info */ /* Preedit attribute info */ typedef struct _Ecore_IMF_Preedit_Attr Ecore_IMF_Preedit_Attr; @@ -156,27 +143,20 @@ EAPI extern int ECORE_IMF_EVENT_PREEDIT_CHANGED; EAPI extern int ECORE_IMF_EVENT_COMMIT; EAPI extern int ECORE_IMF_EVENT_DELETE_SURROUNDING; -/** - * @typedef Ecore_IMF_Event_Cb - * - * @brief Called when a Ecore_IMF event happens. - * - * @see ecore_imf_context_event_callback_add() - */ typedef void (*Ecore_IMF_Event_Cb) (void *data, Ecore_IMF_Context *ctx, void *event_info); /** * @typedef Ecore_IMF_Callback_Type * - * Ecore IMF Event callback types. + * @brief Enumeration that defines the Ecore IMF Event callback types. * * @see ecore_imf_context_event_callback_add() */ typedef enum { - ECORE_IMF_CALLBACK_PREEDIT_START, /**< "PREEDIT_START" is called when a new preediting sequence starts. @since 1.2 */ - ECORE_IMF_CALLBACK_PREEDIT_END, /**< "PREEDIT_END" is called when a preediting sequence has been completed or canceled. @since 1.2 */ - ECORE_IMF_CALLBACK_PREEDIT_CHANGED, /**< "PREEDIT_CHANGED" is called whenever the preedit sequence currently being entered has changed. @since 1.2 */ + ECORE_IMF_CALLBACK_PREEDIT_START, /**< "PREEDIT_START" is called when a new preediting sequence starts @since 1.2 */ + ECORE_IMF_CALLBACK_PREEDIT_END, /**< "PREEDIT_END" is called when a preediting sequence has been completed or cancelled @since 1.2 */ + ECORE_IMF_CALLBACK_PREEDIT_CHANGED, /**< "PREEDIT_CHANGED" is called whenever the preedit sequence currently being entered has changed @since 1.2 */ ECORE_IMF_CALLBACK_COMMIT, /**< "COMMIT" is called when a complete input sequence has been entered by the user @since 1.2 */ ECORE_IMF_CALLBACK_DELETE_SURROUNDING, /**< "DELETE_SURROUNDING" is called when the input method needs to delete all or part of the context surrounding the cursor @since 1.2 */ ECORE_IMF_CALLBACK_SELECTION_SET, /**< "SELECTION_SET" is called when the input method needs to set the selection @since 1.9 */ @@ -186,7 +166,7 @@ typedef enum /** * @typedef Ecore_IMF_Event_Type * - * Ecore IMF event types. + * @brief Enumeration that defines the Ecore IMF event types. * * @see ecore_imf_context_filter_event() */ @@ -203,7 +183,7 @@ typedef enum } Ecore_IMF_Event_Type; /** * @typedef Ecore_IMF_Keyboard_Modifiers - * Type for Ecore_IMF keyboard modifiers + * @brief Enumeration that defines the types of Ecore_IMF keyboard modifiers. */ typedef enum { @@ -217,7 +197,7 @@ typedef enum /** * @typedef Ecore_IMF_Keyboard_Locks - * Type for Ecore_IMF keyboard locks + * @brief Enumeration that defines the types of Ecore_IMF keyboard locks. */ typedef enum { @@ -229,7 +209,7 @@ typedef enum /** * @typedef Ecore_IMF_Mouse_Flags - * Type for Ecore_IMF mouse flags + * @brief Enumeration that defines the types of Ecore_IMF mouse flags. */ typedef enum { @@ -238,10 +218,6 @@ typedef enum ECORE_IMF_MOUSE_TRIPLE_CLICK = 1 << 1 /**< A triple click */ } Ecore_IMF_Mouse_Flags; -/** - * @typedef Ecore_IMF_Input_Mode - * Type for Ecore_IMF input mode - */ typedef enum { ECORE_IMF_INPUT_MODE_ALPHA = 1 << 0, @@ -257,7 +233,7 @@ typedef enum /** * @typedef Ecore_IMF_Preedit_Type * - * Ecore IMF Preedit style types + * @brief Enumeration that defines the Ecore IMF Preedit style types. * * @see ecore_imf_context_preedit_string_with_attributes_get() */ @@ -276,22 +252,22 @@ typedef enum /** * @typedef Ecore_IMF_Autocapital_Type * - * Autocapitalization Types. + * @brief Enumeration that defines the auto-capitalization types. * * @see ecore_imf_context_autocapital_type_set() */ typedef enum { ECORE_IMF_AUTOCAPITAL_TYPE_NONE, /**< No auto-capitalization when typing @since 1.1 */ - ECORE_IMF_AUTOCAPITAL_TYPE_WORD, /**< Autocapitalize each word typed @since 1.1 */ - ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE, /**< Autocapitalize the start of each sentence @since 1.1 */ - ECORE_IMF_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Autocapitalize all letters @since 1.1 */ + ECORE_IMF_AUTOCAPITAL_TYPE_WORD, /**< Auto-capitalize each type word @since 1.1 */ + ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE, /**< Auto-capitalize the start of each sentence @since 1.1 */ + ECORE_IMF_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Auto-capitalize all letters @since 1.1 */ } Ecore_IMF_Autocapital_Type; /** * @typedef Ecore_IMF_Input_Panel_Layout * - * Input panel (virtual keyboard) layout types. + * @brief Enumeration that defines the input panel (virtual keyboard) layout types. * * @see ecore_imf_context_input_panel_layout_set() */ @@ -307,8 +283,8 @@ typedef enum ECORE_IMF_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number Only layout */ ECORE_IMF_INPUT_PANEL_LAYOUT_INVALID, /**< Never use this */ ECORE_IMF_INPUT_PANEL_LAYOUT_HEX, /**< Hexadecimal layout @since 1.2 */ - ECORE_IMF_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout including ESC, Alt, Ctrl key, so on (no auto-correct, no auto-capitalization) @since 1.2 */ - ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD, /**< Like normal, but no auto-correct, no auto-capitalization etc. @since 1.2 */ + ECORE_IMF_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout including the ESC, Alt, Ctrl key, and so on (no auto-correct, no auto-capitalization) @since 1.2 */ + ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD, /**< Like normal, but no auto-correct, no auto-capitalization, and so on @since 1.2 */ ECORE_IMF_INPUT_PANEL_LAYOUT_DATETIME, /**< Date and time layout @since 1.8 */ ECORE_IMF_INPUT_PANEL_LAYOUT_EMOTICON /**< Emoticon layout @since 1.10 */ } Ecore_IMF_Input_Panel_Layout; @@ -316,7 +292,7 @@ typedef enum /** * @typedef Ecore_IMF_Input_Panel_Lang * - * Input panel (virtual keyboard) language modes. + * @brief Enumeration that defines the input panel (virtual keyboard) language modes. * * @see ecore_imf_context_input_panel_language_set() */ @@ -329,7 +305,7 @@ typedef enum /** * @typedef Ecore_IMF_Input_Panel_Return_Key_Type * - * "Return" Key types on the input panel (virtual keyboard). + * @brief Enumeration that defines the "Return" key types on the input panel (virtual keyboard). * * @see ecore_imf_context_input_panel_return_key_type_set() */ @@ -378,6 +354,7 @@ enum ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NORMAL, /**< The normal password layout @since 1.12 */ ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY /**< The password layout to allow only number @since 1.12 */ }; + /** * @typedef Ecore_IMF_BiDi_Direction * @brief Enumeration that defines the types of Ecore_IMF bidirectionality @@ -385,52 +362,32 @@ enum */ typedef enum { - ECORE_IMF_BIDI_DIRECTION_NEUTRAL, /**< The Neutral mode @since 1.12 */ + ECORE_IMF_BIDI_DIRECTION_NEUTRAL, /**< The neutral mode @since 1.12 */ ECORE_IMF_BIDI_DIRECTION_LTR, /**< The Left to Right mode @since 1.12 */ ECORE_IMF_BIDI_DIRECTION_RTL /**< The Right to Left mode @since 1.12 */ } Ecore_IMF_BiDi_Direction; -/** - * @struct _Ecore_IMF_Event_Preedit_Start - * @brief The structure type used with the Preedit_Start Input Method event - */ struct _Ecore_IMF_Event_Preedit_Start { Ecore_IMF_Context *ctx; }; -/** - * @struct _Ecore_IMF_Event_Preedit_End - * @brief The structure type used with the Preedit_End Input Method event - */ struct _Ecore_IMF_Event_Preedit_End { Ecore_IMF_Context *ctx; }; -/** - * @struct _Ecore_IMF_Event_Preedit_Changed - * @brief The structure type used with the Preedit_Changed Input Method event - */ struct _Ecore_IMF_Event_Preedit_Changed { Ecore_IMF_Context *ctx; }; -/** - * @struct _Ecore_IMF_Event_Commit - * @brief The structure type used with the Commit Input Method event - */ struct _Ecore_IMF_Event_Commit { Ecore_IMF_Context *ctx; char *str; }; -/** - * @struct _Ecore_IMF_Event_Delete_Surrounding - * @brief The structure type used with the Delete_Surrounding Input Method event - */ struct _Ecore_IMF_Event_Delete_Surrounding { Ecore_IMF_Context *ctx; @@ -438,10 +395,6 @@ struct _Ecore_IMF_Event_Delete_Surrounding int n_chars; }; -/** - * @struct _Ecore_IMF_Event_Selection - * @brief The structure type used with the Selection Input Method event - */ struct _Ecore_IMF_Event_Selection { Ecore_IMF_Context *ctx; @@ -449,48 +402,36 @@ struct _Ecore_IMF_Event_Selection int end; }; -/** - * @struct _Ecore_IMF_Event_Mouse_Down - * @brief The structure type used with the Mouse_Down event - */ struct _Ecore_IMF_Event_Mouse_Down { - int button; /**< The button which has been pressed */ + int button; /**< The button that has been pressed */ struct { int x, y; } output; struct { int x, y; } canvas; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ - Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding the mouse click (single, double or triple click) */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ + Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding to a mouse click (single, double, or triple click) */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Mouse_Up - * @brief The structure type used with the Mouse_Up event - */ struct _Ecore_IMF_Event_Mouse_Up { - int button; /**< The button which has been pressed */ + int button; /**< The button that has been pressed */ struct { int x, y; } output; struct { int x, y; } canvas; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ - Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding the mouse click (single, double or triple click) */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ + Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding to a mouse click (single, double, or triple click) */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Mouse_In - * @brief The structure type used with the Mouse_In event - */ struct _Ecore_IMF_Event_Mouse_In { int buttons; @@ -500,15 +441,11 @@ struct _Ecore_IMF_Event_Mouse_In struct { int x, y; } canvas; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Mouse_Out - * @brief The structure type used with the Mouse_Out event - */ struct _Ecore_IMF_Event_Mouse_Out { int buttons; @@ -518,15 +455,11 @@ struct _Ecore_IMF_Event_Mouse_Out struct { int x, y; } canvas; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Mouse_Move - * @brief The structure type used with the Mouse_Move event - */ struct _Ecore_IMF_Event_Mouse_Move { int buttons; @@ -538,15 +471,11 @@ struct _Ecore_IMF_Event_Mouse_Move int x, y; } canvas; } cur, prev; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Mouse_Wheel - * @brief The structure type used with the Mouse_Wheel event - */ struct _Ecore_IMF_Event_Mouse_Wheel { int direction; /* 0 = default up/down wheel */ @@ -557,44 +486,33 @@ struct _Ecore_IMF_Event_Mouse_Wheel struct { int x, y; } canvas; - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Key_Down - * @brief The structure type used with the Key_Down event - */ struct _Ecore_IMF_Event_Key_Down { - const char *keyname; /**< The string name of the key pressed */ - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + const char *keyname; /**< The string name of the key that has been pressed */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ const char *key; /**< The logical key : (eg shift+1 == exclamation) */ const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */ const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @struct _Ecore_IMF_Event_Key_Up - * @brief The structure type used with the Key_Up event - */ struct _Ecore_IMF_Event_Key_Up { - const char *keyname; /**< The string name of the key pressed */ - Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */ - Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */ + const char *keyname; /**< The string name of the key that has been pressed */ + Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */ + Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */ const char *key; /**< The logical key : (eg shift+1 == exclamation) */ const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */ const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */ unsigned int timestamp; /**< The timestamp when the event occurred */ }; -/** - * @brief A union of IMF events. - */ union _Ecore_IMF_Event { Ecore_IMF_Event_Mouse_Down mouse_down; @@ -607,171 +525,124 @@ union _Ecore_IMF_Event Ecore_IMF_Event_Key_Up key_up; }; -/** - * @struct _Ecore_IMF_Preedit_Attr - * @brief Structure that contains preedit attribute information. - */ struct _Ecore_IMF_Preedit_Attr { - Ecore_IMF_Preedit_Type preedit_type; /**< preedit style type */ - unsigned int start_index; /**< start index of the range (in bytes) */ - unsigned int end_index; /**< end index of the range (in bytes) */ + Ecore_IMF_Preedit_Type preedit_type; /**< The preedit style type */ + unsigned int start_index; /**< The start index of the range (in bytes) */ + unsigned int end_index; /**< The end index of the range (in bytes) */ }; -/** - * @struct _Ecore_IMF_Context_Class - * @brief Structure used when creating a new Input Method Context. This - * structure is mainly used by modules implementing the Input Method Context - * interface. - * - */ struct _Ecore_IMF_Context_Class { - void (*add) (Ecore_IMF_Context *ctx); /**< Create the Input Method Context */ - void (*del) (Ecore_IMF_Context *ctx); /**< Delete the Input Method Context */ - void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); /**< Set the client window for the Input Method Context */ - void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); /**< Set the client canvas for the Input Method Context */ - void (*show) (Ecore_IMF_Context *ctx); /**< Show the Input Method Context */ - void (*hide) (Ecore_IMF_Context *ctx); /**< Hide the Input Method Context */ - void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); /**< Return current preedit string and cursor position */ - void (*focus_in) (Ecore_IMF_Context *ctx); /**< Input Method context widget has gained focus */ - void (*focus_out) (Ecore_IMF_Context *ctx); /**< Input Method context widget has lost focus */ - void (*reset) (Ecore_IMF_Context *ctx); /**< A change has been made */ - void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); /**< Cursor position changed */ - void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); /**< Use preedit string to display feedback */ - void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); /**< Set the input mode */ - Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); /**< Internally handle an event */ - void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); /**< return current preedit string, attributes, and cursor position */ - void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); /**< Allow text prediction */ - void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); /**< Set auto-capitalization type */ - void (*control_panel_show) (Ecore_IMF_Context *ctx); /**< Show the control panel */ - void (*control_panel_hide) (Ecore_IMF_Context *ctx); /**< Hide the control panel */ - void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); /**< Set the layout of the input panel */ - Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); /**< Return the current layout of the input panel */ - void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); /**< Set the language of the input panel */ - Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); /**< Get the current language of the input panel */ - void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); /**< Set the cursor location */ - void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); /**< Set panel-specific data to the input panel */ - void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); /**< Get current panel-specific data from the input panel */ - void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); /**< Set the return key theme of the input panel based on return key type provided */ - void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); /**< Disable return key of the input panel */ - void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); /**< Set input panel caps lock mode */ - void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return input panel geometry */ - Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); /**< Return input panel state */ - void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); /**< Add a callback on input panel state,language,mode change */ - void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); /**< Delete the input panel event callback */ - void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); /**< Return the current language locale */ - void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return the candidate panel geometry */ - void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); /**< Sets input hint to fine-tune input methods behavior */ - void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); /**< Set bidirectionality at the cursor position */ + void (*add) (Ecore_IMF_Context *ctx); + void (*del) (Ecore_IMF_Context *ctx); + void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); + void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); + void (*show) (Ecore_IMF_Context *ctx); + void (*hide) (Ecore_IMF_Context *ctx); + void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); + void (*focus_in) (Ecore_IMF_Context *ctx); + void (*focus_out) (Ecore_IMF_Context *ctx); + void (*reset) (Ecore_IMF_Context *ctx); + void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); + void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); + void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); + Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); + void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); + void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); + void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); + void (*control_panel_show) (Ecore_IMF_Context *ctx); + void (*control_panel_hide) (Ecore_IMF_Context *ctx); + void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); + Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); + void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); + Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); + void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); + void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); + void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); + void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); + void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); + void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); + void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); + Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); + void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); + void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); + void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); + void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); + void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); + void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); }; -/** - * @struct _Ecore_IMF_Context_Info - * @brief A IMF structure containing context information. - */ struct _Ecore_IMF_Context_Info { - const char *id; /* ID */ - const char *description; /* Human readable description */ - const char *default_locales; /* Languages for which this context is the default, separated by : */ - const char *canvas_type; /* The canvas type used by the input method. Eg.: evas */ - int canvas_required; /* Whether the canvas usage is required for this input method */ + const char *id; /**< ID */ + const char *description; /**< Human readable description */ + const char *default_locales; /**< Languages for which this context is the default, separated by : */ + const char *canvas_type; /**< The canvas type used by the input method. Eg.: evas */ + int canvas_required; /**< Whether canvas usage is required for this input method */ }; /** - * @} - */ - -/** - * Initialises the Ecore_IMF library. - * @return Number of times the library has been initialised without being - * shut down. - * @ingroup Ecore_IMF_Lib_Group + * @brief Initialises the Ecore_IMF library. + * + * @return The number of times the library has been initialised without being + * shut down + * @ingroup Ecore_IMF_Group */ EAPI int ecore_imf_init(void); /** - * Shuts down the Ecore_IMF library. - * @return Number of times the library has been initialised without being - * shut down. - * @ingroup Ecore_IMF_Lib_Group + * @brief Shuts down the Ecore_IMF library. + * + * @return The number of times the library has been initialised without being + * shut down + * @ingroup Ecore_IMF_Group */ EAPI int ecore_imf_shutdown(void); -/** - * Register an Ecore_IMF module. - * - * @param info An Ecore_IMF_Context_Info structure - * @param imf_module_create A function to call at the creation - * @param imf_module_exit A function to call when exiting - * - * @ingroup Ecore_IMF_Lib_Group - */ EAPI void ecore_imf_module_register(const Ecore_IMF_Context_Info *info, Ecore_IMF_Context *(*imf_module_create)(void), Ecore_IMF_Context *(*imf_module_exit)(void)); /** - * Hide the input panel. - * @return EINA_TRUE if the input panel will be hidden - EINA_FALSE if the input panel is already in hidden state - * @ingroup Ecore_IMF_Lib_Group + * @brief Hides the input panel. + * * @since 1.8.0 + * + * @return @c EINA_TRUE if the input panel is hidden, + * otherwise @c EINA_FALSE if the input panel is already in the hidden state + * @ingroup Ecore_IMF_Group */ EAPI Eina_Bool ecore_imf_input_panel_hide(void); /** - * Get the list of the available Input Method Context ids. + * @brief Gets the list of available Input Method Context IDs. * - * Note that the caller is responsible for freeing the Eina_List - * when finished with it. There is no need to finish the list strings. + * @remarks Note that the caller is responsible for freeing the Eina_List + * when he is finished with it. There is no need to finish the list strings. * - * @return Return an Eina_List of strings; - * on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group + * @return An Eina_List of strings, + * otherwise @c NULL on failure */ EAPI Eina_List *ecore_imf_context_available_ids_get(void); -/** - * Get the list of the available Input Method Context ids by canvas type. - * - * Note that the caller is responsible for freeing the Eina_List - * when finished with it. There is no need to finish the list strings. - * - * @param canvas_type A string containing the canvas type. - * @return Return an Eina_List of strings; - * on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group - */ EAPI Eina_List *ecore_imf_context_available_ids_by_canvas_type_get(const char *canvas_type); /** - * Get the id of the default Input Method Context. - * The id may to used to create a new instance of an Input Method - * Context object. + * @brief Gets the ID of the default Input Method Context. * - * @return Return a string containing the id of the default Input - * Method Context; on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group + * @remarks The ID may be used to create a new instance of an Input Method + * Context object. + * + * @return A string containing the ID of the default Input Method Context, + * otherwise @c NULL on failure */ EAPI const char *ecore_imf_context_default_id_get(void); -/** - * Get the id of the default Input Method Context corresponding to a canvas - * type. - * The id may be used to create a new instance of an Input Method - * Context object. - * - * @param canvas_type A string containing the canvas type. - * @return Return a string containing the id of the default Input - * Method Context; on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group - */ EAPI const char *ecore_imf_context_default_id_by_canvas_type_get(const char *canvas_type); /** * Retrieve the info for the Input Method Context with @p id. * - * @param id The Input Method Context id to query for. + * @param[in] id The Input Method Context id to query for. * @return Return a #Ecore_IMF_Context_Info for the Input Method Context with @p id; * on failure it returns NULL. * @ingroup Ecore_IMF_Context_Group @@ -805,127 +676,125 @@ EAPI const char *ecore_imf_context_default_id_by_canvas_type_g EAPI const Ecore_IMF_Context_Info *ecore_imf_context_info_by_id_get(const char *id); /** - * Create a new Input Method Context defined by the given id. + * @brief Gets the info for the Input Method Context with ID @a id. * - * @param id The Input Method Context id. - * @return A newly allocated Input Method Context; - * on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group + * @param[in] id The Input Method Context ID to query for + * @return An #Ecore_IMF_Context_Info for the Input Method Context with ID @a id, + * otherwise @c NULL on failure */ EAPI Ecore_IMF_Context *ecore_imf_context_add(const char *id); /** - * Retrieve the info for the given Input Method Context. + * @brief Gets the info for the given Input Method Context. * - * @param ctx An #Ecore_IMF_Context. - * @return Return a #Ecore_IMF_Context_Info for the given Input Method Context; - * on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context + * @return An #Ecore_IMF_Context_Info for the given Input Method Context, + * otherwise @c NULL on failure */ EAPI const Ecore_IMF_Context_Info *ecore_imf_context_info_get(Ecore_IMF_Context *ctx); /** - * Delete the given Input Method Context and free its memory. + * @brief Deletes the given Input Method Context and frees its memory. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_del(Ecore_IMF_Context *ctx); /** - * Set the client window for the Input Method Context; this is the - * Ecore_X_Window when using X11, Ecore_Win32_Window when using Win32, etc. - * This window is used in order to correctly position status windows, and may - * also be used for purposes internal to the Input Method Context. + * @brief Sets the client window for the Input Method Context. This is the + * Ecore_X_Window when using X11, Ecore_Win32_Window when using Win32, and so on. + * + * @remarks This window is used in order to correctly position status windows and may + * also be used for purposes that are internal to the Input Method Context. * - * @param ctx An #Ecore_IMF_Context. - * @param window The client window. This may be @c NULL to indicate + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] window The client windowc\n + * This may be @c NULL to indicate * that the previous client window no longer exists. - * @ingroup Ecore_IMF_Context_Group */ EAPI void ecore_imf_context_client_window_set(Ecore_IMF_Context *ctx, void *window); /** - * Get the client window of the Input Method Context + * @brief Gets the client window of the Input Method Context. * - * See @ref ecore_imf_context_client_window_set for more details. - * - * @param ctx An #Ecore_IMF_Context. - * @return Return the client window. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The client window + * + * @see ecore_imf_context_client_window_set() */ EAPI void *ecore_imf_context_client_window_get(Ecore_IMF_Context *ctx); /** - * Set the client canvas for the Input Method Context; this is the - * canvas in which the input appears. - * The canvas type can be determined by using the context canvas type. - * Actually only canvas with type "evas" (Evas *) is supported. - * This canvas may be used in order to correctly position status windows, and may - * also be used for purposes internal to the Input Method Context. + * @brief Sets the client canvas for the Input Method Context. This is the + * canvas in which the input appears. * - * @param ctx An #Ecore_IMF_Context. - * @param canvas The client canvas. This may be @c NULL to indicate + * @remarks The canvas type can be determined by using the context canvas type. + * Actually only a canvas with type "evas" (Evas *) is supported. + * + * @remarks This canvas may be used in order to correctly position status windows, and may + * also be used for purposes that are internal to the Input Method Context. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] canvas The client canvas \n + * This may be @c NULL to indicate * that the previous client canvas no longer exists. - * @ingroup Ecore_IMF_Context_Group */ EAPI void ecore_imf_context_client_canvas_set(Ecore_IMF_Context *ctx, void *canvas); /** - * Get the client canvas of the Input Method Context. + * @brief Gets the client canvas of the Input Method Context. * - * See @ref ecore_imf_context_client_canvas_set for more details. - * - * @param ctx An #Ecore_IMF_Context. - * @return Return the client canvas. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The client canvas + * + * @see ecore_imf_context_client_canvas_set() */ EAPI void *ecore_imf_context_client_canvas_get(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to show itself. + * @brief Asks the Input Method Context to show itself. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_show(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to hide itself. + * @brief Asks the Input Method Context to hide itself. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_hide(Ecore_IMF_Context *ctx); /** - * Retrieve the current preedit string and cursor position - * for the Input Method Context. + * @brief Gets the current preedit string and cursor position + * for the Input Method Context. * - * @param ctx An #Ecore_IMF_Context. - * @param str Location to store the retrieved string. The - * string retrieved must be freed with free(). - * @param cursor_pos Location to store position of cursor (in characters) - * within the preedit string. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] str The location to store the retrieved string \n + * The string retrieved must be freed with free(). + * @param[out] cursor_pos The location to store the position of the cursor (in characters) + * within the preedit string */ EAPI void ecore_imf_context_preedit_string_get(Ecore_IMF_Context *ctx, char **str, int *cursor_pos); /** - * Retrieve the current preedit string, attributes and - * cursor position for the Input Method Context. + * @brief Gets the current preedit string, attributes, and + * cursor position for the Input Method Context. * - * @param ctx An #Ecore_IMF_Context. - * @param str Location to store the retrieved string. The - * string retrieved must be freed with free(). - * @param attrs an Eina_List of attributes - * @param cursor_pos Location to store position of cursor (in characters) - * within the preedit string. - * @ingroup Ecore_IMF_Context_Group + * @since 1.1.0 * - * Example + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] str The location to store the retrieved string \n + * The string retrieved must be freed with free(). + * @param[in] attrs An Eina_List of attributes + * @param[out] cursor_pos The location to store the position of the cursor (in characters) + * within the preedit string + * + * Example: * @code * char *preedit_string; * int cursor_pos; @@ -964,18 +833,16 @@ EAPI void ecore_imf_context_preedit_string_get(Ecore_IM * * free(preedit_string); * @endcode - * @since 1.1.0 */ EAPI void ecore_imf_context_preedit_string_with_attributes_get(Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); /** - * Notify the Input Method Context that the widget to which its - * correspond has gained focus. + * @brief Notifies the Input Method Context that the widget to which it + * corresponds has gained focus. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context * - * Example + * Example: * @code * static void * _focus_in_cb(void *data, Evas_Object *o, const char *emission, const char *source) @@ -990,13 +857,12 @@ EAPI void ecore_imf_context_preedit_string_with_attribu EAPI void ecore_imf_context_focus_in(Ecore_IMF_Context *ctx); /** - * Notify the Input Method Context that the widget to which its - * correspond has lost focus. + * @brief Notifies the Input Method Context that the widget to which it + * corresponds has lost focus. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context * - * Example + * Example: * @code * static void * _focus_out_cb(void *data, Evas_Object *o, const char *emission, const char *source) @@ -1012,21 +878,20 @@ EAPI void ecore_imf_context_focus_in(Ecore_IMF_Context EAPI void ecore_imf_context_focus_out(Ecore_IMF_Context *ctx); /** - * Notify the Input Method Context that a change such as a - * change in cursor position has been made. This will typically - * cause the Input Method Context to clear the preedit state or commit the preedit string. + * @brief Notifies the Input Method Context that a change, such as a + * change in the cursor position, has been made. This typically + * causes the Input Method Context to clear the preedit state or commit the preedit string. * - * The operation of ecore_imf_context_reset() depends on the specific characteristics of - * each language. For example, the preedit string is cleared in the Chinese and Japanese Input Method Engine. - * However, The preedit string is committed and then cleared in the Korean Input Method Engine. + * @remarks The operation of ecore_imf_context_reset() depends on the specific characteristics of + * each language. For example, the preedit string is cleared in the Chinese and Japanese Input Method Engine. + * However, The preedit string is committed and then cleared in the Korean Input Method Engine. * - * This function should be called in case of the focus-out and mouse down event callback function. - * In addition, it should be called before inserting some text. + * @remarks This function should be called for the focus-out and mouse down event callback function. + * In addition, it should be called before inserting some text. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context * - * Example + * Example: * @code * static void * _focus_out_cb(void *data, Evas_Object *o, const char *emission, const char *source) @@ -1042,117 +907,114 @@ EAPI void ecore_imf_context_focus_out(Ecore_IMF_Context EAPI void ecore_imf_context_reset(Ecore_IMF_Context *ctx); /** - * Notify the Input Method Context that a change in the cursor - * position has been made. + * @brief Notifies the Input Method Context that a change in the cursor + * position has been made. * - * This function should be called when cursor position is changed or mouse up event is generated. - * Some input methods that do a heavy job using this event can give a critical performance latency problem. - * For better typing performance, we suggest that the cursor position change events need to be occurred - * only if the cursor position is on a confirmed status not on moving status. + * @remarks This function should be called when the cursor position is changed or a mouse up event is generated. + * Some input methods that do a heavy job using this event can give a critical performance latency problem. + * For better typing performance, we suggest that the cursor position change events need to occur + * only if the cursor position is on a confirmed status, not on a moving status. * - * @param ctx An #Ecore_IMF_Context. - * @param cursor_pos New cursor position in characters. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] cursor_pos The new cursor position in characters */ EAPI void ecore_imf_context_cursor_position_set(Ecore_IMF_Context *ctx, int cursor_pos); /** - * Notify the Input Method Context that a change in the cursor - * location has been made. The location is relative to the canvas. - * The cursor location can be used to determine the position of - * candidate word window in the immodule. + * @brief Notifies the Input Method Context that a change in the cursor + * location has been made. The location is relative to the canvas. * - * @param ctx An #Ecore_IMF_Context. - * @param x cursor x position. - * @param y cursor y position. - * @param w cursor width. - * @param h cursor height. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @remarks The cursor location can be used to determine the position of + * the candidate word window in the immodule. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] x The cursor's x position + * @param[in] y The cursor's y position + * @param[in] w The cursor width + * @param[in] h The cursor height */ EAPI void ecore_imf_context_cursor_location_set(Ecore_IMF_Context *ctx, int x, int y, int w, int h); /** - * Set whether the IM context should use the preedit string - * to display feedback. If @c use_preedit is @c EINA_FALSE (default - * is @c EINA_TRUE), then the IM context may use some other method to display - * feedback, such as displaying it in a child of the root window. + * @brief Sets whether the IM context should use the preedit string + * to display feedback. * - * @param ctx An #Ecore_IMF_Context. - * @param use_preedit Whether the IM context should use the preedit string. - * @ingroup Ecore_IMF_Context_Group + * @remarks If @a use_preedit is @c EINA_FALSE (default + * is @c EINA_TRUE), then the IM context may use some other method to display + * feedback, such as displaying it in a child of the root window. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] use_preedit The boolean value that indicates whether the IM context should use the preedit string */ EAPI void ecore_imf_context_use_preedit_set(Ecore_IMF_Context *ctx, Eina_Bool use_preedit); /** - * Set the callback to be used on surrounding_get request. + * @brief Sets the callback to be used on the surrounding_get request. * - * This callback will be called when the Input Method Context - * module requests the surrounding context. - * Input methods typically want context in order to constrain input text based on existing text; - * this is important for languages such as Thai where only some sequences of characters are allowed. + * @remarks This callback is called when the Input Method Context + * module requests the surrounding context. * - * @param ctx An #Ecore_IMF_Context. - * @param func The callback to be called. - * @param data The data pointer to be passed to @p func - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] func The callback to be called + * @param[in] data The data pointer to be passed to @a func */ EAPI void ecore_imf_context_retrieve_surrounding_callback_set(Ecore_IMF_Context *ctx, Eina_Bool (*func)(void *data, Ecore_IMF_Context *ctx, char **text, int *cursor_pos), const void *data); /** - * Set the callback to be used on selection_get request. + * @brief Sets the callback to be used on the selection_get request. * - * This callback will be called when the Input Method Context - * module requests the selection context. - * - * @param ctx An #Ecore_IMF_Context. - * @param func The callback to be called. - * @param data The data pointer to be passed to @p func - * @ingroup Ecore_IMF_Context_Group * @since 1.9.0 + * + * @remarks This callback is called when the Input Method Context + * module requests the selection context. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] func The callback to be called + * @param[in] data The data pointer to be passed to @a func */ EAPI void ecore_imf_context_retrieve_selection_callback_set(Ecore_IMF_Context *ctx, Eina_Bool (*func)(void *data, Ecore_IMF_Context *ctx, char **text), const void *data); /** - * Set the input mode used by the Ecore Input Context. + * @brief Sets the callback to be used on the surrounding_get request. * - * The input mode can be one of the input modes defined in - * Ecore_IMF_Input_Mode. The default input mode is - * ECORE_IMF_INPUT_MODE_FULL. + * @remarks The input mode can be one of the input modes defined in + * Ecore_IMF_Input_Mode. The default input mode is + * @c ECORE_IMF_INPUT_MODE_FULL. * - * @param ctx An #Ecore_IMF_Context. - * @param input_mode The input mode to be used by @p ctx. - * @ingroup Ecore_IMF_Context_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] input_mode The input mode to be used by @a ctx */ EAPI void ecore_imf_context_input_mode_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); /** - * Get the input mode being used by the Ecore Input Context. + * @brief Gets the input mode being used by the Ecore Input Context. * - * See @ref ecore_imf_context_input_mode_set for more details. + * @param[in] ctx An #Ecore_IMF_Context + * @return The input mode being used by @a ctx * - * @param ctx An #Ecore_IMF_Context. - * @return The input mode being used by @p ctx. - * @ingroup Ecore_IMF_Context_Group + * @see ecore_imf_context_input_mode_set */ EAPI Ecore_IMF_Input_Mode ecore_imf_context_input_mode_get(Ecore_IMF_Context *ctx); /** - * Allow an Ecore Input Context to internally handle an event. - * If this function returns @c EINA_TRUE, then no further processing - * should be done for this event. + * @brief Allows an Ecore Input Context to internally handle an event. * - * Input methods must be able to accept all types of events (simply - * returning @c EINA_FALSE if the event was not handled), but there is no - * obligation of any events to be submitted to this function. + * @remarks If this function returns @c EINA_TRUE, then no further processing + * should be done for this event. * - * @param ctx An #Ecore_IMF_Context. - * @param type The type of event defined by #Ecore_IMF_Event_Type. - * @param event The event itself. - * @return @c EINA_TRUE if the event was handled; otherwise @c EINA_FALSE. - * @ingroup Ecore_IMF_Context_Group + * @remarks Input methods must be able to accept all types of events (simply + * returning @c EINA_FALSE if the event is not handled), but there is no + * obligation of any events to be submitted to this function. * - * Example + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] type The type of event defined by #Ecore_IMF_Event_Type + * @param[in] event The event itself + * @return @c EINA_TRUE if the event is handled, + * otherwise @c EINA_FALSE + * + * Example: * @code * static void * _key_down_cb(void *data, Evas *e, Evas_Object *obj, void *event_info) @@ -1176,186 +1038,177 @@ EAPI Ecore_IMF_Input_Mode ecore_imf_context_input_mode_get(Ecore_IMF_Co */ EAPI Eina_Bool ecore_imf_context_filter_event(Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); -/* plugin specific functions */ - -/** - * @defgroup Ecore_IMF_Context_Module_Group Ecore Input Method Context Module Functions - * @ingroup Ecore_IMF_Lib_Group - * - * Functions that should be used by Ecore Input Method Context modules. - */ +/* Plugin specific functions */ /** - * Creates a new Input Method Context with klass specified by @p ctxc. + * @brief Creates a new Input Method Context with the class specified by @a ctxc. * - * This method should be used by modules implementing the Input - * Method Context interface. + * @remarks This method should be used by modules implementing the Input + * Method Context interface. * - * @param ctxc An #Ecore_IMF_Context_Class. - * @return A new #Ecore_IMF_Context; on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctxc An #Ecore_IMF_Context_Class + * @return A new #Ecore_IMF_Context, + * otherwise @c NULL on failure */ EAPI Ecore_IMF_Context *ecore_imf_context_new(const Ecore_IMF_Context_Class *ctxc); /** - * Set the Input Method Context specific data. + * @brief Sets the Input Method Context specific data. * - * Note that this method should be used by modules to set - * the Input Method Context specific data and it's not meant to - * be used by applications to store application specific data. + * @remarks Note that this method should be used by modules to set + * the Input Method Context specific data and it's not meant to + * be used by applications to store application specific data. * - * @param ctx An #Ecore_IMF_Context. - * @param data The Input Method Context specific data. - * @return A new #Ecore_IMF_Context; on failure it returns NULL. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] data The Input Method Context specific data + * @return A new #Ecore_IMF_Context, + * otherwise @c NULL on failure */ EAPI void ecore_imf_context_data_set(Ecore_IMF_Context *ctx, void *data); /** - * Get the Input Method Context specific data. + * @brief Gets the Input Method Context specific data. * - * See @ref ecore_imf_context_data_set for more details. + * @param[in] ctx An #Ecore_IMF_Context + * @return The Input Method Context specific data * - * @param ctx An #Ecore_IMF_Context. - * @return The Input Method Context specific data. - * @ingroup Ecore_IMF_Context_Module_Group + * @see ecore_imf_context_data_set() */ EAPI void *ecore_imf_context_data_get(Ecore_IMF_Context *ctx); /** - * Retrieve context around insertion point. - * Input methods typically want context in order to constrain input text based on existing text; - * this is important for languages such as Thai where only some sequences of characters are allowed. - * In addition, the text around the insertion point can be used for supporting autocapital feature. + * @brief Gets the context around the insertion point. + * + * @remarks Input methods typically want context in order to constrain the input text based on existing text. + * This is important for languages such as Thai where only some sequences of characters are allowed. + * In addition, the text around the insertion point can be used for supporting the auto-capital feature. * - * This function is implemented by calling the - * Ecore_IMF_Context::retrieve_surrounding_func ( - * set using #ecore_imf_context_retrieve_surrounding_callback_set). + * @remarks This function is implemented by calling the + * Ecore_IMF_Context::retrieve_surrounding_func + * (set using #ecore_imf_context_retrieve_surrounding_callback_set). * - * There is no obligation for a widget to respond to the - * retrieve_surrounding_func, so input methods must be prepared - * to function without context. + * @remarks There is no obligation for a widget to respond to + * retrieve_surrounding_func, so input methods must be prepared + * to function without context. * - * @param ctx An #Ecore_IMF_Context. - * @param text Location to store a UTF-8 encoded string of text - * holding context around the insertion point. + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] text The location to store a UTF-8 encoded string of text + * holding context around the insertion point \n * If the function returns @c EINA_TRUE, then you must free - * the result stored in this location with free(). - * @param cursor_pos Location to store the position in characters of - * the insertion cursor within @p text. - * @return @c EINA_TRUE if surrounding text was provided; otherwise - * @c EINA_FALSE. - * @ingroup Ecore_IMF_Context_Module_Group + * the result stored in this location using free(). + * @param[out] cursor_pos The location to store the position in characters of + * the insertion cursor within @a text + * @return @c EINA_TRUE if the surrounding text is provided, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_surrounding_get(Ecore_IMF_Context *ctx, char **text, int *cursor_pos); /** - * Retrieve the selected text. + * @brief Gets the selected text. + * + * @since 1.9.0 * - * This function is implemented by calling the - * Ecore_IMF_Context::retrieve_selection_func ( - * set using #ecore_imf_context_retrieve_selection_callback_set). + * @remarks This function is implemented by calling + * Ecore_IMF_Context::retrieve_selection_func + * (set using #ecore_imf_context_retrieve_selection_callback_set). * - * There is no obligation for a widget to respond to the - * retrieve_surrounding_func, so input methods must be prepared - * to function without context. + * @remarks There is no obligation for a widget to respond to + * retrieve_surrounding_func, so input methods must be prepared + * to function without context. * - * @param ctx An #Ecore_IMF_Context. - * @param text Location to store a UTF-8 encoded string of the selected text. + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] text The location to store a UTF-8 encoded string of the selected text \n * If the function returns @c EINA_TRUE, then you must free - * the result stored in this location with free(). - * @return @c EINA_TRUE if selected text was provided; otherwise - * @c EINA_FALSE. - * @ingroup Ecore_IMF_Context_Module_Group - * @since 1.9.0 + * the result stored in this location using free(). + * @return @c EINA_TRUE if the selected text is provided, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_selection_get(Ecore_IMF_Context *ctx, char **text); /** - * Adds ECORE_IMF_EVENT_PREEDIT_START to the event queue. + * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_START to the event queue. * - * ECORE_IMF_EVENT_PREEDIT_START should be added when a new preedit sequence starts. - * It's asynchronous method to put event to the event queue. - * ecore_imf_context_event_callback_call() can be used as synchronous method. + * @remarks @c ECORE_IMF_EVENT_PREEDIT_START should be added when a new preedit sequence starts. + * It's an asynchronous method to put an event to the event queue. + * ecore_imf_context_event_callback_call() can be used as a synchronous method. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_preedit_start_event_add(Ecore_IMF_Context *ctx); /** - * Adds ECORE_IMF_EVENT_PREEDIT_END to the event queue. + * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_END to the event queue. * - * ECORE_IMF_EVENT_PREEDIT_END should be added when a new preedit sequence has been completed or canceled. - * It's asynchronous method to put event to the event queue. - * ecore_imf_context_event_callback_call() can be used as synchronous method. + * @remarks @c ECORE_IMF_EVENT_PREEDIT_END should be added when a new preedit sequence has been completed or cancelled. + * It's an asynchronous method to put an event to the event queue. + * ecore_imf_context_event_callback_call() can be used as a synchronous method. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_preedit_end_event_add(Ecore_IMF_Context *ctx); /** - * Adds ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue. + * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue. * - * It's asynchronous method to put event to the event queue. - * ecore_imf_context_event_callback_call() can be used as synchronous method. + * @remarks It's an asynchronous method to put an event to the event queue. + * ecore_imf_context_event_callback_call() can be used as a synchronous method. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_preedit_changed_event_add(Ecore_IMF_Context *ctx); /** - * Adds ECORE_IMF_EVENT_COMMIT to the event queue. + * @brief Adds @c ECORE_IMF_EVENT_COMMIT to the event queue. * - * It's asynchronous method to put event to the event queue. - * ecore_imf_context_event_callback_call() can be used as synchronous method. + * @remarks It's an asynchronous method to put an event to the event queue. + * ecore_imf_context_event_callback_call() can be used as a synchronous method. * - * @param ctx An #Ecore_IMF_Context. - * @param str The committed string. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] str The committed string */ EAPI void ecore_imf_context_commit_event_add(Ecore_IMF_Context *ctx, const char *str); /** - * Adds ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue. + * @brief Adds @c ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue. * - * Asks the widget that the input context is attached to to delete characters around the cursor position - * by adding the ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue. - * Note that offset and n_chars are in characters not in bytes. + * @remarks This asks the widget that the input context is attached to delete characters around the cursor position + * by adding @c ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue. + * Note that @a offset and @a n_chars are in characters and not in bytes. * - * It's asynchronous method to put ECORE_IMF_EVENT_DELETE_SURROUNDING event to the event queue. - * ecore_imf_context_event_callback_call() can be used as synchronous method. + * @remarks It's an asynchronous method to put the @c ECORE_IMF_EVENT_DELETE_SURROUNDING event to the event queue. + * ecore_imf_context_event_callback_call() can be used as a synchronous method. * - * @param ctx An #Ecore_IMF_Context. - * @param offset The start offset of surrounding to be deleted. - * @param n_chars The number of characters to be deleted. - * @ingroup Ecore_IMF_Context_Module_Group + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] offset The start offset of the surrounding to be deleted + * @param[in] n_chars The number of characters to be deleted */ EAPI void ecore_imf_context_delete_surrounding_event_add(Ecore_IMF_Context *ctx, int offset, int n_chars); /** - * Add (register) a callback function to a given context event. - * - * This function adds a function callback to the context @p ctx when the - * event of type @p type occurs on it. The function pointer is @p - * func. + * @} + */ + +/** + * @brief Adds (registers) a callback function to a given context event. * - * The event type @p type to trigger the function may be one of - * #ECORE_IMF_CALLBACK_PREEDIT_START, #ECORE_IMF_CALLBACK_PREEDIT_END, - * #ECORE_IMF_CALLBACK_PREEDIT_CHANGED, #ECORE_IMF_CALLBACK_COMMIT and - * #ECORE_IMF_CALLBACK_DELETE_SURROUNDING. + * @details This function adds a function callback to the context @a ctx when the + * event of type @a type occurs on it. The function pointer is + * @a func. * - * @param ctx Ecore_IMF_Context to attach a callback to. - * @param type The type of event that will trigger the callback - * @param func The (callback) function to be called when the event is - * triggered - * @param data The data pointer to be passed to @p func - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 * - * Example + * @remarks The event type @a type to trigger the function may be one of + * #ECORE_IMF_CALLBACK_PREEDIT_START, #ECORE_IMF_CALLBACK_PREEDIT_END, + * #ECORE_IMF_CALLBACK_PREEDIT_CHANGED, #ECORE_IMF_CALLBACK_COMMIT, or + * #ECORE_IMF_CALLBACK_DELETE_SURROUNDING. + * + * @param[in] ctx The Ecore_IMF_Context to attach a callback to + * @param[in] type The type of event that triggers the callback + * @param[in] func The (callback) function to be called when the event is + * triggered + * @param[in] data The data pointer to be passed to @a func + * + * Example: * @code * static void * _imf_event_commit_cb(void *data, Ecore_IMF_Context *ctx, void *event_info) @@ -1370,442 +1223,453 @@ EAPI void ecore_imf_context_delete_surrounding_event_ad EAPI void ecore_imf_context_event_callback_add(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, Ecore_IMF_Event_Cb func, const void *data); /** - * Delete (unregister) a callback function registered to a given - * context event. - * - * This function removes a function callback from the context @p ctx when the - * event of type @p type occurs on it. The function pointer is @p - * func. + * @brief Deletes (unregisters) a callback function registered to a given + * context event. * - * @see ecore_imf_context_event_callback_add() for more details + * @details This function removes a function callback from the context @a ctx when the + * event of type @a type occurs on it. The function pointer is + * @a func. * - * @param ctx Ecore_IMF_Context to remove a callback from. - * @param type The type of event that was triggering the callback - * @param func The (callback) function that was to be called when the event was triggered - * @return the data pointer - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx The Ecore_IMF_Context to remove a callback from + * @param[in] type The type of event that triggers the callback + * @param[in] func The (callback) function to be called when the event is triggered + * @return The data pointer + * + * @see ecore_imf_context_event_callback_add() */ EAPI void *ecore_imf_context_event_callback_del(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, Ecore_IMF_Event_Cb func); /** - * Call a given callback on the context @p ctx. + * @brief Calls a given callback on the context @a ctx. + * + * @since 1.2.0 * - * ecore_imf_context_preedit_start_event_add(), ecore_imf_context_preedit_end_event_add(), - * ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_commit_event_add() and - * ecore_imf_context_delete_surrounding_event_add() APIs are asynchronous - * because those API adds each event to the event queue. + * @remarks The ecore_imf_context_preedit_start_event_add(), ecore_imf_context_preedit_end_event_add(), + * ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_commit_event_add(), and + * ecore_imf_context_delete_surrounding_event_add() APIs are asynchronous + * because those APIs add each event to the event queue. * - * This API provides the way to call each callback function immediately. + * @remarks This API provides a way to call each callback function immediately. * - * @param ctx Ecore_IMF_Context. - * @param type The type of event that will trigger the callback - * @param event_info The pointer to event specific struct or information to - * pass to the callback functions registered on this event - * @ingroup Ecore_IMF_Context_Module_Group - * @since 1.2.0 + * @param[in] ctx An Ecore_IMF_Context + * @param[in] type The type of event that triggers the callback + * @param[in] event_info A pointer to an event specific struct or information to + * pass to the callback functions registered on this event */ EAPI void ecore_imf_context_event_callback_call(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, void *event_info); /** - * Set whether the IM context should allow to use the text prediction. - * If @p prediction is @c EINA_FALSE (default is @c EINA_TRUE), then the IM - * context will not display the text prediction window. + * @brief Sets whether the IM context should allow text prediction. * - * @param ctx An #Ecore_IMF_Context. - * @param prediction Whether the IM context should allow to use the text prediction. - * @note Default value is EINA_TRUE. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @remarks If @a prediction is @c EINA_FALSE (default is @c EINA_TRUE), then the IM + * context does not display the text prediction window. + * Default value is @c EINA_TRUE. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] prediction The boolean value that indicates whether the IM context should allow text prediction */ EAPI void ecore_imf_context_prediction_allow_set(Ecore_IMF_Context *ctx, Eina_Bool prediction); /** - * Get whether the IM context should allow to use the text prediction. + * @brief Gets whether the IM context should allow text prediction. * - * @param ctx An #Ecore_IMF_Context. - * @return @c EINA_TRUE if it allows to use the text prediction, otherwise - * @c EINA_FALSE. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return @c EINA_TRUE if it allows text prediction, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_prediction_allow_get(Ecore_IMF_Context *ctx); /** - * Set the autocapitalization type on the immodule. + * @brief Sets the auto-capitalization type on the immodule. * - * @param ctx An #Ecore_IMF_Context. - * @param autocapital_type the autocapitalization type. - * @note Default type is ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @remarks Default type is @c ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] autocapital_type The auto-capitalization type */ EAPI void ecore_imf_context_autocapital_type_set(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); /** - * Get the autocapitalization type. + * @brief Gets the auto-capitalization type. * - * @param ctx An #Ecore_IMF_Context. - * @return The autocapital type being used by @p ctx. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The autocapital type being used by @a ctx */ EAPI Ecore_IMF_Autocapital_Type ecore_imf_context_autocapital_type_get(Ecore_IMF_Context *ctx); /** * @brief Sets the input hint which allows input methods to fine-tune their behavior. * - * @param ctx An #Ecore_IMF_Context - * @param hints input hint - * @note The default input hint is @c ECORE_IMF_INPUT_HINT_AUTO_COMPLETE. - * @ingroup Ecore_IMF_Context_Group * @since 1.12 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] hints input hint + * @note The default input hint is ECORE_IMF_INPUT_HINT_AUTO_COMPLETE. */ EAPI void ecore_imf_context_input_hint_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints hints); /** * @brief Gets the value of input hint. * - * @param ctx An #Ecore_IMF_Context - * @return The value of input hint - * @ingroup Ecore_IMF_Context_Group * @since 1.12 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The value of input hint */ EAPI Ecore_IMF_Input_Hints ecore_imf_context_input_hint_get(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to show the control panel of using Input Method. + * @brief Asks the Input Method Context to show the control panel for using the Input Method. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_control_panel_show(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to hide the control panel of using Input Method. + * @brief Asks the Input Method Context to hide the control panel for using the Input Method. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_control_panel_hide(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to show the input panel (virtual keyboard). + * @brief Asks the Input Method Context to show the input panel (virtual keyboard). * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_input_panel_show(Ecore_IMF_Context *ctx); /** - * Ask the Input Method Context to hide the input panel. + * @brief Asks the Input Method Context to hide the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context */ EAPI void ecore_imf_context_input_panel_hide(Ecore_IMF_Context *ctx); /** - * Set the layout of the input panel. + * @brief Sets the layout of the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param layout see #Ecore_IMF_Input_Panel_Layout - * @note Default layout type is ECORE_IMF_INPUT_PANEL_LAYOUT_NORMAL. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @remarks Default layout type is @c ECORE_IMF_INPUT_PANEL_LAYOUT_NORMAL. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] layout The #Ecore_IMF_Input_Panel_Layout */ EAPI void ecore_imf_context_input_panel_layout_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); /** - * Get the layout of the current active input panel. + * @brief Gets the layout of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @return layout see #Ecore_IMF_Input_Panel_Layout - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return layout The #Ecore_IMF_Input_Panel_Layout */ EAPI Ecore_IMF_Input_Panel_Layout ecore_imf_context_input_panel_layout_get(Ecore_IMF_Context *ctx); /** - * Set the layout variation of the current active input panel. + * @brief Sets the layout variation of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param variation the layout variation - * @note Default layout variation type is NORMAL. - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @remarks Default layout variation type is @c NORMAL. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] variation The layout variation */ EAPI void ecore_imf_context_input_panel_layout_variation_set(Ecore_IMF_Context *ctx, int variation); /** - * Get the layout variation of the current active input panel. + * @brief Gets the layout variation of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @return the layout variation - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The layout variation */ EAPI int ecore_imf_context_input_panel_layout_variation_get(Ecore_IMF_Context *ctx); /** - * Set the language of the input panel. - * This API can be used when you want to show the English keyboard. + * @brief Sets the language of the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param lang the language to be set to the input panel. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @remarks This API can be used when you want to show the English keyboard. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] lang The language to be set for the input panel */ EAPI void ecore_imf_context_input_panel_language_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); /** - * Get the language of the input panel. - * - * See @ref ecore_imf_context_input_panel_language_set for more details. + * @brief Gets the language of the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @return Ecore_IMF_Input_Panel_Lang - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The Ecore_IMF_Input_Panel_Lang + * + * @see ecore_imf_context_input_panel_language_set() */ EAPI Ecore_IMF_Input_Panel_Lang ecore_imf_context_input_panel_language_get(Ecore_IMF_Context *ctx); /** - * Set whether the Input Method Context should request to show the input panel automatically - * when the widget has focus. + * @brief Sets whether the Input Method Context should request to show the input panel automatically + * when the widget has focus. * - * @param ctx An #Ecore_IMF_Context. - * @param enabled If true, the input panel will be shown when the widget is clicked or has focus. - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] enabled If @c true the input panel is shown when the widget is clicked or has focus, + * otherwise @c false */ EAPI void ecore_imf_context_input_panel_enabled_set(Ecore_IMF_Context *ctx, Eina_Bool enabled); /** - * Get whether the Input Method Context requests to show the input panel automatically. + * @brief Gets whether the Input Method Context requests to show the input panel automatically. * - * @param ctx An #Ecore_IMF_Context. - * @return Return the attribute to show the input panel automatically - * @ingroup Ecore_IMF_Context_Group * @since 1.1.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The attribute to show the input panel automatically */ EAPI Eina_Bool ecore_imf_context_input_panel_enabled_get(Ecore_IMF_Context *ctx); /** - * Set the input panel-specific data to deliver to the input panel. - * This API is used by applications to deliver specific data to the input panel. - * The data format MUST be negotiated by both application and the input panel. - * The size and format of data are defined by the input panel. - * - * @param ctx An #Ecore_IMF_Context. - * @param data The specific data to be set to the input panel. - * @param len the length of data, in bytes, to send to the input panel - * @ingroup Ecore_IMF_Context_Group + * @brief Sets the input panel-specific data to deliver to the input panel. + * * @since 1.2.0 + * + * @remarks This API is used by applications to deliver specific data to the input panel. + * The data format MUST be negotiated by both the application and the input panel. + * The size and format of data is defined by the input panel. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] data The specific data to be set to the input panel + * @param[in] len The length of data, in bytes, to send to the input panel */ EAPI void ecore_imf_context_input_panel_imdata_set(Ecore_IMF_Context *ctx, const void *data, int len); /** - * Get the specific data of the current active input panel. + * @brief Gets the specific data of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param data The specific data to be got from the input panel - * @param len The length of data - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] data The specific data to be obtained from the input panel + * @param[out] len The length of the data */ EAPI void ecore_imf_context_input_panel_imdata_get(Ecore_IMF_Context *ctx, void *data, int *len); /** - * Set the "return" key type. This type is used to set string or icon on the "return" key of the input panel. - * - * An input panel displays the string or icon associated with this type + * @brief Sets the "return" key type. This type is used to set a string or icon on the "return" key of the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param return_key_type The type of "return" key on the input panel - * @note Default type is ECORE_IMF_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT. - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @remarks An input panel displays the string or icon associated to this type. + * + * @remarks Default type is @c ECORE_IMF_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] return_key_type The type of "return" key on the input panel */ EAPI void ecore_imf_context_input_panel_return_key_type_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); /** - * Get the "return" key type. + * @brief Gets the "return" key type. * - * @see ecore_imf_context_input_panel_return_key_type_set() for more details + * @since 1.2.0 * - * @param ctx An #Ecore_IMF_Context. + * @param[in] ctx An #Ecore_IMF_Context * @return The type of "return" key on the input panel - * @ingroup Ecore_IMF_Context_Group - * @since 1.2.0 + * + * @see ecore_imf_context_input_panel_return_key_type_set() */ EAPI Ecore_IMF_Input_Panel_Return_Key_Type ecore_imf_context_input_panel_return_key_type_get(Ecore_IMF_Context *ctx); /** - * Set the return key on the input panel to be disabled. + * @brief Sets the return key on the input panel to be disabled. * - * @param ctx An #Ecore_IMF_Context. - * @param disabled The state - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] disabled The return key state */ EAPI void ecore_imf_context_input_panel_return_key_disabled_set(Ecore_IMF_Context *ctx, Eina_Bool disabled); /** - * Get whether the return key on the input panel should be disabled or not. + * @brief Gets whether the return key on the input panel should be disabled. * - * @param ctx An #Ecore_IMF_Context. - * @return @c EINA_TRUE if it should be disabled. - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return @c EINA_TRUE if it should be disabled, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_input_panel_return_key_disabled_get(Ecore_IMF_Context *ctx); /** - * Set the caps lock mode on the input panel. + * @brief Sets the caps lock mode on the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param mode Turn on caps lock on the input panel if @c EINA_TRUE. - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] mode If @c EINA_TRUE caps lock on the input panel is turned on, + * otherwise @c EINA_FALSE */ EAPI void ecore_imf_context_input_panel_caps_lock_mode_set(Ecore_IMF_Context *ctx, Eina_Bool mode); /** - * Get the caps lock mode on the input panel. + * @brief Gets the caps lock mode on the input panel. * - * @param ctx An #Ecore_IMF_Context. - * @return @c EINA_TRUE if the caps lock is turned on. - * @ingroup Ecore_IMF_Context_Group * @since 1.2.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return @c EINA_TRUE if caps lock is turned on, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_input_panel_caps_lock_mode_get(Ecore_IMF_Context *ctx); /** - * Get the position of the current active input panel. + * @brief Gets the position of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @param x top-left x co-ordinate of the input panel - * @param y top-left y co-ordinate of the input panel - * @param w width of the input panel - * @param h height of the input panel - * @ingroup Ecore_IMF_Context_Group - * @since 1.3 + * @since 1.30 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] x The top-left x co-ordinate of the input panel + * @param[out] y The top-left y co-ordinate of the input panel + * @param[out] w The width of the input panel + * @param[out] h The height of the input panel */ EAPI void ecore_imf_context_input_panel_geometry_get(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /** - * Get state of current active input panel. + * @brief Gets the state of the current active input panel. * - * @param ctx An #Ecore_IMF_Context. - * @return The state of input panel. - * @ingroup Ecore_IMF_Context_Group * @since 1.3 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return The state of the input panel */ EAPI Ecore_IMF_Input_Panel_State ecore_imf_context_input_panel_state_get(Ecore_IMF_Context *ctx); /** - * Register a callback function which will be called if there is change in input panel state,language,mode etc. - * In order to deregister the callback function - * Use @ref ecore_imf_context_input_panel_event_callback_del. - * - * @param ctx An #Ecore_IMF_Context - * @param type event type - * @param func the callback function - * @param data application-input panel specific data. - * @ingroup Ecore_IMF_Context_Group + * @brief Registers a callback function which is called if there is a change in the input panel state, language, mode, and so on. + * * @since 1.3 + * + * @remarks In order to unregister the callback function + * use @ref ecore_imf_context_input_panel_event_callback_del. + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] type The event type + * @param[in] func The callback function + * @param[in] data The application-input panel specific data */ EAPI void ecore_imf_context_input_panel_event_callback_add(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), const void *data); /** - * Unregister a callback function which will be called if there is change in input panel state, language, mode etc. + * @brief Unregisters a callback function which is called if there is a change in the input panel state, language, mode, and so on. * - * @param ctx An #Ecore_IMF_Context. - * @param type An #Ecore_IMF_Input_Panel_Event. - * @param func the callback function - * @ingroup Ecore_IMF_Context_Group * @since 1.3 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] type An #Ecore_IMF_Input_Panel_Event + * @param[in] func The callback function */ EAPI void ecore_imf_context_input_panel_event_callback_del(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); /** - * Call a given input panel callback on the context @p ctx. + * @brief Calls a given input panel callback on the context @a ctx. * - * @param ctx Ecore_IMF_Context. - * @param type The type of event that will trigger the callback - * @param value the event value - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @param[in] ctx An Ecore_IMF_Context + * @param[in] type The type of event that triggers the callback + * @param[in] value The event value */ EAPI void ecore_imf_context_input_panel_event_callback_call(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, int value); /** - * Delete all input panel callback on the context @p ctx. + * @brief Deletes all input panel callbacks on the context @a ctx. * - * Delete all input panel callback to be registered by ecore_imf_context_input_panel_event_callback_add() + * @details This deletes all input panel callbacks to be registered by ecore_imf_context_input_panel_event_callback_add(). * - * @param ctx Ecore_IMF_Context. - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @param[in] ctx An Ecore_IMF_Context */ EAPI void ecore_imf_context_input_panel_event_callback_clear(Ecore_IMF_Context *ctx); /** - * Get the current language locale of the input panel. - * - * ex) fr_FR + * @brief Gets the current language locale of the input panel, eg: fr_FR. * - * @param ctx An #Ecore_IMF_Context. - * @param lang Location to store the retrieved language string. The - * string retrieved must be freed with free(). - * @ingroup Ecore_IMF_Context_Group * @since 1.3 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] lang The location to store the retrieved language string \n + * The string retrieved must be freed with free(). */ EAPI void ecore_imf_context_input_panel_language_locale_get(Ecore_IMF_Context *ctx, char **lang); /** - * Get the geometry information of the candidate panel. + * @brief Gets the geometry information of the candidate panel. * - * @param ctx An #Ecore_IMF_Context. - * @param x top-left x co-ordinate of the candidate panel - * @param y top-left y co-ordinate of the candidate panel - * @param w width of the candidate panel - * @param h height of the candidate panel - * @ingroup Ecore_IMF_Context_Group * @since 1.3 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[out] x The top-left x co-ordinate of the candidate panel + * @param[out] y The top-left y co-ordinate of the candidate panel + * @param[out] w The width of the candidate panel + * @param[out] h The height of the candidate panel */ EAPI void ecore_imf_context_candidate_panel_geometry_get(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /** - * Set whether the Input Method Context should request to show the input panel in case of only an user's explicit Mouse Up event. - * It doesn't request to show the input panel even though the Input Method Context has focus. + * @brief Sets whether the Input Method Context should request to show the input panel if only one user's explicit Mouse Up event has occurred. + * It doesn't request to show the input panel even though the Input Method Context has focus. * - * @param ctx An #Ecore_IMF_Context. - * @param ondemand If true, the input panel will be shown in case of only Mouse up event. (Focus event will be ignored.) - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @param[in] ondemand If @c true the input panel is shown when only one user's Mouse up event occurs, (Focus event is ignored) + * otherwise @c false */ EAPI void ecore_imf_context_input_panel_show_on_demand_set(Ecore_IMF_Context *ctx, Eina_Bool ondemand); /** - * Get whether the Input Method Context should request to show the input panel in case of only an user's explicit Mouse Up event. + * @brief Gets whether the Input Method Context should request to show the input panel if only one user's explicit Mouse Up event has occurred. * - * @param ctx An #Ecore_IMF_Context. - * @return @c EINA_TRUE if the input panel will be shown in case of only Mouse up event. - * @ingroup Ecore_IMF_Context_Group * @since 1.8.0 + * + * @param[in] ctx An #Ecore_IMF_Context + * @return @c EINA_TRUE if the input panel is shown when only one user's Mouse up event occurs, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_imf_context_input_panel_show_on_demand_get(Ecore_IMF_Context *ctx); /** * @brief Sets the bidirectionality at the current cursor position. * - * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context @@ -1816,7 +1680,6 @@ EAPI void ecore_imf_context_bidi_direction_set(Ecore_IM /** * @brief Gets the bidirectionality at the current cursor position. * - * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context @@ -1824,7 +1687,7 @@ EAPI void ecore_imf_context_bidi_direction_set(Ecore_IM */ EAPI Ecore_IMF_BiDi_Direction ecore_imf_context_bidi_direction_get(Ecore_IMF_Context *ctx); -/* The following entry points must be exported by each input method module +/* The following entry points must be exported by each input method module. */ /* @@ -1833,6 +1696,14 @@ EAPI Ecore_IMF_BiDi_Direction ecore_imf_context_bidi_direction_get(Ecore_IM * Ecore_IMF_Context *imf_module_create (void); */ +/** + * @} + */ + +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h b/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h index 84794c2db2..55de59b644 100644 --- a/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h +++ b/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h @@ -31,80 +31,29 @@ #endif /* ! _WIN32 */ /** + * @internal * @defgroup Ecore_IMF_Evas_Group Ecore Input Method Context Evas Helper Functions - * @ingroup Ecore_IMF_Lib_Group + * @ingroup Ecore_IMF_Group * * Helper functions to make it easy to use Evas with Ecore_IMF. * Converts each event from Evas to the corresponding event of Ecore_IMF. * - * An example of usage of these functions can be found at: - * @li @ref ecore_imf_example_c + * @{ */ #ifdef __cplusplus extern "C" { #endif -/** - * Converts a "mouse_in" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_in_wrap(Evas_Event_Mouse_In *evas_event, Ecore_IMF_Event_Mouse_In *imf_event); - -/** - * Converts a "mouse_out" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_out_wrap(Evas_Event_Mouse_Out *evas_event, Ecore_IMF_Event_Mouse_Out *imf_event); - -/** - * Converts a "mouse_move" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_move_wrap(Evas_Event_Mouse_Move *evas_event, Ecore_IMF_Event_Mouse_Move *imf_event); - -/** - * Converts a "mouse_down" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_down_wrap(Evas_Event_Mouse_Down *evas_event, Ecore_IMF_Event_Mouse_Down *imf_event); - -/** - * Converts a "mouse_up" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_up_wrap(Evas_Event_Mouse_Up *evas_event, Ecore_IMF_Event_Mouse_Up *imf_event); - -/** - * Converts a "mouse_wheel" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group - */ EAPI void ecore_imf_evas_event_mouse_wheel_wrap(Evas_Event_Mouse_Wheel *evas_event, Ecore_IMF_Event_Mouse_Wheel *imf_event); /** - * Converts a "key_down" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group + * @brief Converts a "key_down" event from Evas to the corresponding event of Ecore_IMF. * * Example * @code @@ -127,15 +76,14 @@ EAPI void ecore_imf_evas_event_mouse_wheel_wrap(Evas_Event_Mouse_Wheel *evas_eve * * evas_object_event_callback_add(obj, EVAS_CALLBACK_KEY_DOWN, _key_down_cb, data); * @endcode + * + * @param[in] evas_event The received Evas event. + * @param[out] imf_event The location to store the converted Ecore_IMF event. */ EAPI void ecore_imf_evas_event_key_down_wrap(Evas_Event_Key_Down *evas_event, Ecore_IMF_Event_Key_Down *imf_event); /** - * Converts a "key_up" event from Evas to the corresponding event of Ecore_IMF. - * - * @param evas_event The received Evas event. - * @param imf_event The location to store the converted Ecore_IMF event. - * @ingroup Ecore_IMF_Evas_Group + * @brief Converts a "key_up" event from Evas to the corresponding event of Ecore_IMF. * * Example * @code @@ -158,6 +106,9 @@ EAPI void ecore_imf_evas_event_key_down_wrap(Evas_Event_Key_Down *evas_event, Ec * * evas_object_event_callback_add(obj, EVAS_CALLBACK_KEY_UP, _key_up_cb, data); * @endcode + * + * @param[in] evas_event The received Evas event. + * @param[out] imf_event The location to store the converted Ecore_IMF event. */ EAPI void ecore_imf_evas_event_key_up_wrap(Evas_Event_Key_Up *evas_event, Ecore_IMF_Event_Key_Up *imf_event); @@ -165,4 +116,8 @@ EAPI void ecore_imf_evas_event_key_up_wrap(Evas_Event_Key_Up *evas_event, Ecore_ } #endif +/** + * @} + */ + #endif diff --git a/src/lib/ecore_input/Ecore_Input.h b/src/lib/ecore_input/Ecore_Input.h index e6e1259c08..d9b3181369 100644 --- a/src/lib/ecore_input/Ecore_Input.h +++ b/src/lib/ecore_input/Ecore_Input.h @@ -39,20 +39,14 @@ extern "C" { #endif -/** - * @defgroup Ecore_Input_Group Ecore Input - * @ingroup Ecore_Group - * - *@{ - */ - EAPI extern int ECORE_EVENT_KEY_DOWN; - EAPI extern int ECORE_EVENT_KEY_UP; - EAPI extern int ECORE_EVENT_MOUSE_BUTTON_DOWN; - EAPI extern int ECORE_EVENT_MOUSE_BUTTON_UP; - EAPI extern int ECORE_EVENT_MOUSE_MOVE; - EAPI extern int ECORE_EVENT_MOUSE_WHEEL; - EAPI extern int ECORE_EVENT_MOUSE_IN; - EAPI extern int ECORE_EVENT_MOUSE_OUT; +EAPI extern int ECORE_EVENT_KEY_DOWN; +EAPI extern int ECORE_EVENT_KEY_UP; +EAPI extern int ECORE_EVENT_MOUSE_BUTTON_DOWN; +EAPI extern int ECORE_EVENT_MOUSE_BUTTON_UP; +EAPI extern int ECORE_EVENT_MOUSE_MOVE; +EAPI extern int ECORE_EVENT_MOUSE_WHEEL; +EAPI extern int ECORE_EVENT_MOUSE_IN; +EAPI extern int ECORE_EVENT_MOUSE_OUT; #define ECORE_EVENT_MODIFIER_SHIFT 0x0001 #define ECORE_EVENT_MODIFIER_CTRL 0x0002 @@ -67,257 +61,176 @@ extern "C" { #define ECORE_EVENT_LOCK_SHIFT 0x0300 #define ECORE_EVENT_MODIFIER_ALTGR 0x0400 /**< @since 1.7 */ -#ifndef _ECORE_WINDOW_PREDEF - typedef uintptr_t Ecore_Window; -#define _ECORE_WINDOW_PREDEF 1 -#endif - - typedef struct _Ecore_Event_Key Ecore_Event_Key; - typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button; - typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel; - typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move; - typedef struct _Ecore_Event_Mouse_IO Ecore_Event_Mouse_IO; - typedef struct _Ecore_Event_Modifiers Ecore_Event_Modifiers; - - /** - * @typedef Ecore_Event_Modifier - * An enum of modifier events. - */ - typedef enum _Ecore_Event_Modifier - { - ECORE_NONE, - ECORE_SHIFT, - ECORE_CTRL, - ECORE_ALT, - ECORE_WIN, - ECORE_SCROLL, - ECORE_CAPS, - ECORE_MODE, /**< @since 1.7 */ - ECORE_LAST - } Ecore_Event_Modifier; - - /** - * @typedef Ecore_Event_Press - * An enum of press events. - */ - typedef enum _Ecore_Event_Press - { - ECORE_DOWN, - ECORE_UP - } Ecore_Event_Press; - - /** - * @typedef Ecore_Event_IO - * An enum of Input/Output events. - */ - typedef enum _Ecore_Event_IO - { - ECORE_IN, - ECORE_OUT - } Ecore_Event_IO; - - /** - * @typedef Ecore_Compose_State - * An enum of Compose states. - */ - typedef enum _Ecore_Compose_State - { - ECORE_COMPOSE_NONE, - ECORE_COMPOSE_MIDDLE, - ECORE_COMPOSE_DONE - } Ecore_Compose_State; - - /** - * @struct _Ecore_Event_Key - * Contains information about an Ecore keyboard event. - */ - struct _Ecore_Event_Key - { - const char *keyname; /**< The key name */ - const char *key; /**< The key symbol */ - const char *string; - const char *compose; /**< final string corresponding to the key symbol composed */ - Ecore_Window window; /**< The main window where event happened */ - Ecore_Window root_window; /**< The root window where event happened */ - Ecore_Window event_window; /**< The child window where event happened */ - - unsigned int timestamp; /**< Time when the event occurred */ - unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - - int same_screen; /**< same screen flag */ - - unsigned int keycode; /**< Key scan code numeric value @since 1.10 */ - - void *data; /**< User data associated with an Ecore_Event_Key @since 1.10 */ - }; - - /** - * @struct _Ecore_Event_Mouse_Button - * Contains information about an Ecore mouse button event. - */ - struct _Ecore_Event_Mouse_Button - { - Ecore_Window window; /**< The main window where event happened */ - Ecore_Window root_window; /**< The root window where event happened */ - Ecore_Window event_window; /**< The child window where event happened */ - - unsigned int timestamp; /**< Time when the event occurred */ - unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - unsigned int buttons; /**< The button that was used */ - unsigned int double_click; /**< Double click event */ - unsigned int triple_click; /**< Triple click event */ - int same_screen; /**< Same screen flag */ - - int x; /**< x coordinate relative to window where event happened */ - int y; /**< y coordinate relative to window where event happened */ - struct { - int x; - int y; - } root; /**< Coordinates relative to root window */ - +typedef uintptr_t Ecore_Window; +typedef struct _Ecore_Event_Key Ecore_Event_Key; +typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button; +typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel; +typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move; +typedef struct _Ecore_Event_Mouse_IO Ecore_Event_Mouse_IO; +typedef struct _Ecore_Event_Modifiers Ecore_Event_Modifiers; + +typedef enum _Ecore_Event_Modifier + { + ECORE_NONE, + ECORE_SHIFT, + ECORE_CTRL, + ECORE_ALT, + ECORE_WIN, + ECORE_SCROLL, + ECORE_CAPS, + ECORE_MODE, /**< @since 1.7 */ + ECORE_LAST + } Ecore_Event_Modifier; + +typedef enum _Ecore_Event_Press + { + ECORE_DOWN, + ECORE_UP + } Ecore_Event_Press; + +typedef enum _Ecore_Event_IO + { + ECORE_IN, + ECORE_OUT + } Ecore_Event_IO; + +typedef enum _Ecore_Compose_State + { + ECORE_COMPOSE_NONE, + ECORE_COMPOSE_MIDDLE, + ECORE_COMPOSE_DONE + } Ecore_Compose_State; + +struct _Ecore_Event_Key + { + const char *keyname; + const char *key; + const char *string; + const char *compose; + Ecore_Window window; + Ecore_Window root_window; + Ecore_Window event_window; + + unsigned int timestamp; + unsigned int modifiers; + + int same_screen; + }; + +struct _Ecore_Event_Mouse_Button + { + Ecore_Window window; + Ecore_Window root_window; + Ecore_Window event_window; + + unsigned int timestamp; + unsigned int modifiers; + unsigned int buttons; + unsigned int double_click; + unsigned int triple_click; + int same_screen; + + int x; + int y; + struct { + int x; + int y; + } root; + + struct { + int device; /* @c 0 if normal mouse, @c 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /* radius of press point - radius_x and radius_y if it is an ellipse (radius is the average of the 2) */ + double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /* angle relative to the perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /* same as x, y, root.x, root.y, but with sub-pixel precision, if available */ struct { - int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /**< same as x, y, but with sub-pixel precision, if available */ - struct { - double x, y; - } root; /**< same as root.x, root.y, but with sub-pixel precision, if available */ - } multi; - }; - - /** - * @struct _Ecore_Event_Mouse_Wheel - * Contains information about an Ecore mouse wheel event. - */ - struct _Ecore_Event_Mouse_Wheel - { - Ecore_Window window; /**< The main window where event happened */ - Ecore_Window root_window; /**< The root window where event happened */ - Ecore_Window event_window; /**< The child window where event happened */ - - unsigned int timestamp; /**< Time when the event occurred */ - unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - - int same_screen; /**< Same screen flag */ - int direction; /**< Orientation of the wheel (horizontal/vertical) */ - int z; /**< Value of the wheel event (+1/-1) */ - - int x; /**< x coordinate relative to window where event happened */ - int y; /**< y coordinate relative to window where event happened */ + double x, y; + } root; + } multi; + }; + +struct _Ecore_Event_Mouse_Wheel + { + Ecore_Window window; + Ecore_Window root_window; + Ecore_Window event_window; + + unsigned int timestamp; + unsigned int modifiers; + + int same_screen; + int direction; + int z; + + int x; + int y; + struct { + int x; + int y; + } root; + }; + +struct _Ecore_Event_Mouse_Move + { + Ecore_Window window; + Ecore_Window root_window; + Ecore_Window event_window; + + unsigned int timestamp; + unsigned int modifiers; + + int same_screen; + + int x; + int y; + struct { + int x; + int y; + } root; + + struct { + int device; /* @c 0 if normal mouse, @c 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /* radius of press point - radius_x and radius_y if it is an ellipse (radius is the average of the 2) */ + double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /* angle relative to the perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /* same as x, y, root.x, root.y, but with sub-pixel precision, if available */ struct { - int x; - int y; - } root; /**< Coordinates relative to root window */ - }; - - /** - * @struct _Ecore_Event_Mouse_Move - * Contains information about an Ecore mouse move event. - */ - struct _Ecore_Event_Mouse_Move - { - Ecore_Window window; /**< The main window where event happened */ - Ecore_Window root_window; /**< The root window where event happened */ - Ecore_Window event_window; /**< The child window where event happened */ - - unsigned int timestamp; /**< Time when the event occurred */ - unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - - int same_screen; /**< Same screen flag */ - - int x; /**< x coordinate relative to window where event happened */ - int y; /**< y coordinate relative to window where event happened */ - struct { - int x; - int y; - } root; /**< Coordinates relative to root window */ - - struct { - int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /**< same as x, y root.x, root.y, but with sub-pixel precision, if available */ - struct { - double x, y; - } root; - } multi; - }; - - /** - * @struct _Ecore_Event_Mouse_IO - * Contains information about an Ecore mouse input/output event. - */ - struct _Ecore_Event_Mouse_IO - { - Ecore_Window window; /**< The main window where event happened */ - Ecore_Window event_window; /**< The child window where event happened */ - - unsigned int timestamp; /**< Time when the event occurred */ - unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - - int x; /**< x coordinate relative to window where event happened */ - int y; /**< y coordinate relative to window where event happened */ - }; - - /** - * @struct _Ecore_Event_Modifiers - * Contains information about an Ecore event modifier. - */ - struct _Ecore_Event_Modifiers - { - unsigned int size; - unsigned int array[ECORE_LAST]; - }; - - /** - * Initialises the Ecore Event system. - */ - EAPI int ecore_event_init(void); - /** - * Shutdowns the Ecore Event system. - */ - EAPI int ecore_event_shutdown(void); - - /** - * Return the Ecore modifier event integer associated to a - * Ecore_Event_Modifier modifier event. - * - * @param modifier A Ecore_Event_Modifier event. - * @return A event_modifier integer that matches with the provided modifier - * event. - */ - EAPI unsigned int ecore_event_modifier_mask(Ecore_Event_Modifier modifier); - - /** - * Update a Ecore_Event_Modifiers array with "key" modifier. - * - * @param key A string describing a modifier key. - * @param modifiers A Ecore_Event_Modifiers structure. - * @param inc The value to increment in the modifiers array. - * - * @return ECORE_NONE if the key does not match with an existing one, else - * the corresponding Ecore_Event_Modifier. - */ - EAPI Ecore_Event_Modifier ecore_event_update_modifier(const char *key, Ecore_Event_Modifiers *modifiers, int inc); - - /** - * Handle a sequence of key symbols to make a final compose string. - * - * The final compose string seqstr_ret is allocated in this function and - * thus shall be freed when not needed anymore. - * - * @param seq The sequence of key symbols in a Eina_List. - * @param seqstr_ret The final compose string. - * @return The status of the composition. - */ - EAPI Ecore_Compose_State ecore_compose_get(const Eina_List *seq, char **seqstr_ret); + double x, y; + } root; + } multi; + }; + +struct _Ecore_Event_Mouse_IO + { + Ecore_Window window; + Ecore_Window event_window; + + unsigned int timestamp; + unsigned int modifiers; + + int x; + int y; + }; + +struct _Ecore_Event_Modifiers + { + unsigned int size; + unsigned int array[ECORE_LAST]; + }; + +EAPI int ecore_event_init(void); +EAPI int ecore_event_shutdown(void); +EAPI unsigned int ecore_event_modifier_mask(Ecore_Event_Modifier modifier); +EAPI Ecore_Event_Modifier ecore_event_update_modifier(const char *key, Ecore_Event_Modifiers *modifiers, int inc); + +/** + * @internal + * @since 1.7 + */ +EAPI Ecore_Compose_State ecore_compose_get(const Eina_List *seq, char **seqstr_ret); #ifdef __cplusplus } #endif -/** @} */ #endif diff --git a/src/lib/ecore_ipc/Ecore_Ipc.h b/src/lib/ecore_ipc/Ecore_Ipc.h index a3e38710b4..da5380e67e 100644 --- a/src/lib/ecore_ipc/Ecore_Ipc.h +++ b/src/lib/ecore_ipc/Ecore_Ipc.h @@ -30,11 +30,9 @@ #endif /** - * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions. - * @ingroup Ecore - * - * - * @{ + * @internal + * @file Ecore_Ipc.h + * @brief Ecore inter-process communication functions. */ #ifdef __cplusplus @@ -44,17 +42,17 @@ extern "C" { typedef struct _Ecore_Ipc_Server Ecore_Ipc_Server; /**< An IPC connection handle */ typedef struct _Ecore_Ipc_Client Ecore_Ipc_Client; /**< An IPC connection handle */ -EAPI unsigned short _ecore_ipc_swap_16(unsigned short v) EINA_DEPRECATED; -EAPI unsigned int _ecore_ipc_swap_32(unsigned int v) EINA_DEPRECATED; -EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED; +EAPI unsigned short _ecore_ipc_swap_16(unsigned short v); +EAPI unsigned int _ecore_ipc_swap_32(unsigned int v); +EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v); #ifdef WORDS_BIGENDIAN -#define ECORE_IPC_SWAP2NET64(x) eina_swap64(x) -#define ECORE_IPC_SWAP2CPU64(x) eina_swap64(x) -#define ECORE_IPC_SWAP2NET32(x) eina_swap32(x) -#define ECORE_IPC_SWAP2CPU32(x) eina_swap32(x) -#define ECORE_IPC_SWAP2NET16(x) eina_swap16(x) -#define ECORE_IPC_SWAP2CPU16(x) eina_swap16(x) +#define ECORE_IPC_SWAP2NET64(x) _ecore_ipc_swap_64(x) +#define ECORE_IPC_SWAP2CPU64(x) _ecore_ipc_swap_64(x) +#define ECORE_IPC_SWAP2NET32(x) _ecore_ipc_swap_32(x) +#define ECORE_IPC_SWAP2CPU32(x) _ecore_ipc_swap_32(x) +#define ECORE_IPC_SWAP2NET16(x) _ecore_ipc_swap_16(x) +#define ECORE_IPC_SWAP2CPU16(x) _ecore_ipc_swap_16(x) #define ECORE_IPC_SWAP2NET8(x) (x) #define ECORE_IPC_SWAP2CPU8(x) (x) #else @@ -166,7 +164,7 @@ EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED ptr = d; /* footer for the hell of it */ #define ECORE_IPC_DEC_STRUCT_FOOT() return 1 -/* header for encoder - gives native struct type and size of flattened packet */ +/* header for encoder - gives native strct type and size of flattened packet */ #define ECORE_IPC_ENC_STRUCT_HEAD(typ, sz) \ typ *p; \ unsigned char *d, *ptr; \ @@ -220,11 +218,6 @@ EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED } \ return d -/** - * @typedef Ecore_Ipc_Type - * - * Enum containing IPC types. - */ typedef enum _Ecore_Ipc_Type { ECORE_IPC_LOCAL_USER, @@ -241,81 +234,50 @@ typedef struct _Ecore_Ipc_Event_Server_Del Ecore_Ipc_Event_Server_Del; typedef struct _Ecore_Ipc_Event_Client_Data Ecore_Ipc_Event_Client_Data; typedef struct _Ecore_Ipc_Event_Server_Data Ecore_Ipc_Event_Server_Data; -/** - * @struct _Ecore_Ipc_Event_Client_Add - * - * An IPC structure for client_add event. - */ struct _Ecore_Ipc_Event_Client_Add { - Ecore_Ipc_Client *client; /**< An IPC connection handle */ + Ecore_Ipc_Client *client; }; -/** - * @struct _Ecore_Ipc_Event_Client_Del - * - * An IPC structure for client_del event. - */ struct _Ecore_Ipc_Event_Client_Del { - Ecore_Ipc_Client *client; /**< An IPC connection handle */ + Ecore_Ipc_Client *client; }; -/** - * @struct _Ecore_Ipc_Event_Server_Add - * - * An IPC structure for server_add event. - */ struct _Ecore_Ipc_Event_Server_Add { - Ecore_Ipc_Server *server; /**< An IPC connection handle */ + Ecore_Ipc_Server *server; }; -/** - * @struct _Ecore_Ipc_Event_Server_Del - * - * An IPC structure for server_del event. - */ struct _Ecore_Ipc_Event_Server_Del { - Ecore_Ipc_Server *server; /**< An IPC connection handle */ - + Ecore_Ipc_Server *server; }; - -/** - * @struct _Ecore_Ipc_Event_Client_Data - * - * An IPC structure for client_data event. - */ + struct _Ecore_Ipc_Event_Client_Data { - Ecore_Ipc_Client *client; /**< An IPC connection handle */ - /* FIXME: this needs to become an ipc message */ - int major; /**< The message major opcode number */ - int minor; /**< The message minor opcode number */ - int ref; /**< The message reference number */ - int ref_to; /**< Reference number of the message it refers to */ - int response; /**< Requires response */ - void *data; /**< The message data */ - int size; /**< The data length (in bytes) */ + Ecore_Ipc_Client *client; + /* FIXME: This needs to become an IPC message */ + int major; + int minor; + int ref; + int ref_to; + int response; + void *data; + int size; }; - -/** - * @struct _Ecore_Ipc_Event_Server_Data - * - * An IPC structure for server_data event. - */ + struct _Ecore_Ipc_Event_Server_Data { - Ecore_Ipc_Server *server; /**< An IPC connection handle */ - /* FIXME: this needs to become an ipc message */ - int major; /**< The message major opcode number */ - int minor; /**< The message minor opcode number */ - int ref; /**< The message reference number */ - int ref_to; /**< Reference number of the message it refers to */ - int response; /**< Requires response */ - void *data; /**< The message data */ - int size; /**< The data length (in bytes) */ + Ecore_Ipc_Server *server; + /* FIXME: This needs to become an IPC message */ + int major; + int minor; + int ref; + int ref_to; + int response; + void *data; + int size; }; EAPI extern int ECORE_IPC_EVENT_CLIENT_ADD; @@ -328,16 +290,16 @@ EAPI extern int ECORE_IPC_EVENT_SERVER_DATA; EAPI int ecore_ipc_init(void); EAPI int ecore_ipc_shutdown(void); -/* FIXME: need to add protocol type parameter */ +/* FIXME: Need to add protocol type parameter */ EAPI Ecore_Ipc_Server *ecore_ipc_server_add(Ecore_Ipc_Type type, const char *name, int port, const void *data); -/* FIXME: need to add protocol type parameter */ +/* FIXME: Need to add protocol type parameter */ EAPI Ecore_Ipc_Server *ecore_ipc_server_connect(Ecore_Ipc_Type type, char *name, int port, const void *data); EAPI void *ecore_ipc_server_del(Ecore_Ipc_Server *svr); EAPI void *ecore_ipc_server_data_get(Ecore_Ipc_Server *svr); EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr); EAPI Eina_List *ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr); -/* FIXME: this needs to become an ipc message */ +/* FIXME: This needs to become an IPC message */ EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size); EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients); EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *srv, int size); @@ -345,7 +307,7 @@ EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *srv) EAPI const char *ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr); EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr); -/* FIXME: this needs to become an ipc message */ +/* FIXME: This needs to become an IPC message */ EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size); EAPI Ecore_Ipc_Server *ecore_ipc_client_server_get(Ecore_Ipc_Client *cl); EAPI void *ecore_ipc_client_del(Ecore_Ipc_Client *cl); @@ -357,14 +319,11 @@ EAPI const char *ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl); EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl); EAPI int ecore_ipc_ssl_available_get(void); -/* FIXME: need to add a callback to "ok" large ipc messages greater than */ +/* FIXME: Need to add a callback to "ok" large IPC messages greater than */ /* a certain size (security/DOS attack safety) */ #ifdef __cplusplus } #endif -/** - * @} - */ #endif diff --git a/src/lib/ecore_x/Ecore_X.h b/src/lib/ecore_x/Ecore_X.h index 7272b6a948..90e4270203 100644..100755 --- a/src/lib/ecore_x/Ecore_X.h +++ b/src/lib/ecore_x/Ecore_X.h @@ -2,7 +2,6 @@ #define _ECORE_X_H #include <Eina.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI @@ -26,74 +25,41 @@ # endif // ifdef __GNUC__ #endif // ifdef _MSC_VER -#define ECORE_X_VERSION_MAJOR EFL_VERSION_MAJOR -#define ECORE_X_VERSION_MINOR EFL_VERSION_MINOR -/** - * @typedef Ecore_X_Version - * Represents the current version of Ecore_X - */ -typedef struct _Ecore_X_Version -{ - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Ecore_X is built from) */ -} Ecore_X_Version; - -EAPI extern Ecore_X_Version *ecore_x_version; - -#include "ecore_x_version.h" - #include <sys/types.h> /** + * @internal * @file - * @brief Ecore functions for dealing with the X Windows System + * @brief Ecore functions for dealing with the X Windows System. * - * @defgroup Ecore_X_Group Ecore_X - X11 Integration - * @ingroup Ecore - * - * Ecore_X provides a wrapper and convenience functions for using the - * X Windows System. Function groups for this part of the library - * include the following: + * @remarks Ecore_X provides wrapper and convenience functions for using the + * X Windows System. Function groups for this part of the library + * include the following: * @li @ref Ecore_X_Init_Group * @li @ref Ecore_X_Display_Attr_Group * @li @ref Ecore_X_Flush_Group - * @li @ref Ecore_X_DPMS_Group - * @li @ref Ecore_X_Drawable_Group - * @li @ref Ecore_X_Pixmap_Group - * @li @ref Ecore_X_Window_Create_Group - * @li @ref Ecore_X_Window_Properties_Group - * @li @ref Ecore_X_Window_Destroy_Group - * @li @ref Ecore_X_Window_Visibility_Group - * @li @ref Ecore_X_Window_Geometry_Group - * @li @ref Ecore_X_Window_Focus_Functions - * @li @ref Ecore_X_Window_Z_Order_Group - * @li @ref Ecore_X_Window_Parent_Group - * @li @ref Ecore_X_Window_Shape - * - * When using the XLib backend, setting the ECORE_X_SYNC environment variable - * will cause X calls to be run synchronously for easier debugging. + */ + +/** + * @internal + * @defgroup Ecore_X_Group Ecore X + * @ingroup Ecore_Group + * @{ */ typedef unsigned int Ecore_X_ID; #ifndef _ECORE_X_WINDOW_PREDEF typedef Ecore_X_ID Ecore_X_Window; -typedef Ecore_X_ID Ecore_X_Pixmap; -typedef Ecore_X_ID Ecore_X_Atom; -typedef struct _Ecore_X_Icon -{ - unsigned int width, height; - unsigned int *data; -} Ecore_X_Icon; #endif // ifndef _ECORE_X_WINDOW_PREDEF typedef void *Ecore_X_Visual; +typedef Ecore_X_ID Ecore_X_Pixmap; typedef Ecore_X_ID Ecore_X_Drawable; #ifdef HAVE_ECORE_X_XCB typedef Ecore_X_ID Ecore_X_GC; #else // ifdef HAVE_ECORE_X_XCB typedef void *Ecore_X_GC; #endif /* HAVE_ECORE_X_XCB */ +typedef Ecore_X_ID Ecore_X_Atom; typedef Ecore_X_ID Ecore_X_Colormap; typedef Ecore_X_ID Ecore_X_Time; typedef Ecore_X_ID Ecore_X_Cursor; @@ -102,7 +68,6 @@ typedef void Ecore_X_Connection; typedef void Ecore_X_Screen; typedef Ecore_X_ID Ecore_X_Sync_Counter; typedef Ecore_X_ID Ecore_X_Sync_Alarm; -typedef Ecore_X_ID Ecore_X_Sync_Fence; /**< @since 1.9 */ typedef void Ecore_X_XRegion; typedef Ecore_X_ID Ecore_X_Randr_Output; @@ -123,6 +88,12 @@ typedef struct _Ecore_X_Rectangle unsigned int width, height; } Ecore_X_Rectangle; +typedef struct _Ecore_X_Icon +{ + unsigned int width, height; + unsigned int *data; +} Ecore_X_Icon; + typedef enum _Ecore_X_GC_Value_Mask { ECORE_X_GC_VALUE_MASK_FUNCTION = (1L << 0), @@ -158,22 +129,22 @@ typedef enum _Ecore_X_Composite_Update_Type /** * @typedef _Ecore_X_Window_State - * Defines the different states of the window of Ecore_X. + * @brief Enumeration of the different states of the window of Ecore_X. */ typedef enum _Ecore_X_Window_State { ECORE_X_WINDOW_STATE_UNKNOWN = 0, - ECORE_X_WINDOW_STATE_ICONIFIED, /** The window is iconified. */ - ECORE_X_WINDOW_STATE_MODAL, /** The window is a modal dialog box. */ - ECORE_X_WINDOW_STATE_STICKY, /** The window manager should keep the window's position fixed - * even if the virtual desktop scrolls. */ - ECORE_X_WINDOW_STATE_MAXIMIZED_VERT, /** The window has the maximum vertical size. */ - ECORE_X_WINDOW_STATE_MAXIMIZED_HORZ, /** The window has the maximum horizontal size. */ - ECORE_X_WINDOW_STATE_SHADED, /** The window is shaded. */ - ECORE_X_WINDOW_STATE_SKIP_TASKBAR, /** The window should not be included in the taskbar. */ - ECORE_X_WINDOW_STATE_SKIP_PAGER, /** The window should not be included in the pager. */ - ECORE_X_WINDOW_STATE_HIDDEN, /** The window is invisible (i.e. minimized/iconified) */ - ECORE_X_WINDOW_STATE_FULLSCREEN, /** The window should fill the entire screen and have no + ECORE_X_WINDOW_STATE_ICONIFIED, /**< The window is iconified */ + ECORE_X_WINDOW_STATE_MODAL, /**< The window is a modal dialog box */ + ECORE_X_WINDOW_STATE_STICKY, /**< The window manager should keep the window's position fixed + * even if the virtual desktop scrolls */ + ECORE_X_WINDOW_STATE_MAXIMIZED_VERT, /**< The window has the maximum vertical size */ + ECORE_X_WINDOW_STATE_MAXIMIZED_HORZ, /**< The window has the maximum horizontal size */ + ECORE_X_WINDOW_STATE_SHADED, /**< The window is shaded */ + ECORE_X_WINDOW_STATE_SKIP_TASKBAR, /**< The window should not be included in the taskbar */ + ECORE_X_WINDOW_STATE_SKIP_PAGER, /**< The window should not be included in the pager */ + ECORE_X_WINDOW_STATE_HIDDEN, /**< The window is invisible (i.e. minimized/iconified) */ + ECORE_X_WINDOW_STATE_FULLSCREEN, /**< The window should fill the entire screen and have no * window border/decorations */ ECORE_X_WINDOW_STATE_ABOVE, ECORE_X_WINDOW_STATE_BELOW, @@ -196,6 +167,26 @@ typedef enum _Ecore_X_Window_Stack_Mode ECORE_X_WINDOW_STACK_OPPOSITE = 4 } Ecore_X_Window_Stack_Mode; +/** + * @typedef _Ecore_X_Window_Rotation_Transform_Hint + * @brief Enumeration of the different transform hints of the window of Ecore_X. + * + * @remarks A value of @c 3 means, HINT_0 goes to HINT_180(0x3). + * It is same as HINT_0 goes to HINT_FLIP_H(0x1) and it goes to HINT_FLIP_V(0x2).( 0x1 + 0x2 = 0x3 ) + * + * @remarks A value of @c 7 means, HINT_0 goes to HINT_270(0x7). + * It is same as HINT_0 goes to HINT_90(0x4) and it goes to HINT_FLIP_H(0x1) and HINT_FLIP_V(0x2).( 0x4 + 0x1 + 0x2 = 0x7 ) + */ +typedef enum _Ecore_X_Window_Rotation_Transform_Hint +{ + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_0 = 0, + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_FLIP_H = 0x1, /**< Rotate source image along the horizontal axis */ + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_FLIP_V = 0x2, /**< Rotate source image along the vertical axis */ + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_180 = 0x3, /**< Rotate source image 180 degrees clockwise */ + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_90 = 0x4, /**< Rotate source image 90 degrees clockwise */ + ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_270 = 0x7 /**< Rotate source image 270 degrees clockwise */ +} Ecore_X_Window_Rotation_Transform_Hint; + typedef enum _Ecore_X_Randr_Orientation { ECORE_X_RANDR_ORIENTATION_ROT_0 = (1 << 0), @@ -279,7 +270,6 @@ typedef enum _Ecore_X_Randr_Edid_Aspect_Ratio #define ECORE_X_SELECTION_TARGET_STRING "STRING" #define ECORE_X_SELECTION_TARGET_UTF8_STRING "UTF8_STRING" #define ECORE_X_SELECTION_TARGET_FILENAME "FILENAME" -#define ECORE_X_SELECTION_TARGET_X_MOZ_URL "X_MOZ_URL" #define ECORE_X_DND_VERSION 5 @@ -390,42 +380,34 @@ typedef enum _Ecore_X_Netwm_Direction /** * @typedef _Ecore_X_Error_Code - * Defines the error codes of Ecore_X which wraps the X Window Systems - * protocol's errors. + * @brief Enumeration of the error codes of Ecore_X that wraps the X Window Systems + * protocol errors. * * @since 1.7.0 */ typedef enum _Ecore_X_Error_Code { - /** Everything is okay. */ - ECORE_X_ERROR_CODE_SUCCESS = 0, /** Bad request code */ - ECORE_X_ERROR_CODE_BAD_REQUEST = 1, /** Int parameter out of range */ - ECORE_X_ERROR_CODE_BAD_VALUE = 2, /** Parameter not a Window */ - ECORE_X_ERROR_CODE_BAD_WINDOW = 3, /** Parameter not a Pixmap */ - ECORE_X_ERROR_CODE_BAD_PIXMAP = 4, /** Parameter not an Atom */ - ECORE_X_ERROR_CODE_BAD_ATOM = 5, /** Parameter not a Cursor */ - ECORE_X_ERROR_CODE_BAD_CURSOR = 6, /** Parameter not a Font */ - ECORE_X_ERROR_CODE_BAD_FONT = 7, /** Parameter mismatch */ - ECORE_X_ERROR_CODE_BAD_MATCH = 8, /** Parameter not a Pixmap or Window */ - ECORE_X_ERROR_CODE_BAD_DRAWABLE = 9, /** Bad access */ - ECORE_X_ERROR_CODE_BAD_ACCESS = 10, /** Insufficient resources */ - ECORE_X_ERROR_CODE_BAD_ALLOC = 11, /** No such colormap */ - ECORE_X_ERROR_CODE_BAD_COLOR = 12, /** Parameter not a GC */ - ECORE_X_ERROR_CODE_BAD_GC = 13, /** Choice not in range or already used */ - ECORE_X_ERROR_CODE_BAD_ID_CHOICE = 14, /** Font or color name doesn't exist */ - ECORE_X_ERROR_CODE_BAD_NAME = 15, /** Request length incorrect */ - ECORE_X_ERROR_CODE_BAD_LENGTH = 16, /** Server is defective */ + /** Everything is okay */ + ECORE_X_ERROR_CODE_SUCCESS = 0, /**< Bad request code */ + ECORE_X_ERROR_CODE_BAD_REQUEST = 1, /**< Integer parameter is out of range */ + ECORE_X_ERROR_CODE_BAD_VALUE = 2, /**< Parameter is not a Window */ + ECORE_X_ERROR_CODE_BAD_WINDOW = 3, /**< Parameter is not a Pixmap */ + ECORE_X_ERROR_CODE_BAD_PIXMAP = 4, /**< Parameter is not an Atom */ + ECORE_X_ERROR_CODE_BAD_ATOM = 5, /**< Parameter is not a Cursor */ + ECORE_X_ERROR_CODE_BAD_CURSOR = 6, /**< Parameter is not a Font */ + ECORE_X_ERROR_CODE_BAD_FONT = 7, /**< Parameter mismatch */ + ECORE_X_ERROR_CODE_BAD_MATCH = 8, /**< Parameter is not a Pixmap or Window */ + ECORE_X_ERROR_CODE_BAD_DRAWABLE = 9, /**< Bad access */ + ECORE_X_ERROR_CODE_BAD_ACCESS = 10, /**< Insufficient resources */ + ECORE_X_ERROR_CODE_BAD_ALLOC = 11, /**< No such colormap */ + ECORE_X_ERROR_CODE_BAD_COLOR = 12, /**< Parameter is not a GC */ + ECORE_X_ERROR_CODE_BAD_GC = 13, /**< Choice is not in the range or already used */ + ECORE_X_ERROR_CODE_BAD_ID_CHOICE = 14, /**< Font or color name doesn't exist */ + ECORE_X_ERROR_CODE_BAD_NAME = 15, /**< Request length is incorrect */ + ECORE_X_ERROR_CODE_BAD_LENGTH = 16, /**< Server is defective */ ECORE_X_ERROR_CODE_BAD_IMPLEMENTATION = 17, } Ecore_X_Error_Code; -typedef enum _Ecore_X_Dpms_Mode -{ - ECORE_X_DPMS_MODE_ON = 0, - ECORE_X_DPMS_MODE_STANDBY = 1, - ECORE_X_DPMS_MODE_SUSPEND = 2, - ECORE_X_DPMS_MODE_OFF = 3 -} Ecore_X_Dpms_Mode; - typedef struct _Ecore_X_Event_Mouse_In Ecore_X_Event_Mouse_In; typedef struct _Ecore_X_Event_Mouse_Out Ecore_X_Event_Mouse_Out; typedef struct _Ecore_X_Event_Window_Focus_In Ecore_X_Event_Window_Focus_In; @@ -456,7 +438,6 @@ typedef struct _Ecore_X_Event_Fixes_Selection_Notify Ecore_X_Event_Fixes_S typedef struct _Ecore_X_Selection_Data Ecore_X_Selection_Data; typedef struct _Ecore_X_Selection_Data_Files Ecore_X_Selection_Data_Files; typedef struct _Ecore_X_Selection_Data_Text Ecore_X_Selection_Data_Text; -typedef struct _Ecore_X_Selection_Data_X_Moz_Url Ecore_X_Selection_Data_X_Moz_Url; typedef struct _Ecore_X_Selection_Data_Targets Ecore_X_Selection_Data_Targets; typedef struct _Ecore_X_Event_Xdnd_Enter Ecore_X_Event_Xdnd_Enter; typedef struct _Ecore_X_Event_Xdnd_Position Ecore_X_Event_Xdnd_Position; @@ -492,18 +473,11 @@ typedef struct _Ecore_X_Event_Startup_Sequence Ecore_X_Event_Startup typedef struct _Ecore_X_Event_Generic Ecore_X_Event_Generic; - -typedef struct Ecore_X_Event_Present_Configure Ecore_X_Event_Present_Configure; /**< @since 1.9 */ -typedef struct Ecore_X_Event_Present_Complete Ecore_X_Event_Present_Complete; /**< @since 1.9 */ -typedef struct Ecore_X_Event_Present_Idle Ecore_X_Event_Present_Idle; /**< @since 1.9 */ - typedef struct _Ecore_X_Randr_Screen_Size Ecore_X_Randr_Screen_Size; typedef struct _Ecore_X_Randr_Screen_Size_MM Ecore_X_Randr_Screen_Size_MM; -typedef struct _Ecore_X_Randr_Crtc_Info Ecore_X_Randr_Crtc_Info; /**< @since 1.8 */ typedef struct _Ecore_X_Xdnd_Position Ecore_X_Xdnd_Position; - struct _Ecore_X_Event_Mouse_In { int modifiers; @@ -596,7 +570,7 @@ struct _Ecore_X_Event_Window_Hide Ecore_X_Window win; Ecore_X_Window event_win; Ecore_X_Time time; - Eina_Bool send_event : 1; /**< @since 1.8 */ + Eina_Bool send_event : 1; }; struct _Ecore_X_Event_Window_Show @@ -750,7 +724,6 @@ struct _Ecore_X_Selection_Data ECORE_X_SELECTION_CONTENT_NONE, ECORE_X_SELECTION_CONTENT_TEXT, ECORE_X_SELECTION_CONTENT_FILES, - ECORE_X_SELECTION_CONTENT_X_MOZ_URL, ECORE_X_SELECTION_CONTENT_TARGETS, ECORE_X_SELECTION_CONTENT_CUSTOM } content; @@ -773,13 +746,6 @@ struct _Ecore_X_Selection_Data_Text char *text; }; -struct _Ecore_X_Selection_Data_X_Moz_Url -{ - Ecore_X_Selection_Data data; - Eina_Inarray *links; - Eina_Inarray *link_names; -}; - struct _Ecore_X_Selection_Data_Targets { Ecore_X_Selection_Data data; @@ -895,25 +861,11 @@ struct _Ecore_X_Randr_Screen_Size_MM int width, height, width_mm, height_mm; }; -struct _Ecore_X_Randr_Crtc_Info -{ - Ecore_X_Time timestamp; - int x, y; - unsigned int width, height; - Ecore_X_Randr_Mode mode; - Ecore_X_Randr_Orientation rotation; - int noutput; - Ecore_X_Randr_Output *outputs; - Ecore_X_Randr_Orientation rotations; - int npossible; - Ecore_X_Randr_Output *possible; -}; /**< @since 1.8 */ - struct _Ecore_X_Event_Screen_Change { Ecore_X_Window win; Ecore_X_Window root; - Ecore_X_Randr_Screen_Size_MM size; /* in pixel and millimeters */ + Ecore_X_Randr_Screen_Size_MM size; /* In pixel and millimeters */ Ecore_X_Time time; Ecore_X_Time config_time; Ecore_X_Randr_Orientation orientation; @@ -1062,62 +1014,9 @@ struct _Ecore_X_Event_Generic void *data; }; -typedef enum Ecore_X_Present_Event_Mask -{ - ECORE_X_PRESENT_EVENT_MASK_NO_EVENT = 0, - ECORE_X_PRESENT_EVENT_MASK_CONFIGURE_NOTIFY = 1, - ECORE_X_PRESENT_EVENT_MASK_COMPLETE_NOTIFY = 2, - ECORE_X_PRESENT_EVENT_MASK_IDLE_NOTIFY = 4, -} Ecore_X_Present_Event_Mask; /**< @since 1.9 */ - -typedef struct Ecore_X_Present -{ - Ecore_X_Window win; - unsigned int serial; -} Ecore_X_Present; /**< @since 1.9 */ - -struct Ecore_X_Event_Present_Configure -{ - Ecore_X_Window win; - - int x, y; - unsigned int width, height; - int off_x, off_y; - int pixmap_width, pixmap_height; - long pixmap_flags; -}; /**< @since 1.9 */ - -typedef enum -{ - ECORE_X_PRESENT_COMPLETE_MODE_COPY, - ECORE_X_PRESENT_COMPLETE_MODE_FLIP, - ECORE_X_PRESENT_COMPLETE_MODE_SKIP, -} Ecore_X_Present_Complete_Mode; - -struct Ecore_X_Event_Present_Complete -{ - Ecore_X_Window win; - - unsigned int serial; // value provided when generating request - unsigned long long ust; // system time of presentation - unsigned long long msc; // frame count at time of presentation - Eina_Bool kind : 1; /* 0 for PresentCompleteKindPixmap (PresentPixmap completion), - 1 for PresentCompleteKindNotifyMsc (PresentNotifyMSC completion) */ - Ecore_X_Present_Complete_Mode mode; -}; /**< @since 1.9 */ - -struct Ecore_X_Event_Present_Idle -{ - Ecore_X_Window win; - - unsigned int serial; - Ecore_X_Pixmap pixmap; - Ecore_X_Sync_Fence idle_fence; -}; /**< @since 1.9 */ - -EAPI extern int ECORE_X_EVENT_ANY; /**< low level event dependent on - backend in use, if Xlib will be XEvent, if XCB will be xcb_generic_event_t. - @warning avoid using it. +EAPI extern int ECORE_X_EVENT_ANY; /**< Low level event is dependent on the + backend being used, if Xlib is XEvent, if XCB is xcb_generic_event_t. + @remarks Avoid using it */ EAPI extern int ECORE_X_EVENT_MOUSE_IN; EAPI extern int ECORE_X_EVENT_MOUSE_OUT; @@ -1180,10 +1079,6 @@ EAPI extern int ECORE_X_EVENT_XKB_NEWKBD_NOTIFY; /** @since 1.7 */ EAPI extern int ECORE_X_EVENT_GENERIC; -EAPI extern int ECORE_X_EVENT_PRESENT_CONFIGURE; /**< @since 1.9 */ -EAPI extern int ECORE_X_EVENT_PRESENT_COMPLETE; /**< @since 1.9 */ -EAPI extern int ECORE_X_EVENT_PRESENT_IDLE; /**< @since 1.9 */ - EAPI extern int ECORE_X_EVENT_XDND_ENTER; EAPI extern int ECORE_X_EVENT_XDND_POSITION; EAPI extern int ECORE_X_EVENT_XDND_STATUS; @@ -1206,61 +1101,67 @@ EAPI extern int ECORE_X_RAW_BUTTON_PRESS; /**< @since 1.8 */ EAPI extern int ECORE_X_RAW_BUTTON_RELEASE; /**< @since 1.8 */ EAPI extern int ECORE_X_RAW_MOTION; /**< @since 1.8 */ +/** + * @brief Ecore X WM Protocol + */ typedef enum _Ecore_X_WM_Protocol { - /** If enabled the window manager will be asked to send a - * delete message instead of just closing (destroying) the window. */ + /**< If enabled, the window manager is asked to send a + * delete message instead of just closing (destroying) the window */ ECORE_X_WM_PROTOCOL_DELETE_REQUEST, - /** If enabled the window manager will be told that the window - * explicitly sets input focus. */ + /**< If enabled, the window manager is told that the window + * explicitly sets the input focus */ ECORE_X_WM_PROTOCOL_TAKE_FOCUS, - /** If enabled the window manager can ping the window to check - * if it is alive. */ + /**< If enabled, the window manager can ping the window to check + * if it is alive */ ECORE_X_NET_WM_PROTOCOL_PING, - /** If enabled the window manager can sync updating with the + /**< If enabled, the window manager can sync updating with the * window (?) */ ECORE_X_NET_WM_PROTOCOL_SYNC_REQUEST, - /** Number of defined items */ + /**< Number of defined items */ ECORE_X_WM_PROTOCOL_NUM } Ecore_X_WM_Protocol; +/** + * @brief Enumeration Ecore X Window Input Mode type + */ typedef enum _Ecore_X_Window_Input_Mode { - /** The window can never be focused */ + /**< The window can never be focused */ ECORE_X_WINDOW_INPUT_MODE_NONE, - /** The window can be focused by the WM but doesn't focus itself */ + /**< The window can be focused by the WM but doesn't focus itself */ ECORE_X_WINDOW_INPUT_MODE_PASSIVE, - /** The window sets the focus itself if one of its sub-windows - * already is focused */ + /**< The window sets the focus on its own if one of its sub-windows + * is already focused */ ECORE_X_WINDOW_INPUT_MODE_ACTIVE_LOCAL, - /** The window sets the focus itself even if another window + /**< The window sets the focus itself even if another window * is currently focused */ ECORE_X_WINDOW_INPUT_MODE_ACTIVE_GLOBAL } Ecore_X_Window_Input_Mode; /** * @typedef _Ecore_X_Window_State_Hint - * Defines the different state hint of the window of Ecore_X. + * @brief Enumeration of the different state hints of the window of Ecore_X. */ typedef enum _Ecore_X_Window_State_Hint { - /** Do not provide any state hint to the window manager */ + /**< Do not provide any state hint to the window manager */ ECORE_X_WINDOW_STATE_HINT_NONE = -1, - /** The window wants to remain hidden and NOT iconified */ + /**< The window wants to remain hidden and NOT iconified */ ECORE_X_WINDOW_STATE_HINT_WITHDRAWN, - /** The window wants to be mapped normally */ + /**< The window wants to be mapped normally */ ECORE_X_WINDOW_STATE_HINT_NORMAL, - /** The window wants to start in an iconified state */ + /**< The window wants to start in an iconified state */ ECORE_X_WINDOW_STATE_HINT_ICONIC } Ecore_X_Window_State_Hint; @@ -1364,7 +1265,8 @@ typedef enum _Ecore_X_Illume_Indicator_Opacity_Mode ECORE_X_ILLUME_INDICATOR_OPACITY_UNKNOWN = 0, ECORE_X_ILLUME_INDICATOR_OPAQUE, ECORE_X_ILLUME_INDICATOR_TRANSLUCENT, - ECORE_X_ILLUME_INDICATOR_TRANSPARENT + ECORE_X_ILLUME_INDICATOR_TRANSPARENT, + ECORE_X_ILLUME_INDICATOR_BG_TRANSPARENT } Ecore_X_Illume_Indicator_Opacity_Mode; typedef enum _Ecore_X_Illume_Indicator_Type_Mode @@ -1373,12 +1275,13 @@ typedef enum _Ecore_X_Illume_Indicator_Type_Mode ECORE_X_ILLUME_INDICATOR_TYPE_1, ECORE_X_ILLUME_INDICATOR_TYPE_2, ECORE_X_ILLUME_INDICATOR_TYPE_3 -} Ecore_X_Illume_Indicator_Type_Mode; /**< @since 1.8 */ +} Ecore_X_Illume_Indicator_Type_Mode; typedef enum _Ecore_X_Illume_Window_State { ECORE_X_ILLUME_WINDOW_STATE_NORMAL = 0, - ECORE_X_ILLUME_WINDOW_STATE_FLOATING + ECORE_X_ILLUME_WINDOW_STATE_FLOATING, + ECORE_X_ILLUME_WINDOW_STATE_ASSISTANT_MENU } Ecore_X_Illume_Window_State; /* Window layer constants */ @@ -1394,21 +1297,55 @@ typedef enum _Ecore_X_Illume_Window_State EAPI int ecore_x_init(const char *name); EAPI int ecore_x_shutdown(void); EAPI int ecore_x_disconnect(void); + +/** + * Retrieves the Ecore_X_Display handle used for the current X connection. + * @return The current X display. + * @ingroup Ecore_X_Display_Attr_Group + */ EAPI Ecore_X_Display *ecore_x_display_get(void); EAPI Ecore_X_Connection *ecore_x_connection_get(void); EAPI int ecore_x_fd_get(void); EAPI Ecore_X_Screen *ecore_x_default_screen_get(void); EAPI void ecore_x_screen_size_get(const Ecore_X_Screen *screen, int *w, int *h); + +/** + * Retrieves the number of screens. + * + * @return The count of the number of screens. + * @ingroup Ecore_X_Display_Attr_Group + * + * @since 1.1 + */ EAPI int ecore_x_screen_count_get(void); EAPI int ecore_x_screen_index_get(const Ecore_X_Screen *screen); EAPI Ecore_X_Screen *ecore_x_screen_get(int index); EAPI void ecore_x_double_click_time_set(double t); + +/** + * @brief Retrieves the double and triple click flag timeout. + * + * @see ecore_x_double_click_time_set for more information. + * + * @return The timeout for double clicks in seconds. + * @ingroup Ecore_X_Display_Attr_Group + */ EAPI double ecore_x_double_click_time_get(void); EAPI void ecore_x_flush(void); EAPI void ecore_x_sync(void); EAPI void ecore_x_killall(Ecore_X_Window root); EAPI void ecore_x_kill(Ecore_X_Window win); + +/** + * Return the screen DPI + * + * This is a simplistic call to get DPI. It does not account for differing + * DPI in the x amd y axes nor does it account for multihead or xinerama and + * xrander where different parts of the screen may have different DPI etc. + * + * @return the general screen DPI (dots/pixels per inch). + */ EAPI int ecore_x_dpi_get(void); EAPI Eina_Bool ecore_x_bell(int percent); EAPI unsigned int ecore_x_visual_id_get(Ecore_X_Visual visual); @@ -1469,24 +1406,13 @@ EAPI Ecore_X_Atom ecore_x_dnd_source_action_get(void); EAPI void ecore_x_dnd_callback_pos_update_set(void (*cb)(void *, Ecore_X_Xdnd_Position *data), const void *data); EAPI Eina_Bool ecore_x_dnd_abort(Ecore_X_Window xwin_source); /**< @since 1.9 */ -EAPI Ecore_X_Window - ecore_x_window_full_new(Ecore_X_Window parent, - int x, - int y, - int w, - int h, - Ecore_X_Visual *visual, - Ecore_X_Colormap colormap, - int depth, - Eina_Bool override); /**< @since 1.12 */ - EAPI Ecore_X_Window ecore_x_window_new(Ecore_X_Window parent, int x, int y, int w, int h); EAPI Ecore_X_Window ecore_x_window_override_new(Ecore_X_Window parent, int x, int y, int w, int h); EAPI int ecore_x_window_argb_get(Ecore_X_Window win); EAPI Ecore_X_Window ecore_x_window_manager_argb_new(Ecore_X_Window parent, int x, int y, int w, int h); EAPI Ecore_X_Window ecore_x_window_argb_new(Ecore_X_Window parent, int x, int y, int w, int h); EAPI Ecore_X_Window ecore_x_window_override_argb_new(Ecore_X_Window parent, int x, int y, int w, int h); -EAPI Ecore_X_Window ecore_x_window_permanent_new(Ecore_X_Window parent, Ecore_X_Atom unique_atom); /* @since 1.9 */ +EAPI Ecore_X_Window ecore_x_window_permanent_create(Ecore_X_Window parent, Ecore_X_Atom unique_atom); /* @since 1.9 */ EAPI Ecore_X_Window ecore_x_window_input_new(Ecore_X_Window parent, int x, int y, int w, int h); EAPI void ecore_x_window_configure(Ecore_X_Window win, Ecore_X_Window_Configure_Mask mask, int x, int y, int w, int h, int border_width, Ecore_X_Window sibling, int stack_mode); EAPI void ecore_x_window_cursor_set(Ecore_X_Window win, Ecore_X_Cursor c); @@ -1506,10 +1432,48 @@ EAPI Ecore_X_Window ecore_x_window_focus_get(void); EAPI void ecore_x_window_raise(Ecore_X_Window win); EAPI void ecore_x_window_lower(Ecore_X_Window win); EAPI void ecore_x_window_reparent(Ecore_X_Window win, Ecore_X_Window new_parent, int x, int y); + +/** + * Retrieves the size of the given window. + * @param win The given window. + * @param w Pointer to an integer into which the width is to be stored. + * @param h Pointer to an integer into which the height is to be stored. + * @ingroup Ecore_X_Window_Geometry_Group + */ EAPI void ecore_x_window_size_get(Ecore_X_Window win, int *w, int *h); + +/** + * Retrieves the geometry of the given window. + * + * Note that the x & y coordinates are relative to your parent. In + * particular for reparenting window managers - relative to you window border. + * If you want screen coordinates either walk the window tree to the root, + * else for ecore_evas applications see ecore_evas_geometry_get(). Elementary + * applications can use elm_win_screen_position_get(). + * + * @param win The given window. + * @param x Pointer to an integer in which the X position is to be stored. + * @param y Pointer to an integer in which the Y position is to be stored. + * @param w Pointer to an integer in which the width is to be stored. + * @param h Pointer to an integer in which the height is to be stored. + * @ingroup Ecore_X_Window_Geometry_Group + */ EAPI void ecore_x_window_geometry_get(Ecore_X_Window win, int *x, int *y, int *w, int *h); + +/** + * Retrieves the width of the border of the given window. + * @param win The given window. + * @return Width of the border of @p win. + * @ingroup Ecore_X_Window_Geometry_Group + */ EAPI int ecore_x_window_border_width_get(Ecore_X_Window win); EAPI void ecore_x_window_border_width_set(Ecore_X_Window win, int width); + +/** + * Retrieves the depth of the given window. + * @param win The given window. + * @return Depth of the window. + */ EAPI int ecore_x_window_depth_get(Ecore_X_Window win); EAPI void ecore_x_window_cursor_show(Ecore_X_Window win, Eina_Bool show); EAPI void ecore_x_window_defaults_set(Ecore_X_Window win); @@ -1613,13 +1577,14 @@ EAPI Ecore_X_Cursor ecore_x_cursor_shape_get(int shape); EAPI void ecore_x_cursor_size_set(int size); EAPI int ecore_x_cursor_size_get(void); -/* FIXME: these funcs need categorising */ +/* FIXME: These functions need categorising */ EAPI Ecore_X_Window *ecore_x_window_root_list(int *num_ret); EAPI Ecore_X_Window ecore_x_window_root_first_get(void); EAPI Eina_Bool ecore_x_window_manage(Ecore_X_Window win); EAPI void ecore_x_window_container_manage(Ecore_X_Window win); EAPI void ecore_x_window_client_manage(Ecore_X_Window win); EAPI void ecore_x_window_sniff(Ecore_X_Window win); +EAPI void ecore_x_window_unsniff(Ecore_X_Window win); EAPI void ecore_x_window_client_sniff(Ecore_X_Window win); EAPI Ecore_X_Atom ecore_x_atom_get(const char *name); @@ -1840,122 +1805,30 @@ EAPI void ecore_x_e_comp_dump_send(Ecore_X_Window win EAPI void ecore_x_e_comp_pixmap_set(Ecore_X_Window win, Ecore_X_Pixmap pixmap); EAPI Ecore_X_Pixmap ecore_x_e_comp_pixmap_get(Ecore_X_Window win); -/** - * @brief Get the window profile - * - * @param win The client x window - * @return The string value of the window profile, or NULL if none exists - */ EAPI char *ecore_x_e_window_profile_get(Ecore_X_Window win); -/** - * @brief Set the window profile - * - * @param win The client x window - * @param profile The string value of the window profile - */ EAPI void ecore_x_e_window_profile_set(Ecore_X_Window win, const char *profile); -/** - * @brief Set the array of window profiles - * - * @param win The client x window - * @param profiles The string array of window profiles - * @param num_profiles The number of window profiles - * - * @deprecated use ecore_x_e_window_available_profiles_set - */ EAPI void ecore_x_e_window_profile_list_set(Ecore_X_Window win, const char **profiles, unsigned int num_profiles); -/** - * @brief Get the array of window profiles - * - * @param win The client x window - * @param profiles Where to return the string array of window profiles - * @param ret_num Where to return the number of window profiles - * @return EINA_TRUE if window profiles exist, EINA_FALSE otherwise - * - * @deprecated use ecore_x_e_window_available_profiles_get - */ EAPI Eina_Bool ecore_x_e_window_profile_list_get(Ecore_X_Window win, const char ***profiles, int *ret_num); -/** - * @brief Set the status for the window profile support - * - * @param root The root window - * @param enabled The enabled value for the window profile support - * - * @since 1.8 - */ -EAPI void ecore_x_e_window_profile_supported_set(Ecore_X_Window root, Eina_Bool enabled); -/** - * @brief Query if the window profile is supported - * - * @param root The root window - * @return EINA_TRUE if it is supported, EINA_FALSE otherwise - * - * @since 1.8 - */ -EAPI Eina_Bool ecore_x_e_window_profile_supported_get(Ecore_X_Window root); -/** - * @brief Set the array of available window profiles - * - * @param win The client x window - * @param profiles The string array of available window profiles - * @param count The number of available window profiles - * - * @since 1.8 - */ -EAPI void ecore_x_e_window_available_profiles_set(Ecore_X_Window win, const char **profiles, unsigned int count); -/** - * @brief Get the array of avaialbe window profiles - * - * @param win The client x window - * @param profiles Where to return the string array of available window profiles - * @param count Where to return the number of members in profiles - * @return EINA_TRUE if available window profiles exist, EINA_FALSE otherwise - * - * @since 1.8 - */ -EAPI Eina_Bool ecore_x_e_window_available_profiles_get(Ecore_X_Window win, const char ***profiles, int *count); -/** - * @brief Send a profile change event to the window manager - * - * This function sends a request to the window manager to change the profile. - * If honored by the window manager, the client will receive a profile change - * request event back. If the client has replied, the window manager will move - * the client window on the virtual desktop associated with changed profile. - * - * @param root The root x window - * @param win The client x window - * @param profile The string value of the window profile - * - * @since 1.8 - */ -EAPI void ecore_x_e_window_profile_change_send(Ecore_X_Window root, Ecore_X_Window win, const char *profile); -/** - * @brief Send a profile change request event to the client - * - * This function sends a request to the client to change the profile. - * If the client has replied, the window manager will move the client window - * on the virtual desktop associated with changed profile. - * - * @param win The client x window - * @param profile The string value of the window profile - * - * @since 1.8 - */ -EAPI void ecore_x_e_window_profile_change_request_send(Ecore_X_Window win, const char *profile); -/** - * @brief Send a profile change done event to the window manager - * - * This function sends a profile change done event to the window manager. - * Upon receiving, the window manager will move the client window - * on the virtual desktop associated with changed profile. - * - * @param root The root x window - * @param win The client x window - * @param profile The string value of the window profile - * - * @since 1.8 - */ -EAPI void ecore_x_e_window_profile_change_done_send(Ecore_X_Window root, Ecore_X_Window win, const char *profile); + +EAPI void ecore_x_e_window_rotation_supported_set(Ecore_X_Window root, Eina_Bool enabled); +EAPI Eina_Bool ecore_x_e_window_rotation_supported_get(Ecore_X_Window root); +EAPI void ecore_x_e_window_rotation_app_set(Ecore_X_Window win, Eina_Bool set); +EAPI Eina_Bool ecore_x_e_window_rotation_app_get(Ecore_X_Window win); +EAPI void ecore_x_e_window_rotation_preferred_rotation_set(Ecore_X_Window win, int rot); +EAPI Eina_Bool ecore_x_e_window_rotation_preferred_rotation_get(Ecore_X_Window win, int *rot); +EAPI void ecore_x_e_window_rotation_available_rotations_set(Ecore_X_Window win, const int *rots, unsigned int count); +EAPI Eina_Bool ecore_x_e_window_rotation_available_rotations_get(Ecore_X_Window win, int **rots, unsigned int *count); +EAPI void ecore_x_e_window_rotation_change_prepare_send(Ecore_X_Window win, int rot, Eina_Bool resize, int w, int h); +EAPI void ecore_x_e_window_rotation_change_prepare_done_send(Ecore_X_Window root, Ecore_X_Window win, int rot); +EAPI void ecore_x_e_window_rotation_change_request_send(Ecore_X_Window win, int rot); +EAPI void ecore_x_e_window_rotation_change_done_send(Ecore_X_Window root, Ecore_X_Window win, int rot, int w, int h); +EAPI void ecore_x_e_window_rotation_geometry_set(Ecore_X_Window win, int rot, int x, int y, int w, int h); +EAPI Eina_Bool ecore_x_e_window_rotation_geometry_get(Ecore_X_Window win, int rot, int *x, int *y, int *w, int *h); +EAPI void ecore_x_e_virtual_keyboard_control_window_set(Ecore_X_Window root, Ecore_X_Window win, unsigned int zone, Eina_Bool set); +EAPI void ecore_x_e_virtual_keyboard_on_prepare_request_send(Ecore_X_Window win); +EAPI void ecore_x_e_virtual_keyboard_on_prepare_done_send(Ecore_X_Window root, Ecore_X_Window win); +EAPI void ecore_x_e_virtual_keyboard_off_prepare_request_send(Ecore_X_Window win); +EAPI void ecore_x_e_virtual_keyboard_off_prepare_done_send(Ecore_X_Window root, Ecore_X_Window win); EAPI Ecore_X_Sync_Alarm ecore_x_sync_alarm_new(Ecore_X_Sync_Counter counter); EAPI Eina_Bool ecore_x_sync_alarm_free(Ecore_X_Sync_Alarm alarm); @@ -1986,12 +1859,8 @@ EAPI int ecore_x_screensaver_interval_get(void); EAPI void ecore_x_screensaver_event_listen_set(Eina_Bool on); EAPI Eina_Bool ecore_x_screensaver_custom_blanking_enable(void); /** @since 1.7 */ EAPI Eina_Bool ecore_x_screensaver_custom_blanking_disable(void); /** @since 1.7 */ -EAPI void ecore_x_screensaver_supend(void); /** @since 1.11 */ -EAPI void ecore_x_screensaver_resume(void); /** @since 1.11 */ -EAPI void ecore_x_screensaver_reset(void); /** @since 1.11 */ -EAPI void ecore_x_screensaver_activate(void); /** @since 1.11 */ - -/* FIXME: these funcs need categorising */ + +/* FIXME: These functions need categorising */ typedef struct _Ecore_X_Window_Attributes { @@ -2047,7 +1916,6 @@ EAPI void ecore_x_focus_reset(void); EAPI void ecore_x_events_allow_all(void); EAPI void ecore_x_pointer_last_xy_get(int *x, int *y); EAPI void ecore_x_pointer_xy_get(Ecore_X_Window win, int *x, int *y); -EAPI void ecore_x_pointer_root_xy_get(int *x, int *y); /* ecore_x_region.c */ EAPI Ecore_X_XRegion *ecore_x_xregion_new(void); @@ -2066,8 +1934,8 @@ EAPI Eina_Bool ecore_x_xregion_rect_contain(Ecore_X_XRegion *region, Ecor /* ecore_x_randr.c */ /* The usage of 'Ecore_X_Randr_None' or 'Ecore_X_Randr_Unset' - * depends on the context. In most cases 'Ecore_X_Randr_Unset' - * can be used, but in some cases -1 is a special value to + * depends on the context. In most cases, 'Ecore_X_Randr_Unset' + * can be used, but in some cases @c -1 is a special value to * functions, thus 'Ecore_X_Randr_None' (=0) must be used. */ @@ -2095,30 +1963,24 @@ typedef struct _Ecore_X_Randr_Mode_Info unsigned long modeFlags; } Ecore_X_Randr_Mode_Info; -typedef struct _Ecore_X_Randr_Crtc_Gamma_Info -{ - int size; - unsigned short *red; - unsigned short *green; - unsigned short *blue; -} Ecore_X_Randr_Crtc_Gamma_Info; - EAPI int ecore_x_randr_version_get(void); EAPI Eina_Bool ecore_x_randr_query(void); -EAPI Ecore_X_Time ecore_x_randr_config_timestamp_get(Ecore_X_Window root); /** @since 1.8 */ + +/* ecore_x_randr_11.c */ EAPI Ecore_X_Randr_Orientation ecore_x_randr_screen_primary_output_orientations_get(Ecore_X_Window root); EAPI Ecore_X_Randr_Orientation ecore_x_randr_screen_primary_output_orientation_get(Ecore_X_Window root); EAPI Eina_Bool ecore_x_randr_screen_primary_output_orientation_set(Ecore_X_Window root, Ecore_X_Randr_Orientation orientation); EAPI Ecore_X_Randr_Screen_Size_MM *ecore_x_randr_screen_primary_output_sizes_get(Ecore_X_Window root, int *num); /** - * @brief get the current set size of a given screen's primary output - * @param root window which's primary output will be queried - * @param w the current size's width - * @param h the current size's height - * @param w_mm the current size's width in mm - * @param h_mm the current size's height in mm - * @param size_index of current set size to be used with ecore_x_randr_primary_output_size_set() + * @brief Gets the current set size of a given screen's primary output. + * + * @param[in] root The window whose primary output is queried + * @param[out] w The current size's width + * @param[out] h The current size's height + * @param[out] w_mm The current size's width in mm + * @param[out] h_mm The current size's height in mm + * @param[out] size_index The size index of the current set size to be used with ecore_x_randr_primary_output_size_set() */ EAPI void ecore_x_randr_screen_primary_output_current_size_get(Ecore_X_Window root, int *w, int *h, int *w_mm, int *h_mm, int *size_index); EAPI Eina_Bool ecore_x_randr_screen_primary_output_size_set(Ecore_X_Window root, int size_index); @@ -2126,6 +1988,7 @@ EAPI Ecore_X_Randr_Refresh_Rate ecore_x_randr_screen_primary_outp EAPI Ecore_X_Randr_Refresh_Rate *ecore_x_randr_screen_primary_output_refresh_rates_get(Ecore_X_Window root, int size_index, int *num); EAPI Eina_Bool ecore_x_randr_screen_primary_output_refresh_rate_set(Ecore_X_Window root, int size_index, Ecore_X_Randr_Refresh_Rate rate); +/* ecore_x_randr_12.c */ EAPI void ecore_x_randr_events_select(Ecore_X_Window win, Eina_Bool on); EAPI void ecore_x_randr_screen_current_size_get(Ecore_X_Window root, int *w, int *h, int *w_mm, int *h_mm); @@ -2158,8 +2021,6 @@ EAPI Eina_Bool ecore_x_randr_crtc_orientation_se EAPI Eina_Bool ecore_x_randr_crtc_clone_set(Ecore_X_Window root, Ecore_X_Randr_Crtc original, Ecore_X_Randr_Crtc clone); EAPI Eina_Bool ecore_x_randr_crtc_settings_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, Ecore_X_Randr_Output *outputs, int noutputs, int x, int y, Ecore_X_Randr_Mode mode, Ecore_X_Randr_Orientation orientation); EAPI Eina_Bool ecore_x_randr_crtc_pos_relative_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc_r1, Ecore_X_Randr_Crtc crtc_r2, Ecore_X_Randr_Output_Policy policy, Ecore_X_Randr_Relative_Alignment alignment); -EAPI Ecore_X_Randr_Crtc_Info *ecore_x_randr_crtc_info_get(Ecore_X_Window root, const Ecore_X_Randr_Crtc crtc); /**< @since 1.8 */ -EAPI void ecore_x_randr_crtc_info_free(Ecore_X_Randr_Crtc_Info *info); /**< @since 1.8 */ EAPI Eina_Bool ecore_x_randr_output_mode_add(Ecore_X_Randr_Output output, Ecore_X_Randr_Mode mode); EAPI void ecore_x_randr_output_mode_del(Ecore_X_Randr_Output output, Ecore_X_Randr_Mode mode); EAPI Ecore_X_Randr_Mode *ecore_x_randr_output_modes_get(Ecore_X_Window root, Ecore_X_Randr_Output output, int *num, int *npreferred); @@ -2167,9 +2028,9 @@ EAPI Ecore_X_Randr_Output *ecore_x_randr_output_clones_get(E EAPI Ecore_X_Randr_Crtc *ecore_x_randr_output_possible_crtcs_get(Ecore_X_Window root, Ecore_X_Randr_Output output, int *num); EAPI Ecore_X_Randr_Crtc ecore_x_randr_output_crtc_get(Ecore_X_Window root, Ecore_X_Randr_Output output); EAPI char *ecore_x_randr_output_name_get(Ecore_X_Window root, Ecore_X_Randr_Output output, int *len); -EINA_DEPRECATED EAPI int ecore_x_randr_crtc_gamma_ramp_size_get(Ecore_X_Randr_Crtc crtc); -EINA_DEPRECATED EAPI Ecore_X_Randr_Crtc_Gamma **ecore_x_randr_crtc_gamma_ramps_get(Ecore_X_Randr_Crtc crtc); -EINA_DEPRECATED EAPI Eina_Bool ecore_x_randr_crtc_gamma_ramps_set(Ecore_X_Randr_Crtc crtc, const Ecore_X_Randr_Crtc_Gamma *red, const Ecore_X_Randr_Crtc_Gamma *green, const Ecore_X_Randr_Crtc_Gamma *blue); +EAPI int ecore_x_randr_crtc_gamma_ramp_size_get(Ecore_X_Randr_Crtc crtc); +EAPI Ecore_X_Randr_Crtc_Gamma **ecore_x_randr_crtc_gamma_ramps_get(Ecore_X_Randr_Crtc crtc); +EAPI Eina_Bool ecore_x_randr_crtc_gamma_ramps_set(Ecore_X_Randr_Crtc crtc, const Ecore_X_Randr_Crtc_Gamma *red, const Ecore_X_Randr_Crtc_Gamma *green, const Ecore_X_Randr_Crtc_Gamma *blue); EAPI Eina_Bool ecore_x_randr_move_all_crtcs_but(Ecore_X_Window root, const Ecore_X_Randr_Crtc *not_moved, int nnot_moved, int dx, int dy); EAPI Eina_Bool ecore_x_randr_move_crtcs(Ecore_X_Window root, const Ecore_X_Randr_Crtc *crtcs, int ncrtc, int dx, int dy); EAPI void ecore_x_randr_mode_size_get(Ecore_X_Window root, Ecore_X_Randr_Mode mode, int *w, int *h); @@ -2177,191 +2038,196 @@ EAPI Ecore_X_Randr_Connection_Status ecore_x_randr_output_connection_s EAPI void ecore_x_randr_output_size_mm_get(Ecore_X_Window root, Ecore_X_Randr_Output output, int *w, int *h); EAPI Eina_Bool ecore_x_randr_output_crtc_set(Ecore_X_Window root, Ecore_X_Randr_Output output, const Ecore_X_Randr_Crtc crtc); -EAPI int ecore_x_randr_crtc_gamma_size_get(Ecore_X_Randr_Crtc crtc); /**< @since 1.8 */ -EAPI Ecore_X_Randr_Crtc_Gamma_Info *ecore_x_randr_crtc_gamma_get(Ecore_X_Randr_Crtc crtc); /**< @since 1.8 */ -EAPI Eina_Bool ecore_x_randr_crtc_gamma_set(Ecore_X_Randr_Crtc crtc, const Ecore_X_Randr_Crtc_Gamma_Info *gamma); /**< @since 1.8 */ +/* ecore_x_randr_12_edid.c */ /** - * @brief Validates the header from raw EDID data. + * @brief Validates the header from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if the header is valid, @c EINA_FALSE otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if the header is valid, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_has_valid_header(unsigned char *edid, unsigned long edid_length); /** * @brief Checks whether a display's EDID has a valid checksum. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if the checksum is valid, @c EINA_FALSE otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if the checksum is valid, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_info_has_valid_checksum(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded version from raw EDID data. + * @brief Gets the encoded version from the raw EDID data. * - * The return value has the minor version in the lowest 8 bits, and the major - * version in all the rest of the bits. i.e. + * @remarks The return value has the minor version in the lowest 8 bits, and the major + * version in all the rest of the bits. i.e. * - * minor = (version & 0x000000ff); - * major = (version & 0xffffff00) >> 8; + * minor = (version & 0x000000ff); + * major = (version & 0xffffff00) >> 8; * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded major and minor version encasuplated an int. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded major and minor version encasuplated an int */ EAPI int ecore_x_randr_edid_version_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded manufacturer from raw EDID data. + * @brief Gets the encoded manufacturer from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded manufacturer identifier. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded manufacturer identifier */ EAPI char *ecore_x_randr_edid_manufacturer_name_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded name from raw EDID data. + * @brief Gets the encoded name from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded manufacturer identifier. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded manufacturer identifier */ EAPI char *ecore_x_randr_edid_display_name_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded ASCII from raw EDID data. + * @brief Gets the encoded ASCII from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded ASCII display identifier. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded ASCII display identifier */ EAPI char *ecore_x_randr_edid_display_ascii_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded serial identifier from raw EDID data. + * @brief Gets the encoded serial identifier from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded serial identifier. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded serial identifier */ EAPI char *ecore_x_randr_edid_display_serial_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the encoded model number from raw EDID data. + * @brief Gets the encoded model number from the raw EDID data. * - * The manufacturer ID table is necessary for a useful description. + * @remarks The manufacturer ID table is necessary for a useful description. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded model number. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded model number */ EAPI int ecore_x_randr_edid_model_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the manufacturer serial number from raw EDID data. + * @brief Gets the manufacturer serial number from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The encoded serial manufacturer serial number. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The encoded serial manufacturer serial number */ EAPI int ecore_x_randr_edid_manufacturer_serial_number_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the manufacturer model number from raw EDID data. + * @brief Gets the manufacturer model number from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The manufacturer's model number. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The manufacturer model number */ EAPI int ecore_x_randr_edid_manufacturer_model_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Looks up the DPMS support from raw EDID data. + * @brief Looks for DPMS support from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if DPMS is supported in some way, @c EINA_FALSE - * otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if DPMS is supported in some way, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_dpms_available_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Looks up the DPMS Standby support from raw EDID data. + * @brief Looks for DPMS Standby support from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if DPMS Standby is supported, @c EINA_FALSE otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if DPMS Standby is supported, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_dpms_standby_available_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Looks up the DPMS Suspend support from raw EDID data. + * @brief Looks for DPMS Suspend support from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if DPMS Suspend is supported, @c EINA_FALSE otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if DPMS Suspend is supported, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_dpms_suspend_available_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Looks up the DPMS Off support from raw EDID data. + * @brief Looks for DPMS Off support from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if DPMS Off is supported, @c EINA_FALSE otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if DPMS Off is supported, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_dpms_off_available_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the preferred aspect ratio from raw EDID data. + * @brief Gets the preferred aspect ratio from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The preferred aspect ratio. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The preferred aspect ratio */ EAPI Ecore_X_Randr_Edid_Aspect_Ratio ecore_x_randr_edid_display_aspect_ratio_preferred_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the supported aspect ratios from raw EDID data. + * @brief Gets the supported aspect ratios from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The supported aspect ratios. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The supported aspect ratios */ EAPI Ecore_X_Randr_Edid_Aspect_Ratio ecore_x_randr_edid_display_aspect_ratios_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the supported colorschemes from raw EDID data. + * @brief Gets the supported colorschemes from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The supported colorschemes. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The supported colorschemes */ EAPI Ecore_X_Randr_Edid_Display_Colorscheme ecore_x_randr_edid_display_colorscheme_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the display type from raw EDID data. + * @brief Gets the display type from the raw EDID data. * - * @param edid The edid structure. - * @param edid_length Length of the edid structure. - * @return @c EINA_TRUE, if the display is a digital one, @c EINA_FALSE - * otherwise. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return @c EINA_TRUE if the display is a digital one, + * otherwise @c EINA_FALSE */ EAPI Eina_Bool ecore_x_randr_edid_display_type_digital_get(unsigned char *edid, unsigned long edid_length); /** - * @brief Get the display interface type from raw EDID data. + * @brief Gets the display interface type from the raw EDID data. * - * @param edid the edid structure - * @param edid_length length of the edid structure - * @return The interface type. + * @param[in] edid The edid structure + * @param[in] edid_length The length of the edid structure + * @return The interface type */ EAPI Ecore_X_Randr_Edid_Display_Interface_Type ecore_x_randr_edid_display_interface_type_get(unsigned char *edid, unsigned long edid_length); +/* ecore_x_randr_12.c */ + EAPI Eina_Bool ecore_x_randr_output_backlight_available(void); EAPI void ecore_x_randr_screen_backlight_level_set(Ecore_X_Window root, double level); EAPI double ecore_x_randr_output_backlight_level_get(Ecore_X_Window root, Ecore_X_Randr_Output output); @@ -2377,12 +2243,13 @@ EAPI Eina_Bool ecore_x_randr_output_signal_forma EAPI Ecore_X_Randr_Signal_Property *ecore_x_randr_output_signal_properties_get(Ecore_X_Window root, Ecore_X_Randr_Output output, int *num); EAPI int ecore_x_randr_output_connector_number_get(Ecore_X_Window root, Ecore_X_Randr_Output output); EAPI Ecore_X_Randr_Connector_Type ecore_x_randr_output_connector_type_get(Ecore_X_Window root, Ecore_X_Randr_Output output); -EAPI void ecore_x_randr_crtc_panning_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int *x, int *y, int *w, int *h); /**< @since 1.8 */ -EAPI Eina_Bool ecore_x_randr_crtc_panning_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, const int x, const int y, const int w, const int h); /**< @since 1.8 */ -EAPI void ecore_x_randr_crtc_tracking_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int *x, int *y, int *w, int *h); /**< @since 1.8 */ -EAPI Eina_Bool ecore_x_randr_crtc_tracking_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, const int x, const int y, const int w, const int h); /**< @since 1.8 */ -EAPI void ecore_x_randr_crtc_border_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int *x, int *y, int *w, int *h); /**< @since 1.8 */ -EAPI Eina_Bool ecore_x_randr_crtc_border_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, const int left, const int top, const int right, const int bottom); /**< @since 1.8 */ +/* These dont exist in ecore-x */ +EAPI Eina_Rectangle *ecore_x_randr_crtc_panning_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int *x, int *y, int *w, int *h); +EAPI Eina_Bool ecore_x_randr_crtc_panning_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int x, const int y, const int w, const int h); +EAPI Eina_Rectangle *ecore_x_randr_crtc_tracking_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int *x, int *y, int *w, int *h); +EAPI Eina_Bool ecore_x_randr_crtc_tracking_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int x, const int y, const int w, const int h); +EAPI Eina_Rectangle *ecore_x_randr_crtc_border_area_get(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc); +EAPI Eina_Bool ecore_x_randr_crtc_border_area_set(Ecore_X_Window root, Ecore_X_Randr_Crtc crtc, int left, const int top, const int right, const int bottom); /* XRender Support (horrendously incomplete) */ typedef Ecore_X_ID Ecore_X_Picture; @@ -2417,12 +2284,15 @@ EAPI void ecore_x_region_window_shape_set(Ecore_X_Region region, E EAPI void ecore_x_region_picture_clip_set(Ecore_X_Region region, Ecore_X_Picture picture, int x_origin, int y_origin); /** - * xfixes selection notification request. + * @brief Decides the xfixes selection for which to get a notification request. + * + * @details This lets you choose which selections you want to get notifications for. * - * This lets you choose which selections you want to get notifications for. - * @param selection The selection atom. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. * @since 1.1.0 + * + * @param[in] selection The selection atom + * @return @c EINA_TRUE on success, + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool ecore_x_fixes_selection_notification_request(Ecore_X_Atom selection); @@ -2438,20 +2308,6 @@ EAPI void ecore_x_composite_window_events_enable(Ecore_X_Window wi EAPI Ecore_X_Window ecore_x_composite_render_window_enable(Ecore_X_Window root); EAPI void ecore_x_composite_render_window_disable(Ecore_X_Window root); -/* XPresent Extension Support */ -/** @since 1.9 */ -EAPI void ecore_x_present_select_events(Ecore_X_Window win, unsigned int events); -/** @since 1.9 */ -EAPI void ecore_x_present_notify_msc(Ecore_X_Window win, unsigned int serial, unsigned long long target_msc, unsigned long long divisor, unsigned long long remainder); -/** @since 1.9 */ -EAPI void ecore_x_present_pixmap(Ecore_X_Window win, Ecore_X_Pixmap pixmap, unsigned int serial, Ecore_X_Region valid, - Ecore_X_Region update, int x_off, int y_off, Ecore_X_Randr_Crtc target_crtc, - Ecore_X_Sync_Fence wait_fence, Ecore_X_Sync_Fence idle_fence, unsigned int options, - unsigned long long target_msc, unsigned long long divisor, unsigned long long remainder, - Ecore_X_Present *notifies, int num_notifies); -/** @since 1.9 */ -EAPI Eina_Bool ecore_x_present_exists(void); - /* XDamage Extension Support */ typedef Ecore_X_ID Ecore_X_Damage; @@ -2494,7 +2350,6 @@ EAPI Eina_Bool ecore_x_dpms_query(void); EAPI Eina_Bool ecore_x_dpms_capable_get(void); EAPI Eina_Bool ecore_x_dpms_enabled_get(void); EAPI void ecore_x_dpms_enabled_set(int enabled); -EAPI Ecore_X_Dpms_Mode ecore_x_dpms_power_level_get(void); EAPI void ecore_x_dpms_timeouts_get(unsigned int *standby, unsigned int *suspend, unsigned int *off); EAPI Eina_Bool ecore_x_dpms_timeouts_set(unsigned int standby, unsigned int suspend, unsigned int off); EAPI unsigned int ecore_x_dpms_timeout_standby_get(void); @@ -2510,11 +2365,12 @@ EAPI Eina_Bool ecore_x_test_fake_key_press(const char *key); EAPI const char *ecore_x_keysym_string_get(int keysym); /** - * Given a keyname, return the keycode representing that key - * @param keyname The key from which to get the keycode. - * @return The keycode of the key. + * @brief Returns the keycode representing a key, given that the keyname is provided. * * @since 1.2.0 + * + * @param[in] keyname The key from which to get the keycode + * @return The keycode of the key */ EAPI int ecore_x_keysym_keycode_get(const char *keyname); @@ -2530,7 +2386,10 @@ EAPI Eina_Bool ecore_x_image_is_argb32_get(Ecore_X_Image *im); EAPI Eina_Bool ecore_x_image_to_argb_convert(void *src, int sbpp, int sbpl, Ecore_X_Colormap c, Ecore_X_Visual v, int x, int y, int w, int h, unsigned int *dst, int dbpl, int dx, int dy); EAPI Eina_Bool ecore_x_input_multi_select(Ecore_X_Window win); -EAPI Eina_Bool ecore_x_input_raw_select(Ecore_X_Window win); /**< @since 1.8 */ +/** + * @since 1.8 + */ +EAPI Eina_Bool ecore_x_input_raw_select(Ecore_X_Window win); EAPI Eina_Bool ecore_x_vsync_animator_tick_source_set(Ecore_X_Window win); @@ -2684,33 +2543,24 @@ EAPI void ecore_x_e_illume_indicator_opacity_se EAPI Ecore_X_Illume_Indicator_Opacity_Mode ecore_x_e_illume_indicator_opacity_get(Ecore_X_Window win); EAPI void ecore_x_e_illume_indicator_opacity_send(Ecore_X_Window win, Ecore_X_Illume_Indicator_Opacity_Mode mode); -EAPI void ecore_x_e_illume_indicator_type_set(Ecore_X_Window win, Ecore_X_Illume_Indicator_Type_Mode mode); /**< @since 1.8 */ -EAPI Ecore_X_Illume_Indicator_Type_Mode ecore_x_e_illume_indicator_type_get(Ecore_X_Window win); /**< @since 1.8 */ -EAPI void ecore_x_e_illume_indicator_type_send(Ecore_X_Window win, Ecore_X_Illume_Indicator_Type_Mode mode); /**< @since 1.8 */ +EAPI void ecore_x_e_illume_indicator_type_set(Ecore_X_Window win, Ecore_X_Illume_Indicator_Type_Mode mode); +EAPI Ecore_X_Illume_Indicator_Type_Mode ecore_x_e_illume_indicator_type_get(Ecore_X_Window win); +EAPI void ecore_x_e_illume_indicator_type_send(Ecore_X_Window win, Ecore_X_Illume_Indicator_Type_Mode mode); EAPI void ecore_x_e_illume_window_state_set(Ecore_X_Window win, Ecore_X_Illume_Window_State state); EAPI Ecore_X_Illume_Window_State ecore_x_e_illume_window_state_get(Ecore_X_Window win); -EAPI void ecore_x_e_illume_window_state_send(Ecore_X_Window win, Ecore_X_Illume_Window_State state); /**< @since 1.9 */ +EAPI void ecore_x_e_illume_window_state_send(Ecore_X_Window win, Ecore_X_Illume_Window_State state); EAPI void ecore_x_xkb_select_group(int group); /* @since 1.7 */ -EAPI void ecore_x_e_window_rotation_supported_set(Ecore_X_Window root, Eina_Bool enabled); /**< @since 1.9 */ -EAPI Eina_Bool ecore_x_e_window_rotation_supported_get(Ecore_X_Window root); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_app_set(Ecore_X_Window win, Eina_Bool set); /**< @since 1.9 */ -EAPI Eina_Bool ecore_x_e_window_rotation_app_get(Ecore_X_Window win); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_preferred_rotation_set(Ecore_X_Window win, int rot); /**< @since 1.9 */ -EAPI Eina_Bool ecore_x_e_window_rotation_preferred_rotation_get(Ecore_X_Window win, int *rot); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_available_rotations_set(Ecore_X_Window win, const int *rots, unsigned int count); /**< @since 1.9 */ -EAPI Eina_Bool ecore_x_e_window_rotation_available_rotations_get(Ecore_X_Window win, int **rots, unsigned int *count); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_change_prepare_send(Ecore_X_Window win, int rot, Eina_Bool resize, int w, int h); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_change_prepare_done_send(Ecore_X_Window root, Ecore_X_Window win, int rot); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_change_request_send(Ecore_X_Window win, int rot); /**< @since 1.9 */ -EAPI void ecore_x_e_window_rotation_change_done_send(Ecore_X_Window root, Ecore_X_Window win, int rot, int w, int h); /**< @since 1.9 */ - #ifdef __cplusplus } #endif // ifdef __cplusplus +/** + * @} + */ + #include <Ecore_X_Atoms.h> #include <Ecore_X_Cursor.h> diff --git a/src/lib/ecore_x/Ecore_X_Atoms.h b/src/lib/ecore_x/Ecore_X_Atoms.h index 46b2735768..0038d7d334 100644..100755 --- a/src/lib/ecore_x/Ecore_X_Atoms.h +++ b/src/lib/ecore_x/Ecore_X_Atoms.h @@ -2,11 +2,12 @@ #define _ECORE_X_ATOMS_H /** + * @internal * @file - * @brief Ecore X atoms + * @brief Ecore X atoms. */ -/* generic atoms */ +/* Generic atoms */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_ATOM; EAPI extern Ecore_X_Atom ECORE_X_ATOM_CARDINAL; EAPI extern Ecore_X_Atom ECORE_X_ATOM_COMPOUND_TEXT; @@ -14,7 +15,6 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_FILE_NAME; EAPI extern Ecore_X_Atom ECORE_X_ATOM_STRING; EAPI extern Ecore_X_Atom ECORE_X_ATOM_TEXT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_UTF8_STRING; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_X_MOZ_URL; EAPI extern Ecore_X_Atom ECORE_X_ATOM_WINDOW; EAPI extern Ecore_X_Atom ECORE_X_ATOM_PIXMAP; EAPI extern Ecore_X_Atom ECORE_X_ATOM_VISUALID; @@ -38,7 +38,6 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_XDND_STATUS; EAPI extern Ecore_X_Atom ECORE_X_ATOM_XDND_LEAVE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_XDND_DROP; EAPI extern Ecore_X_Atom ECORE_X_ATOM_XDND_FINISHED; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_XDND_DIRECTSAVE0; /**< @since 1.8 */ /* dnd atoms that need to be exposed to the application interface */ EAPI extern Ecore_X_Atom ECORE_X_DND_ACTION_COPY; @@ -47,10 +46,10 @@ EAPI extern Ecore_X_Atom ECORE_X_DND_ACTION_LINK; EAPI extern Ecore_X_Atom ECORE_X_DND_ACTION_ASK; EAPI extern Ecore_X_Atom ECORE_X_DND_ACTION_PRIVATE; -/* old E atom */ +/* Old E atom */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_FRAME_SIZE; -/* old Gnome atom */ +/* Old Gnome atom */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_WIN_LAYER; /* ICCCM: client properties */ @@ -104,7 +103,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_VIRTUAL_ROOTS; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_DESKTOP_LAYOUT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_SHOWING_DESKTOP; -/* pager */ +/* Pager */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_CLOSE_WINDOW; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_MOVERESIZE_WINDOW; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_MOVERESIZE; @@ -117,7 +116,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_ICON_NAME; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_VISIBLE_ICON_NAME; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_DESKTOP; -/* window type */ +/* Window type */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE_DESKTOP; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE_DOCK; @@ -134,7 +133,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE_NOTIFICATION; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE_COMBO; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_WINDOW_TYPE_DND; -/* state */ +/* State */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE_MODAL; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE_STICKY; @@ -149,7 +148,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE_ABOVE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE_BELOW; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_STATE_DEMANDS_ATTENTION; -/* allowed actions */ +/* Allowed actions */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_ALLOWED_ACTIONS; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_ACTION_MOVE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_NET_WM_ACTION_RESIZE; @@ -189,7 +188,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_SELECTION_PROP_PRIMARY; EAPI extern Ecore_X_Atom ECORE_X_ATOM_SELECTION_PROP_SECONDARY; EAPI extern Ecore_X_Atom ECORE_X_ATOM_SELECTION_PROP_CLIPBOARD; -/* currently E specific virtual keyboard extension, aim to submit to netwm spec +/* Currently E specific virtual keyboard extension, aim to submit to netwm spec * later */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD; @@ -247,6 +246,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_OPACITY_MODE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_OPAQUE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_TRANSLUCENT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_TRANSPARENT; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_BG_TRANSPARENT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_TYPE_MODE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_TYPE_1; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_INDICATOR_TYPE_2; @@ -261,6 +261,7 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_CLIPBOARD_GEOMETRY; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_WINDOW_STATE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_WINDOW_STATE_NORMAL; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_WINDOW_STATE_FLOATING; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_WINDOW_STATE_ASSISTANT_MENU; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_CONTROL; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_NEXT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_PREV; @@ -273,15 +274,11 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_UP; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_DOWN; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_BACK; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_SCROLL; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_ZOOM; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_MOUSE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_ENABLE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ACTION_DISABLE; -/* Abi compat fix */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_ENABLE; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_ACCESS_DISABLE; -/* End of Abi compat fix */ - EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_COMP_SYNC_COUNTER; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_COMP_SYNC_DRAW_DONE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_COMP_SYNC_SUPPORTED; @@ -295,29 +292,22 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_COMP_PIXMAP; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIDEO_PARENT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIDEO_POSITION; -/* currently elementary and E specific extension */ -/* @deprecated use ECORE_X_ATOM_E_WINDOW_PROFILE */ +/* For operating indicator and quickpanel */ +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_INDICATOR_FLICK_DONE; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_MOVE_QUICKPANEL_STATE; + +/* Currently elementary and E specific extension */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_PROFILE; -/* @deprecated use ECORE_X_ATOM_E_WINDOW_PROFILE_AVAILABLE_LIST */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_PROFILE_LIST; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE_SUPPORTED; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE_CHANGE; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE_AVAILABLE_LIST; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE_CHANGE_REQUEST; -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_PROFILE_CHANGE_DONE; - -/* for sliding window */ + +/* For sliding window */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_SLIDING_WIN_STATE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_ILLUME_SLIDING_WIN_GEOMETRY; -/* for SDB(Samsung Debug Bridge) */ +/* For SDB */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_SDB_SERVER_CONNECT; EAPI extern Ecore_X_Atom ECORE_X_ATOM_SDB_SERVER_DISCONNECT; -/* for deiconify approve protcol */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_DEICONIFY_APPROVE; - /* E window rotation extension */ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_SUPPORTED; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_APP_SUPPORTED; @@ -327,10 +317,24 @@ EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_CHANGE_PREPARE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_CHANGE_PREPARE_DONE; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_CHANGE_REQUEST; EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_CHANGE_DONE; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_0_GEOMETRY; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_90_GEOMETRY; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_180_GEOMETRY; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_270_GEOMETRY; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_ROTATION_TRANSFORM_HINT; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_DESKTOP_LAYOUT; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD_CONTROL_WINDOW; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD_ON_PREPARE_REQUEST; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD_ON_PREPARE_DONE; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD_OFF_PREPARE_REQUEST; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_VIRTUAL_KEYBOARD_OFF_PREPARE_DONE; + +/* For deiconify approve protcol */ +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_DEICONIFY_APPROVE; -/* E window auxiliary hint */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_SUPPORTED_LIST; /**< @since 1.10 */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_SUPPORT; /**< @since 1.10 */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT; /**< @since 1.10 */ -EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_ALLOWED; /**< @since 1.10 */ +/* For window auxiliary hint */ +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_SUPPORTED_LIST; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_SUPPORT; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT; +EAPI extern Ecore_X_Atom ECORE_X_ATOM_E_WINDOW_AUX_HINT_ALLOWED; #endif /* _ECORE_X_ATOMS_H */ diff --git a/src/lib/ecore_x/Ecore_X_Cursor.h b/src/lib/ecore_x/Ecore_X_Cursor.h index 807541e596..05d3b8a9b4 100644 --- a/src/lib/ecore_x/Ecore_X_Cursor.h +++ b/src/lib/ecore_x/Ecore_X_Cursor.h @@ -2,8 +2,9 @@ #define _ECORE_X_CURSOR_H /** + * @internal * @file - * @brief Defines the various cursor types for the X Windows system. + * @brief Definition for the various cursor types of the X Windows system. */ #define ECORE_X_CURSOR_X 0 diff --git a/src/lib/edje/Edje.h b/src/lib/edje/Edje.h index ccace36e1a..95a7e30ea2 100644 --- a/src/lib/edje/Edje.h +++ b/src/lib/edje/Edje.h @@ -1,8 +1,13 @@ /** +@defgroup Edje_Group Edje +@ingroup EFL_Group + @brief Edje Graphical Design Library These routines are used for Edje. +See @ref edje_main for more details. + @page edje_main Edje @date 2003 (created) @@ -13,116 +18,92 @@ These routines are used for Edje. @li @ref edje_main_work @li @ref edje_main_compiling @li @ref edje_main_next_steps -@li @ref edje_main_intro_example @section edje_main_intro Introduction Edje is a complex graphical design & layout library. -It doesn't intend to do containing and regular layout like a widget +It doesn't intend to do a containing and regular layout like a widget set, but it is the base for such components. Based on the requirements of Enlightenment 0.17, Edje should serve all the purposes of creating visual elements (borders of windows, buttons, scrollbars, etc.) and -allow the designer the ability to animate, layout and control the look +allow the designer the ability to animate, layout, and control the look and feel of any program using Edje as its basic GUI constructor. This library allows for multiple collections of Layouts in one file, sharing the same image and font database and thus allowing a whole theme to be conveniently packaged into 1 file and shipped around. Edje separates the layout and behavior logic. Edje files ship with an -image and font database, used by all the parts in all the collections +image and font database that is used by all the parts of all the collections to source graphical data. It has a directory of logical part names pointing to the part collection entry ID in the file (thus allowing for multiple logical names to point to the same part collection, allowing for the sharing of data between display elements). Each part collection consists of a list of visual parts, as well as a list of -programs. A program is a conditionally run program that if a +programs. A program is a conditionally run program such that if a particular event occurs (a button is pressed, a mouse enters or leaves -a part) will trigger an action that may affect other parts. In this -way a part collection can be "programmed" via its file as to hilight +a part) it triggers an action that may affect other parts. In this +way a part collection can be "programmed" via its file to highlight buttons when the mouse passes over them or show hidden parts when a -button is clicked somewhere etc. The actions performed in changing +button is clicked somewhere, and so on. The actions performed in changing from one state to another are also allowed to transition over a period of time, allowing animation. Programs and animations can be run in "parallel". This separation and simplistic event driven style of programming can produce -almost any look and feel one could want for basic visual elements. Anything -more complex is likely the domain of an application or widget set that may -use Edje as a convenient way of being able to configure parts of the display. +almost any look and feel that one could want for basic visual elements. Anything +more complex is mostly the domain of an application or a widget set that may +use Edje as a convenient way to able to configure parts of the display. -For details of Edje's history, see the @ref edje_history section. +For details on Edje's history, see the @ref edje_history section. @subsection edje_main_work So how does this all work? Edje internally holds a geometry state machine and state graph of what is -visible, not, where, at what size, with what colors etc. This is described +visible or not, where it is visible, at what size, with what colors, and so on. This is described to Edje from an Edje .edj file containing this information. These files can be produced by using edje_cc to take a text file (a .edc file) and "compile" -an output .edj file that contains this information, images and any other -data needed. +an output .edj file that contains this information, images, and any other +data that is needed. -The application using Edje will then create an object in its Evas -canvas and set the bundle file to use, specifying the @b group name to -use. Edje will load such information and create all the required +The application using Edje then creates an object in its Evas +canvas and sets the bundle file to use, specifying the @b group name to +use. Edje loads such information and creates all the required children objects with the specified properties as defined in each @b -part of the given group. See the example at @ref edje_main_intro_example. +part of the given group. -Although simple, this example illustrates that animations and state -changes can be done from the Edje file itself without any requirement -in the C application. - -Before digging into changing or creating your own Edje source (edc) -files, read the @ref edcref. +Before going into the depth of changing or creating your own edje source (edc) +files, read @ref edcref. @subsection edje_history Edje History It's a sequel to "Ebits" which has serviced the needs of Enlightenment development for early version 0.17. The original design parameters under -which Ebits came about were a lot more restricted than the resulting -use of them, thus Edje was born. +which Ebits is built are a lot more restricted than the resulting +use of them, thus Edje is born. Edje is a more complex layout engine compared to Ebits. It doesn't -pretend to do containing and regular layout like a widget set. It +pretend to do a containing and regular layout like a widget set. It still inherits the more simplistic layout ideas behind Ebits, but it now does them a lot more cleanly, allowing for easy expansion, and the -ability to cover much more ground than Ebits ever could. For the -purposes of Enlightenment 0.17, Edje was conceived to serve all the +ability to cover much more ground than Ebits could. For the +purposes of Enlightenment 0.17, Edje is conceived to serve all the purposes of creating visual elements (borders of windows, buttons, scrollbars, etc.) and allow the designer the ability to animate, -layout and control the look and feel of any program using Edje as its +layout, and control the look and feel of any program using Edje as its basic GUI constructor. Unlike Ebits, Edje separates the layout and behavior logic. @section edje_main_compiling How to compile -Edje is a library your application links to. The procedure for this is -very simple. You simply have to compile your application with the -appropriate compiler flags that the @c pkg-config script outputs. For -example: - -Compiling C or C++ files into object files: - -@verbatim -gcc -c -o main.o main.c `pkg-config --cflags edje` -@endverbatim - -Linking object files into a binary executable: - -@verbatim -gcc -o my_application main.o `pkg-config --libs edje` -@endverbatim - -See @ref pkgconfig - @section edje_main_next_steps Next Steps After you understood what Edje is and installed it in your system you should proceed understanding the programming interface for all objects, then see the specific for the most used elements. We'd -recommend you to take a while to learn @ref Ecore, @ref Evas, @ref Eo -and @ref Eina as they are the building blocks for Edje. There is a +recommend you to take a while to learn @ref Ecore_Group, @ref Evas, +and @ref Eina_Group as they are the building blocks for Edje. There is a widget set built on top of Edje providing high level elements such as buttons, lists and selectors called Elementary (http://docs.enlightenment.org/auto/elementary/) as they will likely @@ -130,70 +111,26 @@ save you tons of work compared to using just Evas directly. Recommended reading: @li @ref edcref +@internal @li @ref Edje_General_Group +@endinternal @li @ref Edje_Object_Group +@internal @li @ref Edje_External_Group +@endinternal @li @ref luaref -@section edje_main_intro_example Introductory Example - -What follows is a list with various commented examples, covering a great -part of Edje's API: - -@include edje_example.c - -The above example requires the following annotated source Edje file: -@include edje_example.edc - - -More examples can be found at @ref edje_examples. */ /** + * @page edcref + * See http://docs.enlightenment.org/auto/edje/edcref.html + */ -@example embryo_custom_state.edc -This example shows how to create a custom state from embryo. Clicking on the -3 labels will rotate the object in the given direction. - -@example embryo_pong.edc -Super-simple Pong implementation in pure embryo. - -@example embryo_run_program.edc -This example shows how to run an edje program from embryo code. - -@example embryo_set_state.edc -This example shows how to change the state of a part from embryo code. - -@example embryo_set_text.edc -This example shows how to set the text in TEXT part from embryo code. - -@example embryo_timer.edc -This example shows the usage of timers in embryo. - -@example external_elm_anchorblock.edc -This example use an elementary anchorblock and a button to animate the text. - -@example external_elm_button.edc -This example create some elementary buttons and do some actions on user click. - -@example external_elm_check.edc -This example shows EXTERNAL checkbox in action. - -@example external_elm_panes.edc -This example shows EXTERNAL elementary panes in action. - -@example external_emotion_elm.edc -Super-concise video player example using Edje/Emotion/Elementary. - -@example lua_script.edc -This example shows the usage of lua scripting to create and animate some -objects in the canvas. - -@example toggle_using_filter.edc -This example shows how to toggle the state of a part using the 'filter' -param in edje programs - -*/ +/** + * @page luaref + * See http://docs.enlightenment.org/auto/edje/luaref.html + */ /** * @file Edje.h @@ -202,6 +139,20 @@ param in edje programs * These routines are used for Edje. */ +/** + * @internal + * @defgroup Edje_General_Group Edje General + * @ingroup Edje_Group + * + * @brief This group discusses the functions that have general purposes or affect Edje as a whole. + * + * Besides containing the initialize and shutdown functions of the library, which should + * always be called when we are using Edje, this module contains some other utilities that + * could be used in many contexts or should do their jobs independent of the context inside Edje. + * + * @{ + */ + #ifndef _EDJE_H #define _EDJE_H @@ -213,13 +164,15 @@ param in edje programs #include <limits.h> #include <Evas.h> -#include <Eo.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI #endif +#ifdef HAVE_ECORE_IMF +#include <Ecore_IMF.h> +#endif + #ifdef _WIN32 # ifdef EFL_EDJE_BUILD # ifdef DLL_EXPORT @@ -246,16 +199,5174 @@ param in edje programs extern "C" { #endif -#define EDJE_VERSION_MAJOR EFL_VERSION_MAJOR -#define EDJE_VERSION_MINOR EFL_VERSION_MINOR +#define EDJE_VERSION_MAJOR 1 +#define EDJE_VERSION_MINOR 8 -#include "Edje_Common.h" -#ifndef EFL_NOLEGACY_API_SUPPORT -#include "Edje_Legacy.h" -#endif -#ifdef EFL_EO_API_SUPPORT -#include "Edje_Eo.h" +typedef struct _Edje_Version +{ + int major; + int minor; + int micro; + int revision; +} Edje_Version; + +EAPI extern Edje_Version *edje_version; + +/** + * @brief Initializes the edje library. + * + * @details This function initializes the Ejde library, making proper calls + * to internal initialization functions. It also initializes its + * @b dependencies, making calls to @c eina_init(), @c ecore_init(), + * @c embryo_init(), and @c eet_init(). So there is no need to call + * those functions again, in your code. To shutdown Edje you can call the + * function edje_shutdown(). + * + * @return The new init count \n + * The initial value is zero. + * + * @see edje_shutdown() + * @see eina_init() + * @see ecore_init() + * @see embryo_init() + * @see eet_init() + */ +EAPI int edje_init (void); + +/** + * @brief Shutsdown the edje library. + * + * @details This function shuts down the edje library. It also calls the + * shutdown functions of its @b dependencies, which are @c + * eina_shutdown(), @c ecore_shutdown(), @c embryo_shutdown(), and @c + * eet_shutdown(), so there is no need to call these functions again, + * in your code. + * + * @return The number of times the library has been initialised + * without being shutdown + * + * @see edje_init() + * @see eina_shutdown() + * @see ecore_shutdown() + * @see embryo_shutdown() + * @see eet_shutdown() + * + */ +EAPI int edje_shutdown (void); + +/** + * @brief Sets the edje append fontset. + * + * @details This function sets the edje append fontset. + * + * @param[in] fonts The fontset to append + * + */ +EAPI void edje_fontset_append_set (const char *fonts); + +/** + * @brief Gets the edje append fontset. + * + * @details This function returns the edje append fontset set by the + * edje_fontset_append_set() function. + * + * @return The edje append fontset + * + * @see edje_fontset_append_set() + * + */ +EAPI const char *edje_fontset_append_get (void); + +/** + * @brief Loads a new module in Edje. + * + * @remarks Modules are used to add functionality to Edje. + * So when a module is loaded, its functionality should be available for use. + * + * @param[in] module The name of the module that is added to Edje + * @return #EINA_TRUE if the module is successfully loaded, + * otherwise #EINA_FALSE + * + */ +EAPI Eina_Bool edje_module_load (const char *module); + +/** + * @brief Retrieves all modules that can be loaded. + * + * @details This function retrieves all the modules that can be loaded by edje_module_load(). + * + * @return A list of all the loadable modules + * + * @see edje_module_load() + * + */ +EAPI const Eina_List *edje_available_modules_get (void); + +/** + * @brief Sets the file cache size. + * + * @details This function sets the file cache size. Edje keeps this cache in + * order to prevent duplicate edje file entries in the memory. The + * file cache size can be retrieved using edje_file_cache_get(). + * + * @param[in] count The file cache size in edje file units \n + * Default is 16. + * + * @see edje_file_cache_get() + * @see edje_file_cache_flush() + * + */ +EAPI void edje_file_cache_set (int count); + +/** + * @brief Gets the file cache size. + * + * @details This function returns the file cache size set by + * edje_file_cache_set(). + * + * @return The file cache size in edje file units \n + * Default is 16. + * + * @see edje_file_cache_set() + * @see edje_file_cache_flush() + * + */ +EAPI int edje_file_cache_get (void); + +/** + * @brief Cleans the file cache. + * + * @details This function cleans the file cache entries, but keeps this cache's + * size to the last value set. + * + * @see edje_file_cache_set() + * @see edje_file_cache_get() + * + */ +EAPI void edje_file_cache_flush (void); + +/** + * @brief Sets the collection cache size. + * + * @details This function sets the collection cache size. Edje keeps this cache + * in order to prevent duplicate edje {collection,group,part} + * entries in the memory. The collection cache size can be retrieved using + * edje_collection_cache_get(). + * + * @param[in] count The collection cache size, in edje object units \n + * Default is 16. + * + * @see edje_collection_cache_get() + * @see edje_collection_cache_flush() + * + */ +EAPI void edje_collection_cache_set (int count); + +/** + * @brief Gets the collection cache size. + * + * @details This function returns the collection cache size set by + * edje_collection_cache_set(). + * + * @return The collection cache size, in edje object units \n + * Default is 16. + * + * @see edje_collection_cache_set() + * @see edje_collection_cache_flush() + * + */ +EAPI int edje_collection_cache_get (void); + +/** + * @brief Cleans the collection cache. + * + * @details This function cleans the collection cache, but keeps this cache's + * size to the last value set. + * + * @see edje_collection_cache_set() + * @see edje_collection_cache_get() + * + */ +EAPI void edje_collection_cache_flush (void); + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_External_Group Edje External + * @ingroup Edje_Group + * + * @brief This group discusses functions of the external section of Edje. + * + * @remarks The programmer can create new types of parts, that are generically called + * EXTERNALS as they are not natives of Edje. The developer must also create + * plugins that define the meaning of each extra property carried by + * these parts of type EXTERNAL. + * + * As long as there are new types that are properly registered with the plugins that are created, + * the user can use the parts of type EXTERNAL as all the parts of native types. + * + * @{ + */ + +/** + * @brief Enumeration of the possible types of an EXTERNAL part parameter. + */ +typedef enum _Edje_External_Param_Type +{ + EDJE_EXTERNAL_PARAM_TYPE_INT, /**< Parameter value is an integer */ + EDJE_EXTERNAL_PARAM_TYPE_DOUBLE, /**< Parameter value is a double */ + EDJE_EXTERNAL_PARAM_TYPE_STRING, /**< Parameter value is a string */ + EDJE_EXTERNAL_PARAM_TYPE_BOOL, /**< Parameter value is boolean */ + EDJE_EXTERNAL_PARAM_TYPE_CHOICE, /**< Parameter value is one from a set of + predefined string choices */ + EDJE_EXTERNAL_PARAM_TYPE_MAX /**< Sentinel. Don't use */ +} Edje_External_Param_Type; + +/** + * @brief Enumeration of the flags that determine how a parameter may be accessed in different + * circumstances. + */ +typedef enum _Edje_External_Param_Flags +{ + EDJE_EXTERNAL_PARAM_FLAGS_NONE = 0, /**< Property is incapable of operations, this is used to catch bogus flags */ + EDJE_EXTERNAL_PARAM_FLAGS_GET = (1 << 0), /**< Property can be read/obtained */ + EDJE_EXTERNAL_PARAM_FLAGS_SET = (1 << 1), /**< Property can be written/set. This only enables edje_object_part_external_param_set() and Embryo scripts. To enable the parameter that is set from a state description whenever it changes state, use #EDJE_EXTERNAL_PARAM_FLAGS_STATE */ + EDJE_EXTERNAL_PARAM_FLAGS_STATE = (1 << 2), /**< Property can be set from a state description */ + EDJE_EXTERNAL_PARAM_FLAGS_CONSTRUCTOR = (1 << 3), /**< This property is only set once when the object is constructed using its value from the "default" 0.0 state description. Setting this overrides #EDJE_EXTERNAL_PARAM_FLAGS_STATE */ + EDJE_EXTERNAL_PARAM_FLAGS_REGULAR = (EDJE_EXTERNAL_PARAM_FLAGS_GET | + EDJE_EXTERNAL_PARAM_FLAGS_SET | + EDJE_EXTERNAL_PARAM_FLAGS_STATE) /**< Convenience flag that sets the property as GET, SET, or STATE */ +} Edje_External_Param_Flags; + +/** + * @brief Converts the type identifier to a string representation. + * + * @remarks This may be used to debug or for other informational purposes. + * + * @param[in] type The identifier to convert + * @return The string with the string representation, otherwise @c "(unknown)" + */ +EAPI const char *edje_external_param_type_str(Edje_External_Param_Type type) EINA_PURE; + +/** + * @brief The structure type that holds parameters for the parts of type EXTERNAL. + */ +struct _Edje_External_Param +{ + const char *name; /**< The name of the parameter */ + Edje_External_Param_Type type; /**< The type of the parameter. This defines + which of the next three variables holds + the value for it */ + // XXX these could be in a union, but eet doesn't support them (or does it?) + int i; /**< Used by both integer and boolean */ + double d; /**< Used by double */ + const char *s; /**< Used by both string and choice */ +}; +/** + * @brief The structure type that holds parameters for the parts of type EXTERNAL. + */ +typedef struct _Edje_External_Param Edje_External_Param; + +/** + * @brief Definition of the helper macro to indicate that an EXTERNAL integer parameter is undefined. + */ +#define EDJE_EXTERNAL_INT_UNSET INT_MAX +/** + * @brief Definition of the helper macro to indicate that an EXTERNAL double parameter is undefined. + */ +#define EDJE_EXTERNAL_DOUBLE_UNSET DBL_MAX + +/** + * + * @brief The structure type holding information about an EXTERNAL part's parameters. + * + * @remarks When creating types to use with EXTERNAL parts, an array of this type is + * used to describe the different parameters that the object uses. + * + * @remarks This struct holds the name, type, and flags that define how and when the + * parameter is used, as well as information specific to each type, like the + * maximum or minimum value that can be used by editors to restrict the + * range of values to set for each parameter. + */ +typedef struct _Edje_External_Param_Info Edje_External_Param_Info; + +/** + * @internal + * @brief The structure type holding information about an EXTERNAL part's parameters. + * + * @remarks When creating types to use with EXTERNAL parts, an array of this type is + * used to describe the different parameters that the object uses. + * + * @remarks This struct holds the name, type, and flags that define how and when the + * parameter is used, as well as information specific to each type, like the + * maximum or minimum value that can be used by editors to restrict the + * range of values to set for each parameter. + */ +struct _Edje_External_Param_Info +{ + const char *name; /**< Name of the parameter */ + Edje_External_Param_Type type; /**< Type of the parameter */ + Edje_External_Param_Flags flags; /**< Flags indicating how this parameter is + used */ + union { + struct { + int def, /**< Default value for the parameter */ + min, /**< Minimum value it can have */ + max, /**< Maximum value it can have */ + step; /**< Values are a multiple of this */ + } i; /**< Information about integer type parameters. Use #EDJE_EXTERNAL_INT_UNSET on any of them to indicate that they are not defined */ + struct { + double def, /**< Default value for the parameter */ + min, /**< Minimum value it can have */ + max, /**< Maximum value it can have */ + step; /**< Values are a multiple of this */ + } d; /**< Information about double type parameters. Use #EDJE_EXTERNAL_DOUBLE_UNSET on any of them to indicate that they are not defined */ + struct { + const char *def; /**< Default value */ + const char *accept_fmt; /**< Not implemented */ + const char *deny_fmt; /**< Not implemented */ + } s; /**< Information about string type parameters. NULL indicates undefined */ + struct { + int def; /**< Default value */ + const char *false_str; /**< String shown by editors to indicate the false state */ + const char *true_str; /**< String shown by editors to indicate the true state */ + } b; /**< Information about boolean type parameters */ + struct { + const char *def; /**< Default value */ + const char **choices; /* Array of strings, each represents a + valid value for this parameter. The + last element of the array must be + NULL */ + char *(*def_get)(void *data, const Edje_External_Param_Info *info); /** return malloc() memory with the default choice, should be used if def is NULL. First parameter is Edje_External_Type::data */ + char **(*query)(void *data, const Edje_External_Param_Info *info); /** NULL terminated array of strings, memory is dynamically allocated and should be freed with free() for each array and element. First parameter is Edje_External_Type::data */ + } c; /**< Information about choice type parameters */ + } info; +}; + +#define EDJE_EXTERNAL_PARAM_INFO_INT_FULL_FLAGS(name, def, min, max, step, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_INT, flags, {.i = {def, min, max, step}}} +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FULL_FLAGS(name, def, min, max, step, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_DOUBLE, flags, {.d = {def, min, max, step}}} +#define EDJE_EXTERNAL_PARAM_INFO_STRING_FULL_FLAGS(name, def, accept, deny, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_STRING, flags, {.s = {def, accept, deny}}} +#define EDJE_EXTERNAL_PARAM_INFO_BOOL_FULL_FLAGS(name, def, false_str, true_str, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_BOOL, flags, {.b = {def, false_str, true_str}}} +#define EDJE_EXTERNAL_PARAM_INFO_CHOICE_FULL_FLAGS(name, def, choices, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_CHOICE, flags, {.c = {def, choices, NULL, NULL}}} +#define EDJE_EXTERNAL_PARAM_INFO_CHOICE_DYNAMIC_FULL_FLAGS(name, def_get, query, flags) \ + {name, EDJE_EXTERNAL_PARAM_TYPE_CHOICE, flags, {.c = {NULL, NULL, def_get, query}}} + +#define EDJE_EXTERNAL_PARAM_INFO_INT_FULL(name, def, min, max, step) \ + EDJE_EXTERNAL_PARAM_INFO_INT_FULL_FLAGS(name, def, min, max, step, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FULL(name, def, min, max, step) \ + EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FULL_FLAGS(name, def, min, max, step, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) +#define EDJE_EXTERNAL_PARAM_INFO_STRING_FULL(name, def, accept, deny) \ + EDJE_EXTERNAL_PARAM_INFO_STRING_FULL_FLAGS(name, def, accept, deny, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) +#define EDJE_EXTERNAL_PARAM_INFO_BOOL_FULL(name, def, false_str, true_str) \ + EDJE_EXTERNAL_PARAM_INFO_BOOL_FULL_FLAGS(name, def, false_str, true_str, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) +#define EDJE_EXTERNAL_PARAM_INFO_CHOICE_FULL(name, def, choices) \ + EDJE_EXTERNAL_PARAM_INFO_CHOICE_FULL_FLAGS(name, def, choices, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) +#define EDJE_EXTERNAL_PARAM_INFO_CHOICE_DYNAMIC_FULL(name, def_get, query) \ + EDJE_EXTERNAL_PARAM_INFO_CHOICE_DYNAMIC_FULL_FLAGS(name, def_get, query, EDJE_EXTERNAL_PARAM_FLAGS_REGULAR) + +#define EDJE_EXTERNAL_PARAM_INFO_INT_DEFAULT(name, def) \ + EDJE_EXTERNAL_PARAM_INFO_INT_FULL(name, def, EDJE_EXTERNAL_INT_UNSET, EDJE_EXTERNAL_INT_UNSET, EDJE_EXTERNAL_INT_UNSET) +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE_DEFAULT(name, def) \ + EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FULL(name, def, EDJE_EXTERNAL_DOUBLE_UNSET, EDJE_EXTERNAL_DOUBLE_UNSET, EDJE_EXTERNAL_DOUBLE_UNSET) +#define EDJE_EXTERNAL_PARAM_INFO_STRING_DEFAULT(name, def) \ + EDJE_EXTERNAL_PARAM_INFO_STRING_FULL(name, def, NULL, NULL) +#define EDJE_EXTERNAL_PARAM_INFO_BOOL_DEFAULT(name, def) \ + EDJE_EXTERNAL_PARAM_INFO_BOOL_FULL(name, def, "false", "true") + +#define EDJE_EXTERNAL_PARAM_INFO_INT_DEFAULT_FLAGS(name, def, flags) \ + EDJE_EXTERNAL_PARAM_INFO_INT_FULL_FLAGS(name, def, EDJE_EXTERNAL_INT_UNSET, EDJE_EXTERNAL_INT_UNSET, EDJE_EXTERNAL_INT_UNSET, flags) +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE_DEFAULT_FLAGS(name, def, flags) \ + EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FULL_FLAGS(name, def, EDJE_EXTERNAL_DOUBLE_UNSET, EDJE_EXTERNAL_DOUBLE_UNSET, EDJE_EXTERNAL_DOUBLE_UNSET, flags) +#define EDJE_EXTERNAL_PARAM_INFO_STRING_DEFAULT_FLAGS(name, def, flags) \ + EDJE_EXTERNAL_PARAM_INFO_STRING_FULL_FLAGS(name, def, NULL, NULL, flags) +#define EDJE_EXTERNAL_PARAM_INFO_BOOL_DEFAULT_FLAGS(name, def, flags) \ + EDJE_EXTERNAL_PARAM_INFO_BOOL_FULL_FLAGS(name, def, "false", "true", flags) + +#define EDJE_EXTERNAL_PARAM_INFO_INT(name) \ + EDJE_EXTERNAL_PARAM_INFO_INT_DEFAULT(name, 0) +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE(name) \ + EDJE_EXTERNAL_PARAM_INFO_DOUBLE_DEFAULT(name, 0.0) +#define EDJE_EXTERNAL_PARAM_INFO_STRING(name) \ + EDJE_EXTERNAL_PARAM_INFO_STRING_DEFAULT(name, NULL) +#define EDJE_EXTERNAL_PARAM_INFO_BOOL(name) \ + EDJE_EXTERNAL_PARAM_INFO_BOOL_DEFAULT(name, 0) + +#define EDJE_EXTERNAL_PARAM_INFO_INT_FLAGS(name, flags) \ + EDJE_EXTERNAL_PARAM_INFO_INT_DEFAULT_FLAGS(name, 0, flags) +#define EDJE_EXTERNAL_PARAM_INFO_DOUBLE_FLAGS(name, flags) \ + EDJE_EXTERNAL_PARAM_INFO_DOUBLE_DEFAULT_FLAGS(name, 0.0, flags) +#define EDJE_EXTERNAL_PARAM_INFO_STRING_FLAGS(name, flags) \ + EDJE_EXTERNAL_PARAM_INFO_STRING_DEFAULT_FLAGS(name, NULL, flags) +#define EDJE_EXTERNAL_PARAM_INFO_BOOL_FLAGS(name, flags) \ + EDJE_EXTERNAL_PARAM_INFO_BOOL_DEFAULT_FLAGS(name, 0, flags) + +/** + * @brief definition of EDJE_EXTERNAL_PARAM_INFO_SENTINEL + */ +#define EDJE_EXTERNAL_PARAM_INFO_SENTINEL {NULL, 0, 0, {.s = {NULL, NULL, NULL}}} + +/** + * @brief definition of EDJE_EXTERNAL_TYPE_ABI_VERSION + */ +#define EDJE_EXTERNAL_TYPE_ABI_VERSION (3) + +/** + * @internal + * @struct _Edje_External_Type + * + * @brief The structure type containing information about an external type to be used. + * + * @remarks This structure provides information on how to display and modify a + * third party Evas_Object in Edje. + * + * @remarks Some function pointers are not really used by Edje, but provide + * a means for edje users to interact with such objects in a better way. For + * instance, an editor may use label_get() and icon_get() to list all the + * registered external types. + * + * @remarks The function pointers provided in this structure must check + * for errors and invalid or out-of-range values. As for + * performance reasons, Edje does not enforce hints provided as + * #Edje_External_Param_Info in the member parameters_info. + */ +struct _Edje_External_Type +{ + unsigned int abi_version; /**< Always use: + * - #EDJE_EXTERNAL_TYPE_ABI_VERSION to declare. + * - edje_external_type_abi_version_get() to check. + */ + const char *module; /**< Name of the module that holds these definitions, + as used in the externals {} block of a theme + definition */ + const char *module_name; /**< Canonical name of the module, for displaying + in edition programs, for example */ + Evas_Object *(*add) (void *data, Evas *evas, Evas_Object *parent, const Eina_List *params, const char *part_name); /**< Creates the object to be used by Edje as a part. @a part_name is the name of the part that holds the object and can be used to forward callbacks from the object as signals from Edje. @a params is the list of #Edje_External_Param, not parsed, from the default state of the part. Parameters of type #EDJE_EXTERNAL_PARAM_FLAGS_CONSTRUCTOR should be set on + the object here */ + void (*state_set) (void *data, Evas_Object *obj, const void *from_params, const void *to_params, float pos); /**< Called upon state changes, including the initial "default" 0.0 state. Parameters are the value returned by params_parse(). The @a pos parameter is a value between 0.0 and 1.0 indicating the position in time within the state transition */ + void (*signal_emit) (void *data, Evas_Object *obj, const char *emission, const char *source); /**< Feeds a signal emitted with emission originally set as part_name:signal to this object (without the "part_name:" prefix) */ + Eina_Bool (*param_set) (void *data, Evas_Object *obj, const Edje_External_Param *param); /**< Dynamically changes a parameter of this external, called by scripts and user code. Returns #EINA_TRUE on success */ + Eina_Bool (*param_get) (void *data, const Evas_Object *obj, Edje_External_Param *param); /**< Dynamically fetches a parameter of this external, called by scripts and user code. Returns #EINA_TRUE on success (Must check the parameter name and type) */ + Evas_Object *(*content_get) (void *data, const Evas_Object *obj, const char *content); /**< Dynamically fetches a sub object of this external, called by scripts and user code. Returns @c Evas_Object * on success (Must check the parameter name and type) */ + void *(*params_parse) (void *data, Evas_Object *obj, const Eina_List *params); /**< Parses the list of parameters, converting them into a friendly representation. Used with state_set() */ + void (*params_free) (void *params); /**< Frees parameters parsed with params_parse() */ + + /* The following callbacks aren't used by Edje itself, but by UI design + tools instead */ + const char *(*label_get) (void *data); /**< Gets a label to use to identify this EXTERNAL (For editors) */ + const char *(*description_get) (void *data); /**< Gets a user friendly description of this EXTERNAL (For editors) */ + Evas_Object *(*icon_add) (void *data, Evas *e); /**< Gets an icon to use to identify this EXTERNAL (For editors) */ + Evas_Object *(*preview_add) (void *data, Evas *e); /**< Gets a preview of the EXTERNAL object in use (For editors) */ + const char *(*translate) (void *data, const char *orig); /**< Called to translate parameters_info name properties for use in user interfaces that support internationalization (i18n) (For editors) */ + + Edje_External_Param_Info *parameters_info; /**< An array of #Edje_External_Param_Info describing the different parameters that EXTERNAL may have. The last element in the array must be #EDJE_EXTERNAL_PARAM_INFO_SENTINEL */ + void *data; /**< Private user data that is passed to all the class functions */ +}; + +/** + * @brief typedef to struct #_Edje_External_Type + */ +typedef struct _Edje_External_Type Edje_External_Type; + +/** + * @brief The convenience structure type used to mass-register types of EXTERNAL objects. + * + * @remarks Used with edje_external_type_array_register(). + */ +struct _Edje_External_Type_Info +{ + const char *name; /**< The name of the type to register */ + const Edje_External_Type *info; /**< The type definition */ +}; + +typedef struct _Edje_External_Type_Info Edje_External_Type_Info; + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_External_Part_Group Edje Use of External Parts + * @ingroup Edje_External_Group + * + * @brief This group discusses functions to manipulate parts of type EXTERNAL. + * + * @remarks Edje supports parts of type EXTERNAL, which call plugins defined by the user + * to create and manipulate the object that's allocated in that part. + * + * Parts of type external may carry extra properties that have meanings defined + * by the external plugin. For instance, it may be a string that defines a button + * label and setting this property changes that label on the fly. + * + * @{ + */ + +/** + * @brief Gets the object created by this external part. + * + * @remarks Parts of type external create the part object using the information + * provided by external plugins. It's somehow like "swallow" + * (edje_object_part_swallow()), but it's set automatically. + * + * @remarks This function returns the part created by such external plugins and + * being currently managed by this Edje. + * + * @remarks Almost all swallow rules apply: you should not move, resize, + * hide, show, or set the color or clipper of such a part. It's a bit + * more restrictive as one must @b never delete this object. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The externally created object, otherwise @c NULL if there is no such object or + * the part is not an external + * + */ +EAPI Evas_Object *edje_object_part_external_object_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the parameter for the external part. + * + * @remarks Parts of type external may carry extra properties that have their + * meanings defined by the external plugin. For instance, it may be a + * string that defines a button label and setting this property + * changes that label on the fly. + * + * @remarks External parts have their parameters set when they change + * states. Those parameters are never changed by this + * function. The interpretation of how the state_set parameters and + * param_set interact is up to the external plugin. + * + * @remarks This function does not check if the parameter value is valid + * using #Edje_External_Param_Info minimum, maximum, valid + * choices, and others. However, these should be checked by the + * underlying implementation provided by the external + * plugin. This is done for performance reasons. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] param The parameter details, including its name, type, and + * actual value \n + * This pointer should be valid, and the + * parameter must exist in + * #Edje_External_Type::parameters_info, with the exact type, + * otherwise the operation fails and #EINA_FALSE is + * returned. + * + * @return #EINA_TRUE if everything works fine, + * otherwise #EINA_FALSE on errors + * + */ +EAPI Eina_Bool edje_object_part_external_param_set (Evas_Object *obj, const char *part, const Edje_External_Param *param); + +/** + * @brief Gets the parameter for the external part. + * + * @remarks Parts of type external may carry extra properties that have + * meanings defined by the external plugin. For instance, it may be a + * string that defines a button label. This property can be modified by + * the state parameters, by making explicit calls to + * edje_object_part_external_param_set() or by getting the actual object + * using edje_object_part_external_object_get() and calling native + * functions. + * + * @remarks This function asks the external plugin about the current value, + * independent of how it is set. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] param The parameter details \n + * It is used as both the input and output variable \n + * This pointer should be valid and the + * parameter must exist in + * #Edje_External_Type::parameters_info, with the exact type, + * otherwise the operation fails and #EINA_FALSE is + * returned. + * + * @return #EINA_TRUE if everything works fine and @a param members + * are filled with information, otherwise #EINA_FALSE on errors + * and if @a param member values are not set or valid + */ +EAPI Eina_Bool edje_object_part_external_param_get (const Evas_Object *obj, const char *part, Edje_External_Param *param); + +/** + * @brief Gets an object contained in a part of type EXTERNAL. + * + * @remarks The @a content string must not be @c NULL. Its actual value depends on the + * code providing the type EXTERNAL. + * + * @param[in] obj The edje object + * @param[in] part The name of the part holding the type EXTERNAL + * @param[out] content A string identifying the content to get from the type EXTERNAL + */ +EAPI Evas_Object *edje_object_part_external_content_get (const Evas_Object *obj, const char *part, const char *content); + +/** + * @brief Gets the type of the given parameter of the given part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] param The parameter name to use + * + * @return @c EDJE_EXTERNAL_PARAM_TYPE_MAX on errors, otherwise another value + * from #Edje_External_Param_Type on success + */ +EAPI Edje_External_Param_Type edje_object_part_external_param_type_get (const Evas_Object *obj, const char *part, const char *param); + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_External_Plugin_Development_Group Edje Development of External Plugins + * @ingroup Edje_External_Group + * + * @brief This group discusses functions to register and unregister EXTERNAL types as well as develop plugins. + * + * @remarks This group dicusses the functions that are useful for the development of new plugins. + * These functions deal with the new EXTERNAL types by registering, unregistering, and manipulating them. + * + * @{ + */ + +/** + * @brief Registers a type to be used by EXTERNAL parts. + * + * @remarks Parts of type EXTERNAL call user defined functions + * to create and manipulate the object that's allocated in that part. This is + * done by specifying the name of the external to use + * in the @c source property of that part. + * This property must be registered with this function. + * + * @param[in] type_name The name to register and be known by edje's "source:" + * parameter of "type: EXTERNAL" parts + * @param[in] type_info The meta-information describing how to interact with the @c source parameter + * + * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure (like + * type already registered) + * + * @see edje_external_type_array_register() + */ +EAPI Eina_Bool edje_external_type_register (const char *type_name, const Edje_External_Type *type_info); + +/** + * @brief Unregisters a previously registered EXTERNAL type. + * + * @param[in] type_name The name to unregister \n + * It should have been registered with + * edje_external_type_register() earlier. + * + * @return #EINA_TRUE on success, + * otherwise #EINA_FALSE on failure (like type_name did not exist) + * + * @see edje_external_type_array_unregister() + */ +EAPI Eina_Bool edje_external_type_unregister (const char *type_name); + +/** + * @brief Registers a batch of types and their information. + * + * @remarks When several types are registered, it is recommended to use this + * function instead of several calls to edje_external_type_register(), as it + * is faster. + * + * @remarks The contents of the array are referenced directly for as long as + * the type remains registered, so both the @c name and @c info in the + * @a array must be kept alive during this period (usually, the entire + * program lifetime). The most common case would be to keep the array as a + * @c static @c const type. + * + * @param[in] array The @c NULL terminated array with type name and + * information \n + * Note that type name or information is + * referenced directly, so they must be kept alive after + * this function returns. + * + * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure (like + * type already registered) + * + * @see edje_external_type_register() + */ +EAPI void edje_external_type_array_register (const Edje_External_Type_Info *array); + +/** + * @brief Unregisters a batch of given external type arrays that were previously registered. + * + * @param[in] array The @c NULL terminated array, should be same as the + * one registered with edje_external_type_array_register() + * + * @see edje_external_type_unregister() + */ +EAPI void edje_external_type_array_unregister (const Edje_External_Type_Info *array); + +/** + * @brief Gets the current ABI version for the #Edje_External_Type structure. + * + * @remarks Always check this number before accessing #Edje_External_Type in + * your own software. If the number is not the same, your software may + * access invalid memory and crash, or just get garbage values. + * + * @remarks @b NEVER, define your own #Edje_External_Type using the + * return of this function as it changes as the edje library + * (libedje.so) changes, but your type definition does + * not. Instead, use #EDJE_EXTERNAL_TYPE_ABI_VERSION. + * + * Summary: + * - Use edje_external_type_abi_version_get() to check. + * - Use #EDJE_EXTERNAL_TYPE_ABI_VERSION to define/declare. + * + * @return The external ABI version that the edje library is compiled with, + * that is, the value #EDJE_EXTERNAL_TYPE_ABI_VERSION had at that moment + * + */ +EAPI unsigned int edje_external_type_abi_version_get (void) EINA_CONST; + +/** + * @brief Gets an iterator of all the registered EXTERNAL types. + * + * @remarks Each item in the iterator is an @c Eina_Hash_Tuple which has the type + * of the external in the @c key and #Edje_External_Type as the @c data. + * + * @code + * const Eina_Hash_Tuple *tuple; + * Eina_Iterator *itr; + * const Eina_List *l, *modules; + * const char *s; + * + * modules = edje_available_modules_get(); + * EINA_LIST_FOREACH(modules, l, s) + * { + * if (!edje_module_load(s)) + * printf("Error loading edje module: %s\n", s); + * } + * + * itr = edje_external_iterator_get(); + * EINA_ITERATOR_FOREACH(itr, tuple) + * { + * const char *name = tuple->key; + * const Edje_External_Type *type = tuple->data; + * + * if ((!type) || + * (type->abi_version != edje_external_type_abi_version_get())) + * { + * printf("Error: invalid type %p (abi: %d, expected: %d)\n", + * type, type ? type->abi_version : 0, + * edje_external_type_abi_version_get()); + * continue; + * } + * + * printf("%s: %s (%s) label='%s' desc='%s'\n", + * name, type->module, type->module_name, + * type->label_get ? type->label_get(type->data) : "", + * type->description_get ? type->description_get(type->data) : ""); + * } + * + * @endcode + */ +EAPI Eina_Iterator *edje_external_iterator_get (void); + +/** + * @brief Finds a specific parameter from a list of external parameters. + * + * @param[in] params The list of parameters + * @param[in] key The parameter to look for + * + * @return The matching #Edje_External_Param, + * otherwise @c NULL if it's not found + */ +EAPI Edje_External_Param *edje_external_param_find (const Eina_List *params, const char *key); + +/** + * @brief Gets the value of the given parameter of integer type. + * + * @remarks Look for the @a key parameter in the @a params list and return its value in + * @a ret. If the parameter is found and is of type + * #EDJE_EXTERNAL_PARAM_TYPE_INT, its value is stored in the int pointed + * by @a ret, returning #EINA_TRUE. In any other case, the function returns + * #EINA_FALSE. + * + * @param[in] params The list of parameters to look at + * @param[in] key The name of the parameter to fetch + * @param[out] ret An Int pointer to store the value, must not be NULL + * + * @return #EINA_TRUE if the parameter is found and is of integer type, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_external_param_int_get (const Eina_List *params, const char *key, int *ret); + +/** + * @brief Gets the value of the given parameter of double type. + * + * @remarks Look for the @a key parameter in the @a params list and return its value in + * @a ret. If the parameter is found and is of type + * #EDJE_EXTERNAL_PARAM_TYPE_DOUBLE, its value is stored in the double + * pointed by @a ret, returning #EINA_TRUE. In any other case, the function + * returns #EINA_FALSE. + * + * @param[in] params The list of parameters to look at + * @param[in] key The name of the parameter to fetch + * @param[out] ret A double pointer to store the value, must not be NULL + * + * @return #EINA_TRUE if the parameter is found and is of double type, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_external_param_double_get (const Eina_List *params, const char *key, double *ret); + +/** + * @brief Gets the value of the given parameter of string type. + * + * @remarks Look for the @a key parameter in the @a params list and return its value in + * @a ret. If the parameter is found and is of type + * #EDJE_EXTERNAL_PARAM_TYPE_STRING, its value is stored in the pointer + * pointed by @a ret, returning #EINA_TRUE. In any other case, the function + * returns #EINA_FALSE. + * + * @remarks The string stored in @a ret must not be freed or modified. + * + * @param[in] params The list of parameters to look at + * @param[in] key The name of the parameter to fetch + * @param[out] ret A string pointer to store the value, must not be NULL + * + * @return #EINA_TRUE if the parameter is found and is of string type, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_external_param_string_get (const Eina_List *params, const char *key, const char **ret); + +/** + * @brief Gets the value of the given parameter of boolean type. + * + * @remarks Look for the @a key parameter in the @a params list and return its value in + * @a ret. If the parameter is found and is of type + * #EDJE_EXTERNAL_PARAM_TYPE_BOOL, its value is stored in the Eina_Bool + * pointed by @a ret, returning #EINA_TRUE. In any other case, the function + * returns #EINA_FALSE. + * + * @param[in] params The list of parameters to look at + * @param[in] key The name of the parameter to fetch + * @param[out] ret An Eina_Bool pointer to store the value, must not be NULL + * + * @return #EINA_TRUE if the parameter is found and is of boolean type, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_external_param_bool_get (const Eina_List *params, const char *key, Eina_Bool *ret); + +/** + * @brief Gets the value of the given parameter of choice type. + * + * @remarks Look for the @a key parameter in the @a params list and return its value in + * @a ret. If the parameter is found and is of type + * #EDJE_EXTERNAL_PARAM_TYPE_CHOICE, its value is stored in the string + * pointed by @a ret, returning #EINA_TRUE. In any other case, the function + * returns #EINA_FALSE. + * + * @remarks The string stored in @a ret must not be freed or modified. + * + * @param[in] params The list of parameters to look at + * @param[in] key The name of the parameter to fetch + * @param[out] ret A string pointer to store the value, must not be NULL + * + * @return #EINA_TRUE if the parameter is found and is of integer type, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_external_param_choice_get (const Eina_List *params, const char *key, const char **ret); + +/** + * @brief Gets the array of parameter information about a type, given that its name is provided. + * + * @remarks The type names and other strings are static, that means they are + * @b NOT translated. One must use + * Edje_External_Type::translate() to translate them. + * + * @return The NULL terminated array, otherwise @c NULL if the type is unknown or + * it does not have any parameter information + * + * @see edje_external_type_get() + */ +EAPI const Edje_External_Param_Info *edje_external_param_info_get (const char *type_name); + +/** + * @brief Gets #Edje_External_Type that defines an EXTERNAL type registered with + * the name @a type_name. + */ +EAPI const Edje_External_Type *edje_external_type_get (const char *type_name); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Group Edje Object + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with edje layouts and its components. + * + * @remarks An important thing to know about this group is that there is no + * Edje_Object in the @b code. What we refer to as an object are actually layouts (or themes) + * defined by groups, and parts, both declared in EDC files. They are of + * type Evas_Object as the other native objects of Evas, but they only exist + * in Edje, so that is why we are calling them "edje objects". + * + * @remarks With the Edje Object Group functions we can deal with layouts by managing + * its aspect, content, message, and signal exchange and animation, among others. + * + * @{ + */ + +/** + * @brief Instantiates a new edje object. + * + * @details This function creates a new edje smart object, returning its @c + * Evas_Object handle. An edje object is useless without a (source) + * file set to it, so you would most probably call edje_object_file_set() + * afterwards, like in: + * + * @since_tizen 2.3 + * + * @code + * Evas_Object *edje; + * + * edje = edje_object_add(canvas); + * if (!edje) + * { + * fprintf(stderr, "could not create edje object!\n"); + * return NULL; + * } + * + * if (!edje_object_file_set(edje, "theme.edj", "group_name")) + * { + * int err = edje_object_load_error_get(edje); + * const char *errmsg = edje_load_error_str(err); + * fprintf(stderr, "could not load 'group_name' from theme.edj: %s", + * errmsg); + * + * evas_object_del(edje); + * return NULL; + * } + * + * @endcode + * + * @remarks You can get a callback every time edje re-calculates the object + * (either due to animation or some kind of signal or input). This is called + * in-line just after the recalculation has occurred. It is a good idea to not + * go and delete or alter the object inside this callback, simply make + * a note that the recalculation has taken place and then do something about + * it outside the callback. To register a callback use a code like: + * + * @code + * evas_object_smart_callback_add(edje_obj, "recalc", my_cb, my_cb_data); + * @endcode + * + * @remarks Before creating the first edje object in your code, remember + * to initialize the library, with edje_init(), or unexpected behavior + * might occur. + * + * @param[in] evas A valid Evas handle, the canvas to place the new object in + * @return A handle to the new object created, otherwise @c NULL on errors + * + * @see evas_object_smart_callback_add() + */ +EAPI Evas_Object *edje_object_add (Evas *evas); + +/** + * @brief Preloads the images on the edje Object in the background. + * + * @details This function requests the preload of data images (on the given + * object) in the background. The work is queued before being processed + * (because there might be other pending requests of this type). + * It emits a signal "preload,done" when finished. + * + * @since_tizen 2.3 + * + * @remarks Use #EINA_TRUE in scenarios where you don't need + * the image data to be preloaded anymore. + * + * @param[in] obj A handle to an edje object + * @param[in] cancel If #EINA_FALSE it is added to the preloading work queue, + * otherwise #EINA_TRUE to remove it (if it is issued before) + * @return @c EINA_FASLE if @a obj is not a valid edje object, + * otherwise #EINA_TRUE + */ +EAPI Eina_Bool edje_object_preload (Evas_Object *obj, Eina_Bool cancel); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Scale Edje Scale + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with scaling objects. + * + * @remarks Edje allows one to build scalable interfaces. Scaling factors, + * which are set to neutral (@c 1.0) values by default (no scaling, + * actual sizes), are of two types: @b global and @b individual. + * + * @remarks Scaling affects the values of minimum/maximum @b part sizes, which + * are @b multiplied by it. Font sizes are scaled, too. + * + * @{ + */ + +/** + * @brief Sets Edje's global scaling factor. + * + * @since_tizen 2.3 + * + * @remarks Edje's global scaling factor affects all its objects whose + * individual scaling factors are not altered from the default + * value (which is zero). If they had it set differently, by + * edje_object_scale_set(), that factor @b overrides the global + * one. + * + * @remarks Only parts which, at EDC level, have their @c "scale" + * property set to @c 1, are affected by this function. Check the + * complete @ref edcref "syntax reference" for EDC files. + * + * @param[in] scale The global scaling factor (the default value is @c 1.0) + * + * @see edje_scale_get() + */ +EAPI void edje_scale_set (double scale); + +/** + * @brief Gets Edje's global scaling factor. + * + * @details This function returns Edje's global scaling factor. + * + * @since_tizen 2.3 + * + * @return The global scaling factor + * + * @see edje_scale_set() + * + */ +EAPI double edje_scale_get (void); + +/** + * @brief Sets the scaling factor for a given edje object. + * + * @details This function sets an @b individual scaling factor on the @a obj + * edje object. This property (or Edje's global scaling factor, when + * applicable), affects this object's part sizes. If @a scale is + * not zero, then the individual scaling @b overrides any global + * scaling set, for the object @a obj's parts. Put it back to zero to + * get the effects of global scaling again. + * + * @since_tizen 2.3 + * + * @remarks Only parts which, at EDC level, have their @c "scale" + * property set to @c 1, are affected by this function. Check the + * complete @ref edcref "syntax reference" for EDC files. + * + * @param[in] obj A handle to an edje object + * @param[in] scale The scaling factor (the default value is @c 0.0, + * meaning individual scaling is @b not set) + * @return #EINA_TRUE if success, otherwise #EINA_FALSE + + * @see edje_object_scale_get() + * @see edje_scale_get() + */ +EAPI Eina_Bool edje_object_scale_set (Evas_Object *obj, double scale); + +/** + * @brief Gets a given Edje object's scaling factor. + * + * @details This function returns the @c individual scaling factor set on the + * @a obj edje object. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return A scale factor + * + * @see edje_object_scale_set() + * + */ +EAPI double edje_object_scale_get (const Evas_Object *obj); + +/** + * @brief Gets a given Edje object's base_scale factor. + * + * @details This function returns the base_scale factor set on the + * Edje object. + * The base_scale can be set in the collection of edc. + * If it isn't set, the default value is 1.0. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return A base scale factor + */ +EAPI double edje_object_base_scale_get(const Evas_Object *obj); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Color_Class Edje Class: Color + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with Color Classes. + * + * @remarks Sometimes we want to change the color of two or more parts equally and + * that's when we use color classes. + * + * @remarks If one or more parts are assigned with a color class, when we set color + * values to this class it causes all these parts to have their colors + * multiplied by the values. Setting values to a color class at a process level + * affects all parts within that color class, while at an object level it + * only affects the parts inside a specified object. + * + * @{ + */ + +/** + * @brief Sets the Edje color class. + * + * @details This function sets the color values for a process level color + * class. This causes all the edje parts in the current process that + * have the specified color class to have their colors multiplied by + * these values. (Object level color classes set by + * edje_object_color_class_set() override the values set by this + * function). + * + * @since_tizen 2.3 + * + * @remarks The first color is the object, the second is the text outline, and + * the third is the text shadow. (Note that the second and third only apply + * to text parts). + * + * @remarks Setting color emits a signal "color_class,set" with source being + * the given color class in all objects. + * + * @remarks Unlike Evas, Edje colors are @b not pre-multiplied. That is, + * half-transparent white is 255 255 255 128. + * + * @param[in] color_class The color class name + * @param[in] r The object Red value + * @param[in] g The object Green value + * @param[in] b The object Blue value + * @param[in] a The object Alpha value + * @param[in] r2 The outline Red value + * @param[in] g2 The outline Green value + * @param[in] b2 The outline Blue value + * @param[in] a2 The outline Alpha value + * @param[in] r3 The shadow Red value + * @param[in] g3 The shadow Green value + * @param[in] b3 The shadow Blue value + * @param[in] a3 The shadow Alpha value + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_color_class_set() + */ +EAPI Eina_Bool edje_color_class_set (const char *color_class, int r, int g, int b, int a, int r2, int g2, int b2, int a2, int r3, int g3, int b3, int a3); + +/** + * @brief Gets the Edje color class. + * + * @details This function gets the color values for a process level color + * class. This value is globally set and not per-object, that is, + * the value that would be used by objects if they do not override using + * edje_object_color_class_set(). + * + * @since_tizen 2.3 + * + * @remarks The first color is the object, the second is the text outline, and + * the third is the text shadow. (Note that the second and third only apply + * to text parts). + * + * @remarks Unlike Evas, edje colors are @b not pre-multiplied. That is, + * half-transparent white is 255 255 255 128. + * + * @param[in] color_class The color class name + * @param[out] r The object Red value + * @param[out] g The object Green value + * @param[out] b The object Blue value + * @param[out] a The object Alpha value + * @param[out] r2 The outline Red value + * @param[out] g2 The outline Green value + * @param[out] b2 The outline Blue value + * @param[out] a2 The outline Alpha value + * @param[out] r3 The shadow Red value + * @param[out] g3 The shadow Green value + * @param[out] b3 The shadow Blue value + * @param[out] a3 The shadow Alpha value + * + * @return #EINA_TRUE if found, + * otherwise #EINA_FALSE if not found and all values are zeroed + * + * @see edje_color_class_set() + */ +EAPI Eina_Bool edje_color_class_get (const char *color_class, int *r, int *g, int *b, int *a, int *r2, int *g2, int *b2, int *a2, int *r3, int *g3, int *b3, int *a3); + +/** + * @brief Deletes the Edje color class. + * + * @details This function deletes any values at the process level for the + * specified color class. + * + * @since_tizen 2.3 + * + * @remarks Deleting the color class reverts it to the + * values defined in the theme file. + * Deleting the color class emits the signal "color_class,del" + * to all the edje objects in the running program. + * + * @param[in] color_class The color class name + * + */ +EAPI void edje_color_class_del (const char *color_class); + +/** + * @brief Lists the color classes. + * + * @details This function lists all the color classes known by the current + * process. + * + * @since_tizen 2.3 + * + * @return A list of color class names (strings) \n + * These strings and + * the list must be freed by the caller using free(). + * + */ +EAPI Eina_List *edje_color_class_list (void); + +/** + * @brief Sets the object color class. + * + * @details This function sets the color values for an object level color + * class. This causes all edje parts in the specified object that + * have the specified color class to have their colors multiplied by + * these values. + * + * @since_tizen 2.3 + * + * @remarks The first color is the object, the second is the text outline, and + * the third is the text shadow. (Note that the second and third only apply + * to text parts). + * + * @remarks Setting color emits a signal "color_class,set" with source being + * the given color. + * + * @remarks Unlike Evas, edje colors are @b not pre-multiplied. That is, + * half-transparent white is 255 255 255 128. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] color_class The color class name + * @param[in] r The object Red value + * @param[in] g The object Green value + * @param[in] b The object Blue value + * @param[in] a The object Alpha value + * @param[in] r2 The outline Red value + * @param[in] g2 The outline Green value + * @param[in] b2 The outline Blue value + * @param[in] a2 The outline Alpha value + * @param[in] r3 The shadow Red value + * @param[in] g3 The shadow Green value + * @param[in] b3 The shadow Blue value + * @param[in] a3 The shadow Alpha value + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + */ +EAPI Eina_Bool edje_object_color_class_set (Evas_Object *obj, const char *color_class, int r, int g, int b, int a, int r2, int g2, int b2, int a2, int r3, int g3, int b3, int a3); + +/** + * @brief Gets the object color class. + * + * @details This function gets the color values for an object level color + * class. If no explicit object color is set, then global values are + * used. + * + * @since_tizen 2.3 + * + * @remarks The first color is the object, the second is the text outline, and + * the third is the text shadow. (Note that the second and third only apply + * to text parts). + * + * @remarks Unlike Evas, edje colors are @b not pre-multiplied. That is, + * half-transparent white is 255 255 255 128. + * + * @param[in] o A valid Evas_Object handle + * @param[in] color_class The color class name + * @param[out] r The object Red value + * @param[out] g The object Green value + * @param[out] b The object Blue value + * @param[out] a The object Alpha value + * @param[out] r2 The outline Red value + * @param[out] g2 The outline Green value + * @param[out] b2 The outline Blue value + * @param[out] a2 The outline Alpha value + * @param[out] r3 The shadow Red value + * @param[out] g3 The shadow Green value + * @param[out] b3 The shadow Blue value + * @param[out] a3 The shadow Alpha value + * + * @return #EINA_TRUE if found, otherwise #EINA_FALSE if not found and all + * values are zeroed + * + */ +EAPI Eina_Bool edje_object_color_class_get (const Evas_Object *o, const char *color_class, int *r, int *g, int *b, int *a, int *r2, int *g2, int *b2, int *a2, int *r3, int *g3, int *b3, int *a3); + +/** + * @brief Deletes the object color class. + * + * @details This function deletes any values at the object level for the + * specified object and color class. + * + * @since_tizen 2.3 + * + * @remarks Deleting the color class reverts it to the values + * defined by edje_color_class_set() or the color class + * defined in the theme file. + * Deleting the color class emits the signal "color_class,del" + * for the given edje object. + * + * @param[in] obj The edje object reference + * @param[in] color_class The color class to be deleted + * + */ + EAPI void edje_object_color_class_del (Evas_Object *obj, const char *color_class); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Text_Class Edje Class: Text + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with Text Classes. + * + * @remarks Sometimes we want to change the text of two or more parts equally and + * that's when we use text classes. + * + * @remarks If one or more parts are assigned with a text class, when we set font + * attributes to this class it updates all these parts with the new font + * attributes. Setting values to a text class at a process level affects + * all parts within that text class, while at the object level it only affects + * the parts inside a specified object. + * + * @{ + */ + +/** + * @brief Sets the Edje text class. + * + * @details This function updates all edje members at the process level which + * belong to this text class with the new font attributes. + * If the @a size is 0 then the font size is kept as the previous size. + * If the @a size is less then 0 then the font size is calculated as a + * percentage. For example, if the @a size is -50, then the font size is + * scaled to half of the original size and if the @a size is -10 then the font + * size is scaled by 0.1x. + * + * @since_tizen 2.3 + * + * @param[in] text_class The text class name + * @param[in] font The font name + * @param[in] size The font size + * + * @return #EINA_TRUE on success, otherwise #EINA_FALSE on error + * + * @see edje_text_class_get() + * + */ +EAPI Eina_Bool edje_text_class_set (const char *text_class, const char *font, Evas_Font_Size size); + +/** + * @brief Gets the Edje text class. + * + * @details This function gets the text values for a process level text class. + * + * @since_tizen 2.3 + * + * @param[in] text_class The text class name + * @param[out] font The font name \n + * This string is a stringshare and must be freed by the caller using free(). + * @param[out] size The font size + * + * @return #EINA_TRUE if found, otherwise #EINA_FALSE if not found + * + * @see edje_text_class_set() + * + */ +EAPI Eina_Bool edje_text_class_get (const char *text_class, char **font, Evas_Font_Size *size); + +/** + * @brief Deletes the text class. + * + * @details This function deletes any values at the process level for the + * specified text class. + * + * @since_tizen 2.3 + * + * @param[in] text_class The text class name string + */ +EAPI void edje_text_class_del (const char *text_class); + +/** + * @brief Lists the text classes. + * + * @details This function lists all the text classes known by the current + * process. + * + * @since_tizen 2.3 + * + * @return A list of text class names (strings) \n + * These strings are + * stringshares and the list must be freed by the caller using free(). + * + */ +EAPI Eina_List *edje_text_class_list (void); + +/** + * @brief Sets the Edje text class. + * + * @details This function sets the text class for Edje. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] text_class The text class name + * @param[in] font The font name + * @param[in] size The font Size + * + * @return #EINA_TRUE on success, + * otherwise #EINA_FALSE on error + * + */ +EAPI Eina_Bool edje_object_text_class_set (Evas_Object *obj, const char *text_class, const char *font, Evas_Font_Size size); + +/** + * @brief Gets the Edje text class. + * + * @details This function gets the text values for a process level text class. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] text_class The text class name + * @param[out] font The font name \n + * This string is a stringshare and must be freed by the caller using free(). + * @param[out] size The font size + * + * @return #EINA_TRUE if found, + * otherwise #EINA_FALSE if not found + * + * @see edje_text_class_set() + * + */ +EAPI Eina_Bool edje_object_text_class_get(const Evas_Object *obj, const char *text_class, char **font, Evas_Font_Size *size); + +/** + * @} + */ + +/** + * @defgroup Edje_File Edje File + * @ingroup Edje_Group + * + * @brief This group discusses functions to deal with EDJ files. + * + * @remarks Layouts in Edje are usually called themes and they are + * created using the EDC language. The EDC language is declarative + * and must be compiled before being used. The output of this + * compilation is an EDJ file, this file can be loaded by Edje, + * and the result is an edje object. + * + * @remarks This group of functions interacts with these EDJ files, + * either by loading them or retrieving information from the EDC + * file about objects. + * + * @{ + */ + +/** + * @brief Edje Load Error Type + */ +typedef enum _Edje_Load_Error +{ + EDJE_LOAD_ERROR_NONE = 0, /**< No error occurred, the loading is successful */ + EDJE_LOAD_ERROR_GENERIC = 1, /**< A generic error occurred during loading */ + EDJE_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< The file being pointed to does not exist */ + EDJE_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission to read the given file has been denied */ + EDJE_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Resource allocation failed during loading */ + EDJE_LOAD_ERROR_CORRUPT_FILE = 5, /**< The file being pointed to is corrupt */ + EDJE_LOAD_ERROR_UNKNOWN_FORMAT = 6, /**< The file being pointed to has an unknown format */ + EDJE_LOAD_ERROR_INCOMPATIBLE_FILE = 7, /**< The file being pointed to is incompatible, i.e., it doesn't match the library's current version format */ + EDJE_LOAD_ERROR_UNKNOWN_COLLECTION = 8, /**< The group/collection set to load from is @b not found in the file */ + EDJE_LOAD_ERROR_RECURSIVE_REFERENCE = 9 /**< The group/collection set to load from had <b>recursive references</b> on its components */ +} Edje_Load_Error; /**< Edje file is loading error codes that one can get - see edje_load_error_str() too */ + +/** + * @brief Gets data from the file level data block of an edje file. + * + * @since_tizen 2.3 + * + * @remarks If an edje file is built from the following edc: + * + * data { + * item: "key1" "value1"; + * item: "key2" "value2"; + * } + * collections { ... } + * + * Then, edje_file_data_get("key1") returns "value1". + * + * @param[in] file The path to the .edj file + * @param[in] key The data key + * @return The string value of the data, must be freed by the user when no + * longer needed + * + */ +EAPI char *edje_file_data_get (const char *file, const char *key); + +/** + * @brief Gets the list of groups in an edje file. + * + * @since_tizen 2.3 + * + * @remarks The list must be freed using edje_file_collection_list_free() + * when you are done with it. + * + * @param[in] file The path to the edje file + * + * @return An Eina_List of group names (char *) + */ +EAPI Eina_List *edje_file_collection_list (const char *file); + +/** + * @brief Frees the file collection list. + * + * @details This frees the list returned by edje_file_collection_list(). + * + * @param[in] lst An Eina_List of groups + */ +EAPI void edje_file_collection_list_free (Eina_List *lst); + +/** + * @brief Checks whether a group matching glob exists in an edje file. + * + * @since_tizen 2.3 + * + * @param[in] file The file path + * @param[in] glob The glob to match with + * + * @return @c 1 if a match is found, otherwise @c 0 + */ +EAPI Eina_Bool edje_file_group_exists (const char *file, const char *glob); + +/** + * @brief Sets the @b EDJ file (and group within it) from which to load an edje + * object's contents. + * + * @since_tizen 2.3 + * + * @remarks Edje expects EDJ files, which are theming objects' descriptions and + * resources packed together in an EET file, to read edje object + * definitions from. They are usually created with the @c .edj + * extension. EDJ files, in turn, are assembled from @b textual object + * description files, where one describes edje objects declaratively, + * the EDC files (see @ref edcref "the syntax" for those files). + * + * @remarks Those description files were designed so that many edje object + * definitions, also called @b groups (or collections), could be + * packed together <b>in the same EDJ file</b>, so that a whole + * application's theme could be packed into a single file only. This is the + * reason for the @a group argument. + * + * @remarks Use this function after you instantiate a new edje object, so that + * you can "give it life", by telling it from where it can get its contents. + * + * @param[in] obj A handle to an edje object + * @param[in] file The path to the EDJ file to load @a from + * @param[in] group The name of the group, in @a file, which implements an + * edje object + * @return #EINA_TRUE on success otherwise #EINA_FALSE on errors (check + * edje_object_load_error_get() after this call to get errors causes) + * + * @see edje_object_add() + * @see edje_object_file_get() + */ +EAPI Eina_Bool edje_object_file_set (Evas_Object *obj, const char *file, const char *group); + +/** + * @brief Gets the file and group name that a given edje object is bound to. + * + * @since_tizen 2.3 + * + * @remarks This gets the EDJ file's path, with the respective group set for + * the given edje object. If @a obj is either not an edje file, or has + * not had its file/group set previously, by edje_object_file_set(), + * then both @a file and @a group are set to @c NULL, indicating + * an error. + * + * @remarks Use @c NULL pointers on the file/group components you're not + * interested in, they are ignored by the function. + * + * @param[in] obj A handle to an edje object + * @param[out] file A pointer to a variable to store the <b>file path</b> + * + * @param[out] group A pointer to a variable to store the <b>group name</b> + * + * @see edje_object_file_set() + */ +EAPI void edje_object_file_get (const Evas_Object *obj, const char **file, const char **group); + +/** + * @brief Gets an <b>EDC data field value</b> from a given Edje + * object group. + * + * @details This function fetches an EDC data field value, which is declared + * on the object's building EDC file, <b>under its group</b>. EDC data + * blocks are most commonly used to pass arbitrary parameters from an + * application's theme to its code. + * + * @since_tizen 2.3 + * + * They look like the following: + * + * @code + * collections { + * group { + * name: "a_group"; + * data { + * item: "key1" "value1"; + * item: "key2" "value2"; + * } + * } + * } + * @endcode + * + * @remarks EDC data fields always hold @b strings as values, hence the return + * type of this function. Check the complete @ref edcref "syntax reference" + * for EDC files. + * + * @remarks Do not confuse this call with edje_file_data_get(), which + * queries for a @b global EDC data field on an EDC declaration file. + * + * @param[in] obj A handle to an edje object + * @param[in] key The data field key string + * @return The data value string, must not be freed + * + * @see edje_object_file_set() + */ +EAPI const char *edje_object_data_get (const Evas_Object *obj, const char *key); + +/** + * @brief Gets the (last) file loading error for a given edje object. + * + * @details This function is meant to be used after an edje EDJ <b>file + * load</b> that takes place with the edje_object_file_set() + * function. If that function does not return #EINA_TRUE, one should + * check for the reason of failure. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * + * @return The Edje loading error, one from: + * - #EDJE_LOAD_ERROR_NONE + * - #EDJE_LOAD_ERROR_GENERIC + * - #EDJE_LOAD_ERROR_DOES_NOT_EXIST + * - #EDJE_LOAD_ERROR_PERMISSION_DENIED + * - #EDJE_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED + * - #EDJE_LOAD_ERROR_CORRUPT_FILE + * - #EDJE_LOAD_ERROR_UNKNOWN_FORMAT + * - #EDJE_LOAD_ERROR_INCOMPATIBLE_FILE + * - #EDJE_LOAD_ERROR_UNKNOWN_COLLECTION + * - #EDJE_LOAD_ERROR_RECURSIVE_REFERENCE + * + * @see edje_load_error_str() + */ +EAPI Edje_Load_Error edje_object_load_error_get (const Evas_Object *obj); + +/** + * @brief Converts the given edje file load error code into a string + * describing it in English. + * + * @since_tizen 2.3 + * + * @remarks edje_object_file_set() is a function that sets an error value later, + * which can be fetched with edje_object_load_error_get(). + * The function in question is meant + * to be used in conjunction with the latter, for pretty-printing any + * possible error cause. + * + * @param[in] error The error code, a value in ::Edje_Load_Error + * @return A valid string \n + * If the given @a error is not + * supported, <code>"Unknown error"</code> is returned. + */ +EAPI const char *edje_load_error_str (Edje_Load_Error error); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Communication_Interface_Signal Edje Communication Interface: Signal + * @ingroup Edje_Object_Group + + * + * @brief This group discusses functions that deal with signals. + * + * @remarks Edje has two communication interfaces between @b code and @b theme, + * signals and messages. + * + * @remarks This group has functions that deal with signals. One can either + * emit a signal from @b code to @b theme or create handles for + * the ones emitted from @b theme. Signals are identified by strings. + * + * @{ + */ + +/** + * @brief Edje signal callback functions's prototype definition. + * + * @c data will have the auxiliary data pointer set at the time the callback + * registration. @c obj will be a pointer the Edje object where the signal + * comes from. @c emission will identify the exact signal's emission string and + * @c source the exact signal's source one. + */ +typedef void (*Edje_Signal_Cb) (void *data, Evas_Object *obj, const char *emission, const char *source); + +/** + * @brief Adds a callback for an arriving edje signal, emitted by + * a given Ejde object. + * + * @since_tizen 2.3 + * + * @remarks Edje signals are one of the communication interfaces between + * @b code and a given edje object's @b theme. With signals, one can + * communicate two string values at a time, which are: + * - "emission" value: The name of the signal, in general. + * - "source" value: A name for the signal's context, in general. + * + * Though there are common uses for the two strings, one is free + * to use them however they like. + * + * @remarks This function adds a callback function to a signal emitted by @a obj, to + * be issued every time an EDC program like the following: + * @code + * program { + * name: "emit_example"; + * action: SIGNAL_EMIT "a_signal" "a_source"; + * } + * @endcode + * is run, if @a emission and @a source are given those same values, + * here. + * + * @remarks Signal callback registration is powerful because @b blobs + * may be used to match <b>multiple signals at once</b>. All the @c + * *?[\ set of @c fnmatch() operators can be used, both for @a + * emission and @a source. + * + * @remarks Edje has @b internal signals that it emits, automatically, on + * various actions taking place on group parts. For example, the mouse + * cursor being moved, pressed, released, etc., over a given part's + * area, all generate individual signals. + * + * By using something like + * @code + * edje_object_signal_callback_add(obj, "mouse,down,*", "button.*", + * signal_cb, NULL); + * @endcode + * @c "button.*" being the pattern for the names of parts implementing + * buttons on an interface that you would be registering for notifications on + * events of mouse buttons being pressed down on either of those parts + * (all those events have the @c "mouse,down," common prefix on their + * names, with a suffix giving the button number). The actual emission + * and source strings of an event are passed as the @a emission + * and @a source parameters of the callback function (e.g. @c + * "mouse,down,2" and @c "button.close"), for each of those events. + * + * @remarks See @ref edcref "the syntax" for EDC files. + * + * @param[in] obj A handle to an edje object + * @param[in] emission The signal's "emission" string + * @param[in] source The signal's "source" string + * @param[in] func The callback function to be executed when the signal is + * emitted + * @param[in] data A pointer to the data to pass to @a func + * + * @see edje_object_signal_emit() on how to emit edje signals from + * the code to an object + * @see edje_object_signal_callback_del_full() + */ +EAPI void edje_object_signal_callback_add (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data); + +/** + * @brief Deletes a signal-triggered callback from an object. + * + * @details This function removes a callback that had been previously attached to the + * emission of a signal, from the object @a obj. The parameters @a + * emission, @a source, and @a func must exactly match those that are passed to + * a previous call to edje_object_signal_callback_add(). The data + * pointer that is passed to this call is returned. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] emission The emission string + * @param[in] source The source string + * @param[in] func The callback function + * @return The data pointer + * + * @see edje_object_signal_callback_add() + * @see edje_object_signal_callback_del_full() + * + */ +EAPI void *edje_object_signal_callback_del (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func); + +/** + * @brief Unregisters/deletes a callback set for an arriving edje + * signal, emitted by a given Ejde object. + * + * @details This function removes a callback that had been previously attached to the + * emission of a signal, from the object @a obj. The parameters + * @a emission, @a source, @a func, and @a data must exactly match those + * that are passed to a previous call to edje_object_signal_callback_add(). The + * data pointer that is passed to this call is returned. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @param[in] emission The signal's "emission" string + * @param[in] source The signal's "source" string + * @param[in] func The callback function passed on the callback + * registration + * @param[in] data A pointer to be passed as data to @a func + * @return @a data on success, otherwise @c NULL on errors (or if @a data + * has this value) + * + * @see edje_object_signal_callback_add(). + * @see edje_object_signal_callback_del(). + * + */ +EAPI void *edje_object_signal_callback_del_full(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data); + +/** + * @brief Sends/emits an edje signal to a given edje object. + * + * @details This function sends a signal to the object @a obj. An edje program, + * at @a obj's EDC specification level, can respond to a signal by + * declaring matching @c 'signal' and @c 'source' fields on its + * block (see @ref edcref "the syntax" for EDC files). + * + * @since_tizen 2.3 + * + * As an example, + * @code + * edje_object_signal_emit(obj, "a_signal", ""); + * @endcode + * would trigger a program which has an EDC declaration block like + * @code + * program { + * name: "a_program"; + * signal: "a_signal"; + * source: ""; + * action: ... + * } + * @endcode + * + * @param[in] obj A handle to an edje object + * @param[in] emission The signal's "emission" string + * @param[in] source The signal's "source" string + * + * @see edje_object_signal_callback_add() for more on edje signals. + */ +EAPI void edje_object_signal_emit (Evas_Object *obj, const char *emission, const char *source); + +/** + * @brief Gets the extra data passed to callbacks. + * + * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @remarks Some callbacks pass extra information. This function gives access to that + * extra information. It's somehow like event_info when it comes to smart callbacks. + * + * @return The extra data for that callback. + * + * @see edje_object_signal_callback_add() for more on edje signals. + * + */ +EAPI void * edje_object_signal_callback_extra_data_get(void); + +/** + * @} + */ + +/** + * @defgroup Edje_Animation Edje Animation + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with animations. + * + * @remarks Edje has the ability to animate objects. One can start, stop, play, + * pause, freeze, and thaw edje animations using the functions of this section. + * + * @{ + */ + +typedef enum _Edje_Tween_Mode +{ + EDJE_TWEEN_MODE_NONE = 0, + EDJE_TWEEN_MODE_LINEAR = 1, + EDJE_TWEEN_MODE_SINUSOIDAL = 2, + EDJE_TWEEN_MODE_ACCELERATE = 3, + EDJE_TWEEN_MODE_DECELERATE = 4, + EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, + EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, + EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, + EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, + EDJE_TWEEN_MODE_BOUNCE = 9, + EDJE_TWEEN_MODE_SPRING = 10, + EDJE_TWEEN_MODE_LAST = 11, + EDJE_TWEEN_MODE_MASK = 0xff, + EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) +} Edje_Tween_Mode; + +#define PLUGIN + +/** + * @brief Edje Action Type + */ +typedef enum _Edje_Action_Type +{ + EDJE_ACTION_TYPE_NONE = 0, + EDJE_ACTION_TYPE_STATE_SET = 1, + EDJE_ACTION_TYPE_ACTION_STOP = 2, + EDJE_ACTION_TYPE_SIGNAL_EMIT = 3, + EDJE_ACTION_TYPE_DRAG_VAL_SET = 4, + EDJE_ACTION_TYPE_DRAG_VAL_STEP = 5, + EDJE_ACTION_TYPE_DRAG_VAL_PAGE = 6, + EDJE_ACTION_TYPE_SCRIPT = 7, + EDJE_ACTION_TYPE_FOCUS_SET = 8, + EDJE_ACTION_TYPE_RESERVED00 = 9, + EDJE_ACTION_TYPE_FOCUS_OBJECT = 10, + EDJE_ACTION_TYPE_PARAM_COPY = 11, + EDJE_ACTION_TYPE_PARAM_SET = 12, + EDJE_ACTION_TYPE_SOUND_SAMPLE = 13, /**< @since 1.1 */ + EDJE_ACTION_TYPE_SOUND_TONE = 14, /**< @since 1.1 */ +#ifdef PLUGIN + EDJE_ACTION_TYPE_RUN_PLUGIN = 15, + EDJE_ACTION_TYPE_LAST = 16 +#else + EDJE_ACTION_TYPE_LAST = 15 #endif +} Edje_Action_Type; + +/** + * @brief Sets the edje trasitions' frame time. + * + * @details This function sets the edje built-in animations' frame time (thus, + * affecting their resolution) by calling + * ecore_animator_frametime_set(). This frame time can be retrieved + * with edje_frametime_get(). + * + * @since_tizen 2.3 + * + * @param[in] t The frame time, in seconds \n + * Default value is 1/30. + * + * @see edje_frametime_get() + */ +EAPI void edje_frametime_set (double t); + +/** + * @brief Gets the edje trasitions' frame time. + * + * @details This function returns the edje frame time set by + * edje_frametime_set() or the default value of 1/30. + * + * @since_tizen 2.3 + * + * @return The frame time, in seconds + * + * @see edje_frametime_set() + */ +EAPI double edje_frametime_get (void); + +/** + * @brief Freezes the edje objects. + * + * @details This function freezes all edje animations in the current process. + * + * @since_tizen 2.3 + * + * @see edje_object_freeze() to freeze a specific object + * + * @see edje_thaw() + */ +EAPI void edje_freeze (void); + +/** + * @brief Thaws the edje objects. + * + * @details This function thaws all the edje animations in the current process. + * + * @since_tizen 2.3 + * + * @see edje_object_thaw() to thaw a specific object + * + * @see edje_freeze() + */ +EAPI void edje_thaw (void); + +/** + * @brief Sets the edje object to the playing or paused states. + * + * @details This function sets the edje object @a obj to the playing or paused + * states, depending on the parameter @a play. This has no effect if + * the object is already in that state. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @param[in] play The object state (#EINA_TRUE for the playing state, + * #EINA_FALSE for the paused state) + * + * @see edje_object_play_get() + */ +EAPI void edje_object_play_set (Evas_Object *obj, Eina_Bool play); + +/** + * @brief Gets the edje object's state. + * + * @details This function gets whether an edje object is playing or not. This state + * is set by edje_object_play_set(). + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return #EINA_FALSE if the object is not connected, its @c delete_me flag + * is set, or it is in the paused state; otherwise #EINA_TRUE if the object is in playing + * state. + * + * @see edje_object_play_set() + */ +EAPI Eina_Bool edje_object_play_get (const Evas_Object *obj); + +/** + * @brief Sets the object's animation state. + * + * @details This function starts or stops an edje object's animation. The + * information about whether it's stopped can be retrieved by + * edje_object_animation_get(). + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @param[in] on The animation state \n + * If #EINA_TRUE the object starts, + * otherwise #EINA_FALSE to stop it + * + * @see edje_object_animation_get() + */ +EAPI void edje_object_animation_set (Evas_Object *obj, Eina_Bool on); + +/** + * @brief Gets the edje object's animation state. + * + * @details This function gets whether the animation is stopped or not. The + * animation state is set by edje_object_animation_set(). + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return #EINA_FALSE on error or if the object is not animated, + * otherwise #EINA_TRUE if it is animated + * + * @see edje_object_animation_set() + */ +EAPI Eina_Bool edje_object_animation_get (const Evas_Object *obj); + +/** + * @brief Freezes the edje object. + * + * @details This function puts all changes on hold. Successive freezes are + * nested, requiring an equal number of thaws. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return The frozen state, otherwise @c 0 on error + * + * @see edje_object_thaw() + */ +EAPI int edje_object_freeze (Evas_Object *obj); + +/** + * @brief Thaws the edje object. + * + * @details This function thaws the given edje object. + * + * @since_tizen 2.3 + * + * @remarks If sucessives freezes are done, an equal number of + * thaws are required. + * + * @param[in] obj A handle to an edje object + * @return The frozen state, otherwise @c 0 if the object is not frozen or on error + * + * @see edje_object_freeze() + */ +EAPI int edje_object_thaw (Evas_Object *obj); + +/** + * @brief Gets the state of the edje part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] val_ret The part state name + * + * @return The part state:\n + * "default" for the default state\n + * "" for other states + */ +EAPI const char *edje_object_part_state_get (const Evas_Object *obj, const char *part, double *val_ret); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Geometry_Group Edje Geometry + * @ingroup Edje_Object_Group + * + * @brief This group discusses functions that deal with an object's geometry. + * + * @remarks By geometry we mean size and position. So in this group there are + * functions to manipulate an object's geometry or retrieve information + * about it. + * + * @remarks Keep in mind that by changing an object's geometry, it may affect + * its appearance on the screen of the parts inside. Most of the time + * that is what you want. + * + * @{ + */ + +/** + * @brief Gets the minimum size specified, as an EDC property, for a + * given edje object. + * + * @details This function retrieves the @a obj object's minimum size values, + * <b>as declared in its EDC group definition</b>. Minimum size + * groups have the following syntax: + * + * @since_tizen 2.3 + * + * @code + * collections { + * group { + * name: "a_group"; + * min: 100 100; + * } + * } + * @endcode + * + * where one declares a minimum size of 100 pixels for both width and + * height. Those are (hint) values that should be respected when the + * given object/group is to be controlled by a given container object + * (e.g. an edje object being "swallowed" into a given @c SWALLOW + * type part, as in edje_object_part_swallow()). Check the complete + * @ref edcref "syntax reference" for EDC files. + * + * @remarks If the @c min EDC property is not declared for @a obj, this + * call returns the value 0, for each axis. + * + * @remarks On failure, this function makes all non-@c NULL size + * pointers' pointed variables as zero. + * + * + * @param[in] obj A handle to an edje object + * @param[out] minw A pointer to a variable to store the minimum width + * @param[out] minh A pointer to a variable to store the minimum height + * + * + * @see edje_object_size_max_get() + */ +EAPI void edje_object_size_min_get (const Evas_Object *obj, Evas_Coord *minw, Evas_Coord *minh); + +/** + * @brief Sets whether Edje is going to update size hints on itself. + * + * @since_tizen 2.3 + * + * @remarks By default Edje doesn't set size hints on itself. With this function + * call, it does so if @a update is @c true. Be careful, it costs a lot to + * trigger this feature as it recalculates the object every time it makes + * sense to be sure that its minimal size hint is always accurate. + * + * @param[in] obj A handle to an edje object + * @param[in] update A boolean value that indicates whether to update the size hints + * + */ +EAPI void edje_object_update_hints_set(Evas_Object *obj, Eina_Bool update); + +/** + * @brief Gets whether Edje is going to update size hints on itself. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * @return @c true if it does, otherwise @c false if it doesn't + */ +EAPI Eina_Bool edje_object_update_hints_get(Evas_Object *obj); + +/** + * @brief Gets the maximum size specified, as an EDC property, for a + * given edje object. + * + * @details This function retrieves the @a obj object's maximum size values, + * <b>as declared in its EDC group definition</b>. Maximum size + * groups have the following syntax: + * + * @since_tizen 2.3 + * + * @code + * collections { + * group { + * name: "a_group"; + * max: 100 100; + * } + * } + * @endcode + * + * where one declares a maximum size of 100 pixels for both width and + * height. Those are (hint) values that should be respected when the + * given object/group is to be controlled by a given container object + * (e.g. an edje object being "swallowed" into a given @c SWALLOW + * type part, as in edje_object_part_swallow()). Check the complete + * @ref edcref "syntax reference" for EDC files. + * + * @remarks If the @c max EDC property is not declared for @a obj, this + * call returns the maximum size that a given edje object may have, for + * each axis. + * + * @remarks On failure, this function makes all non-@c NULL size + * pointers' pointed variables as zero. + * + * @param[in] obj A handle to an edje object + * @param[out] maxw A pointer to a variable to store the maximum width + * @param[out] maxh A pointer to a variable to store the maximum height + * + * @see edje_object_size_min_get() + */ +EAPI void edje_object_size_max_get (const Evas_Object *obj, Evas_Coord *maxw, Evas_Coord *maxh); + +/** + * @brief Forces a Size/Geometry calculation. + * + * @details This forces the object @a obj to recalculate the layout regardless of + * freeze/thaw. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * + */ +EAPI void edje_object_calc_force (Evas_Object *obj); + +/** + * @brief Calculates the minimum required size for a given edje object. + * + * @since_tizen 2.3 + * + * @remarks This call works exactly like edje_object_size_min_restricted_calc(), + * with the last two arguments set to 0. Please refer to its + * documentation. + * + * @param[in] obj A handle to an edje object + * @param[out] minw A pointer to a variable to store the minimum + * required width + * @param[out] minh A pointer to a variable to store the minimum + * required height + */ +EAPI void edje_object_size_min_calc (Evas_Object *obj, Evas_Coord *minw, Evas_Coord *minh); + +/** + * @brief Calculates the geometry of the region, relative to a given edje + * object's area, <b>occupied by all parts in the object</b>. + * + * @details This function gets the geometry of the rectangle that is equal to the area + * required to group all parts in @a obj's group/collection. The @a x + * and @a y coordinates are relative to the top left corner of the + * whole @a obj object's area. Parts placed out of the group's + * boundaries are also taken into account, so that @a x and @a y + * <b>may be negative</b>. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the geometry components you're not + * interested in, they are ignored by the function. + * + * @remarks On failure, this function makes all non-@c NULL geometry + * pointers' pointed variables as zero. + * + * @param[in] obj A handle to an edje object + * @param[out] x A pointer to a variable to store the parts region's + * x coordinate + * @param[out] y A pointer to a variable to store the parts region's + * y coordinate + * @param[out] w A pointer to a variable to store the parts region's + * width + * @param[out] h A pointer to a variable to store the parts region's + * height + * @return #EINA_TRUE if success, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_parts_extends_calc (Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + +/** + * @brief Calculates the minimum required size for a given edje object. + * + * @since_tizen 2.3 + * + * @remarks This call triggers an internal recalculation of all the parts of + * the @a obj object, in order to return its minimum required + * dimensions of width and height. The user might choose to @b impose + * those minimum sizes, making the resulting calculation to get to values + * equal or bigger than @a restrictedw and @a restrictedh, for width and + * height, respectively. + * + * @remarks At the end of this call, @a obj @b isn't automatically + * resized to new dimensions, but just returns the calculated + * sizes. The caller is the one who changes its geometry. + * + * @remarks Be advised that invisible parts in @a obj @b are taken + * into account in this calculation. + * + * @param[in] obj A handle to an edje object + * @param[out] minw A pointer to a variable to store the minimum required width + * + * @param[out] minh A pointer to a variable to store the minimum required width + * + * @param[in] restrictedw Minimum value for an object's calculated (minimum) width + * + * @param[in] restrictedh Minimum value for an object's calculated (minimum) height + * + */ +EAPI void edje_object_size_min_restricted_calc(Evas_Object *obj, Evas_Coord *minw, Evas_Coord *minh, Evas_Coord restrictedw, Evas_Coord restrictedh); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Part Edje Part + * @ingroup Edje_Object_Group + * + * @brief This group discusses functions that deal with layout components. + * + * @remarks Parts are layout components, but as a layout, they are objects too. + * + * There are several types of parts, these types can be divided into two + * main categories, the first being containers. Containers are parts + * that are in effect a group of elements. The second group is that of + * the elements, these part types may not contain others. + * + * @remarks This section has some functions specific for some types and others that + * could be applied to any type. + * + * @{ + */ + +/** + * @brief Edje Part Type + */ +typedef enum _Edje_Part_Type +{ + EDJE_PART_TYPE_NONE = 0, + EDJE_PART_TYPE_RECTANGLE = 1, + EDJE_PART_TYPE_TEXT = 2, + EDJE_PART_TYPE_IMAGE = 3, + EDJE_PART_TYPE_SWALLOW = 4, + EDJE_PART_TYPE_TEXTBLOCK = 5, + EDJE_PART_TYPE_GRADIENT = 6, + EDJE_PART_TYPE_GROUP = 7, + EDJE_PART_TYPE_BOX = 8, + EDJE_PART_TYPE_TABLE = 9, + EDJE_PART_TYPE_EXTERNAL = 10, + EDJE_PART_TYPE_PROXY = 11, + EDJE_PART_TYPE_SPACER = 12, /**< @since 1.7 */ + EDJE_PART_TYPE_LAST = 13 +} Edje_Part_Type; + +/** + * @brief Checks whether an edje part exists in a given edje object's group + * definition. + * + * @details This function returns if a given part exists in the edje group + * bound to object @a obj (with edje_object_file_set()). + * + * @since_tizen 2.3 + * + * @remarks This call is useful, for example, when one could expect a + * given GUI element, depending on the @b theme applied to @a obj. + * + * @param[in] obj A handle to an edje object + * @param[in] part The part's name to check for existence in @a obj's + * group + * @return #EINA_TRUE, if the edje part exists in @a obj's group, + * otherwise #EINA_FALSE (and on errors) + */ +EAPI Eina_Bool edje_object_part_exists (const Evas_Object *obj, const char *part); + +/** + * @brief Get a handle to the Evas object implementing a given edje + * part, in an edje object. + * + * @details This function gets a pointer of the Evas object corresponding to a + * given part in the @a obj object's group. + * + * @since_tizen 2.3 + * + * @remarks You should @b never modify the state of the returned object (with + * @c evas_object_move() or @c evas_object_hide() for example), + * because it's meant to be managed by Edje, solely. You are safe to + * query information about its current state (with @c + * evas_object_visible_get() or @c evas_object_color_get() for + * example), though. + * + * @param[in] obj A handle to an edje object + * @param[in] part The edje part's name + * @return A pointer to the Evas object implementing the given part, + * otherwise @c NULL on failure (e.g. the given part doesn't exist) + */ +EAPI const Evas_Object *edje_object_part_object_get (const Evas_Object *obj, const char *part); + +/** + * @brief Gets the geometry of a given edje part, in a given edje + * object's group definition, <b>relative to the object's area</b>. + * + * @details This function gets the geometry of an edje part within its + * group. The @a x and @a y coordinates are relative to the top left + * corner of the whole @a obj object's area. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the geometry components you're not + * interested in, they are ignored by the function. + * + * @remarks On failure, this function makes all non-@c NULL geometry + * pointers' pointed variables as zero. + * + * @param[in] obj A handle to an edje object + * @param[in] part The edje part's name + * @param[out] x A pointer to a variable to store the part's x + * coordinate + * @param[out] y A pointer to a variable to store the part's y + * coordinate + * @param[out] w A pointer to a variable to store the part's width + * @param[out] h A pointer to a variable to store the part's height + * @return #EINA_TRUE if success, otherwise #EINA_FALSE + * + */ +EAPI Eina_Bool edje_object_part_geometry_get (const Evas_Object *obj, const char *part, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + +/** + * @brief Gets a list of all accessibility part names. + * + * @since 1.7.0 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @return A list of all accessibility part names on @a obj + */ +EAPI Eina_List *edje_object_access_part_list_get (const Evas_Object *obj); + +/** + * @} + */ + +/** + * @defgroup Edje_Part_Text Edje Text Part + * @ingroup Edje_Object_Part + * + * @brief This group discusses functions that deal with parts of type text. + * + * @remarks Text is an element type for parts. It's basic functionality is to + * display a string on the layout, but a lot more can be done + * with texts, like string selection, setting the cursor, and including + * an input panel, where one can set a virtual keyboard to handle + * keyboard entry easily. + * + * @{ + */ + +typedef enum _Edje_Text_Effect +{ +#define EDJE_TEXT_EFFECT_MASK_BASIC 0xf +#define EDJE_TEXT_EFFECT_BASIC_SET(x, s) \ + do { x = ((x) & ~EDJE_TEXT_EFFECT_MASK_BASIC) | (s); } while (0) + EDJE_TEXT_EFFECT_NONE = 0, + EDJE_TEXT_EFFECT_PLAIN = 1, + EDJE_TEXT_EFFECT_OUTLINE = 2, + EDJE_TEXT_EFFECT_SOFT_OUTLINE = 3, + EDJE_TEXT_EFFECT_SHADOW = 4, + EDJE_TEXT_EFFECT_SOFT_SHADOW = 5, + EDJE_TEXT_EFFECT_OUTLINE_SHADOW = 6, + EDJE_TEXT_EFFECT_OUTLINE_SOFT_SHADOW = 7, + EDJE_TEXT_EFFECT_FAR_SHADOW = 8, + EDJE_TEXT_EFFECT_FAR_SOFT_SHADOW = 9, + EDJE_TEXT_EFFECT_GLOW = 10, +// ****************************************************************** +// ******************* TIZEN ONLY - START**************************** +// ****************************************************************** +// 2013.11.06 : Font effect for tizen. + EDJE_TEXT_EFFECT_TIZEN_GLOW_SHADOW = 11, + EDJE_TEXT_EFFECT_TIZEN_SOFT_GLOW_SHADOW = 12, + EDJE_TEXT_EFFECT_TIZEN_SHADOW = 13, +// ****************************************************************** +// ******************* TIZEN ONLY - END **************************** +// ****************************************************************** + EDJE_TEXT_EFFECT_LAST = 14, + +#define EDJE_TEXT_EFFECT_MASK_SHADOW_DIRECTION (0x7 << 4) +#define EDJE_TEXT_EFFECT_SHADOW_DIRECTION_SET(x, s) \ + do { x = ((x) & ~EDJE_TEXT_EFFECT_MASK_SHADOW_DIRECTION) | (s); } while (0) + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_LEFT = (0x3 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP = (0x5 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_RIGHT = (0x7 << 4) +} Edje_Text_Effect; + +/** + * @brief Edje text change callback prototype + */ +typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, const char *part); + +/** + * @brief Sets the object text callback. + * + * @details This function sets the callback to be called when the text changes. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] func The callback function to handle the text change + * @param[in] data The data associated with the callback function + */ +EAPI void edje_object_text_change_cb_set (Evas_Object *obj, Edje_Text_Change_Cb func, void *data); + +/** + * @brief Sets the text for an object part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas Object handle + * @param[in] part The part name + * @param[in] text The text string + * + * @return #EINA_TRUE on success, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_set (Evas_Object *obj, const char *part, const char *text); + +/** + * @brief Sets the text for an object part, but converts HTML escapes to UTF8. + * + * @details This converts the given string @a text to UTF8 assuming it contains HTML + * style escapes like "&" and "©", IF the part is of type TEXT, + * as opposed to TEXTBLOCK. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas Object handle + * @param[in] part The part name + * @param[in] text The text string + * + * @return #EINA_TRUE on success, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_escaped_set (Evas_Object *obj, const char *part, const char *text); + +/** + * @brief Gets the text of the object part. + * + * @details This function returns the text associated with the object part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The text string + * + * @see edje_object_part_text_set() + */ +EAPI const char *edje_object_part_text_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the style of the textblock part + * + * @details This function sets the style associated with the textblock part + * + * @since_tizen 2.3 + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] style The style to set (textblock conventions) + */ +EAPI void edje_object_part_text_style_user_push(Evas_Object *obj, const char *part, const char *style); + +/** + * @brief Gets the text of the object part. + * + * @details This function returns the style associated with the textblock part. + * + * @since 1.2.0 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The text string + */ +EAPI const char *edje_object_part_text_style_user_peek(const Evas_Object *obj, const char *part); + +/** + * @brief Deletes the top style form of the the user style stack. + * + * @since 1.2.0 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_style_user_pop(Evas_Object *obj, const char *part); + +/** + * @brief Sets the raw (non escaped) text for an object part. + * + * @details This funciton does escape for you if it is a TEXTBLOCK part, that is, + * if text contains tags, these tags are not interpreted/parsed by the TEXTBLOCK. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas Object handle + * @param[in] part The part name + * @param[in] text_to_escape The text string + * @return #EINA_TRUE if success, otherwise #EINA_FALSE + * + * @see edje_object_part_text_unescaped_get() + */ +EAPI Eina_Bool edje_object_part_text_unescaped_set (Evas_Object *obj, const char *part, const char *text_to_escape); + +/** + * @brief Gets the text of the object part, without escaping. + * + * @details This function is the counterpart of + * edje_object_part_text_unescaped_set(). Note that the + * result is newly allocated memory and should be released with free() + * when done. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The @b allocated text string without escaping, otherwise @c NULL on errors + * + * @see edje_object_part_text_unescaped_set() + */ +EAPI char *edje_object_part_text_unescaped_get (const Evas_Object *obj, const char *part); + +/** + * @brief Inserts text for an object part. + * + * @details This function inserts the text for an object part just before the + * cursor position. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas Object handle + * @param[in] part The part name + * @param[in] text The text string + * + */ +EAPI void edje_object_part_text_insert (Evas_Object *obj, const char *part, const char *text); + +/** + * @brief Inserts text for an object part. + * + * @details This function inserts the text for an object part at the end. It does not + * move the cursor. + * + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas Object handle + * @param[in] part The part name + * @param[in] text The text string + */ +EAPI void edje_object_part_text_append(Evas_Object *obj, const char *part, const char *text); + +/** + * @brief Gets a list of char anchor names. + * + * @details This function returns a list of char anchor names. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The list of anchors (const char *), do not modify them + * + */ +EAPI const Eina_List *edje_object_part_text_anchor_list_get (const Evas_Object *obj, const char *part); + +/** + * @brief Gets a list of Evas_Textblock_Rectangle anchor rectangles. + * + * @details This function returns a list of Evas_Textblock_Rectangle anchor + * rectangles. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] anchor The anchor name + * + * @return The list of anchor rects (const Evas_Textblock_Rectangle *), + * do not modify them \n + * Geometry is relative to the entry part. + * + */ +EAPI const Eina_List *edje_object_part_text_anchor_geometry_get (const Evas_Object *obj, const char *part, const char *anchor); + +/** + * @brief Gets a list of char item names. + * + * @details This function returns a list of char item names. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The list of items (const char *), do not modify them + * + */ +EAPI const Eina_List *edje_object_part_text_item_list_get (const Evas_Object *obj, const char *part); + +/** + * @brief Gets the item geometry. + * + * @details This function returns a list of Evas_Textblock_Rectangle item + * rectangles. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] item The item name + * @param[out] cx The item's x coordinate (relative to the entry part) + * @param[out] cy The item's y coordinate (relative to the entry part) + * @param[out] cw The item width + * @param[out] ch The item height + * + * @return @c 1 if the item exists, otherwise @c 0 if it does not + * + */ +EAPI Eina_Bool edje_object_part_text_item_geometry_get (const Evas_Object *obj, const char *part, const char *item, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch); + +/** + * @brief Inserts text as if the user has inserted it. + * + * @since 1.2.0 + * + * @since_tizen 2.3 + * + * @remarks This means it actually registers as a change and emits signals, triggers + * callbacks as appropriate. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] text The text string + */ +EAPI void edje_object_part_text_user_insert (const Evas_Object *obj, const char *part, const char *text); + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_Text_Selection Edje Text Selection + * @ingroup Edje_Part_Text + * + * @brief This group discusses functions that deal with selection of text parts. + * + * @remarks Selection is a known functionality for texts in the whole computational + * world. It is a block of text marked for further manipulation. + * + * @remarks Edje is responsible for handling this functionality through the + * following functions. + * + * @{ + */ + +/** + * @brief Gets the selection text of the object part. + * + * @details This function returns selection text of the object part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The text string + * + * @see edje_object_part_text_select_all() + * @see edje_object_part_text_select_none() + */ +EAPI const char *edje_object_part_text_selection_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the selection to be none. + * + * @details This function sets the selection text to be none. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + */ +EAPI void edje_object_part_text_select_none (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the selection to be everything. + * + * @details This function selects all the text of the object of the part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + */ +EAPI void edje_object_part_text_select_all (const Evas_Object *obj, const char *part); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Sets the selection to be word pointed by the current cursor. + * + * @details This function selects the word pointed by the cursor of the object of the part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + */ +EAPI void edje_object_part_text_select_word (const Evas_Object *obj, const char *part); + +/** + * @brief Enables selection if the entry is an EXPLICIT selection mode + * type. + * + * @remarks The default is to @b not allow selection. This function only affects user + * selection, functions such as edje_object_part_text_select_all() and + * edje_object_part_text_select_none() are not affected. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] allow If #EINA_TRUE it enables selection, otherwise #EINA_FALSE + * + */ +EAPI void edje_object_part_text_select_allow_set (const Evas_Object *obj, const char *part, Eina_Bool allow); + +/** + * @brief Aborts any selection action on a part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_select_abort (const Evas_Object *obj, const char *part); + +/** + * @brief Starts selecting at the current cursor position. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_select_begin (const Evas_Object *obj, const char *part); + +/** + * @brief Extends the current selection to the current cursor position. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_select_extend (const Evas_Object *obj, const char *part); + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_Text_Cursor Edje Text Cursor + * @ingroup Edje_Part_Text + * + * @brief This group discusses functions that deal with a cursor in text parts. + * + * @remarks Cursor is a known functionality for texts in the whole computational + * world. It marks a position in the text from where one may want + * to make an insertion, deletion, or selection. + * + * @remarks Edje is responsible for handling this functionality through the + * following functions. + * + * @{ + */ + +typedef enum _Edje_Cursor +{ + EDJE_CURSOR_MAIN, + EDJE_CURSOR_SELECTION_BEGIN, + EDJE_CURSOR_SELECTION_END, + EDJE_CURSOR_PREEDIT_START, + EDJE_CURSOR_PREEDIT_END, + EDJE_CURSOR_USER, + EDJE_CURSOR_USER_EXTRA, + // more later +} Edje_Cursor; + +/** + * @brief Advances the cursor to the next cursor position. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to advance + * + * @see evas_textblock_cursor_char_next + */ +EAPI Eina_Bool edje_object_part_text_cursor_next (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the previous char + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + * + * @see evas_textblock_cursor_char_prev + */ +EAPI Eina_Bool edje_object_part_text_cursor_prev (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the char above the current cursor position. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + */ +EAPI Eina_Bool edje_object_part_text_cursor_up (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the char below the current cursor position. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + */ +EAPI Eina_Bool edje_object_part_text_cursor_down (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the beginning of the text part + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + * + * @see evas_textblock_cursor_paragraph_first + */ +EAPI void edje_object_part_text_cursor_begin_set (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the end of the text part. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + * + * @see evas_textblock_cursor_paragraph_last + */ +EAPI void edje_object_part_text_cursor_end_set (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Copies the cursor to another cursor. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] src The cursor to copy from + * @param[in] dst The cursor to copy to + */ +EAPI void edje_object_part_text_cursor_copy (Evas_Object *obj, const char *part, Edje_Cursor src, Edje_Cursor dst); + +/** + * @brief Moves the cursor to the beginning of the line. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + * + * @see evas_textblock_cursor_line_char_first + */ +EAPI void edje_object_part_text_cursor_line_begin_set (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Moves the cursor to the end of the line. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The edje cursor to work on + * + * @see evas_textblock_cursor_line_char_last + */ +EAPI void edje_object_part_text_cursor_line_end_set (Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Sets the given cursor to an X,Y position. + * + * @remarks This is frequently used with the user cursor. + * + * @param[in] obj An edje object + * @param[in] part The part containing the object + * @param[in] cur The cursor to adjust + * @param[in] x The X Coordinate + * @param[in] y The Y Coordinate + * @return @c true on success, @c false on error + */ +EAPI Eina_Bool edje_object_part_text_cursor_coord_set (Evas_Object *obj, const char *part, Edje_Cursor cur, Evas_Coord x, Evas_Coord y); + +/** + * @brief Gets whether the cursor points to a format. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The cursor to adjust + * @return #EINA_TRUE if it's true, otherwise #EINA_FALSE + * + * @see evas_textblock_cursor_is_format + */ +EAPI Eina_Bool edje_object_part_text_cursor_is_format_get (const Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Checks whether (x,y) is on top of the selected-text. + * @details This function returns @c true if (x,y) is on top of the selected-text. + * + * @param[in] obj An edje object + * @param[in] part The part containing the object. + * @param[in] x The X Coordinate + * @param[in] y The Y Coordinate + * @return @c true if (x,y) is on top of the selected-text, otherwise @c false + */ +EAPI Eina_Bool +edje_object_part_text_xy_in_selection_get(Evas_Object *obj, const char *part, Evas_Coord x, Evas_Coord y); + +/** + * @brief Gets @c true if the cursor points to a visible format. + * For example \\t, \\n, item and so on. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The cursor to adjust + * + * @see evas_textblock_cursor_format_is_visible_get + */ +EAPI Eina_Bool edje_object_part_text_cursor_is_visible_format_get(const Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Gets the content (char) at the cursor position. + * + * @remarks You must free the return value (if not @c NULL) after you are done with it. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The cursor to use + * @return The character string pointed to, (may be a multi-byte utf8 sequence) which is terminated by a @c null byte. + * + * @see evas_textblock_cursor_content_get + */ +EAPI char *edje_object_part_text_cursor_content_get (const Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Sets the cursor position to the given value. + * + * @since 1.1.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The cursor to move + * @param[in] pos The position of the cursor + */ +EAPI void edje_object_part_text_cursor_pos_set (Evas_Object *obj, const char *part, Edje_Cursor cur, int pos); + +/** + * @brief Gets the current position of the cursor. + * + * @since 1.1.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] cur The cursor to get the position + * @return The cursor position + */ +EAPI int edje_object_part_text_cursor_pos_get (const Evas_Object *obj, const char *part, Edje_Cursor cur); + +/** + * @brief Gets the cursor geometry of the part relative to the edje + * object. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] x The cursor's X position + * @param[out] y The cursor's Y position + * @param[out] w The cursor's width + * @param[out] h The cursor's height + * + */ +EAPI void edje_object_part_text_cursor_geometry_get (const Evas_Object *obj, const char *part, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + +/** + * @} + */ + +/** + * @internal + * @defgroup Edje_Text_Entry Edje Text Entry + * @ingroup Edje_Part_Text + * + * @brief This group discusses functions that deal with text entries. + * + * @remarks In Edje it's possible to use a text part as an entry so that the user is + * able to make inputs of text. To do so, the text part must be set + * with an input panel that works as a virtual keyboard. + * + * @remarks Some of the effects can be applied to the entered text and also plenty + * actions can be performed after any input. + * + * @remarks Use the functions of this section to handle the user input of text. + * + * @{ + */ + +struct _Edje_Entry_Change_Info +{ + union { + struct { + const char *content; + size_t pos; + size_t plain_length; /**< Number of cursor positions represented + in the content */ + } insert; + struct { + const char *content; + size_t start, end; + } del; + } change; + Eina_Bool insert : 1; /**< @c true if the "change" union's "insert" is valid */ + Eina_Bool merge : 1; /**< @c true if it can be merged with the previous one. Used, for example, with insertion when something is already selected */ +}; + +/** + * @since 1.1.0 + */ +typedef struct _Edje_Entry_Change_Info Edje_Entry_Change_Info; + +typedef enum _Edje_Text_Filter_Type +{ + EDJE_TEXT_FILTER_TEXT = 0, + EDJE_TEXT_FILTER_FORMAT = 1, + EDJE_TEXT_FILTER_MARKUP = 2 +} Edje_Text_Filter_Type; + +typedef enum _Edje_Text_Autocapital_Type +{ + EDJE_TEXT_AUTOCAPITAL_TYPE_NONE, + EDJE_TEXT_AUTOCAPITAL_TYPE_WORD, + EDJE_TEXT_AUTOCAPITAL_TYPE_SENTENCE, + EDJE_TEXT_AUTOCAPITAL_TYPE_ALLCHARACTER +} Edje_Text_Autocapital_Type; + +/** + * @brief Edje Input Panel Language + */ +typedef enum _Edje_Input_Panel_Lang +{ + EDJE_INPUT_PANEL_LANG_AUTOMATIC, /**< Automatic @since 1.2 */ + EDJE_INPUT_PANEL_LANG_ALPHABET /**< Alphabet @since 1.2 */ +} Edje_Input_Panel_Lang; + +/** + * @brief Edje Input Panel Return Key Type + */ +typedef enum _Edje_Input_Panel_Return_Key_Type +{ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT, /**< Default @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_DONE, /**< Done @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_GO, /**< Go @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_JOIN, /**< Join @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_LOGIN, /**< Login @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_NEXT, /**< Next @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_SEARCH, /**< Search or magnifier icon @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_SEND, /**< Send @since 1.2 */ + EDJE_INPUT_PANEL_RETURN_KEY_TYPE_SIGNIN /**< Sign-in @since 1.8 */ +} Edje_Input_Panel_Return_Key_Type; + +/** + * @brief Edje Input Panel Layout + */ +typedef enum _Edje_Input_Panel_Layout +{ + EDJE_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */ + EDJE_INPUT_PANEL_LAYOUT_NUMBER, /**< Number layout */ + EDJE_INPUT_PANEL_LAYOUT_EMAIL, /**< Email layout */ + EDJE_INPUT_PANEL_LAYOUT_URL, /**< URL layout */ + EDJE_INPUT_PANEL_LAYOUT_PHONENUMBER, /**< Phone number layout */ + EDJE_INPUT_PANEL_LAYOUT_IP, /**< IP layout */ + EDJE_INPUT_PANEL_LAYOUT_MONTH, /**< Month layout */ + EDJE_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number only layout */ + EDJE_INPUT_PANEL_LAYOUT_INVALID, /**< Never use this */ + EDJE_INPUT_PANEL_LAYOUT_HEX, /**< Hexadecimal layout @since 1.2 */ + EDJE_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout including esc, alt, ctrl key, snd so on (no auto-correct, no auto-capitalization) @since 1.2 */ + EDJE_INPUT_PANEL_LAYOUT_PASSWORD, /**< Like normal, but no auto-correct, no auto-capitalization. @since 1.2 */ + EDJE_INPUT_PANEL_LAYOUT_DATETIME, /**< Date and time layout @since 1.8 */ + EDJE_INPUT_PANEL_LAYOUT_EMOTICON /**< Emoticon layout @since 1.10 */ +} Edje_Input_Panel_Layout; + + +/** + * @brief Edje Input Hints + */ +typedef enum +{ + EDJE_INPUT_HINT_NONE = 0, /**< No active hints @since 1.12 */ + EDJE_INPUT_HINT_AUTO_COMPLETE = 1 << 0, /**< suggest word auto completion @since 1.12 */ + EDJE_INPUT_HINT_SENSITIVE_DATA = 1 << 1, /**< typed text should not be stored. @since 1.12 */ +} Edje_Input_Hints; + +enum +{ + EDJE_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_NORMAL, /**< The plain normal layout @since 1.12 */ + EDJE_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_FILENAME, /**< Filename layout. Symbols such as '/' should be disabled. @since 1.12 */ + EDJE_INPUT_PANEL_LAYOUT_NORMAL_VARIATION_PERSON_NAME /**< The name of a person. @since 1.12 */ +}; + +enum +{ + EDJE_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_NORMAL, /**< The plain normal number layout @since 1.8 */ + EDJE_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_SIGNED, /**< The number layout to allow a positive or negative sign at the start @since 1.8 */ + EDJE_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_DECIMAL, /**< The number layout to allow decimal point to provide fractional value @since 1.8 */ + EDJE_INPUT_PANEL_LAYOUT_NUMBERONLY_VARIATION_SIGNED_AND_DECIMAL /**< The number layout to allow decimal point and negative sign @since 1.8 */ +}; + +enum +{ + EDJE_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NORMAL, /**< The normal password layout @since 1.12 */ + EDJE_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY /**< The password layout to allow only number @since 1.12 */ +}; + +typedef void (*Edje_Text_Filter_Cb) (void *data, Evas_Object *obj, const char *part, Edje_Text_Filter_Type type, char **text); +typedef void (*Edje_Markup_Filter_Cb) (void *data, Evas_Object *obj, const char *part, char **text); +typedef Evas_Object *(*Edje_Item_Provider_Cb) (void *data, Evas_Object *obj, const char *part, const char *item); + +/** + * @brief Shows the last character in the password mode. + * + * @details This function enables the last input to be visible when in the password mode for a few seconds + * or until the next input is entered. + * + * @remarks The time out value is obtained by the edje_password_show_last_timeout_set function. + * + * @param[in] password_show_last If #EINA_TRUE it enables the last character shown in the password mode + * + * @see edje_password_show_last_timeout_set() + */ +EAPI void edje_password_show_last_set(Eina_Bool password_show_last); + +/** + * @brief Sets the timeout value for the last shown input in the password mode. + * + * @details This function sets the time out value for which the last input entered in the password + * mode is visible. + * + * @remarks This value can be used only when last shown input is set in the password mode. + * + * @param[in] password_show_last_timeout The timeout value + * + * @see edje_password_show_last_set() + * + */ +EAPI void edje_password_show_last_timeout_set(double password_show_last_timeout); + +/** + * @brief Sets the RTL orientation for this object. + * + * @since 1.1.0 + * + * @param[in] obj A handle to an edje object + * @param[in] rtl A new flag value (#EINA_TRUE/#EINA_FALSE) + */ +EAPI void edje_object_mirrored_set (Evas_Object *obj, Eina_Bool rtl); + +/** + * @brief Gets the RTL orientation for this object. + * + * @since 1.1.0 + * + * @remarks You can set the RTL orientation explicitly with edje_object_mirrored_set. + * + * @param[in] obj A handle to an edje object + * @return #EINA_TRUE if the flag is set, otherwise #EINA_FALSE if it is not + */ +EAPI Eina_Bool edje_object_mirrored_get (const Evas_Object *obj); + +/** + * @brief Sets the function that provides item objects for named items in an edje entry text. + * + * @remarks Item objects may be deleted any time by Edje, and are deleted when the + * edje object is deleted (or the file is set to a new file). + * + * @param[in] obj A valid Evas Object handle + * @param[in] func The function to call (or @c NULL to disable) to get item objects + * @param[in] data The data pointer to pass to the @a func callback + */ +EAPI void edje_object_item_provider_set (Evas_Object *obj, Edje_Item_Provider_Cb func, void *data); + +/** + * @brief Resets the input method context if needed. + * + * @since 1.2.0 + * + * @remarks This can be necessary in case modifying the buffer would confuse an on-going input method behavior. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_imf_context_reset (const Evas_Object *obj, const char *part); + +/** + * @brief Gets the input method context in the entry. + * + * @since 1.2.0 + * + * @remarks If ecore_imf is not available when Edje is compiled, this function returns @c NULL, + * otherwise the returned pointer is an Ecore_IMF *. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The input method context (Ecore_IMF_Context *) in the entry + */ +EAPI void *edje_object_part_text_imf_context_get (const Evas_Object *obj, const char *part); + +// ****************************************************************** +// ******************* TIZEN ONLY - START**************************** +// ****************************************************************** +/** + * @internal + * @brief Gets the current position of the selection. + * + * @param obj A valid Evas_Object handle + * @param part The part name + * @param x A pointer to a variable to select the part's x + * coordinate + * @param y A pointer to a variable to select the part's y + * coordinate + * @param w A pointer to a variable to select the part's width + * @param h A pointer to a variable to select the part's height + * @return #EINA_TRUE if the part is selected, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_selection_geometry_get (const Evas_Object *obj, const char *part, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); +// ****************************************************************** +// ******************* TIZEN ONLY - END **************************** +// ****************************************************************** + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Gets the number of lines occupied by the selection. + * + * @param obj A valid Evas_Object handle + * @param part The part name + * @return The number of lines occupied by the selection + */ +EAPI unsigned long edje_object_part_text_selection_lines_number_get(const Evas_Object *obj, const char *part); + +/** + * @internal + * @remarks Tizen only feature + * + * @brief Gets the current position of the given selection line. + * + * @param obj A valid Evas_Object handle + * @param part The part name + * @param line given selection line + * @param x A pointer to a variable to insert the line's x + * coordinate + * @param y A pointer to a variable to insert the line's y + * coordinate + * @param w A pointer to a variable to inset the line's width + * @param h A pointer to a variable to insert the line's height + * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool edje_object_part_text_selection_line_properties_get(const Evas_Object *obj, const char *part, unsigned long line, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + + +/** + * @brief Sets the layout of the input panel. + * + * @since 1.1 + * + * @remarks The layout of the input panel or virtual keyboard can make it easier or + * harder to enter content. This allows you to hint what kind of input you + * are expecting to enter and thus have the input panel automatically + * come up with the right mode. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] layout The layout type + */ +EAPI void edje_object_part_text_input_panel_layout_set (Evas_Object *obj, const char *part, Edje_Input_Panel_Layout layout); + +/** + * @brief Gets the layout of the input panel. + * + * @since 1.1 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The layout type of the input panel + * + * @see edje_object_part_text_input_panel_layout_set + */ +EAPI Edje_Input_Panel_Layout edje_object_part_text_input_panel_layout_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the layout variation of the input panel. + * + * @since 1.8 + * + * @remarks The layout variation of the input panel or virtual keyboard can make it easier or + * harder to enter content. This allows you to hint what kind of input you + * are expecting to enter and thus have the input panel automatically + * come up with the right mode. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] variation The layout variation type + */ +EAPI void edje_object_part_text_input_panel_layout_variation_set(Evas_Object *obj, const char *part, int variation); + +/** + * @brief Gets the layout variation of the input panel. + * + * @since 1.8 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return The layout variation type of the input panel + * + * @see edje_object_part_text_input_panel_layout_variation_set + */ +EAPI int edje_object_part_text_input_panel_layout_variation_get(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the autocapitalization type on the immodule. + * + * @since 1.1.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] autocapital_type The type of autocapitalization + */ +EAPI void edje_object_part_text_autocapital_type_set (Evas_Object *obj, const char *part, Edje_Text_Autocapital_Type autocapital_type); + +/** + * @brief Gets the autocapitalization type. + * + * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The autocapitalization type + */ +EAPI Edje_Text_Autocapital_Type edje_object_part_text_autocapital_type_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets whether prediction is allowed. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] prediction If @c true, the prediction feature is allowed + */ +EAPI void edje_object_part_text_prediction_allow_set (Evas_Object *obj, const char *part, Eina_Bool prediction); + +/** + * @brief Gets whether prediction is allowed. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return #EINA_TRUE if the prediction feature is allowed + */ +EAPI Eina_Bool edje_object_part_text_prediction_allow_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the attribute to show the input panel automatically. + * + * @since 1.1.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] enabled If @c true, the input panel appears when an entry is clicked or has focus + */ +EAPI void edje_object_part_text_input_panel_enabled_set (Evas_Object *obj, const char *part, Eina_Bool enabled); + +/** + * @brief Gets the attribute to show the input panel automatically. + * + * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return #EINA_TRUE if it supports this feature, otherwise #EINA_FALSE + * + * @see edje_object_part_text_input_panel_enabled_set + */ +EAPI Eina_Bool edje_object_part_text_input_panel_enabled_get (const Evas_Object *obj, const char *part); + +/** + * @brief Shows the input panel (virtual keyboard) based on the input panel property such as layout, autocapital types, and so on. + * + * @since 1.2.0 + * + * @remarks Note that the input panel is shown or hidden automatically according to the focus state. + * This API can be used for manually controlling by using edje_object_part_text_input_panel_enabled_set. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + */ +EAPI void edje_object_part_text_input_panel_show(const Evas_Object *obj, const char *part); + +/** + * @brief Hides the input panel (virtual keyboard). + * + * @since 1.2.0 + * + * @remarks Note that the input panel is shown or hidden automatically according to the focus state. + * This API can be used for manually controlling by using edje_object_part_text_input_panel_enabled_set. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @see edje_object_part_text_input_panel_show + */ +EAPI void edje_object_part_text_input_panel_hide(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the language mode of the input panel. + * + * @since 1.2.0 + * + * @remarks This API can be used if you want to show the Alphabet keyboard. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] lang The language to be set for the input panel + */ +EAPI void edje_object_part_text_input_panel_language_set(Evas_Object *obj, const char *part, Edje_Input_Panel_Lang lang); + +/** + * @brief Gets the language mode of the input panel. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The input panel language type + * + * @see @ref edje_object_part_text_input_panel_language_set + */ +EAPI Edje_Input_Panel_Lang edje_object_part_text_input_panel_language_get(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the input panel-specific data to deliver to the input panel. + * + * @since 1.2.0 + * + * @remarks This API is used by applications to deliver specific data to the input panel. + * The data format MUST be negotiated by both the application and the input panel. + * The size and format of the data are defined by the input panel. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] data The specific data to set to the input panel + * @param[in] len The length of the data, in bytes, to send to the input panel + */ +EAPI void edje_object_part_text_input_panel_imdata_set(Evas_Object *obj, const char *part, const void *data, int len); + +/** + * @brief Gets the specific data of the current active input panel. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] data The specific data to get from the input panel + * @param[in] len The length of data + */ +EAPI void edje_object_part_text_input_panel_imdata_get(const Evas_Object *obj, const char *part, void *data, int *len); + +/** + * @brief Sets the "return" key type. This type is used to set a string or icon on the "return" key of the input panel. + * + * @since 1.2.0 + * + * @remarks An input panel displays the string or icon associated with this type. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] return_key_type The type of "return" key on the input panel + */ +EAPI void edje_object_part_text_input_panel_return_key_type_set(Evas_Object *obj, const char *part, Edje_Input_Panel_Return_Key_Type return_key_type); + +/** + * @brief Gets the "return" key type. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The type of "return" key on the input panel + * + * @see edje_object_part_text_input_panel_return_key_type_set() + */ +EAPI Edje_Input_Panel_Return_Key_Type edje_object_part_text_input_panel_return_key_type_get(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the return key on the input panel to be disabled. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] disabled The state + */ +EAPI void edje_object_part_text_input_panel_return_key_disabled_set(Evas_Object *obj, const char *part, Eina_Bool disabled); + +/** + * @brief Gets whether the return key on the input panel should be disabled. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return #EINA_TRUE if it should be disabled, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_input_panel_return_key_disabled_get(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the attribute to show the input panel only on a user's explicit Mouse Up event. + * + * @since 1.8.0 + * + * @remarks It doesn't request to show the input panel even though it has focus. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] ondemand If @c true the input panel is shown on a Mouse up event(The Focus event is ignored.) + */ +EAPI void edje_object_part_text_input_panel_show_on_demand_set(Evas_Object *obj, const char *part, Eina_Bool ondemand); + +/** + * @brief Gets the attribute to show the input panel only on a user's explicit Mouse Up event. + * + * @since 1.8.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return #EINA_TRUE if the input panel is shown on a Mouse up event + */ +EAPI Eina_Bool edje_object_part_text_input_panel_show_on_demand_get(const Evas_Object *obj, const char *part); + +/** + * @brief Sets the input hint which allows input methods to fine-tune their behavior. + * + * @since 1.12 + * + * @param obj A valid Evas_Object handle + * @param part The part name + * @param input_hints input hints + */ +EAPI void edje_object_part_text_input_hint_set(Evas_Object *obj, const char *part, Edje_Input_Hints input_hints); + +/** + * @brief Gets the value of input hint. + * + * @since 1.12 + * + * @param obj A valid Evas_Object handle + * @param part The part name + * @return The value of input hint + */ +EAPI Edje_Input_Hints edje_object_part_text_input_hint_get(const Evas_Object *obj, const char *part); + +// ****************************************************************** +// ******************* TIZEN ONLY - START**************************** +// ****************************************************************** +typedef enum _Edje_Selection_Handler +{ + EDJE_SELECTION_HANDLER_START, + EDJE_SELECTION_HANDLER_END, +} Edje_Selection_Handler; + +/** + * @internal + * @brief Sets the viewport region of the text. + * + * @remarks Viewport region is used for showing or hiding text selection handlers. + * + * @param obj A valid object handle + * @param part The part name + * @param x A pointer to a variable to set the viewport's x coordinate + * @param y A pointer to a variable to set the viewport's y coordinate + * @param w A pointer to a variable to set the viewport's width + * @param h A pointer to a variable to set the viewport's height + */ +EAPI void edje_object_part_text_viewport_region_set (const Evas_Object *obj, const char *part, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h); + +/** + * @internal + * @brief Sets the layout region of the text. + * + * @remarks Layout region is used for showing or hiding text selection handlers. + * + * @param obj A valid object handle + * @param part The part name + * @param x A pointer to a variable to set the layout's x coordinate + * @param y A pointer to a variable to set the layout's y coordinate + * @param w A pointer to a variable to set the layout's width + * @param h A pointer to a variable to set the layout's height + */ +EAPI void edje_object_part_text_layout_region_set (const Evas_Object *obj, const char *part, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h); + +/** + * @internal + * @brief Gets the geometry of the selection handler. + * + * @param obj A valid object handle + * @param part The edje part + * @param type The type of handler (start, end) + * @param x A pointer to a variable to get the handler's x coordinate + * @param y A pointer to a variable to get the handler's y coordinate + * @param w A pointer to a variable to get the handler's width + * @param h A pointer to a variable to get the handler's height + */ +EAPI Eina_Bool edje_object_part_text_selection_handler_geometry_get (const Evas_Object *obj, const char *part, Edje_Selection_Handler type, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + +/** + * @internal + * @brief Gets whether the cursor handler is disabled. + * + * @param obj A valid object handle + * @param part The edje part + * @return #EINA_TRUE if the cursor handler is disabled, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_cursor_handler_disabled_get (const Evas_Object *obj, const char *part); + +/** + * @internal + * @brief Sets whether the cursor handler is disabled. + * + * @param obj A valid object handle + * @param part The edje part + * @param disabled #EINA_TRUE to disable the cursor handler, otherwise #EINA_FALSE + */ +EAPI void edje_object_part_text_cursor_handler_disabled_set (Evas_Object *obj, const char *part, Eina_Bool disabled); + +/** + * @internal + * @brief Gets the geometry of the cursor handler. + * + * @param obj A valid object handle + * @param part The edje part + * @param x A pointer to a variable to get the handler's x coordinate + * @param y A pointer to a variable to get the handler's y coordinate + * @param w A pointer to a variable to get the handler's width + * @param h A pointer to a variable to get the handler's height + * @return #EINA_TRUE if the cursor handler is valid (existing and visible), otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_text_cursor_handler_geometry_get (const Evas_Object *obj, const char *part, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); +// ****************************************************************** +// ******************* TIZEN ONLY - END ***************************** +// ****************************************************************** + +/** + * @brief Adds a filter function for a newly inserted text. + * + * @remarks Whenever text is inserted (not the same as set) into the given @a part, + * the list of filter functions are called to decide if and how the new + * text should be accepted. + * @remarks There are three types of filters, EDJE_TEXT_FILTER_TEXT, + * EDJE_TEXT_FILTER_FORMAT, and EDJE_TEXT_FILTER_MARKUP. + * @remarks The text parameter in the @a func filter can be modified by the user and + * it's up to him to free the one passed if he has to change the pointer. On + * doing so, the newly set text should be malloc'ed, as once all the filters + * are called Edje frees it. + * If the text is to be rejected, freeing it and setting the pointer to @c NULL + * makes Edje break out of the filter cycle and reject the inserted + * text. + * + * @remarks This function is deprecated because of difficulty in use. + * The type(format, text, or markup) of text should always + * be checked in the filter function for correct filtering. + * Use edje_object_text_markup_filter_callback_add() instead. There + * is no need to check the type of text in the filter function + * because the text is always markup. + * @remarks If you use this function with + * edje_object_text_markup_filter_callback_add(), all + * Edje_Text_Filter_Cb functions and Edje_Markup_Filter_Cb functions + * are executed, and then the filtered text is inserted. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The callback function that acts as a filter + * @param[in] data The user provided data to pass to the filter function + * + * + * @see edje_object_text_insert_filter_callback_del + * @see edje_object_text_insert_filter_callback_del_full + * @see edje_object_text_markup_filter_callback_add + */ +EAPI void edje_object_text_insert_filter_callback_add (Evas_Object *obj, const char *part, Edje_Text_Filter_Cb func, void *data); + +/** + * @brief Deletes a function from the filter list. + * + * @details This deletes the given @a func filter from the list in @a part and returns + * the user data pointer given when added. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The function callback to remove + * + * @return The user data pointer if successful, otherwise @c NULL + * + * @see edje_object_text_insert_filter_callback_add + * @see edje_object_text_insert_filter_callback_del_full + */ +EAPI void *edje_object_text_insert_filter_callback_del (Evas_Object *obj, const char *part, Edje_Text_Filter_Cb func); + +/** + * @brief Deletes a function and its matching user data from the filter list. + * + * @details This deletes the given @a func filter and @a data user data from the list + * in @a part. + * It returns the user data pointer given when added. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The function callback to remove + * @param[in] data The data passed to the callback function + * + * @return The same data pointer if successful, otherwise @c NULL + * + * @see edje_object_text_insert_filter_callback_add + * @see edje_object_text_insert_filter_callback_del + */ +EAPI void *edje_object_text_insert_filter_callback_del_full (Evas_Object *obj, const char *part, Edje_Text_Filter_Cb func, void *data); + +/** + * @brief Adds a markup filter function for a newly inserted text. + * + * @since 1.2.0 + * + * @remarks Whenever text is inserted (not the same as set) into the given @a part, + * the list of markup filter functions are called to decide if and how + * the new text should be accepted. + * @remarks The text parameter in the @a func filter is always markup. It can be + * modified by the user and it's up to him to free the one passed if he has to + * change the pointer. On doing so, the newly set text should be malloc'ed, + * as once all the filters are called Edje it frees it. + * If the text is to be rejected, freeing it and setting the pointer to @c NULL + * makes Edje break out of the filter cycle and reject the inserted + * text. + * @remarks This function is different from edje_object_text_insert_filter_callback_add(), + * in that the text parameter in the @a func filter is always markup. + * + * @remarks If you use this function with + * edje_object_text_insert_filter_callback_add(), all + * Edje_Text_Filter_Cb functions and Edje_Markup_Filter_Cb functions + * are executed, and then the filtered text is inserted. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The callback function that acts as a markup filter + * @param[in] data The user provided data to pass to the filter function + * + * @see edje_object_text_markup_filter_callback_del + * @see edje_object_text_markup_filter_callback_del_full + * @see edje_object_text_insert_filter_callback_add + */ +EAPI void edje_object_text_markup_filter_callback_add(Evas_Object *obj, const char *part, Edje_Markup_Filter_Cb func, void *data); + +/** + * @brief Deletes a function from the markup filter list. + * + * @details This deletes the given @a func filter from the list in @a part and returns + * the user data pointer given when added. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The function callback to remove + * + * @return The user data pointer if successful, otherwise @c NULL + * + * @see edje_object_text_markup_filter_callback_add + * @see edje_object_text_markup_filter_callback_del_full + */ +EAPI void *edje_object_text_markup_filter_callback_del(Evas_Object *obj, const char *part, Edje_Markup_Filter_Cb func); + +/** + * @brief Deletes a function and its matching user data from the markup filter list. + * + * @details This deletes the given @a func filter and @a data user data from the list + * in @a part and returns the user data pointer given when added. + * + * @since 1.2.0 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] func The function callback to remove + * @param[in] data The data passed to the callback function + * + * @return The same data pointer if successful, otherwise @c NULL + * + * @see edje_object_text_markup_filter_callback_add + * @see edje_object_text_markup_filter_callback_del + */ +EAPI void *edje_object_text_markup_filter_callback_del_full(Evas_Object *obj, const char *part, Edje_Markup_Filter_Cb func, void *data); + +/** + * @} + */ + +/** + * @defgroup Edje_Part_Swallow Edje Swallow Part + * @ingroup Edje_Object_Part + * + * @brief This group discusses functions that deal with parts of type swallow and swallowed objects. + * + * @remarks An important feature of Edje is to be able to create Evas_Objects + * in the code and place them in a layout. And that is what swallowing + * is all about. + * + * @remarks Swallow parts are place holders defined in the EDC file for + * objects that one may want to include in the layout later, or for + * objects that are not natives of Edje. In this last case, Edje only + * only treat the Evas_Object properties of the swallowed objects. + * + * @{ + */ + +typedef enum _Edje_Aspect_Control +{ + EDJE_ASPECT_CONTROL_NONE = 0, + EDJE_ASPECT_CONTROL_NEITHER = 1, + EDJE_ASPECT_CONTROL_HORIZONTAL = 2, + EDJE_ASPECT_CONTROL_VERTICAL = 3, + EDJE_ASPECT_CONTROL_BOTH = 4 +} Edje_Aspect_Control; + +/** + * @brief Sets the object's minimum size. + * + * @details This sets the minimum size restriction for the object. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] minw The minimum width + * @param[in] minh The minimum height + */ +EAPI void edje_extern_object_min_size_set (Evas_Object *obj, Evas_Coord minw, Evas_Coord minh); + +/** + * @brief Sets the object's maximum size. + * + * @details This sets the maximum size restriction for the object. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] maxw The maximum width + * @param[in] maxh The maximum height + */ +EAPI void edje_extern_object_max_size_set (Evas_Object *obj, Evas_Coord maxw, Evas_Coord maxh); + +/** + * @brief Sets the object's aspect size. + * + * @details This sets the desired aspect ratio to keep for an object that is + * swallowed by Edje. The width and height defines a preferred size + * ASPECT and the object may be scaled to be larger or smaller, but + * retaining the relative scale of both the aspect width and height. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] aspect The aspect control axes + * @param[in] aw The aspect radio width + * @param[in] ah The aspect ratio height + */ +EAPI void edje_extern_object_aspect_set (Evas_Object *obj, Edje_Aspect_Control aspect, Evas_Coord aw, Evas_Coord ah); + +/** + * @brief "Swallows" an object into one of the edje object @c SWALLOW + * parts. + * + * @since_tizen 2.3 + * + * @remarks Swallowing an object into an edje object is, for a given part of + * type @c SWALLOW in the EDC group, which gave life to @a obj, to set + * an external object to be controlled by @a obj, being displayed + * exactly over that part's region inside the whole edje object's + * viewport. + * + * From this point on, @a obj has total control over @a + * obj_swallow's geometry and visibility. For instance, if @a obj is + * visible, as in @c evas_object_show(), the swallowed object is + * visible too, if the given @c SWALLOW part it's in is also + * visible. Other actions on @a obj also reflect on the swallowed + * object (e.g. resizing, moving, raising/lowering, and so on). + * + * Finally, all internal changes to @a part, specifically, + * reflect on the displaying of @a obj_swallow, for example state + * changes leading to different visibility states, geometries, + * positions, and so on. + * + * @remarks If an object has already been swallowed into this part, then it + * is first unswallowed (as in edje_object_part_unswallow()) + * before the new object is swallowed. + * + * @a obj @b won't delete the swallowed object once it is + * deleted, @a obj_swallow gets to an unparented state again. + * + * For more details on EDC @c SWALLOW parts, see @ref edcref "syntax + * reference". + * + * @param[in] obj A valid edje object handle + * @param[in] part The swallow part's name + * @param[in] obj_swallow The object to occupy that part + * @return #EINA_TRUE if success, otherwise #EINA_FALSE + */ +EAPI Eina_Bool edje_object_part_swallow (Evas_Object *obj, const char *part, Evas_Object *obj_swallow); + +/** + * @brief Unswallows an object. + * + * @details It causes the Edje to regurgitate a previously swallowed object. + * + * @since_tizen 2.3 + * + * @remarks @a obj_swallow is @b not deleted or hidden. + * @a obj_swallow may appear on the evas depending on the state in which + * it got unswallowed. Make sure you delete it or hide it if you do not want it. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] obj_swallow The swallowed object + */ +EAPI void edje_object_part_unswallow (Evas_Object *obj, Evas_Object *obj_swallow); + +/** + * @brief Gets the object currently swallowed by a part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @return The swallowed object, otherwise @c NULL if there are none + */ +EAPI Evas_Object *edje_object_part_swallow_get (const Evas_Object *obj, const char *part); + +/** + * @} + */ + +/** + * @defgroup Edje_Part_Drag Edje Drag + * @ingroup Edje_Object_Part + * + * @brief This group discusses functions that deal with draggable parts. + * + * @remarks To create a movable part it must be declared as draggable + * in the EDC file. To do so, one must define a "draggable" block inside + * the "part" block. + * + * @remarks These functions are used to set dragging properties for a + * part or get dragging information about it. + * + * @{ + */ + + +/** + * @brief Edje drag direction + */ +typedef enum _Edje_Drag_Dir +{ + EDJE_DRAG_DIR_NONE = 0, /**< Direction None. */ + EDJE_DRAG_DIR_X = 1, /**< Direction X. */ + EDJE_DRAG_DIR_Y = 2, /**< Direction Y. */ + EDJE_DRAG_DIR_XY = 3 /**< Direction XY. */ +} Edje_Drag_Dir; + +/** + * @brief Gets the draggable directions. + * + * @since_tizen 2.3 + * + * @remarks The draggable directions are defined in the EDC file, inside the @c draggable + * section, by the attributes @c x and @c y. See the @ref edcref for more + * information. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * + * @return #EDJE_DRAG_DIR_NONE: Not draggable\n + * #EDJE_DRAG_DIR_X: Draggable in the X direction\n + * #EDJE_DRAG_DIR_Y: Draggable in the Y direction\n + * #EDJE_DRAG_DIR_XY: Draggable in the X & Y directions + */ +EAPI Edje_Drag_Dir edje_object_part_drag_dir_get (const Evas_Object *obj, const char *part); + +/** + * @brief Sets the draggable object location. + * + * @details It places the draggable object at the given location. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1, + * representing its relative position on the draggable area on that axis. + * + * This value means, for the vertical axis, @c 0.0 is at the top if the + * first parameter of @c y in the draggable part theme is @c 1, and it is at the bottom if it + * is @c -1. + * + * For the horizontal axis, @c 0.0 means left if the first parameter of @c x in the + * draggable part theme is @c 1, and it means right if it is @c -1. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dx The x value + * @param[in] dy The y value + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_value_get() + */ +EAPI Eina_Bool edje_object_part_drag_value_set (Evas_Object *obj, const char *part, double dx, double dy); + +/** + * @brief Gets the draggable object location. + * + * @details This gets the drag location values. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1, + * representing its relative position on the draggable area on that axis. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] dx The X value pointer + * @param[out] dy The Y value pointer + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_value_set() + */ +EAPI Eina_Bool edje_object_part_drag_value_get (const Evas_Object *obj, const char *part, double *dx, double *dy); + +/** + * @brief Sets the draggable object size. + * + * @details This sets the size of the draggable object. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dw and @a dh are real numbers that range from @c 0 to @c 1, + * representing the relative size of the draggable area on that axis. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dw The drag width + * @param[in] dh The drag height + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_size_get() + */ +EAPI Eina_Bool edje_object_part_drag_size_set (Evas_Object *obj, const char *part, double dw, double dh); + +/** + * @brief Gets the draggable object size. + * + * @details This gets the draggable object size + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] dw The drag width pointer + * @param[out] dh The drag height pointer + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_size_set() + */ +EAPI Eina_Bool edje_object_part_drag_size_get (const Evas_Object *obj, const char *part, double *dw, double *dh); + +/** + * @brief Sets the drag step increment. + * + * @details This sets the x,y step increments for a draggable object. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1, + * representing the relative size of the draggable area on that axis by which the + * part is moved. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dx The x step amount + * @param[in] dy The y step amount + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_step_get() + */ +EAPI Eina_Bool edje_object_part_drag_step_set (Evas_Object *obj, const char *part, double dx, double dy); + +/** + * @brief Gets the drag step increment values. + * + * @details This gets the x and y step increments for the draggable object. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part + * @param[out] dx The x step increment pointer + * @param[out] dy The y step increment pointer + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_step_set() + */ +EAPI Eina_Bool edje_object_part_drag_step_get (const Evas_Object *obj, const char *part, double *dx, double *dy); + +/** + * @brief Sets the page step increments. + * + * @details This sets the x,y page step increment values. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1, + * representing the relative size of the draggable area on that axis by which the + * part is moved. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dx The x page step increment + * @param[in] dy The y page step increment + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_page_get() + */ +EAPI Eina_Bool edje_object_part_drag_page_set (Evas_Object *obj, const char *part, double dx, double dy); + +/** + * @brief Gets the page step increments. + * + * @details This sets the x,y page step increments for the draggable object. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] dx The dx page increment pointer + * @param[out] dy The dy page increment pointer + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_page_set() + */ +EAPI Eina_Bool edje_object_part_drag_page_get (const Evas_Object *obj, const char *part, double *dx, double *dy); + +/** + * @brief Steps the draggable x,y steps. + * + * @details This steps x,y, where the step increment is the amount set by + * edje_object_part_drag_step_set. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dx The x step + * @param[in] dy The y step + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_page() + */ +EAPI Eina_Bool edje_object_part_drag_step (Evas_Object *obj, const char *part, double dx, double dy); + +/** + * @brief Pages the draggable x,y steps. + * + * @details This pages x,y, where the increment is defined by + * edje_object_part_drag_page_set. + * + * @since_tizen 2.3 + * + * @remarks The values for @a dx and @a dy are real numbers that range from @c 0 to @c 1. + * + * @remarks Paging contains bugs. + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] dx The x step + * @param[in] dy The y step + * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE + * + * @see edje_object_part_drag_step() + */ +EAPI Eina_Bool edje_object_part_drag_page (Evas_Object *obj, const char *part, double dx, double dy); + +/** + * @} + */ + +/** + * @defgroup Edje_Part_Box Edje Box Part + * @ingroup Edje_Object_Part + * + * @brief This group discusses functions that deal with parts of type box. + * + * @remarks A box is a container type for parts, that means it can contain + * other parts. + * + * @{ + */ + +/** + * @brief Registers a custom layout to be used in edje boxes. + * + * @details This function registers custom layouts that can be referred from + * themes by the registered name. The Evas_Object_Box_Layout + * functions receive two pointers for internal use, one being private + * data, and the other being the function to free that data when it's not + * longer needed. From Edje, this private data is retrieved by + * calling layout_data_get, and layout_data_free is the free + * function passed to @c func. layout_data_get is called with @a data + * as its parameter, and this one is freed by free_data whenever + * the layout is unregistered from Edje. + * + * @since_tizen 2.3 + * + * @param[in] name The name of the layout + * @param[in] func The function defining the layout + * @param[in] layout_data_get This function gets the custom data pointer + * for @a func + * @param[in] layout_data_free Passed to @a func to free its private data + * when needed + * @param[in] free_data Frees data + * @param[in] data A private pointer passed to layout_data_get + */ +EAPI void edje_box_layout_register (const char *name, Evas_Object_Box_Layout func, void *(*layout_data_get)(void *), void (*layout_data_free)(void *), void (*free_data)(void *), void *data); + +/** + * @brief Appends an object to the box. + * + * @details This appends a child to the box indicated by the part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child The object to append + * + * @return #EINA_TRUE if it is successfully added, \n + * otherwise #EINA_FALSE if an error occurs + * + * @see edje_object_part_box_prepend() + * @see edje_object_part_box_insert_before() + * @see edje_object_part_box_insert_at() + */ +EAPI Eina_Bool edje_object_part_box_append (Evas_Object *obj, const char *part, Evas_Object *child); + +/** + * @brief Prepends an object to the box. + * + * @details This prepends a child to the box indicated by the part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child The object to prepend + * + * @return #EINA_TRUE if it is successfully added, \n + * otherwise #EINA_FALSE if an error occurs + * + * @see edje_object_part_box_append() + * @see edje_object_part_box_insert_before() + * @see edje_object_part_box_insert_at() + */ +EAPI Eina_Bool edje_object_part_box_prepend (Evas_Object *obj, const char *part, Evas_Object *child); + +/** + * @brief Adds an object to the box. + * + * @details This inserts a child in the box given by the part, in the position marked by + * the reference. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child The object to insert + * @param[in] reference The object to be used as a reference + * + * @return #EINA_TRUE if it is successfully added, \n + * otherwise #EINA_FALSE if an error occurs + * + * @see edje_object_part_box_append() + * @see edje_object_part_box_prepend() + * @see edje_object_part_box_insert_at() + */ +EAPI Eina_Bool edje_object_part_box_insert_before (Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference); + +/** + * @brief Inserts an object to the box. + * + * @details This adds a child to the box indicated by the part, in the position given by + * @a pos. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child The object to insert + * @param[in] pos The position at which to insert the child + * + * @return #EINA_TRUE if it is successfully added, \n + * otherwise #EINA_FALSE if an error occurs + * + * @see edje_object_part_box_append() + * @see edje_object_part_box_prepend() + * @see edje_object_part_box_insert_before() + */ +EAPI Eina_Bool edje_object_part_box_insert_at (Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos); + +/** + * @brief Removes an object from the box. + * + * @details This removes a child from the box indicated by the part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child The object to remove + * + * @return A pointer to the removed object, otherwise @c NULL + * + * @see edje_object_part_box_remove_at() + * @see edje_object_part_box_remove_all() + */ +EAPI Evas_Object *edje_object_part_box_remove (Evas_Object *obj, const char *part, Evas_Object *child); + +/** + * @brief Removes an object from the box. + * + * @details This removes a child from the box indicated by the part, in the position given by + * @a pos. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] pos The position index of the object (starts counting from 0) + * + * @return A pointer to the object that is removed, otherwise @c NULL + * + * @see edje_object_part_box_remove() + * @see edje_object_part_box_remove_all() + */ +EAPI Evas_Object *edje_object_part_box_remove_at (Evas_Object *obj, const char *part, unsigned int pos); + +/** + * @brief Removes all elements from the box. + * + * @details This removes all the external objects from the box indicated by the part. + * The elements created from the theme are not removed. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] clear Deletes objects on removal + * + * @return @c 1 if it is successfully cleared \n + * otherwise, @c 0 if an error occurs + * + * @see edje_object_part_box_remove() + * @see edje_object_part_box_remove_at() + */ +EAPI Eina_Bool edje_object_part_box_remove_all (Evas_Object *obj, const char *part, Eina_Bool clear); + +/** + * @} + */ + +/** + * @defgroup Edje_Part_Table Edje Table Part + * @ingroup Edje_Object_Part + * + * @brief This group discusses functions that deal with parts of type table. + * + * @remarks Table is a container type for parts, that means it can contain + * other parts. + * + * @{ + */ + +typedef enum _Edje_Object_Table_Homogeneous_Mode +{ + EDJE_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, + EDJE_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, + EDJE_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 +} Edje_Object_Table_Homogeneous_Mode; + +/** + * @brief Gets a child from a table. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] col The column of the child to get + * @param[in] row The row of the child to get + * @return The child Evas_Object + */ +EAPI Evas_Object *edje_object_part_table_child_get (const Evas_Object *obj, const char *part, unsigned int col, unsigned int row); + +/** + * @brief Packs an object into the table. + * + * @details This packs an object into the table indicated by the part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child_obj The object to pack in + * @param[in] col The column to place it in + * @param[in] row The row to place it in + * @param[in] colspan The columns the child takes + * @param[in] rowspan The rows the child takes + * + * @return #EINA_TRUE if the object is added, otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool edje_object_part_table_pack (Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan); + +/** + * @brief Removes an object from the table. + * + * @details This removes an object from the table indicated by the part. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] child_obj The object to pack in + * + * @return #EINA_TRUE if the object is removed, otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool edje_object_part_table_unpack (Evas_Object *obj, const char *part, Evas_Object *child_obj); + +/** + * @brief Gets the number of columns and rows that the table has. + * + * @details This gets the size of the table in the form of number of columns and rows. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[out] cols A pointer to store the number of columns (can be @c NULL) + * @param[out] rows A pointer to store the number of rows (can be @c NULL) + * + * @return #EINA_TRUE to get some data, otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool edje_object_part_table_col_row_size_get (const Evas_Object *obj, const char *part, int *cols, int *rows); + +/** + * @brief Removes all the objects from the table. + * + * @details This removes all the objects from the table indicated by the part, except the + * internal ones set from the theme. + * + * @since_tizen 2.3 + * + * @param[in] obj A valid Evas_Object handle + * @param[in] part The part name + * @param[in] clear If set, it deletes subobjs on removal + * + * @return #EINA_TRUE to clear the table, otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool edje_object_part_table_clear (Evas_Object *obj, const char *part, Eina_Bool clear); + +/** + * @} + */ + +/** + * @defgroup Edje_Object_Communication_Interface_Message Edje Communication Interface: Message + * @ingroup Edje_Object_Group + * + * @brief This group discusses functions that deal with messages. + * + * @remarks Edje has two communication interfaces between @b code and @b theme, + * signals and messages. + * + * @remarks Edje messages are one of the communication interfaces between + * @b code and a given edje object's @b theme. With messages, one can + * communicate values like strings, float numbers, and integer + * numbers. Moreover, messages can be identified by integer + * numbers. See #Edje_Message_Type for the full list of message types. + * + * @remarks Messages must be handled by scripts. + * + * @{ + */ + +/** + * @brief Enumeration of identifiers of edje message types, which can be sent back and forth + * through code and a given edje object's theme file/group. + * + * @see edje_object_message_send() + * @see edje_object_message_handler_set() + */ +typedef enum _Edje_Message_Type +{ + EDJE_MESSAGE_NONE = 0, + + EDJE_MESSAGE_SIGNAL = 1, /* DONT USE THIS */ + + EDJE_MESSAGE_STRING = 2, /**< A message with a string as a value. Use #Edje_Message_String structs as the message body, for this type */ + EDJE_MESSAGE_INT = 3, /**< A message with an integer number as a value. Use #Edje_Message_Int structs as the message body, for this type */ + EDJE_MESSAGE_FLOAT = 4, /**< A message with a floating pointer number as a value. Use #Edje_Message_Float structs as the message body, for this type */ + + EDJE_MESSAGE_STRING_SET = 5, /**< A message with a list of strings as values. Use #Edje_Message_String_Set structs as the message body, for this type */ + EDJE_MESSAGE_INT_SET = 6, /**< A message with a list of integer numbers as values. Use #Edje_Message_Int_Set structs as the message body, for this type */ + EDJE_MESSAGE_FLOAT_SET = 7, /**< A message with a list of floating point numbers as values. Use #Edje_Message_Float_Set structs as the message body, for this type */ + + EDJE_MESSAGE_STRING_INT = 8, /**< A message with a struct containing a string and an integer number as values. Use #Edje_Message_String_Int structs as the message body, for this type */ + EDJE_MESSAGE_STRING_FLOAT = 9, /**< A message with a struct containing a string and a floating point number as values. Use #Edje_Message_String_Float structs as the message body, for this type */ + + EDJE_MESSAGE_STRING_INT_SET = 10, /**< A message with a struct containing a string and a list of integer numbers as values. Use #Edje_Message_String_Int_Set structs as the message body, for this type */ + EDJE_MESSAGE_STRING_FLOAT_SET = 11 /**< A message with a struct containing a string and a list of floating point numbers as values. Use #Edje_Message_String_Float_Set structs as the message body, for this type */ +} Edje_Message_Type; + +/** + * @brief typedef of struct _Edje_Message_String + */ +typedef struct _Edje_Message_String Edje_Message_String; + +/** + * @brief typedef of struct _Edje_Message_Int + */ +typedef struct _Edje_Message_Int Edje_Message_Int; + +/** + * @brief typedef of struct _Edje_Message_Float + */ +typedef struct _Edje_Message_Float Edje_Message_Float; + +/** + * @brief typedef of struct _Edje_Message_String_Set + */ +typedef struct _Edje_Message_String_Set Edje_Message_String_Set; + +/** + * @brief typedef of struct _Edje_Message_Int_Set + */ +typedef struct _Edje_Message_Int_Set Edje_Message_Int_Set; + +/** + * @brief typedef of struct _Edje_Message_Float_Set + */ +typedef struct _Edje_Message_Float_Set Edje_Message_Float_Set; + +/** + * @brief typedef of struct _Edje_Message_String_Int_Set + */ +typedef struct _Edje_Message_String_Int Edje_Message_String_Int; + +/** + * @brief typedef of struct _Edje_Message_String_Int_Set + */ +typedef struct _Edje_Message_String_Float Edje_Message_String_Float; + +/** + * @brief typedef of struct _Edje_Message_String_Int_Set + */ +typedef struct _Edje_Message_String_Int_Set Edje_Message_String_Int_Set; + +/** + * @brief typedef of struct _Edje_Message_String_Float_Set + */ +typedef struct _Edje_Message_String_Float_Set Edje_Message_String_Float_Set; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING messages. + * The string in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_String +{ + char *str; /**< The message's string pointer */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_INT messages. + */ +struct _Edje_Message_Int +{ + int val; /**< The message's value */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_FLOAT messages + */ +struct _Edje_Message_Float +{ + double val; /**< The message's value */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING_SET messages. + * The array in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_String_Set +{ + int count; /**< The size of the message's array (may be greater than 1) */ + char *str[1]; /**< The message's @b array of string pointers */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_INT_SET messages. + * The array in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_Int_Set +{ + int count; /**< The size of the message's array (may be greater than 1) */ + int val[1]; /**< The message's @b array of integers */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_FLOAT_SET messages. + * The array in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_Float_Set +{ + int count; /**< The size of the message's array (may be greater than 1) */ + double val[1]; /**< The message's @b array of floats */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING_INT messages. + * The string in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_String_Int +{ + char *str; /**< The message's string value */ + int val; /**< The message's integer value */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING_FLOAT messages. + * The string in it is automatically freed by Edje if passed by Edje + */ +struct _Edje_Message_String_Float +{ + char *str; /**< The message's string value */ + double val; /**< The message's float value */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING_INT_SET messages. + * The array and string in it are automatically freed by Edje if passed + * by Edje + */ +struct _Edje_Message_String_Int_Set +{ + char *str; /**< The message's string value */ + int count; /**< The size of the message's array (may be greater than 1) */ + int val[1]; /**< The message's @b array of integers */ +}; + +/** + * @brief Structure passed as a value for #EDJE_MESSAGE_STRING_FLOAT_SET + * messages. The array and string in it are automatically freed by + * Edje if passed by Edje + */ +struct _Edje_Message_String_Float_Set +{ + char *str; /**< The message's string value */ + int count; /**< The size of the message's array (may be greater than 1) */ + double val[1]; /**< The message's @b array of floats */ +}; + +typedef void (*Edje_Message_Handler_Cb) (void *data, Evas_Object *obj, Edje_Message_Type type, int id, void *msg); /**< Edje message handler callback functions' prototype definition. @c data has an auxiliary data pointer set at the time of the callback registration. @c obj is a pointer to the Edje object from where the message comes. @c type identifies the type of the given message and @c msg is a pointer to the message's contents, de facto, which depend on @c type */ + +/** + * @brief Sends an (edje) message to a given edje object. + * + * @details This function sends an edje message to @a obj and to all of its + * child objects, if it has any (swallowed objects are a kind of + * child object). @a type and @a msg @b must be matched accordingly, + * as documented in #Edje_Message_Type. + * + * @since_tizen 2.3 + * + * @remarks The @a id argument is a form of code and theme defining a common + * interface on message communication. One should define the same IDs + * on both the code and the EDC declaration (see @ref edcref "the syntax" for + * EDC files), to individualize messages (binding them to a given + * context). + * + * @remarks The function to handle messages arriving @b from @a obj is set with + * edje_object_message_handler_set(). + * + * @param[in] obj A handle to an edje object + * @param[in] type The type of message to send to @a obj + * @param[in] id An identification number for the message to be sent + * @param[in] msg The message's body, a struct depending on @a type + * + */ +EAPI void edje_object_message_send (Evas_Object *obj, Edje_Message_Type type, int id, void *msg); + +/** + * @brief Sets an edje message handler function for a given edje object. + * + * @since_tizen 2.3 + * + * @remarks For scriptable programs on an edje object's defining EDC file, which + * send messages with the @c send_message() primitive, one can attach + * <b>handler functions</b>, to be called in the code which creates + * that object (see @ref edcref "the syntax" for EDC files). + * + * @remarks This function associates a message handler function and the + * attached data pointer to the object @a obj. + * + * @param[in] obj A handle to an edje object + * @param[in] func The function to handle messages @b coming from @a obj + * @param[in] data The auxiliary data to be passed to @a func + * + * @see edje_object_message_send() + */ +EAPI void edje_object_message_handler_set (Evas_Object *obj, Edje_Message_Handler_Cb func, void *data); + +/** + * @brief Processes an object's message queue. + * + * @details This function goes through the object message queue and processes the + * pending messages for @b this specific edje object. Normally they + * are processed only at idle time. + * + * @since_tizen 2.3 + * + * @param[in] obj A handle to an edje object + * + * + */ +EAPI void edje_object_message_signal_process (Evas_Object *obj); + + +/** + * @brief Processes all queued up edje messages. + * + * @details This function triggers the processing of messages addressed to any + * (alive) edje objects. + * + * @since_tizen 2.3 + * + */ +EAPI void edje_message_signal_process (void); + +/** + * @} + */ + +/** + * @defgroup Edje_Perspective Edje Perspective + * @ingroup Edje_Group + * + * @brief This group discusses functions that deal with 3D projection of a 2D object. + * + * @remarks Perspective is a graphical tool that makes objects represented in the 2D format + * look like they have a 3D appearance. + * + * Edje allows us to use perspective on any edje object. This group of + * functions deals with the use of perspective, by creating and configuring + * a perspective object that must be set to an edje object or a canvas, + * affecting all the objects inside that has no particular perspective + * set already. + * + * @{ + */ + +/** + * @brief perspective info for maps inside edje objects + */ +typedef struct _Edje_Perspective Edje_Perspective; + +/** + * @brief Creates a new perspective in the given canvas. + * + * @details This function creates a perspective object that can be set on an edje + * object, or can be set globally to all edje objects on this canvas. + * + * @param[in] e The given canvas (Evas) + * @return An @ref Edje_Perspective object for this canvas, otherwise @c NULL on errors + * + * + * @see edje_perspective_set() + * @see edje_perspective_free() + */ +EAPI Edje_Perspective *edje_perspective_new (Evas *e); + +/** + * @brief Deletes the given perspective object. + * + * @details This function deletes the perspective object. If the perspective + * effect is being applied to any edje object or part, this effect won't be + * applied anymore. + * + * @since_tizen 2.3 + * + * @param[in] ps A valid perspective object, otherwise @c NULL + * + * + * @see edje_perspective_new() + */ +EAPI void edje_perspective_free (Edje_Perspective *ps); + +/** + * @brief Setsup the transform for this perspective object. + * + * @details This sets the parameters of the perspective transformation. 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 like when artists draw + * 3D by hand). The @a z0 value specifies the z value at which there is a 1:1 + * mapping between spatial coordinates and screen coordinates. Any points + * on this z value do not have their X and Y values modified in the transform. + * Those further away (Z value higher) shrink into the distance, and + * those less than this value expand and become bigger. The @a foc value + * determines the "focal length" of the camera. This is in reality the distance + * between the camera lens plane itself (at or closer than this, rendering + * results are undefined) and the "z0" z value. This allows for some "depth" + * control and @a foc must be greater than 0. + * + * @since_tizen 2.3 + * + * @param[in] ps The perspective object + * @param[in] px The X coordinate of the perspective distance + * @param[in] py The Y coordinate of the perspective distance + * @param[in] z0 The "0" z plane value + * @param[in] foc The focal distance + */ + +EAPI void edje_perspective_set (Edje_Perspective *ps, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc); + +/** + * @brief Sets this perspective object to be global for its canvas. + * + * @since_tizen 2.3 + * + * @remarks The canvas for which this perspective object is being set as global is the one + * given as an argument upon object creation (the @a evas parameter of the + * function @c edje_perspective_new(evas) ). + * + * There can only be one global perspective object set per canvas, and if + * a perspective object is set to global when there is already another + * global perspective set, the old one is set as non-global. + * + * A global perspective just affects a part, if its edje object doesn't have a + * perspective object set to it and if the part doesn't point to another + * part to be used as a perspective. + * + * @param[in] ps The given perspective object + * @param[in] global If #EINA_TRUE the perspective should be global, + * otherwise #EINA_FALSE + * + * @see edje_object_perspective_set() + * @see edje_perspective_global_get() + * @see edje_perspective_new() + */ +EAPI void edje_perspective_global_set (Edje_Perspective *ps, Eina_Bool global); + +/** + * @brief Gets whether the given perspective object is global. + * + * @since_tizen 2.3 + * + * @param[in] ps The given perspective object + * @return #EINA_TRUE if this perspective object is global, + * otherwise #EINA_FALSE + * + * @see edje_perspective_global_set() + */ +EAPI Eina_Bool edje_perspective_global_get (const Edje_Perspective *ps); + +/** + * @brief Gets the global perspective object set for this canvas. + * + * @details This function returns the perspective object that is set as global + * with edje_perspective_global_set(). + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas (Evas) + * @return The perspective object set as global for this canvas, otherwise @c NULL + * if there is no global perspective set and on errors + * + * @see edje_perspective_global_set() + * @see edje_perspective_global_get() + */ +EAPI const Edje_Perspective *edje_evas_global_perspective_get(const Evas *e); + +/** + * @brief Sets the given perspective object on this edje object. + * + * @details This makes the given perspective object the default perspective for this edje + * object. + * + * There can only be one perspective object per edje object, and if a + * previous one is set, it is removed and the new perspective object + * is used. + * + * An Edje perspective only affects a part if it doesn't point to another + * part to be used as a perspective. + * + * @since_tizen 2.3 + * + * @param[in] obj The edje object on the perspective that is set + * @param[in] ps The perspective object that is used + * + * @see edje_object_perspective_new() + * @see edje_object_perspective_get() + * @see edje_perspective_set() + */ +EAPI void edje_object_perspective_set (Evas_Object *obj, Edje_Perspective *ps); + +/** + * @brief Gets the current perspective used on this edje object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given edje object + * @return The perspective object being used on this edje object, otherwise @c NULL + * if there is no object set and on errors + * + * @see edje_object_perspective_set() + */ +EAPI const Edje_Perspective *edje_object_perspective_get (const Evas_Object *obj); + +/** + * @internal + * @brief These APIs are for communicating with edje_entry for not moving + * cursor position meanwhile. + * + * @remarks Tizen only feature (2013.01.29) + * + * @remarks Applications NEVER USE THESE APIs for private purporse. + * + * @see edje_object_part_text_thaw() + */ +EAPI void edje_object_part_text_freeze (Evas_Object *obj, const char *part); + +/** + * @internal + * @brief These APIs are for communicating with edje_entry for not moving + * cursor position meanwhile. + * + * @remarks Tizen only feature (2013.01.29) + * + * @remarks Applications NEVER USE THESE APIs for private purporse. + * + * @see edje_object_part_text_freeze() + */ +EAPI void edje_object_part_text_thaw (Evas_Object *obj, const char *part); + +/** + * @internal + * @brief For cursor movement when mouse up. + * + * @remarks Tizen only feature (2013.08.30) + * + * @remarks Applications NEVER USE THESE APIs for private purporse. + * + * @see edje_object_part_text_freeze() + */ +EAPI void edje_object_part_text_select_disabled_set(const Evas_Object *obj, const char *part, Eina_Bool disabled); + +/** + * @} + */ #ifdef __cplusplus } diff --git a/src/lib/edje/Edje_Edit.h b/src/lib/edje/Edje_Edit.h index 01dd3665d6..057d2f3d4f 100644 --- a/src/lib/edje/Edje_Edit.h +++ b/src/lib/edje/Edje_Edit.h @@ -33,121 +33,29 @@ # endif #endif -/** - * Compression type for the image. - * - * @ref edcref - */ + typedef enum _Edje_Edit_Image_Comp { EDJE_EDIT_IMAGE_COMP_RAW, EDJE_EDIT_IMAGE_COMP_USER, EDJE_EDIT_IMAGE_COMP_COMP, - EDJE_EDIT_IMAGE_COMP_LOSSY, - EDJE_EDIT_IMAGE_COMP_LOSSY_ETC1, - EDJE_EDIT_IMAGE_COMP_LOSSY_ETC2 + EDJE_EDIT_IMAGE_COMP_LOSSY } Edje_Edit_Image_Comp; -/** - * Mode for a textblock part. - * - * @ref edcref - */ -typedef enum _Edje_Edit_Select_Mode -{ - EDJE_EDIT_SELECT_MODE_DEFAULT, - EDJE_EDIT_SELECT_MODE_EXPLICIT -} Edje_Edit_Select_Mode; - -/** - * Sound type compression. - * - * @ref edcref - */ -typedef enum _Edje_Edit_Sound_Comp -{ - EDJE_EDIT_SOUND_COMP_NONE, - EDJE_EDIT_SOUND_COMP_RAW, - EDJE_EDIT_SOUND_COMP_COMP, - EDJE_EDIT_SOUND_COMP_LOSSY, - EDJE_EDIT_SOUND_COMP_AS_IS -} Edje_Edit_Sound_Comp; - -/** - * Mode for a textblock part. - * - * @ref edcref - */ -typedef enum _Edje_Edit_Entry_Mode -{ - EDJE_EDIT_ENTRY_MODE_NONE, - EDJE_EDIT_ENTRY_MODE_PLAIN, - EDJE_EDIT_ENTRY_MODE_EDITABLE, - EDJE_EDIT_ENTRY_MODE_PASSWORD -} Edje_Edit_Entry_Mode; - -/** - * @typedef Edje_Edit_Script_Error - * - * This is structure used for the list of errors that resulted from the last - * attempt to rebuild the Embryo script for the edited group. - * - * @see edje_edit_script_error_list_get() - */ struct _Edje_Edit_Script_Error { - const char *program_name; /**< name of the script, if null then it is group shared script */ - int line; /**< Line of the error inside in scriptcode */ - const char *error_str; /**< Error Message */ + const char *program_name; /* null == group shared script */ + int line; + const char *error_str; }; typedef struct _Edje_Edit_Script_Error Edje_Edit_Script_Error; /** - * @typedef Edje_Part_Image_Use - * - * This is structure used for the list of group-part-state triplets where certain - * image is being used and pointed. - * - * @see edje_edit_image_usage_list_get() - * @see edje_edit_image_usage_list_free() - */ -struct _Edje_Part_Image_Use -{ - const char *group; /**< name of group that use image */ - const char *part; /**< name of part that use image */ - struct { - const char *name; /**< name of the state */ - double value; /**< value of the state */ - } state; /**< structure that contain state's information */ -}; -typedef struct _Edje_Part_Image_Use Edje_Part_Image_Use; - -/** - * @typedef Edje_Edit_Limit - * - * This is structure used for list with the item names inside the limits block. - * - * @see edje_edit_group_limits_vertical_list_get() - * @see edje_edit_group_limits_horizontal_list_get() - * @see edje_edit_group_limits_vertical_del() - * @see edje_edit_group_limits_horizontal_del() - * @see edje_edit_group_limits_vertical_add() - * @see edje_edit_group_limits_horizontal_add() - * @see edje_edit_limits_list_free() - */ -struct _Edje_Edit_Limit -{ - Eina_Stringshare *name; /**< name of the limit */ - int value; /**< value of the limit */ -}; -typedef struct _Edje_Edit_Limit Edje_Edit_Limit; - -/** * @file * @brief Functions to deal with edje internal object. Don't use in standard * situations. The use of any of the edje_edit_* functions can break your * theme ability, remember that the program must be separated from the interface! - * + * * This was intended ONLY for use in an actual edje editor program. Unless * you are writing one of these, do NOT use this API here. * @@ -202,7 +110,7 @@ extern "C" { * An Edje_Edit object is, for the most part, a standard Edje object. Only * difference is you can use the Edje_Edit API on them. * - * @param e Evas canvas where to add the object. + * @param[in] e Evas canvas where to add the object. * * @return An Evas_Object of type Edje_Edit, or NULL if an error occurred. */ @@ -210,20 +118,20 @@ EAPI Evas_Object * edje_edit_object_add(Evas *e); /** Free a generic Eina_List of (char *) allocated by an edje_edit_*_get() function. * - * @param lst List of strings to free. + * @param[in] lst List of strings to free. */ EAPI void edje_edit_string_list_free(Eina_List *lst); /** Free a generic string (char *) allocated by an edje_edit_*_get() function. * - * @param str String to free. + * @param[in] str String to free. */ EAPI void edje_edit_string_free(const char *str); /** Get the name of the program that compiled the edje file. * Can be 'edje_cc' or 'edje_edit' * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return Compiler stored in the Edje file */ @@ -237,9 +145,9 @@ EAPI const char * edje_edit_compiler_get(Evas_Object *obj); * @note Source for the whole file will be auto generated and will overwrite * any previously stored source. * - * @param obj Object to save back to the file it was loaded from. + * @param[in] obj Object to save back to the file it was loaded from. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. * * @todo Add a way to check what the error actually was, the way Edje Load does. */ @@ -247,57 +155,20 @@ EAPI Eina_Bool edje_edit_save(Evas_Object *obj); /** Saves every group back into the file. * - * @param obj Object to save. + * @param[in] obj Object to save. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. * * @see edje_edit_save() */ EAPI Eina_Bool edje_edit_save_all(Evas_Object *obj); -/** Save every group into new file. - * - * Use this function when you need clean eet dictionary in .edj file from - * unnecessary text entries (e.g. names of deleted groups etc.). - * - * @param obj Object to save. - * @param new_file_name Where to save object. File should not exist, otherwise - * EINA_FALSE will be returned. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_save() - */ -EAPI Eina_Bool edje_edit_clean_save_as(Evas_Object *obj, const char* new_file_name); - -/** Save the group(s) back to the file, without generation source code. - * - * This function saves changes in group(s) back into the edj file. Process of - * saving takes a bit time in compare with @see edje_edit_save() and @see edje_edit_save_all(), - * because this function DOES NOT generate source code for groups. - * - * @note With using this function all source code will be erased. And DOES NOT - * generated new code. In attempt to decompile edj file, wich was saved with - * using this functions will unpacked only resources(like fonts, images, sounds). - * If needed saving source code into file, please use @see edje_edit_save() or - * @see edje_edit_save_all(). - - * @param obj Object to save back to the file it was loaded from. - * @param current_group EINA_TRUE if needed save only group which loaded with obj, - * or EINA_FALSE for save all groups, which exists in edj file. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_without_source_save(Evas_Object *obj, Eina_Bool current_group); - /** Print on standard output many information about the internal status * of the edje object. * * This is probably only useful to debug. * - * @param obj Object being edited. + * @param[in] obj Object being edited. */ EAPI void edje_edit_print_internal_status(Evas_Object *obj); @@ -310,13 +181,24 @@ EAPI void edje_edit_print_internal_status(Evas_Object *obj); * Functions to deal with groups property (see @ref edcref). */ //@{ +/** Create a new empty group in the given edje. + * + * If a group with the same name exist none is created. + * + * @param obj Object being edited. + * @param name Name of the new group. + * + * @return EINA_TRUE if successfully added the group, EINA_FALSE if an error + * occurred or if a group with the same name exists. + */ + /** * @brief Add an edje (empty) group to an edje object's group set. * - * @param obj The pointer to edje object. - * @param name The name of the group. + * @param[in] obj The pointer to edje object. + * @param[in] name The name of the group. * - * @return @c EINA_TRUE If it could allocate memory to the part group added + * @return 1 If it could allocate memory to the part group added * or zero if not. * * This function adds, at run time, one more group, which will reside @@ -329,31 +211,23 @@ EAPI void edje_edit_print_internal_status(Evas_Object *obj); */ EAPI Eina_Bool edje_edit_group_add(Evas_Object *obj, const char *name); -/** - * @brief Copy whole group and all it's data into separate group. - * - * @param obj The pointer to edje object. - * @param group_name The name of the group. - * @param copy_name The name of the new group that is a copy. +/** Delete the specified group from the given edje. * - * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. + * You can only delete a currently unused group. + * All the parts and the programs inside the group will be deleted as well, + * but not image or font embedded in the edje. * - * This function copy, at run time, a whole group, which will reside - * in memory, to the group set found in the .edj file which @a obj was - * loaded with. This group can be manipulated by other API functions, - * like @c edje_edit_part_add(), for example. - * - * @attention This group will copy the whole group and this operation can't be undone as all references to the group will be added to the file. - * (for example all scripts will be written to the file directly) + * @param obj Object being edited. + * @param group_name Name of group to delete. * + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ -EAPI Eina_Bool edje_edit_group_copy(Evas_Object *obj, const char *group_name, const char *copy_name); /** * @brief Delete the specified group from the edje file. * - * @param obj The pointer to the edje object. - * @param group_name Group to delete. + * @param[in] obj The pointer to the edje object. + * @param[in] group_name Group to delete. * * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. * @@ -362,18 +236,15 @@ EAPI Eina_Bool edje_edit_group_copy(Evas_Object *obj, const char *group_name, co * the file. * This function may fail if the group to be deleted is currently in use. * - * @attention be carefull, if you deleting group, it will delete all it's aliases also, - * if you deleting alias, then it will delete alias only. - * */ EAPI Eina_Bool edje_edit_group_del(Evas_Object *obj, const char *group_name); /** Check if a group with the given name exist in the edje. * - * @param obj Object being edited. - * @param group Group name to check for. + * @param[in] obj Object being edited. + * @param[in] group Group name to check for. * - * @return @c EINA_TRUE if group exists, @c EINA_FALSE if not. + * @return EINA_TRUE if group exists, EINA_FALSE if not. */ EAPI Eina_Bool edje_edit_group_exist(Evas_Object *obj, const char *group); @@ -381,16 +252,17 @@ EAPI Eina_Bool edje_edit_group_exist(Evas_Object *obj, const char *group); * * You can only rename a group that is currently loaded * Note that the relative getter function don't exist as it doesn't make sense ;) - * @param obj Object being edited. - * @param new_name New name for the group. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] new_name New name for the group. + * + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_group_name_set(Evas_Object *obj, const char *new_name); /** Get the group minimum width. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return The minimum width set for the group. -1 if an error occurred. */ @@ -398,16 +270,14 @@ EAPI int edje_edit_group_min_w_get(Evas_Object *obj); /** Set the group minimum width. * - * @param obj Object being edited. - * @param w New minimum width for the group. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] w New minimum width for the group. */ -EAPI Eina_Bool edje_edit_group_min_w_set(Evas_Object *obj, int w); +EAPI void edje_edit_group_min_w_set(Evas_Object *obj, int w); /** Get the group minimum height. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return The minimum height set for the group. -1 if an error occurred. */ @@ -415,16 +285,14 @@ EAPI int edje_edit_group_min_h_get(Evas_Object *obj); /** Set the group minimum height. * - * @param obj Object being edited. - * @param h New minimum height for the group. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] h New minimum height for the group. */ -EAPI Eina_Bool edje_edit_group_min_h_set(Evas_Object *obj, int h); +EAPI void edje_edit_group_min_h_set(Evas_Object *obj, int h); /** Get the group maximum width. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return The maximum width set for the group. -1 if an error occurred. */ @@ -432,16 +300,14 @@ EAPI int edje_edit_group_max_w_get(Evas_Object *obj); /** Set the group maximum width. * - * @param obj Object being edited. - * @param w New maximum width for the group. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] w New maximum width for the group. */ -EAPI Eina_Bool edje_edit_group_max_w_set(Evas_Object *obj, int w); +EAPI void edje_edit_group_max_w_set(Evas_Object *obj, int w); /** Get the group maximum height. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return The maximum height set for the group. -1 if an error occurred. */ @@ -449,151 +315,11 @@ EAPI int edje_edit_group_max_h_get(Evas_Object *obj); /** Set the group maximum height. * - * @param obj Object being edited. - * @param h New maximum height for the group. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] h New maximum height for the group. */ -EAPI Eina_Bool edje_edit_group_max_h_set(Evas_Object *obj, int h); +EAPI void edje_edit_group_max_h_set(Evas_Object *obj, int h); -/** Get the group broadcast_signal. - * - * @param obj Object being edited. - * - * @return @c EINA_FALSE if group not accept broadcast signal, @c EINA_TRUE otherwise (Default to true since 1.1.). - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_group_broadcast_signal_get(Evas_Object *obj); - -/** Set the group broadcast signal. - * - * @param obj Object being edited. - * @param bs @c EINA_TRUE if group will accept broadcast signal, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_group_broadcast_signal_set(Evas_Object *obj, Eina_Bool bs); - -//@} - - -/** Retrieves a list with the item names inside the vertical limits block at the group level. - * - * @param obj Object being edited. - * - * @return List of strings, each being a name of vertical limit in the limits block for the group. - */ -EAPI Eina_List * edje_edit_group_limits_vertical_list_get(Evas_Object *obj); - -/** Delete given pair name-value from the vertical limits block at the group level. - * - * @param obj Object being edited. - * @param name Limit name. - * @param value Limit value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_limits_vertical_del(Evas_Object *obj, const char *name, int value); - -/** Add given pair name-value to the vertical limits block at the group level. - * - * @param obj Object being edited. - * @param name Limit name. - * @param value Limit value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_limits_vertical_add(Evas_Object *obj, const char *name, int value); - -/** Retrieves a list with the item names inside the horizontal limits block at the group level. - * - * @param obj Object being edited. - * - * @return List of strings, each being a name of horizontal limit in the limits block for the group. - */ -EAPI Eina_List * edje_edit_group_limits_horizontal_list_get(Evas_Object *obj); - -/** Delete given pair name-value from the horizontal limits block at the group level. - * - * @param obj Object being edited. - * @param name Limit name. - * @param value Limit value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_limits_horizontal_del(Evas_Object *obj, const char *name, int value); - -/** Add given pair name-value to the horizontal limits block at the group level. - * - * @param obj Object being edited. - * @param name Limit name. - * @param value Limit value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_limits_horizontal_add(Evas_Object *obj, const char *name, int value); - -/** Free an Eina_List of (Edje_Edit_List *) allocated by an edje_edit_limits_vertical_list_get() or edje_edit_limits_horizontal_list_get() functions. - * - * @param lst List to free. - */ -EAPI void edje_edit_limits_list_free(Eina_List *lst); - -/******************************************************************************/ -/************************** ALIAS API **************************************/ -/******************************************************************************/ -/** @name Alias API - * Functions to deal with aliases that just another names of the group in the edje (see @ref edcref). - */ //@{ - -/** - * Retrieves a list of aliases for this group. - * If given group name is an alias name then this function will return NULL. - * - * @attention After you done using returned list, please use edje_edit_string_list_free to free this list. - * - * @param obj Object being edited. - * @param group_name Group name or alias. - * - * @return List of strings, each being a name of alias of given group or alias name. - */ -EAPI Eina_List * edje_edit_group_aliases_get(Evas_Object *obj, const char *group_name); - -/** - * Check if this group is an alias name. - * - * @param obj Object being edited. - * @param alias_name Group name that is alias. - * - * @return @c EINA_TRUE if alias, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_alias_is(Evas_Object *obj, const char *alias_name); - -/** - * Return the main group name that is aliased by given alias name. - * - * @attention After you done using this string, please use edje_edit_string_free to free this string. - * - * @param obj Object being edited. - * @param alias_name Group name that is alias. - * - * @return name of the main group that is being aliased. - */ -EAPI const char * edje_edit_group_aliased_get(Evas_Object *obj, const char *alias_name); - -/** - * Add new alias to the given group. - * - * @attention when aliasing a group, be sure that the given group_name is no an alias. - * - * @param obj Object being edited. - * @param group_name Group name that is being aliased. - * @param alias_name Group name that is alias. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_group_alias_add(Evas_Object *obj, const char *group_name, const char *alias_name); //@} /******************************************************************************/ @@ -605,7 +331,7 @@ EAPI Eina_Bool edje_edit_group_alias_add(Evas_Object *obj, const char *group_nam /** Retrieves a list with the item names inside the data block. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being a name entry in the global data block for the file. */ @@ -616,27 +342,27 @@ EAPI Eina_List * edje_edit_data_list_get(Evas_Object *obj); * If another data entry with the same name exists, nothing is created and * EINA_FALSE is returned. * - * @param obj Object being edited. - * @param itemname Name for the new data entry. - * @param value Value for the new data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name for the new data entry. + * @param[in] value Value for the new data entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_data_add(Evas_Object *obj, const char *itemname, const char *value); /** Delete the given data object from edje. * - * @param obj Object being edited. - * @param itemname Data entry to remove from the global data block. + * @param[in] obj Object being edited. + * @param[in] itemname Data entry to remove from the global data block. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_data_del(Evas_Object *obj, const char *itemname); /** Get the data associated with the given itemname. * - * @param obj Object being edited. - * @param itemname Name of the data entry to fetch the value for. + * @param[in] obj Object being edited. + * @param[in] itemname Name of the data entry to fetch the value for. * * @return Value of the given entry, or NULL if not found. */ @@ -644,27 +370,27 @@ EAPI const char * edje_edit_data_value_get(Evas_Object *obj, const char *itemnam /** Set the data associated with the given itemname. * - * @param obj Object being edited. - * @param itemname Name of data entry to change the value. - * @param value New value for the entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name of data entry to change the value. + * @param[in] value New value for the entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_data_value_set(Evas_Object *obj, const char *itemname, const char *value); /** Change the name of the given data object. * - * @param obj Object being edited. - * @param itemname Data entry to rename. - * @param newname New name for the data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Data entry to rename. + * @param[in] newname New name for the data entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_data_name_set(Evas_Object *obj, const char *itemname, const char *newname); /** Retrieves a list with the item names inside the data block at the group level. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being a name entry in the data block for the group. */ @@ -675,27 +401,27 @@ EAPI Eina_List * edje_edit_group_data_list_get(Evas_Object *obj); * If another data entry with the same name exists, * nothing is created and EINA_FALSE is returned. * - * @param obj Object being edited. - * @param itemname Name for the new data entry. - * @param value Value for the new data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name for the new data entry. + * @param[in] value Value for the new data entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_group_data_add(Evas_Object *obj, const char *itemname, const char *value); /** Delete the given data object from the group. * - * @param obj Object being edited. - * @param itemname Name of the data entry to remove. + * @param[in] obj Object being edited. + * @param[in] itemname Name of the data entry to remove. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_group_data_del(Evas_Object *obj, const char *itemname); /** Get the data associated with the given itemname. * - * @param obj Object being edited. - * @param itemname Name of the data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name of the data entry. * * @return Value of the data entry or NULL if not found. */ @@ -703,21 +429,21 @@ EAPI const char * edje_edit_group_data_value_get(Evas_Object *obj, const char *i /** Set the data associated with the given itemname. * - * @param obj Object being edited. - * @param itemname Name of the data entry to set the value. - * @param value Value to set for the data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name of the data entry to set the value. + * @param[in] value Value to set for the data entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_group_data_value_set(Evas_Object *obj, const char *itemname, const char *value); /** Change the name of the given data object. * - * @param obj Object being edited. - * @param itemname Name of the data entry to rename. - * @param newname New name for the data entry. + * @param[in] obj Object being edited. + * @param[in] itemname Name of the data entry to rename. + * @param[in] newname New name for the data entry. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_group_data_name_set(Evas_Object *obj, const char *itemname, const char *newname); @@ -732,7 +458,7 @@ EAPI Eina_Bool edje_edit_group_data_name_set(Evas_Object *obj, const char *itemn /** Get the list of all the Color Classes in the given edje object. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being one color class. */ @@ -742,19 +468,19 @@ EAPI Eina_List * edje_edit_color_classes_list_get(Evas_Object *obj); * * If another class with the same name exists nothing is created and EINA_FALSE is returned. * - * @param obj Object being edited. - * @param name Name for the new color class. + * @param[in] obj Object being edited. + * @param[in] name Name for the new color class. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_color_class_add(Evas_Object *obj, const char *name); /** Delete the given class object from edje. * - * @param obj Object being edited. - * @param name Color class to delete. + * @param[in] obj Object being edited. + * @param[in] name Color class to delete. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_color_class_del(Evas_Object *obj, const char *name); @@ -762,22 +488,22 @@ EAPI Eina_Bool edje_edit_color_class_del(Evas_Object *obj, const char *name); * * You can pass NULL to colors you are not intrested in. * - * @param obj Object being edited. - * @param class_name Color class to fetch values. - * @param r Red component of main color. - * @param g Green component of main color. - * @param b Blue component of main color. - * @param a Alpha component of main color. - * @param r2 Red component of secondary color. - * @param g2 Green component of secondary color. - * @param b2 Blue component of secondary color. - * @param a2 Alpha component of secondary color. - * @param r3 Red component of tertiary color. - * @param g3 Green component of tertiary color. - * @param b3 Blue component of tertiary color. - * @param a3 Alpha component of tertiary color. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] class_name Color class to fetch values. + * @param[out] r Red component of main color. + * @param[out] g Green component of main color. + * @param[out] b Blue component of main color. + * @param[out] a Alpha component of main color. + * @param[out] r2 Red component of secondary color. + * @param[out] g2 Green component of secondary color. + * @param[out] b2 Blue component of secondary color. + * @param[out] a2 Alpha component of secondary color. + * @param[out] r3 Red component of tertiary color. + * @param[out] g3 Green component of tertiary color. + * @param[out] b3 Blue component of tertiary color. + * @param[out] a3 Alpha component of tertiary color. + * + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_color_class_colors_get(Evas_Object *obj, const char *class_name, int *r, int *g, int *b, int *a, int *r2, int *g2, int *b2, int *a2, int *r3, int *g3, int *b3, int *a3); @@ -785,32 +511,32 @@ EAPI Eina_Bool edje_edit_color_class_colors_get(Evas_Object *obj, const char *cl * * If you set a color to -1 it will not be touched. * - * @param obj Object being edited. - * @param class_name Color class to fetch values. - * @param r Red component of main color. - * @param g Green component of main color. - * @param b Blue component of main color. - * @param a Alpha component of main color. - * @param r2 Red component of secondary color. - * @param g2 Green component of secondary color. - * @param b2 Blue component of secondary color. - * @param a2 Alpha component of secondary color. - * @param r3 Red component of tertiary color. - * @param g3 Green component of tertiary color. - * @param b3 Blue component of tertiary color. - * @param a3 Alpha component of tertiary color. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] class_name Color class to fetch values. + * @param[in] r Red component of main color. + * @param[in] g Green component of main color. + * @param[in] b Blue component of main color. + * @param[in] a Alpha component of main color. + * @param[in] r2 Red component of secondary color. + * @param[in] g2 Green component of secondary color. + * @param[in] b2 Blue component of secondary color. + * @param[in] a2 Alpha component of secondary color. + * @param[in] r3 Red component of tertiary color. + * @param[in] g3 Green component of tertiary color. + * @param[in] b3 Blue component of tertiary color. + * @param[in] a3 Alpha component of tertiary color. + * + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_color_class_colors_set(Evas_Object *obj, const char *class_name, int r, int g, int b, int a, int r2, int g2, int b2, int a2, int r3, int g3, int b3, int a3); /** Change the name of a color class. * - * @param obj Object being edited. - * @param name Color class to rename. - * @param newname New name for the color class. + * @param[in] obj Object being edited. + * @param[in] name Color class to rename. + * @param[in] newname New name for the color class. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_color_class_name_set(Evas_Object *obj, const char *name, const char *newname); @@ -826,7 +552,7 @@ EAPI Eina_Bool edje_edit_color_class_name_set(Evas_Object *obj, const char *name /** Get the list of all the text styles in the given edje object. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being the name for a text style. */ @@ -836,26 +562,24 @@ EAPI Eina_List * edje_edit_styles_list_get(Evas_Object *obj); * * If another style with the same name exists nothing is created and EINA_FALSE is returned. * - * @param obj Object being edited. - * @param style Name for the new style. + * @param[in] obj Object being edited. + * @param[in] style Name for the new style. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_style_add(Evas_Object *obj, const char *style); /** Delete the given text style and all the child tags. * - * @param obj Object being edited. - * @param style Style to delete. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] style Style to delete. */ -EAPI Eina_Bool edje_edit_style_del(Evas_Object *obj, const char *style); +EAPI void edje_edit_style_del(Evas_Object *obj, const char *style); /** Get the list of all the tags name in the given text style. * - * @param obj Object being edited. - * @param style Style to get the tags for. + * @param[in] obj Object being edited. + * @param[in] style Style to get the tags for. * * @return List of strings, each being one tag in the given style. */ @@ -863,9 +587,9 @@ EAPI Eina_List * edje_edit_style_tags_list_get(Evas_Object *obj, const char *sty /** Get the value of the given tag. * - * @param obj Object being edited. - * @param style Style containing the tag being. - * @param tag Tag to get the value for. + * @param[in] obj Object being edited. + * @param[in] style Style containing the tag being. + * @param[in] tag Tag to get the value for. * * @return Value of the given tag. */ @@ -873,47 +597,41 @@ EAPI const char * edje_edit_style_tag_value_get(Evas_Object *obj, const char *st /** Set the value of the given tag. * - * @param obj Object being edited. - * @param style Style containing the tag to change. - * @param tag Name of the tag to set the value for. - * @param new_value Value for the tag. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] style Style containing the tag to change. + * @param[in] tag Name of the tag to set the value for. + * @param[in] new_value Value for the tag. */ -EAPI Eina_Bool edje_edit_style_tag_value_set(Evas_Object *obj, const char *style, const char *tag, const char *new_value); +EAPI void edje_edit_style_tag_value_set(Evas_Object *obj, const char *style, const char *tag, const char *new_value); /** Set the name of the given tag. * - * @param obj Object being edited. - * @param style Style containing the tag to rename. - * @param tag Tag to rename. - * @param new_name New name for the tag. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] style Style containing the tag to rename. + * @param[in] tag Tag to rename. + * @param[in] new_name New name for the tag. */ -EAPI Eina_Bool edje_edit_style_tag_name_set(Evas_Object *obj, const char *style, const char *tag, const char *new_name); +EAPI void edje_edit_style_tag_name_set(Evas_Object *obj, const char *style, const char *tag, const char *new_name); /** Add a new tag to the given text style. * * If another tag with the same name exists nothing is created and EINA_FALSE is returned. * - * @param obj Object being edited. - * @param style Style where to add the new tag. - * @param tag_name Name for the new tag. + * @param[in] obj Object being edited. + * @param[in] style Style where to add the new tag. + * @param[in] tag_name Name for the new tag. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_style_tag_add(Evas_Object *obj, const char *style, const char *tag_name); /** Delete the given tag. * - * @param obj Object being edited. - * @param style Style from where to remove the tag. - * @param tag Tag to delete. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] style Style from where to remove the tag. + * @param[in] tag Tag to delete. */ -EAPI Eina_Bool edje_edit_style_tag_del(Evas_Object *obj, const char *style, const char *tag); +EAPI void edje_edit_style_tag_del(Evas_Object *obj, const char *style, const char *tag); //@} @@ -926,7 +644,7 @@ EAPI Eina_Bool edje_edit_style_tag_del(Evas_Object *obj, const char *style, cons /** Get the list of all the externals requested in the given edje object. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being an entry in the block of automatically loaded external modules. */ @@ -934,19 +652,19 @@ EAPI Eina_List * edje_edit_externals_list_get(Evas_Object *obj); /** Add an external module to be requested on edje load. * - * @param obj Object being edited. - * @param external Name of the external module to add to the list of autoload. + * @param[in] obj Object being edited. + * @param[in] external Name of the external module to add to the list of autoload. * - * @return @c EINA_TRUE on success (or it was already there), @c EINA_FALSE otherwise. + * @return EINA_TRUE on success (or it was already there), EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_external_add(Evas_Object *obj, const char *external); /** Delete the given external from the list. * - * @param obj Object being edited. - * @param external Name of the external module to remove from the autoload list. + * @param[in] obj Object being edited. + * @param[in] external Name of the external module to remove from the autoload list. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE on success, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_external_del(Evas_Object *obj, const char *external); @@ -959,62 +677,11 @@ EAPI Eina_Bool edje_edit_external_del(Evas_Object *obj, const char *external); * Functions to deal with part objects (see @ref edcref). */ //@{ -/** Get the select mode for a textblock part - - * @param obj Object being edited. - * @param part Name of the part. - * - * @return One of possible enum Edje_Edit_Select_Mode. - * @since 1.11 - */ -EAPI Edje_Edit_Select_Mode -edje_edit_part_select_mode_get(Evas_Object *obj, const char *part); - -/** Set the select mode for a textblock part - * - * @param obj Object being edited. - * @param part Name of the part. - * @param mode One of possible enum Edje_Edit_Select_Mode: - * EDJE_EDIT_SELECT_MODE_DEFAULT, EDJE_EDIT_SELECT_MODE_EXPLICIT. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_part_select_mode_set(Evas_Object *obj, const char *part, Edje_Edit_Select_Mode mode); - -/** Get the edit mode for a textblock part - * - * @param obj Object being edited. - * @param part Name of the part. - * - * @return One of possible enum Edje_Entry_Mode. - * @since 1.11 - */ -EAPI Edje_Edit_Entry_Mode -edje_edit_part_entry_mode_get(Evas_Object *obj, const char *part); - -/** Set the edit mode for a textblock part - * - * @param obj Object being edited. - * @param part Name of the part. - * @param mode One of possible enum Edje_Entry_Mode: - * EDJE_EDIT_ENTRY_MODE_NONE, EDJE_EDIT_ENTRY_MODE_PLAIN, EDJE_EDIT_ENTRY_MODE_EDITABLE, EDJE_EDIT_ENTRY_MODE_PASSWORD. - - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_part_entry_mode_set(Evas_Object *obj, const char *part, Edje_Edit_Entry_Mode mode); - /** Get the list of all the parts in the given edje object. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return List of strings, each being the name for a part in the open group. - * The return value should be freed with edje_edit_string_list_free(). - * - * @see edje_edit_string_list_free() */ EAPI Eina_List * edje_edit_parts_list_get(Evas_Object *obj); @@ -1023,11 +690,11 @@ EAPI Eina_List * edje_edit_parts_list_get(Evas_Object *obj); * If another part with the same name just exists nothing is created and EINA_FALSE is returned. * Note that this function also create a default description for the part. * - * @param obj Object being edited. - * @param name Name for the new part. - * @param type Type of the new part. See @ref edcref for more info on this. + * @param[in] obj Object being edited. + * @param[in] name Name for the new part. + * @param[in] type Type of the new part. See @ref edcref for more info on this. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_add(Evas_Object *obj, const char *name, Edje_Part_Type type); @@ -1036,11 +703,11 @@ EAPI Eina_Bool edje_edit_part_add(Evas_Object *obj, const char *name, Edje_Part_ * If another part with the same name just exists nothing is created and EINA_FALSE is returned. * Note that this function also create a default description for the part. * - * @param obj Object being edited. - * @param name Name for the new part. - * @param source The registered external type to use for this part. + * @param[in] obj Object being edited. + * @param[in] name Name for the new part. + * @param[in] source The registered external type to use for this part. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_external_add(Evas_Object *obj, const char *name, const char *source); @@ -1048,39 +715,26 @@ EAPI Eina_Bool edje_edit_part_external_add(Evas_Object *obj, const char *name, c * * All the reference to this part will be zeroed. * - * @param obj Object being edited. - * @param part Name of part to delete. + * @param[in] obj Object being edited. + * @param[in] part Name of part to delete. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_del(Evas_Object *obj, const char *part); -/** Copy the given part in edje. - * - * If another part with the same name just exists nothing is created and EINA_FALSE is returned. - * - * @param obj Object being edited. - * @param part Name of the part. - * @param new_copy Name of the new copied part. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_copy(Evas_Object *obj, const char *part, const char *new_copy); - /** Check if a part with the given name exist in the edje object. * - * @param obj Object being edited. - * @param part Name of part to check for its existence. + * @param[in] obj Object being edited. + * @param[in] part Name of part to check for its existence. * - * @return @c EINA_TRUE if the part exists, @c EINA_FALSE if not. + * @return EINA_TRUE if the part exists, EINA_FALSE if not. */ EAPI Eina_Bool edje_edit_part_exist(Evas_Object *obj, const char *part); /** Get the name of part stacked above the one passed. * - * @param obj Object being edited. - * @param part Name of part of which to check the one above. + * @param[in] obj Object being edited. + * @param[in] part Name of part of which to check the one above. * * @return Name of the part above. NULL if an error occurred or if @p part is * the topmost part in the group. @@ -1089,8 +743,8 @@ EAPI const char * edje_edit_part_above_get(Evas_Object *obj, const char *part); /** Get the name of part stacked below the one passed. * - * @param obj Object being edited. - * @param part Name of part of which to check the one below. + * @param[in] obj Object being edited. + * @param[in] part Name of part of which to check the one below. * * @return Name of the part below. NULL if an error occurred or if @p part is * the bottommost part in the group. @@ -1099,60 +753,38 @@ EAPI const char * edje_edit_part_below_get(Evas_Object *obj, const char *part); /** Move the given part below the previous one. * - * @param obj Object being edited. - * @param part Name of part to move one step below. + * @param[in] obj Object being edited. + * @param[in] part Name of part to move one step below. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_restack_below(Evas_Object *obj, const char *part); -/** Move the given part below the part named below. - * - * @param obj Object being edited. - * @param part Name of part which will be moved. - * @param below Name of part for which will be moved 'part'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_part_restack_part_below(Evas_Object *obj, const char* part, const char *below); - /** Move the given part above the next one. * - * @param obj Object being edited. - * @param part Name of part to move one step above. + * @param[in] obj Object being edited. + * @param[in] part Name of part to move one step above. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_restack_above(Evas_Object *obj, const char *part); -/** Move the given part above the part named above. - * - * @param obj Object being edited. - * @param part Name of part which will be moved. - * @param above Name of part for which will be moved 'part'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_part_restack_part_above(Evas_Object *obj, const char* part, const char *above); - /** Set a new name for part. * * Note that the relative getter function don't exist as it don't make sense ;) * - * @param obj Object being edited. - * @param part Name of part to rename. - * @param new_name New name for the given part. + * @param[in] obj Object being edited. + * @param[in] part Name of part to rename. + * @param[in] new_name New name for the given part. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_name_set(Evas_Object *obj, const char *part, const char *new_name); /** Get api's name of a part. * - * @param obj Object being edited. - * @param part Name of the part. + * @param[in] obj Object being edited. + * @param[in] part Name of the part. * * @return name of the api if successful, NULL otherwise. */ @@ -1160,8 +792,8 @@ EAPI const char * edje_edit_part_api_name_get(Evas_Object *obj, const char *part /** Get api's description of a part. * - * @param obj Object being edited. - * @param part Name of the part. + * @param[in] obj Object being edited. + * @param[in] part Name of the part. * * @return description of the api if successful, NULL otherwise. */ @@ -1169,28 +801,28 @@ EAPI const char * edje_edit_part_api_description_get(Evas_Object *obj, const cha /** Set api's name of a part. * - * @param obj Object being edited. - * @param part Name of the part. - * @param name New name for the api property. + * @param[in] obj Object being edited. + * @param[in] part Name of the part. + * @param[in] name New name for the api property. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_api_name_set(Evas_Object *obj, const char *part, const char *name); /** Set api's description of a part. * - * @param obj Object being edited. - * @param part Name of part. - * @param description New description for the api property. + * @param[in] obj Object being edited. + * @param[in] part Name of part. + * @param[in] description New description for the api property. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_api_description_set(Evas_Object *obj, const char *part, const char *description); /** Get the type of a part. * - * @param obj Object being edited. - * @param part Name of part to get the type of. + * @param[in] obj Object being edited. + * @param[in] part Name of part to get the type of. * * @return Type of the part. See @ref edcref for details. */ @@ -1198,8 +830,8 @@ EAPI Edje_Part_Type edje_edit_part_type_get(Evas_Object *obj, const char *part); /** Get the clip_to part. * - * @param obj Object being edited. - * @param part Name of the part whose clipper to get. + * @param[in] obj Object being edited. + * @param[in] part Name of the part whose clipper to get. * * @return Name of the part @p part is clipped to. NULL is returned on errors and if the part don't have a clip. */ @@ -1207,11 +839,11 @@ EAPI const char * edje_edit_part_clip_to_get(Evas_Object *obj, const char *part) /** Set a part to clip part to. * - * @param obj Object being edited. - * @param part Part to set the clipper to. - * @param clip_to Part to use as clipper, if NULL then the clipping value will be cancelled (unset clipping). + * @param[in] obj Object being edited. + * @param[in] part Part to set the clipper to. + * @param[in] clip_to Part to use as clipper, if NULL then the clipping value will be cancelled (unset clipping). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_clip_to_set(Evas_Object *obj, const char *part, const char *clip_to); @@ -1225,8 +857,8 @@ EAPI Eina_Bool edje_edit_part_clip_to_set(Evas_Object *obj, const char *part, co * For EXTERNAL parts, it's the name of the registered external widget to load * and swallow on this part. * - * @param obj Object being edited. - * @param part Part to get the source from. + * @param[in] obj Object being edited. + * @param[in] part Part to get the source from. * * @return Content of the source parameter or NULL if nothing set or an error occurred. */ @@ -1234,11 +866,11 @@ EAPI const char * edje_edit_part_source_get(Evas_Object *obj, const char *part); /** Set the source of part. * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. + * @param[in] obj Object being edited. + * @param[in] part Part to set the source of. + * @param[in] source Value for the source parameter. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. * * @see edje_edit_part_source_get() * @@ -1249,176 +881,30 @@ EAPI const char * edje_edit_part_source_get(Evas_Object *obj, const char *part); */ EAPI Eina_Bool edje_edit_part_source_set(Evas_Object *obj, const char *part, const char *source); -/** Get the source2 of part. - * - * Only available to TEXTBLOCK parts. It is used for the group to be loaded and - * used for selection display OVER the selected text. source is used for under - * of the selected text, if source is specified. - * - * @param obj Object being edited. - * @param part Part to get the source from. - * - * @return Content of the source2 parameter or NULL if nothing set or an error occurred. - * @since 1.11 - */ -EAPI const char * edje_edit_part_source2_get(Evas_Object *obj, const char *part); - -/** Set the source2 of part. - * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_part_source2_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_source2_set(Evas_Object *obj, const char *part, const char *source); - -/** Get the source3 of part. - * - * Only available to TEXTBLOCK parts. It is used for the group to be loaded and - * used for cursor display UNDER the cursor position. source4 is used for over - * the cursor text, if source4 is specified. - * - * @param obj Object being edited. - * @param part Part to get the source from. - * - * @return Content of the source3 parameter or NULL if nothing set or an error occurred. - * @since 1.11 - */ -EAPI const char * edje_edit_part_source3_get(Evas_Object *obj, const char *part); - -/** Set the source3 of part. - * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_part_source3_get() - * @since 1.11 - * - * NOTE: This is not applied now. You must reload the edje to see the change. - */ -EAPI Eina_Bool edje_edit_part_source3_set(Evas_Object *obj, const char *part, const char *source); - -/** Get the source4 of part. - * - * Only available to TEXTBLOCK parts. It is used for the group to be loaded and - * used for cursor display OVER the cursor position. source3 is used for under - * the cursor text, if source4 is specified. - * - * @param obj Object being edited. - * @param part Part to get the source from. - * - * @return Content of the source4 parameter or NULL if nothing set or an error occurred. - * @since 1.11 - */ -EAPI const char * edje_edit_part_source4_get(Evas_Object *obj, const char *part); - -/** Set the source4 of part. - * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_part_source4_get() - * @since 1.11 - * - * NOTE: This is not applied now. You must reload the edje to see the change. - */ -EAPI Eina_Bool edje_edit_part_source4_set(Evas_Object *obj, const char *part, const char *source); - -/** Get the source5 of part. - * - * Only available to TEXTBLOCK parts. It is used for the group to be loaded and - * used for anchors display UNDER the anchor position. source6 is used for over - * the anchors text, if source6 is specified. - * - * @param obj Object being edited. - * @param part Part to get the source from. - * - * @return Content of the source5 parameter or NULL if nothing set or an error occurred. - * @since 1.11 - */ -EAPI const char * edje_edit_part_source5_get(Evas_Object *obj, const char *part); - -/** Set the source5 of part. - * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_part_source5_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_source5_set(Evas_Object *obj, const char *part, const char *source); - -/** Get the source6 of part. - * - * Only available to TEXTBLOCK parts. It is used for the group to be loaded and - * used for anchor display OVER the anchor position. source5 is used for under - * the anchor text, if source6 is specified. - * - * @param obj Object being edited. - * @param part Part to get the source from. - * - * @return Content of the source6 parameter or NULL if nothing set or an error occurred. - * @since 1.11 - */ -EAPI const char * edje_edit_part_source6_get(Evas_Object *obj, const char *part); - -/** Set the source6 of part. - * - * @param obj Object being edited. - * @param part Part to set the source of. - * @param source Value for the source parameter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see edje_edit_part_source6_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_source6_set(Evas_Object *obj, const char *part, const char *source); - /** Get the effect for a given part. * * Gets the effect used for parts of type TEXT. See @ref edcref for more details. * - * @param obj Object being edited. - * @param part Part to get the effect of. + * @param[in] obj Object being edited. + * @param[in] part Part to get the effect of. * * @return The effect set for the part. */ EAPI Edje_Text_Effect edje_edit_part_effect_get(Evas_Object *obj, const char *part); /** Set the effect for a given part. - * Effects and shadow directions can be combined. * - * For effect and shadow direction list please look at Edje Part Text ref page. - * - * @param obj Object being edited. - * @param part Part to set the effect to. Only makes sense on type TEXT. - * @param effect Effect to set for the part. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * - * @see Edje_Part_Text + * @param[in] obj Object being edited. + * @param[in] part Part to set the effect to. Only makes sense on type TEXT. + * @param[in] effect Effect to set for the part. */ -EAPI Eina_Bool edje_edit_part_effect_set(Evas_Object *obj, const char *part, Edje_Text_Effect effect); +EAPI void edje_edit_part_effect_set(Evas_Object *obj, const char *part, Edje_Text_Effect effect); /** Get the current selected state in part. * - * @param obj Object being edited. - * @param part Part to get the selected state of. - * @param value Pointer to a double where the value of the state will be stored. + * @param[in] obj Object being edited. + * @param[in] part Part to get the selected state of. + * @param[out] value Pointer to a double where the value of the state will be stored. * * @return The name of the currently selected state for the part. */ @@ -1426,120 +912,53 @@ EAPI const char * edje_edit_part_selected_state_get(Evas_Object *obj, const char /** Set the current state in part. * - * @param obj Object being edited. - * @param part Part to set the state of. - * @param state Name of the state to set. - * @param value Value of the state. + * @param[in] obj Object being edited. + * @param[in] part Part to set the state of. + * @param[in] state Name of the state to set. + * @param[in] value Value of the state. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_selected_state_set(Evas_Object *obj, const char *part, const char *state, double value); /** Get mouse_events for part. * - * @param obj Object being edited. - * @param part Part to get if the mouse events is accepted. + * @param[in] obj Object being edited. + * @param[in] part Part to get if the mouse events is accepted. * - * @return @c EINA_TRUE if part will accept mouse events, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_mouse_events_get(Evas_Object *obj, const char *part); /** Set mouse_events for part. * - * @param obj Object being edited. - * @param part The part to set if the mouse events is accepted. - * @param mouse_events EINA_TRUE if part will accept mouse events, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part The part to set if the mouse events is accepted. + * @param[in] mouse_events EINA_TRUE if part will accept mouse events, EINA_FALSE otherwise. */ -EAPI Eina_Bool edje_edit_part_mouse_events_set(Evas_Object *obj, const char *part, Eina_Bool mouse_events); +EAPI void edje_edit_part_mouse_events_set(Evas_Object *obj, const char *part, Eina_Bool mouse_events); /** Get repeat_events for part. * - * @param obj Object being edited. - * @param part Part to get if it will pass all events to the other parts. + * @param[in] obj Object being edited. + * @param[in] part Part to set if will pass all events to the other parts. * - * @return @c EINA_TRUE if the events received will propagate to other parts, @c EINA_FALSE otherwise + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_part_repeat_events_get(Evas_Object *obj, const char *part); /** Set repeat_events for part. * - * @param obj Object being edited. - * @param part Part to set if will repeat all the received mouse events to other parts. - * @param repeat_events EINA_TRUE if the events received will propagate to other parts, @c EINA_FALSE otherwise - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_part_repeat_events_set(Evas_Object *obj, const char *part, Eina_Bool repeat_events); - -/** Get multiline for part. - * - * @param obj Object being edited. - * @param part Part to get if editing multiple lines for text or textblock part is enabled. - * - * @return @c EINA_TRUE if multiple lines for editing is enabled, @c EINA_FALSE otherwise - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_multiline_get(Evas_Object *obj, const char *part); - -/** Set multiline for part. - * - * @param obj Object being edited. - * @param part Part to set if editing multiple lines for text or textblock part is enabled. - * @param multiline EINA_TRUE if multiple lines for editing is enabled, @c EINA_FALSE otherwise - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_multiline_set(Evas_Object *obj, const char *part, Eina_Bool multiline); - -/** Get precise_is_inside for part. - * - * @param obj Object being edited. - * @param part Part to get if it will enable point collision detection for the part. - * - * @return @c EINA_TRUE if point collision detection for the part is enabled, @c EINA_FALSE otherwise - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_precise_is_inside_get(Evas_Object *obj, const char *part); - -/** Set precise_is_inside for part. - * - * @param obj Object being edited. - * @param part Part to set if it will enable point collision detection for the part. - * @param precise_is_inside EINA_TRUE if point collision detection for the part is enabled, @c EINA_FALSE otherwise - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 + * @param[in] obj Object being edited. + * @param[in] part Part to set if will repeat all the received mouse events to other parts. + * @param[in] repeat_events EINA_TRUE if the events received will propagate to other parts, EINA_FALSE otherwise */ -EAPI Eina_Bool edje_edit_part_precise_is_inside_set(Evas_Object *obj, const char *part, Eina_Bool precise_is_inside); - -/** Get accessibility for part. - * - * @param obj Object being edited. - * @param part Part to get if it uses accessibility feature. - * - * @return @c EINA_TRUE if part uses accessibility feature, @c EINA_FALSE otherwise - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_access_get(Evas_Object *obj, const char *part); - -/** Set accessibility for part. - * - * @param obj Object being edited. - * @param part Part to set if it uses accessibility feature. - * @param access EINA_TRUE if part uses accessibility feature, @c EINA_FALSE otherwise - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_access_set(Evas_Object *obj, const char *part, Eina_Bool access); +EAPI void edje_edit_part_repeat_events_set(Evas_Object *obj, const char *part, Eina_Bool repeat_events); /** Get ignore_flags for part. * - * @param obj Object being edited. - * @param part Part to get which event_flags are being ignored. + * @param[in] obj Object being edited. + * @param[in] part Part to get which event_flags are being ignored. * * @return The Event flags set to the part. */ @@ -1547,90 +966,27 @@ EAPI Evas_Event_Flags edje_edit_part_ignore_flags_get(Evas_Object *obj, const ch /** Set ignore_flags for part. * - * @param obj Object being edited. - * @param part Part to set which event flags will be ignored. - * @param ignore_flags The Event flags to be ignored by the part. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_part_ignore_flags_set(Evas_Object *obj, const char *part, Evas_Event_Flags ignore_flags); - -/** Get pointer_mode of a part. - * - * @param obj Object being edited. - * @param part Part name to get it's pointer_mode. - * - * @return Ponter Mode of the part. - * @since 1.11 - */ -EAPI Evas_Object_Pointer_Mode edje_edit_part_pointer_mode_get(Evas_Object *obj, const char *part); - -/** Get pointer_mode of a part. - * - * Note that Ponter Mode can be: - * - EVAS_OBJECT_POINTER_MODE_AUTOGRAB - default, X11-like - * - EVAS_OBJECT_POINTER_MODE_NOGRAB - pointer always bound to the object right below it - * - EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN - useful on object with "repeat events" enabled, @since 1.2 - * - * @param obj Object being edited. - * @param part Part name to get it's pointer_mode. - * @param pointer_mode Pointer Mode. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_pointer_mode_set(Evas_Object *obj, const char *part, Evas_Object_Pointer_Mode pointer_mode); - -/** Get cursor_mode of a part. - * - * Note that Cursor Mode can be: - * 0 - UNDER cursor mode means the cursor will draw below the character pointed - * at. That's the default. - * 1 - BEFORE cursor mode means the cursor is drawn as a vertical line before - * the current character, just like many other GUI toolkits handle it. - * - * @param obj Object being edited. - * @param part Part name to get it's cursor_mode. - * - * @return Ponter Mode of the part. - * @since 1.11 - */ -EAPI unsigned char edje_edit_part_cursor_mode_get(Evas_Object *obj, const char *part); - -/** Get pointer_mode of a part. - * - * Note that Cursor Mode can be: - * 0 - UNDER cursor mode means the cursor will draw below the character pointed - * at. That's the default. - * 1 - BEFORE cursor mode means the cursor is drawn as a vertical line before - * the current character, just like many other GUI toolkits handle it. - * - * @param obj Object being edited. - * @param part Part name to get it's pointer_mode. - * @param cursor_mode Pointer Mode. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 + * @param[in] obj Object being edited. + * @param[in] part Part to set which event flags will be ignored. + * @param[in] ignore_flags The Event flags to be ignored by the part. */ -EAPI Eina_Bool edje_edit_part_cursor_mode_set(Evas_Object *obj, const char *part, unsigned char cursor_mode); +EAPI void edje_edit_part_ignore_flags_set(Evas_Object *obj, const char *part, Evas_Event_Flags ignore_flags); /** Set scale property for the part. * * This property tells Edje that the given part should be scaled by the * Edje scale factor. * - * @param obj Object being edited. - * @param part Part to set scale for. - * @param scale Scale value to set. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set scale for. + * @param[in] scale Scale value to set. */ -EAPI Eina_Bool edje_edit_part_scale_set(Evas_Object *obj, const char *part, Eina_Bool scale); +EAPI void edje_edit_part_scale_set(Evas_Object *obj, const char *part, Eina_Bool scale); /** Get scale for the part. * - * @param obj Object being edited. - * @param part Part to get the scale value of. + * @param[in] obj Object being edited. + * @param[in] part Part to get the scale value of. * * @return Whether scale is on (EINA_TRUE) or not. */ @@ -1638,8 +994,8 @@ EAPI Eina_Bool edje_edit_part_scale_get(Evas_Object *obj, const char *part); /** Get horizontal dragable state for part. * - * @param obj Object being edited. - * @param part Part to get if can be dragged horizontally; + * @param[in] obj Object being edited. + * @param[in] part Part to get if can be dragged horizontally; * * @return 1 (or -1) if the part can be dragged horizontally, 0 otherwise. */ @@ -1647,18 +1003,16 @@ EAPI int edje_edit_part_drag_x_get(Evas_Object *obj, const char *part); /** Set horizontal dragable state for part. * - * @param obj Object being edited. - * @param part Part to set if should be dragged horizontally. - * @param drag 1 (or -1) if the part should be dragged horizontally, 0 otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set if should be dragged horizontally. + * @param[in] drag 1 (or -1) if the part should be dragged horizontally, 0 otherwise. */ -EAPI Eina_Bool edje_edit_part_drag_x_set(Evas_Object *obj, const char *part, int drag); +EAPI void edje_edit_part_drag_x_set(Evas_Object *obj, const char *part, int drag); /** Get vertical dragable state for part. * - * @param obj Object being edited. - * @param part Part to get if can be dragged vertically. + * @param[in] obj Object being edited. + * @param[in] part Part to get if can be dragged vertically. * * @return 1 (or - 1) if the part can be dragged vertically, 0 otherwise. */ @@ -1666,18 +1020,16 @@ EAPI int edje_edit_part_drag_y_get(Evas_Object *obj, const char *part); /** Set vertical dragable state for part. * - * @param obj Object being edited. - * @param part Part to set if should be dragged vertically. - * @param drag 1 (or -1) of the part shpuld be dragged vertically, 0 otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set if should be dragged vertically. + * @param[in] drag 1 (or -1) of the part shpuld be dragged vertically, 0 otherwise. */ -EAPI Eina_Bool edje_edit_part_drag_y_set(Evas_Object *obj, const char *part, int drag); +EAPI void edje_edit_part_drag_y_set(Evas_Object *obj, const char *part, int drag); /** Get horizontal dragable step for part. * - * @param obj Object being edited. - * @param part Part to get the drag horizontal step value. + * @param[in] obj Object being edited. + * @param[in] part Part to get the drag horizontal step value. * * @return The step value. */ @@ -1685,18 +1037,16 @@ EAPI int edje_edit_part_drag_step_x_get(Evas_Object *obj, const char *part); /** Set horizontal dragable state for part. * - * @param obj Object being edited. - * @param part Part to set the drag horizontal step value. - * @param step The step the will be dragged. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the drag horizontal step value. + * @param[in] step The step the will be dragged. */ -EAPI Eina_Bool edje_edit_part_drag_step_x_set(Evas_Object *obj, const char *part, int step); +EAPI void edje_edit_part_drag_step_x_set(Evas_Object *obj, const char *part, int step); /** Get vertical dragable step for part. * - * @param obj Object being edited. - * @param part Part to get the drag vertical step value. + * @param[in] obj Object being edited. + * @param[in] part Part to get the drag vertical step value. * * @return The step value. */ @@ -1704,56 +1054,46 @@ EAPI int edje_edit_part_drag_step_y_get(Evas_Object *obj, const char *part); /** Set vertical dragable state for part. * - * @param obj Object being edited. - * @param part Part to set the drag vertical step value. - * @param step The step the will be dragged. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the drag vertical step value. + * @param[in] step The step the will be dragged. */ -EAPI Eina_Bool edje_edit_part_drag_step_y_set(Evas_Object *obj, const char *part, int step); +EAPI void edje_edit_part_drag_step_y_set(Evas_Object *obj, const char *part, int step); /** Get horizontal dragable count for part. * - * @param obj Object being edited. - * @param part Part to get the drag horizontal count value. - * - * @return horizontal dragable count value + * @param[in] obj Object being edited. + * @param[in] part Part to get the drag horizontal count value. */ EAPI int edje_edit_part_drag_count_x_get(Evas_Object *obj, const char *part); /** Set horizontal dragable count for part. * - * @param obj Object being edited. - * @param part Part to set the drag horizontal count value. - * @param count The count value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the drag horizontal count value. + * @param[in] count The count value. */ -EAPI Eina_Bool edje_edit_part_drag_count_x_set(Evas_Object *obj, const char *part, int count); +EAPI void edje_edit_part_drag_count_x_set(Evas_Object *obj, const char *part, int count); /** Get vertical dragable count for part. * - * @param obj Object being edited. - * @param part Part to get the drag vertical count value. - * - * @return vertical dragable count value + * @param[in] obj Object being edited. + * @param[in] part Part to get the drag vertical count value. */ EAPI int edje_edit_part_drag_count_y_get(Evas_Object *obj, const char *part); /** Set vertical dragable count for part. * - * @param obj Object being edited. - * @param part Part to set the drag vertical count value. - * @param count The count value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the drag vertical count value. + * @param[in] count The count value. */ -EAPI Eina_Bool edje_edit_part_drag_count_y_set(Evas_Object *obj, const char *part, int count); +EAPI void edje_edit_part_drag_count_y_set(Evas_Object *obj, const char *part, int count); /** Get the name of the part that is used as 'confine' for the given draggies. * - * @param obj Object being edited. - * @param part Part to get the name that is used as 'confine' for the given draggies. + * @param[in] obj Object being edited. + * @param[in] part Part to get the name that is used as 'confine' for the given draggies. * * @return The name of the confine part or NULL (if unset). */ @@ -1761,18 +1101,16 @@ EAPI const char * edje_edit_part_drag_confine_get(Evas_Object *obj, const char * /** Set the name of the part that is used as 'confine' for the given draggies. * - * @param obj Object being edited. - * @param part Part to set the name that is used as 'confine' for the given draggies. - * @param confine The name of the confine part or NULL to unset confine. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the name that is used as 'confine' for the given draggies. + * @param[in] confine The name of the confine part or NULL to unset confine. */ -EAPI Eina_Bool edje_edit_part_drag_confine_set(Evas_Object *obj, const char *part, const char *confine); +EAPI void edje_edit_part_drag_confine_set(Evas_Object *obj, const char *part, const char *confine); /** Get the name of the part that is used as the receiver of the drag event. * - * @param obj Object being edited. - * @param part Part to get the name that is used as the receiver of the drag event. + * @param[in] obj Object being edited. + * @param[in] part Part to get the name that is used as the receiver of the drag event. * * @return The name of the part that will receive events, or NULL (if unset). */ @@ -1780,556 +1118,12 @@ EAPI const char * edje_edit_part_drag_event_get(Evas_Object *obj, const char *pa /** Set the name of the part that will receive events from the given draggies. * - * @param obj Object being edited. - * @param part Part to set the name that will receive events from the given draggies. - * @param event The name of the part that will receive events, or NULL to unset. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the name that will receive events from the given draggies. + * @param[in] event The name of the part that will receive events, or NULL to unset. */ -EAPI Eina_Bool edje_edit_part_drag_event_set(Evas_Object *obj, const char *part, const char *event); +EAPI void edje_edit_part_drag_event_set(Evas_Object *obj, const char *part, const char *event); -/** Get the name of the part that is used as 'threshold' for the given draggies. - * - * @param obj Object being edited. - * @param part Part to get the name that is used as 'threshold' for the given draggies. - * - * @return The name of the threshold part or NULL (if unset). - */ -EAPI const char * edje_edit_part_drag_threshold_get(Evas_Object *obj, const char *part); - -/** Set the name of the part that is used as 'threshold' for the given draggies. - * - * @param obj Object being edited. - * @param part Part to set the name that is used as 'threshold' for the given draggies. - * @param threshold The name of the threshold part or NULL to unset confine. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_part_drag_threshold_set(Evas_Object *obj, const char *part, const char *threshold); - -//@} -/******************************************************************************/ -/************************** BOX & TABLE ITEMS API *************************/ -/******************************************************************************/ -/** @name Items API - * Functions to deal with table and box part's items (see @ref edcref). - */ //@{ - -/** Append new item to box or table part. - * - * @param obj Object being edited. - * @param part Part to add a new item. This part should have BOX or TABLE type. - * @param item_name Name of new item that is not exist in BOX or TABLE yet. - * @param source_group Source (means group name) of the new item - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_append(Evas_Object *obj, const char *part, const char *item_name, const char *source_group); - -/** Get the list of all part items in the given edje. - * - * @param obj Object being edited. - * @param part Name of part which is TABLE or BOX part and contain items. - * - * @return A List containing all part items names found in the edje file. - * @since 1.11 - */ -EAPI Eina_List * edje_edit_part_items_list_get(Evas_Object *obj, const char *part); - -/** Delete item from box or table part. - * - * @param obj Object being edited. - * @param part Part to delete exist item. This part should have BOX or TABLE type. - * @param name Name of exist item to delete it from BOX or TABLE. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_del(Evas_Object *obj, const char *part, const char* name); - -/** Set source for item from table or box items. - * - * @param obj Object being edited. - * @param part Part to change item's source. This part should have BOX or TABLE type. - * @param item_name Name of item. - * @param source_group New gorup name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_source_set(Evas_Object *obj, const char *part, const char *item_name, const char *source_group); - -/** Get source for item from table or box items. - * - * @param obj Object being edited. - * @param part Part to return item's source. This part should have BOX or TABLE type. - * @param item_name Name of item. - * - * @return source of the given item. - * @since 1.11 - */ -EAPI const char * edje_edit_part_item_source_get(Evas_Object *obj, const char *part, const char *item_name); - -/** Get the minimum width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get minimum width. - * - * @return The minimum width value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_min_w_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the minimum width value of a part's item. - * The minimum width should be greater than 0. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set minimum width. - * @param min_w Minimum width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_min_w_set(Evas_Object *obj, const char *part, const char *item, int min_w); - -/** Get the minimum height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get minimum height. - * - * @return The minimum height value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_min_h_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the minimum height value of a part's item. - * The minimum height should be greater than 0. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set minimum height. - * @param min_h Minimum height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_min_h_set(Evas_Object *obj, const char *part, const char *item, int min_h); - -/** Get the maximum width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get maximum width. - * - * @return The maximum width value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_max_w_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the maximum width value of a part's item. - * The maximum width should be greater than -1. - * The value -1 means that state doesn't have any boundaries on width direction. - * (it can be any size that is bigger than it's min) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set maximum width. - * @param max_w Maximum width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_max_w_set(Evas_Object *obj, const char *part, const char *item, int max_w); - -/** Get the maximum height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get maximum height. - * - * @return The maximum height value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_max_h_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the maximum height value of a part's item. - * The maximum height should be greater than -1. - * The value -1 means that state doesn't have any boundaries on height direction. - * (it can be any size that is bigger than it's min) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set maximum height. - * @param max_h Maximum height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_max_h_set(Evas_Object *obj, const char *part, const char *item, int max_h); - -/** Get the aspect width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get aspect width. - * - * @return The aspect width value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_aspect_w_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the aspect width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set aspect width. - * @param aspect_w Aspect width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_aspect_w_set(Evas_Object *obj, const char *part, const char *item, int aspect_w); - -/** Get the aspect height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get aspect height. - * - * @return The maximum height value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_aspect_h_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the aspect height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set aspect height. - * @param aspect_h Aspect height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_aspect_h_set(Evas_Object *obj, const char *part, const char *item, int aspect_h); - -/** Get the prefer width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get prefer width. - * - * @return The prefer width value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_prefer_w_get(Evas_Object *obj, const char *part, const char *item); - -/** Get aspect mode for an item of TABLE or BOX. - * - * This may return next values: - * - EDJE_ASPECT_CONTROL_NONE - * - EDJE_ASPECT_CONTROL_NEITHER - * - EDJE_ASPECT_CONTROL_HORIZONTAL - * - EDJE_ASPECT_CONTROL_VERTICAL - * - EDJE_ASPECT_CONTROL_BOTH - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to set aspect mode. - * - * @return One of possible enum Edje_Aspect_Control. - * @since 1.11 - */ -EAPI Edje_Aspect_Control -edje_edit_part_item_aspect_mode_get(Evas_Object *obj, const char *part, const char *item); - -/** Set aspect mode for an item of TABLE or BOX. - * - * Mode may be next: - * - EDJE_ASPECT_CONTROL_NONE - * - EDJE_ASPECT_CONTROL_NEITHER - * - EDJE_ASPECT_CONTROL_HORIZONTAL - * - EDJE_ASPECT_CONTROL_VERTICAL - * - EDJE_ASPECT_CONTROL_BOTH - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to set aspect mode. - * @param mode One of possible enum from Edje_Aspect_Control: - - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_part_item_aspect_mode_set(Evas_Object *obj, const char *part, const char *item, Edje_Aspect_Control mode); - -/** Set the prefer width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set prefer width. - * @param prefer_w Prefer width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_prefer_w_set(Evas_Object *obj, const char *part, const char *item, int prefer_w); - -/** Get the prefer height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get prefer height. - * - * @return The maximum height value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_prefer_h_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the prefer height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set prefer height. - * @param prefer_h Prefer height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_prefer_h_set(Evas_Object *obj, const char *part, const char *item, int prefer_h); - -/** Get the spread width value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get spread width. - * - * @return The spread width value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_spread_w_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the spread width value of a part's item. - * - * @attention be carefull, if you set up huge number (like 10 or 100). width and height of - * spread is being multiplied and you will get huge number of objects that may "eat" - * all of your processor performance at once... Or if you want, you may - * get some coffee and wait until it will recalculate all of those objects :) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set spread width. - * @param spread_w Maximum width value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_spread_w_set(Evas_Object *obj, const char *part, const char *item, int spread_w); - -/** Get the spread height value of a part's item. - * - * @attention be carefull, if you set up huge number (like 10 or 100). width and height of - * spread is being multiplied and you will get huge number of objects that may "eat" - * all of your processor performance at once... Or if you want, you may - * get some coffee and wait until it will recalculate all of those objects :) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to get spread height. - * - * @return The spread height value. - * @since 1.11 - */ -EAPI int edje_edit_part_item_spread_h_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the spread height value of a part's item. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param item The name of the item to set spread height. - * @param spread_h spread height value. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_spread_h_set(Evas_Object *obj, const char *part, const char *item, int spread_h); - -/** Get paddings of the part's item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item_name The name of the item. - * @param l A pointer to store the left padding value. - * @param r A pointer to store the right padding value. - * @param t A pointer to store the top padding value. - * @param b A pointer to store the bottom padding value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_padding_get(Evas_Object *obj, const char *part, const char *item_name, int *l, int *r, int *t, int *b); - -/** Set paddings of the part's item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item_name The name of the item. - * @param l Value of the left padding. - * @param r Value of the right padding. - * @param t Value of the top padding. - * @param b Value of the bottom padding. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_padding_set(Evas_Object *obj, const char *part, const char *item_name, int l, int r, int t, int b); - -/** Get the horizontal align value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to get horizontal align value. - * - * @return The horizontal align value for the given align (value is between -1.0 and 1.0) - * @since 1.11 - */ -EAPI double edje_edit_part_item_align_x_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the horizontal align value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain itemf - * @param item The name of the item to set horizontal align value. - * @param align_x New value of the horizontal align. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_align_x_set(Evas_Object *obj, const char *part, const char *item, double align_x); - -/** Get the vertical align value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to get vertical align value. - * - * @return The vertical align value for the given align (value is between -1.0 and 1.0) - * @since 1.11 - */ -EAPI double edje_edit_part_item_align_y_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the vertical align value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to set vertical align value. - * @param align_y New value of the vertical align. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_align_y_set(Evas_Object *obj, const char *part, const char *item, double align_y); - -/** Get the horizontal weight value of a part item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to get horizontal weight value. - * - * @return The horizontal weight value for the given item (value is between -1.0 and 1.0) - * @since 1.11 - */ -EAPI double edje_edit_part_item_weight_x_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the horizontal we value of a part item. - * - * @param obj Object being edited. - * @param part Part that contain itemf - * @param item The name of the item to set horizontal weight value. - * @param weight_x New value of the horizontal weight. - * - * @return @c EINA_TRUE If successfull, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_weight_x_set(Evas_Object *obj, const char *part, const char *item, double weight_x); - -/** Get the vertical weight value of a part item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to get vertical weight value. - * - * @return The vertical weight value for the given item (value is between -1.0 and 1.0) - * @since 1.11 - */ -EAPI double edje_edit_part_item_weight_y_get(Evas_Object *obj, const char *part, const char *item); - -/** Set the vertical weight value of a part item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item The name of the item to set vertical weight value. - * @param weight_y New value of the vertical weight. - * - * @return @c EINA_TRUE If successfull, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_weight_y_set(Evas_Object *obj, const char *part, const char *item, double weight_y); - -/** Get column/row position of the part's item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item_name The name of the item. - * @param col Column item position. - * @param row Row item position. - * - * @return @c EINA_TRUE If successfull, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_position_get(Evas_Object *obj, const char *part, const char *item_name, unsigned short *col, unsigned short *row); - -/** Set column/row position of a new part's item. - * - * @param obj Object being edited. - * @param part Part that contain item. - * @param item_name The name of the item. - * @param col Column item position. - * @param row Row item position. - * - * @return @c EINA_TRUE If successfull, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_position_set(Evas_Object *obj, const char *part, const char *item_name, unsigned short col, unsigned short row); - -/** Retrieves the how many columns and rows will span for use by item. - * - * @param obj object being edited. - * @param part part that contain item. - * @param item the name of the item of part. - * @param col Pointer to an unsigned char in which to store the columns count. - * @param row Pointer to an unsigned char in which to store the rows count. - * - * @since 1.11 - */ -EAPI void edje_edit_part_item_span_get(Evas_Object *obj, const char *part, const char *item, unsigned char *col, unsigned char *row); - -/** Set the count of columns and rows, which this item will spans for use. - * - * @param obj object being edited. - * @param part part that contain item. - * @param item the name of the item to set new count of columns spans. - * @param col new count of the columns spans. - * @param row new count of the rows spans. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_part_item_span_set(Evas_Object *obj, const char *part, const char *item, unsigned char col, unsigned char row); //@} /******************************************************************************/ @@ -2341,8 +1135,8 @@ EAPI Eina_Bool edje_edit_part_item_span_set(Evas_Object *obj, const char *part, /** Get the list of all the states in the given part. * - * @param obj Object being edited. - * @param part Part to get the states names list. + * @param[in] obj Object being edited. + * @param[in] part Part to get the states names list. * * @return An Eina_List* of string (char *)containing all the states names found * in part, including the float value (ex: "default 0.00"). @@ -2353,69 +1147,69 @@ EAPI Eina_List * edje_edit_part_states_list_get(Evas_Object *obj, const char *pa /** Set a new name for the given state in the given part. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state Name of the state to rename. - * @param value Value of the state to rename. - * @param new_name The new name for the state. - * @param new_value The new value for the state. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state Name of the state to rename. + * @param[in] value Value of the state to rename. + * @param[in] new_name The new name for the state. + * @param[in] new_value The new value for the state. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_name_set(Evas_Object *obj, const char *part, const char *state, double value, const char *new_name, double new_value); /** Create a new state to the give part. * - * @param obj Object being edited. - * @param part Part to set the name of the new state. - * @param name Name for the new state (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part to set the name of the new state. + * @param[in] name Name for the new state (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE if successfully, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successfully, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_add(Evas_Object *obj, const char *part, const char *name, double value); /** Delete the given part state from the edje. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The current name of the state (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The current name of the state (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE if successfully, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successfully, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_del(Evas_Object *obj, const char *part, const char *state, double value); /** Check if a part state with the given name exist. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to check (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to check (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE if the part state exist, @c EINA_FALSE otherwise. + * @return EINA_TRUE if the part state exist, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_exist(Evas_Object *obj, const char *part, const char *state, double value); /** Copies the state @p from into @p to. If @p to doesn't exist it will be created. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param from State to copy from (not including state value). - * @param val_from The value of the state to copy from. - * @param to State to copy into (not including state value). - * @param val_to The value of the state to copy into. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] from State to copy from (not including state value). + * @param[in] val_from The value of the state to copy from. + * @param[in] to State to copy into (not including state value). + * @param[in] val_to The value of the state to copy into. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_copy(Evas_Object *obj, const char *part, const char *from, double val_from, const char *to, double val_to); /** Get the 'rel1 relative X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel1 relative X' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel1 relative X' (not including the state value). + * @param[in] value The state value. * * @return The 'rel1 relative X' value of the part state. */ @@ -2423,10 +1217,10 @@ EAPI double edje_edit_state_rel1_relative_x_get(Evas_Object *obj, const char *pa /** Get the 'rel1 relative Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel1 relative Y' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel1 relative Y' (not including the state value). + * @param[in] value The state value. * * @return The 'rel1 relative Y' value of the part state. */ @@ -2434,10 +1228,10 @@ EAPI double edje_edit_state_rel1_relative_y_get(Evas_Object *obj, const char *pa /** Get the 'rel2 relative X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel2 relative X' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel2 relative X' (not including the state value). + * @param[in] value The state value. * * @return The 'rel2 relative X' value of the part state. */ @@ -2445,10 +1239,10 @@ EAPI double edje_edit_state_rel2_relative_x_get(Evas_Object *obj, const char *pa /** Get the 'rel2 relative Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel2 relative Y' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel2 relative Y' (not including the state value). + * @param[in] value The state value. * * @return The 'rel2 relative Y' value of the part state. */ @@ -2456,58 +1250,50 @@ EAPI double edje_edit_state_rel2_relative_y_get(Evas_Object *obj, const char *pa /** Set the 'rel1 relative X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel1 relative X' (not including the state value). - * @param value The state value. - * @param x The new 'rel1 relative X' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel1 relative X' (not including the state value). + * @param[in] value The state value. + * @param[in] x The new 'rel1 relative X' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel1_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_rel1_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the 'rel1 relative Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel1 relative Y' (not including the state value). - * @param value The state value. - * @param y The new 'rel1 relative Y' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel1 relative Y' (not including the state value). + * @param[in] value The state value. + * @param[in] y The new 'rel1 relative Y' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel1_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); +EAPI void edje_edit_state_rel1_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Set the 'rel2 relative X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel2 relative X' (not including the state value). - * @param value The state value. - * @param x The new 'rel2 relative X' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel2 relative X' (not including the state value). + * @param[in] value The state value. + * @param[in] x The new 'rel2 relative X' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel2_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_rel2_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the 'rel2 relative Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel2 relative Y' (not including the state value). - * @param value The state value. - * @param y The new 'rel2 relative Y' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel2 relative Y' (not including the state value). + * @param[in] value The state value. + * @param[in] y The new 'rel2 relative Y' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel2_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); +EAPI void edje_edit_state_rel2_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Get the 'rel1 offset X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel1 offset X' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel1 offset X' (not including the state value). + * @param[in] value The state value. * * @return The 'rel1 offset X' value of the part state. */ @@ -2515,10 +1301,10 @@ EAPI int edje_edit_state_rel1_offset_x_get(Evas_Object *obj, const char *part, c /** Get the 'rel1 offset Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel1 offset Y' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel1 offset Y' (not including the state value). + * @param[in] value The state value. * * @return The 'rel1 offset Y' value of the part state. */ @@ -2526,10 +1312,10 @@ EAPI int edje_edit_state_rel1_offset_y_get(Evas_Object *obj, const char *part, c /** Get the 'rel2 offset X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel2 offset X' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel2 offset X' (not including the state value). + * @param[in] value The state value. * * @return The 'rel2 offset X' value of the part state. */ @@ -2537,10 +1323,10 @@ EAPI int edje_edit_state_rel2_offset_x_get(Evas_Object *obj, const char *part, c /** Get the 'rel2 offset Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get 'rel2 offset Y' (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get 'rel2 offset Y' (not including the state value). + * @param[in] value The state value. * * @return The 'rel2 offset Y' value of the part state. */ @@ -2548,58 +1334,50 @@ EAPI int edje_edit_state_rel2_offset_y_get(Evas_Object *obj, const char *part, c /** Set the 'rel1 offset X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel1 offset X' (not including the state value). - * @param value The state value. - * @param x The new 'rel1 offset X' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel1 offset X' (not including the state value). + * @param[in] value The state value. + * @param[in] x The new 'rel1 offset X' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel1_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, int x); +EAPI void edje_edit_state_rel1_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the 'rel1 offset Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel1 offset Y' (not including the state value). - * @param value The state value. - * @param y The new 'rel1 offset Y' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel1 offset Y' (not including the state value). + * @param[in] value The state value. + * @param[in] y The new 'rel1 offset Y' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel1_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, int y); +EAPI void edje_edit_state_rel1_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Set the 'rel2 offset X' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel2 offset X' (not including the state value). - * @param value The state value. - * @param x The new 'rel2 offset X' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel2 offset X' (not including the state value). + * @param[in] value The state value. + * @param[in] x The new 'rel2 offset X' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel2_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, int x); +EAPI void edje_edit_state_rel2_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the 'rel2 offset Y' value of state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set 'rel2 offset Y' (not including the state value). - * @param value The state value. - * @param y The new 'rel2 offset Y' value to set'. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set 'rel2 offset Y' (not including the state value). + * @param[in] value The state value. + * @param[in] y The new 'rel2 offset Y' value to set'. */ -EAPI Eina_Bool edje_edit_state_rel2_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, int y); +EAPI void edje_edit_state_rel2_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Get the part name rel1x is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The state that contain which the part name rel1x is relative to (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The state that contain which the part name rel1x is relative to (not including the state value). + * @param[in] value The state value. * * @return The part name rel1x is relative to or NULL if the part is relative to the whole interface. */ @@ -2607,10 +1385,10 @@ EAPI const char * edje_edit_state_rel1_to_x_get(Evas_Object *obj, const char *pa /** Get the part name rel1y is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The state that contain which the part name rel1y is relative to (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The state that contain which the part name rel1y is relative to (not including the state value). + * @param[in] value The state value. * * @return The part name rel1y is relative to or NULL if the part is relative to the whole interface. */ @@ -2618,10 +1396,10 @@ EAPI const char * edje_edit_state_rel1_to_y_get(Evas_Object *obj, const char *pa /** Get the part name rel2x is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The state that contain which the part name rel2x is relative to (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The state that contain which the part name rel2x is relative to (not including the state value). + * @param[in] value The state value. * * @return The part name rel2x is relative to or NULL if the part is relative to the whole interface. */ @@ -2629,10 +1407,10 @@ EAPI const char * edje_edit_state_rel2_to_x_get(Evas_Object *obj, const char *pa /** Get the part name rel2y is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The state that contain which the part name rel2y is relative to (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The state that contain which the part name rel2y is relative to (not including the state value). + * @param[in] value The state value. * * @return The part name rel2y is relative to or NULL if the part is relative to the whole interface. */ @@ -2640,142 +1418,136 @@ EAPI const char * edje_edit_state_rel2_to_y_get(Evas_Object *obj, const char *pa /** Set the part rel1x is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set rel1x is relative to (not including the state value). - * @param value The state value. - * @param rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set rel1x is relative to (not including the state value). + * @param[in] value The state value. + * @param[in] rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return The part name rel1x is relative to or NULL if the part is relative to the whole interface. */ -EAPI Eina_Bool edje_edit_state_rel1_to_x_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); +EAPI void edje_edit_state_rel1_to_x_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); /** Set the part rel1y is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set rel1y is relative to (not including the state value). - * @param value The state value. - * @param rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set rel1y is relative to (not including the state value). + * @param[in] value The state value. + * @param[in] rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return The part name rel1y is relative to or NULL if the part is relative to the whole interface. */ -EAPI Eina_Bool edje_edit_state_rel1_to_y_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); +EAPI void edje_edit_state_rel1_to_y_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); /** Set the part rel2x is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set rel2x is relative to (not including the state value). - * @param value The state value. - * @param rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set rel2x is relative to (not including the state value). + * @param[in] value The state value. + * @param[in] rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return The part name rel2x is relative to or NULL if the part is relative to the whole interface. */ -EAPI Eina_Bool edje_edit_state_rel2_to_x_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); +EAPI void edje_edit_state_rel2_to_x_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); /** Set the part rel2y is relative to. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set rel2y is relative to (not including the state value). - * @param value The state value. - * @param rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set rel2y is relative to (not including the state value). + * @param[in] value The state value. + * @param[in] rel_to The name of the part that is used as container/parent (NULL make the part relative to the whole interface). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return The part name rel2y is relative to or NULL if the part is relative to the whole interface. */ -EAPI Eina_Bool edje_edit_state_rel2_to_y_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); +EAPI void edje_edit_state_rel2_to_y_set(Evas_Object *obj, const char *part, const char *state, double value, const char *rel_to); /** Get the color of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get color (not including the state value). - * @param value The state value. - * @param r A pointer to store the red value. - * @param g A pointer to store the green value. - * @param b A pointer to store the blue value. - * @param a A pointer to store the alpha value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get color (not including the state value). + * @param[in] value The state value. + * @param[out] r A pointer to store the red value. + * @param[out] g A pointer to store the green value. + * @param[out] b A pointer to store the blue value. + * @param[out] a A pointer to store the alpha value. */ EAPI void edje_edit_state_color_get(Evas_Object *obj, const char *part, const char *state, double value, int *r, int *g, int *b, int *a); /** Get the color2 of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get color (not including the state value). - * @param value The state value. - * @param r A pointer to store the red value. - * @param g A pointer to store the green value. - * @param b A pointer to store the blue value. - * @param a A pointer to store the alpha value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get color (not including the state value). + * @param[in] value The state value. + * @param[out] r A pointer to store the red value. + * @param[out] g A pointer to store the green value. + * @param[out] b A pointer to store the blue value. + * @param[out] a A pointer to store the alpha value. */ EAPI void edje_edit_state_color2_get(Evas_Object *obj, const char *part, const char *state, double value, int *r, int *g, int *b, int *a); /** Get the color3 of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get color (not including the state value). - * @param value The state value. - * @param r A pointer to store the red value. - * @param g A pointer to store the green value. - * @param b A pointer to store the blue value. - * @param a A pointer to store the alpha value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get color (not including the state value). + * @param[in] value The state value. + * @param[out] r A pointer to store the red value. + * @param[out] g A pointer to store the green value. + * @param[out] b A pointer to store the blue value. + * @param[out] a A pointer to store the alpha value. */ EAPI void edje_edit_state_color3_get(Evas_Object *obj, const char *part, const char *state, double value, int *r, int *g, int *b, int *a); /** Set the color of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set color (not including the state value). - * @param value The state value. - * @param r The red value of the color. - * @param g The green value of the color. - * @param b The blue value of the color. - * @param a The alpha value of the color. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set color (not including the state value). + * @param[in] value The state value. + * @param[in] r The red value of the color. + * @param[in] g The green value of the color. + * @param[in] b The blue value of the color. + * @param[in] a The alpha value of the color. */ -EAPI Eina_Bool edje_edit_state_color_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); +EAPI void edje_edit_state_color_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); /** Set the color2 of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set color (not including the state value). - * @param value The state value. - * @param r The red value of the color. - * @param g The green value of the color. - * @param b The blue value of the color. - * @param a The alpha value of the color. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set color (not including the state value). + * @param[in] value The state value. + * @param[in] r The red value of the color. + * @param[in] g The green value of the color. + * @param[in] b The blue value of the color. + * @param[in] a The alpha value of the color. */ -EAPI Eina_Bool edje_edit_state_color2_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); +EAPI void edje_edit_state_color2_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); /** Set the color3 of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set color (not including the state value). - * @param value The state value. - * @param r The red value of the color. - * @param g The green value of the color. - * @param b The blue value of the color. - * @param a The alpha value of the color. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set color (not including the state value). + * @param[in] value The state value. + * @param[in] r The red value of the color. + * @param[in] g The green value of the color. + * @param[in] b The blue value of the color. + * @param[in] a The alpha value of the color. */ -EAPI Eina_Bool edje_edit_state_color3_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); +EAPI void edje_edit_state_color3_set(Evas_Object *obj, const char *part, const char *state, double value, int r, int g, int b, int a); /** Get the horizontal align value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get horizontal align (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get horizontal align (not including the state value). + * @param[in] value The state value. * * @return The horizontal align value for the given state */ @@ -2783,10 +1555,10 @@ EAPI double edje_edit_state_align_x_get(Evas_Object *obj, const char *part, cons /** Get the vertical align value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get horizontal align (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get horizontal align (not including the state value). + * @param[in] value The state value. * * @return The vertical align value for the given state */ @@ -2794,230 +1566,114 @@ EAPI double edje_edit_state_align_y_get(Evas_Object *obj, const char *part, cons /** Set the horizontal align value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get horizontal align (not including the state value). - * @param value The state value. - * @param align The new vertical align value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get horizontal align (not including the state value). + * @param[in] value The state value. + * @param[in] align The new vertical align value. */ -EAPI Eina_Bool edje_edit_state_align_x_set(Evas_Object *obj, const char *part, const char *state, double value, double align); +EAPI void edje_edit_state_align_x_set(Evas_Object *obj, const char *part, const char *state, double value, double align); /** Set the vertical align value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get vertical align (not including the state value). - * @param value The state value. - * @param align The new vertical align value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get vertical align (not including the state value). + * @param[in] value The state value. + * @param[in] align The new vertical align value. */ -EAPI Eina_Bool edje_edit_state_align_y_set(Evas_Object *obj, const char *part, const char *state, double value, double align); +EAPI void edje_edit_state_align_y_set(Evas_Object *obj, const char *part, const char *state, double value, double align); /** Get the minimum width value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get minimum width (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get minimum width (not including the state value). + * @param[in] value The state value. * * @return The minimum width value. */ EAPI int edje_edit_state_min_w_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set the minimum width value of a part state. - * The minimum width should be greater than 0. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set minimum width (not including the state value). - * @param value The state value. - * @param min_w Minimum width value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set minimum width (not including the state value). + * @param[in] value The state value. + * @param[in] min_w Minimum width value. */ -EAPI Eina_Bool edje_edit_state_min_w_set(Evas_Object *obj, const char *part, const char *state, double value, int min_w); +EAPI void edje_edit_state_min_w_set(Evas_Object *obj, const char *part, const char *state, double value, int min_w); /** Get the minimum height value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get minimum height (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get minimum height (not including the state value). + * @param[in] value The state value. * * @return The minimum height value. */ EAPI int edje_edit_state_min_h_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set the minimum height value of a part state. - * The minimum height should be greater than 0. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set minimum height (not including the state value). - * @param value The state value. - * @param min_h Minimum height value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set minimum height (not including the state value). + * @param[in] value The state value. + * @param[in] min_h Minimum height value. */ -EAPI Eina_Bool edje_edit_state_min_h_set(Evas_Object *obj, const char *part, const char *state, double value, int min_h); +EAPI void edje_edit_state_min_h_set(Evas_Object *obj, const char *part, const char *state, double value, int min_h); /** Get the maximum width value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get maximum width (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get maximum width (not including the state value). + * @param[in] value The state value. * * @return The maximum width value. */ EAPI int edje_edit_state_max_w_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set the maximum width value of a part state. - * The maximum width should be greater than -1. - * The value -1 means that state doesn't have any boundaries on width direction. - * (it can be any size that is bigger than it's min) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set maximum width (not including the state value). - * @param value The state value. - * @param max_w Maximum width value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set maximum width (not including the state value). + * @param[in] value The state value. + * @param[in] max_w Maximum width value. */ -EAPI Eina_Bool edje_edit_state_max_w_set(Evas_Object *obj, const char *part, const char *state, double value, int max_w); +EAPI void edje_edit_state_max_w_set(Evas_Object *obj, const char *part, const char *state, double value, int max_w); /** Get the maximum height value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get maximum height (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get maximum height (not including the state value). + * @param[in] value The state value. * * @return The maximum height value. */ EAPI int edje_edit_state_max_h_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set the maximum height value of a part state. - * The maximum height should be greater than -1. - * The value -1 means that state doesn't have any boundaries on height direction. - * (it can be any size that is bigger than it's min) - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set maximum height (not including the state value). - * @param value The state value. - * @param max_h Maximum height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_max_h_set(Evas_Object *obj, const char *part, const char *state, double value, int max_h); - -/** Get the multiplier (minmul) width value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get multiplier width (not including the state value). - * @param value The state value. - * - * @return The maximum width value. - * @since 1.11 - */ -EAPI double edje_edit_state_minmul_w_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the multiplier (minmul) width value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set multiplier width (not including the state value). - * @param value The state value. - * @param minmul_w Multiplier width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_state_minmul_w_set(Evas_Object *obj, const char *part, const char *state, double value, double minmul_w); - -/** Get the multiplier (minmul) height value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get multiplier height (not including the state value). - * @param value The state value. * - * @return The maximum height value. - * @since 1.11 + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set maximum height (not including the state value). + * @param[in] value The state value. + * @param[in] max_h Maximum height value. */ -EAPI double edje_edit_state_minmul_h_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the multiplier (minmul) height value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set multiplier height (not including the state value). - * @param value The state value. - * @param minmul_h Multiplier height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_state_minmul_h_set(Evas_Object *obj, const char *part, const char *state, double value, double minmul_h); - -/** Get the fixed width value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fixed width value (not including the state value). - * @param value The state value. - * - * @return The fixed width value. - */ -EAPI Eina_Bool edje_edit_state_fixed_w_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the fixed width value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fixed width value (not including the state value). - * @param value The state value. - * @param fixed Fixed width value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_fixed_w_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fixed); - -/** Get the fixed height value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fixed height value (not including the state value). - * @param value The state value. - * - * @return The fixed height value. - */ -EAPI Eina_Bool edje_edit_state_fixed_h_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the fixed height value of a part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set maximum height (not including the state value). - * @param value The state value. - * @param fixed Fixed height value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_fixed_h_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fixed); +EAPI void edje_edit_state_max_h_set(Evas_Object *obj, const char *part, const char *state, double value, int max_h); /** Get the minimum aspect value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get minimum aspect (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get minimum aspect (not including the state value). + * @param[in] value The state value. * * @return The minimum aspect */ @@ -3025,10 +1681,10 @@ EAPI double edje_edit_state_aspect_min_get(Evas_Object *obj, const char *part, c /** Get the maximum aspect value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get maximum aspect (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get maximum aspect (not including the state value). + * @param[in] value The state value. * * @return The maximum aspect */ @@ -3036,34 +1692,30 @@ EAPI double edje_edit_state_aspect_max_get(Evas_Object *obj, const char *part, c /** Set the minimum aspect value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set minimum aspect (not including the state value). - * @param value The state value. - * @param aspect Minimum aspect value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set minimum aspect (not including the state value). + * @param[in] value The state value. + * @param[in] aspect Minimum aspect value. */ -EAPI Eina_Bool edje_edit_state_aspect_min_set(Evas_Object *obj, const char *part, const char *state, double value, double aspect); +EAPI void edje_edit_state_aspect_min_set(Evas_Object *obj, const char *part, const char *state, double value, double aspect); /** Set the maximum aspect value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set maximum aspect (not including the state value). - * @param value The state value. - * @param aspect Maximum aspect value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set maximum aspect (not including the state value). + * @param[in] value The state value. + * @param[in] aspect Maximum aspect value. */ -EAPI Eina_Bool edje_edit_state_aspect_max_set(Evas_Object *obj, const char *part, const char *state, double value, double aspect); +EAPI void edje_edit_state_aspect_max_set(Evas_Object *obj, const char *part, const char *state, double value, double aspect); /** Get the aspect preference of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get aspect preference (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get aspect preference (not including the state value). + * @param[in] value The state value. * * @return The aspect preference (0 = None, 1 = Vertical, 2 = Horizontal, 3 = Both) */ @@ -3071,97 +1723,22 @@ EAPI unsigned char edje_edit_state_aspect_pref_get(Evas_Object *obj, const char /** Set the aspect preference of a part state. * - * The available values of aspect preference are: - * <ul style="list-style-type:none"> - * <li>0 - None</li> - * <li>1 - Vertical</li> - * <li>2 - Horizontal</li> - * <li>3 - Both</li> - * <li>4 - Source</li> - * </ul> - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set aspect preference (not + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set aspect preference (not * including the state value). - * @param value The state value. - * @param pref The aspect preference to be set - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_aspect_pref_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char pref); - -/** Get the smooth property for given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the fill horizontal origin relative to area (not including the state value). - * @param value The state value. - * - * @return The smooth value. + * @param[in] value The state value. + * @param[in] pref The aspect preference to set (0 = None, 1 = Vertical, 2 + * = Horizontal, 3 = Both) */ -EAPI Eina_Bool -edje_edit_state_fill_smooth_get(Evas_Object *obj, const char *part, const char *state, double value); - - -/** Set the smooth property for given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal origin relative to area (not including the state value). - * @param value The state value. - * @param smooth The smooth value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_fill_smooth_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool smooth); - -/** Get the fill type property for given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * - * @return The value that represents fill type: 0 for SCALE or 1 for TILE. In case of error (for example, if part type does not match) returns 2. - * @see edje_edit_state_fill_type_set() - * @since 1.11 - */ -EAPI unsigned char edje_edit_state_fill_type_get(Evas_Object *obj, const char *part, const char *state, double value); - - -/** Set the fill type property for given part state. - * - * Sets the image fill type. The available types are: - * <dl> - * <dt>SCALE</dt> - * <dd>image will be scaled accordingly to the 'relative' and 'offset' params values from 'origin' and 'size' blocks.</dd> - * <dt>TILE</dt> - * <dd>image will be tiled accordingly to the 'relative' and 'offset' params values from 'origin' and 'size' blocks.</dd> - * </dl> - * <b>Important</b>: the part parameter 'min' must be set, it's size of tiled image. - * If parameter 'max' is set tiled area will be resized accordingly to the 'max' values of part. - * The default value of fill type is SCALE. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * @param fill_type The value that represents fill type: 0 for SCALE or 1 for TILE. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_state_fill_type_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_state_fill_type_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char fill_type); +EAPI void edje_edit_state_aspect_pref_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char pref); /** Get the fill horizontal origin relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the fill horizontal origin relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the fill horizontal origin relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill horizontal origin relative to area. */ @@ -3169,10 +1746,10 @@ EAPI double edje_edit_state_fill_origin_relative_x_get(Evas_Object *obj, const c /** Get the fill vertical origin relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill vertical origin relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill vertical origin relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill vertical origin relative to area. */ @@ -3180,10 +1757,10 @@ EAPI double edje_edit_state_fill_origin_relative_y_get(Evas_Object *obj, const c /** Get the fill horizontal origin offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill horizontal origin offset relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill horizontal origin offset relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill horizontal origin offset relative to area. */ @@ -3191,10 +1768,10 @@ EAPI int edje_edit_state_fill_origin_offset_x_get(Evas_Object *obj, const char * /** Get the fill vertical origin offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill vertical origin offset relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill vertical origin offset relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill vertical origin offset value. */ @@ -3202,58 +1779,50 @@ EAPI int edje_edit_state_fill_origin_offset_y_get(Evas_Object *obj, const char * /** Set the fill horizontal origin relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal origin relative to area (not including the state value). - * @param value The state value. - * @param x The fill horizontal origin value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill horizontal origin relative to area (not including the state value). + * @param[in] value The state value. + * @param[in] x The fill horizontal origin value. */ -EAPI Eina_Bool edje_edit_state_fill_origin_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_fill_origin_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the fill horizontal origin relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill vertical origin relative to area (not including the state value). - * @param value The state value. - * @param y The fill vertical origin value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill vertical origin relative to area (not including the state value). + * @param[in] value The state value. + * @param[in] y The fill vertical origin value. */ -EAPI Eina_Bool edje_edit_state_fill_origin_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); +EAPI void edje_edit_state_fill_origin_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Set the fill horizontal origin offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal origin offset relative to area (not including the state value). - * @param value The state value. - * @param x The fill horizontal origin offset value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill horizontal origin offset relative to area (not including the state value). + * @param[in] value The state value. + * @param[in] x The fill horizontal origin offset value. */ -EAPI Eina_Bool edje_edit_state_fill_origin_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_fill_origin_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the fill vertical origin offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill vertical origin offset relative to area (not including the state value). - * @param value The state value. - * @param y The fill vertical origin offset value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill vertical origin offset relative to area (not including the state value). + * @param[in] value The state value. + * @param[in] y The fill vertical origin offset value. */ -EAPI Eina_Bool edje_edit_state_fill_origin_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); +EAPI void edje_edit_state_fill_origin_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Get the fill horizontal size relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill horizontal size relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill horizontal size relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill horizontal size relative to area. */ @@ -3261,10 +1830,10 @@ EAPI double edje_edit_state_fill_size_relative_x_get(Evas_Object *obj, const cha /** Get the fill vertical size relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill vertical size relative to area (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill vertical size relative to area (not including the state value). + * @param[in] value The state value. * * @return The fill vertical size relative to area. */ @@ -3272,11 +1841,11 @@ EAPI double edje_edit_state_fill_size_relative_y_get(Evas_Object *obj, const cha /** Get the fill horizontal size offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill horizontal size + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill horizontal size * offset relative to area (not including the state value). - * @param value The state value. + * @param[in] value The state value. * * @return The fill horizontal size offset relative to area. */ @@ -3284,11 +1853,11 @@ EAPI int edje_edit_state_fill_size_offset_x_get(Evas_Object *obj, const char *pa /** Get the fill vertical size offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get fill vertical size offset + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get fill vertical size offset * relative to area (not including the state value). - * @param value The state value. + * @param[in] value The state value. * * @return The fill vertical size offset relative to area. */ @@ -3296,87 +1865,77 @@ EAPI int edje_edit_state_fill_size_offset_y_get(Evas_Object *obj, const char *pa /** Set the fill horizontal size relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal size + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill horizontal size * relative value (not including the state value). - * @param value The state value. - * @param x The horizontal size relative value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] value The state value. + * @param[in] x The horizontal size relative value. */ -EAPI Eina_Bool edje_edit_state_fill_size_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_fill_size_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the fill vertical size relative value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill vertical size + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill vertical size * relative value (not including the state value). - * @param value The state value. - * @param x The vertical size relative value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] value The state value. + * @param[in] x The vertical size relative value. */ -EAPI Eina_Bool edje_edit_state_fill_size_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_fill_size_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the fill horizontal size offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal size + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill horizontal size * offset relative value (not including the state value). - * @param value The state value. - * @param x The horizontal size offset value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] value The state value. + * @param[in] x The horizontal size offset value. */ -EAPI Eina_Bool edje_edit_state_fill_size_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); +EAPI void edje_edit_state_fill_size_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, double x); /** Set the fill vertical size offset value of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill vertical size offset + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set fill vertical size offset * relative value (not including the state value). - * @param value The state value. - * @param y The vertical size offset value. - * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @param[in] value The state value. + * @param[in] y The vertical size offset value. */ -EAPI Eina_Bool edje_edit_state_fill_size_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); +EAPI void edje_edit_state_fill_size_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, double y); /** Get the visibility of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get visibility (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get visibility (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE if the state is visible, @c EINA_FALSE otherwise. + * @return EINA_TRUE if the state is visible, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_visible_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set the visibility of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set visibility (not including the state value). - * @param value The state value. - * @param visible To set state visible (EINA_TRUE if the state is visible, @c EINA_FALSE otherwise) - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set visibility (not including the state value). + * @param[in] value The state value. + * @param[in] visible To set state visible (EINA_TRUE if the state is visible, EINA_FALSE otherwise) */ -EAPI Eina_Bool edje_edit_state_visible_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool visible); +EAPI void edje_edit_state_visible_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool visible); /** Get the color class of the given part state. * * Remember to free the string with edje_edit_string_free() * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get color class (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get color class (not including the state value). + * @param[in] value The state value. * * @return The current color class. */ @@ -3384,24 +1943,22 @@ EAPI const char *edje_edit_state_color_class_get(Evas_Object *obj, const char *p /** Set the color class of the given part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set color class (not including the state value). - * @param value The state value. - * @param color_class The color class to assign. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set color class (not including the state value). + * @param[in] value The state value. + * @param[in] color_class The color class to assign. */ -EAPI Eina_Bool edje_edit_state_color_class_set(Evas_Object *obj, const char *part, const char *state, double value, const char *color_class); +EAPI void edje_edit_state_color_class_set(Evas_Object *obj, const char *part, const char *state, double value, const char *color_class); /** Get the list of parameters for an external part. * * DO NOT FREE THE LIST! * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get list of Edje_External_Param (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get list of Edje_External_Param (not including the state value). + * @param[in] value The state value. * * @return The list of Edje_External_Param. */ @@ -3409,83 +1966,83 @@ EAPI const Eina_List * edje_edit_state_external_params_list_get(Evas_Object *obj /** Get the external parameter type and value. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter (not including the state value). - * @param value The state value. - * @param param The name of the paramter to look for. - * @param type The type of the parameter will be stored here. - * @param val Pointer to value will be stored here - DO NOT FREE IT! + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter to look for. + * @param[out] type The type of the parameter will be stored here. + * @param[out] val Pointer to value will be stored here - DO NOT FREE IT! * - * @return @c EINA_TRUE if the parameter was found, @c EINA_FALSE otherwise. + * @return EINA_TRUE if the parameter was found, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, Edje_External_Param_Type *type, void **val); /** Get external parameter of type INT. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type INT (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val The value of the parameter. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type INT (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[out] val The value of the parameter. * - * @return @c EINA_TRUE if successful. @c EINA_FALSE if not found or is of different type. + * @return EINA_TRUE if successful. EINA_FALSE if not found or is of different type. */ EAPI Eina_Bool edje_edit_state_external_param_int_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, int *val); /** Get external parameter of type BOOL. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type BOOL (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val The value of the parameter. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type BOOL (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[out] val The value of the parameter. * - * @return @c EINA_TRUE if successful. @c EINA_FALSE if not found or is of different type. + * @return EINA_TRUE if successful. EINA_FALSE if not found or is of different type. */ EAPI Eina_Bool edje_edit_state_external_param_bool_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, Eina_Bool *val); /** Get external parameter of type DOUBLE. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type DOUBLE (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val The value of the parameter. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type DOUBLE (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[out] val The value of the parameter. * - * @return @c EINA_TRUE if successful. @c EINA_FALSE if not found or is of different type. + * @return EINA_TRUE if successful. EINA_FALSE if not found or is of different type. */ EAPI Eina_Bool edje_edit_state_external_param_double_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, double *val); /** Get external parameter of type STRING. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of * type STRING (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val The value of the parameter. + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[out] val The value of the parameter. * - * @return @c EINA_TRUE if successful. @c EINA_FALSE if not found or is of + * @return EINA_TRUE if successful. EINA_FALSE if not found or is of * different type. */ EAPI Eina_Bool edje_edit_state_external_param_string_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, const char **val); /** Get external parameter of type CHOICE. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of * type CHOICE (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val The value of the parameter. + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[out] val The value of the parameter. * - * @return @c EINA_TRUE if successful. @c EINA_FALSE if not found or is of + * @return EINA_TRUE if successful. EINA_FALSE if not found or is of * different type. */ EAPI Eina_Bool edje_edit_state_external_param_choice_get(Evas_Object *obj, const char *part, const char *state, double value, const char *param, const char **val); @@ -3493,16 +2050,16 @@ EAPI Eina_Bool edje_edit_state_external_param_choice_get(Evas_Object *obj, const /** Set the external parameter type and value, adding it if it didn't * exist before. * - * @param obj Object being edited. + * @param[in] obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter (not + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter (not * including the state value). - * @param value The state value. - * @param param The name of the paramter set. - * @param type The type of the parameter. + * @param[in] value The state value. + * @param[in] param The name of the paramter set. + * @param[in] type The type of the parameter. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ /** @@ -3520,544 +2077,70 @@ EAPI Eina_Bool edje_edit_state_external_param_set(Evas_Object *obj, const char * /** Set external parameter of type INT. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of * type INT (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val Value will be stored here. + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[in] val Value will be stored here. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_int_set(Evas_Object *obj, const char *part, const char *state, double value, const char *param, int val); /** Set external parameter of type BOOL. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type BOOL (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val Value will be stored here. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type BOOL (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[in] val Value will be stored here. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_bool_set(Evas_Object *obj, const char *part, const char *state, double value, const char *param, Eina_Bool val); /** Set external parameter of type DOUBLE. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type DOUBLE (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val Value will be stored here. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type DOUBLE (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[in] val Value will be stored here. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_double_set(Evas_Object *obj, const char *part, const char *state, double value, const char *param, double val); /** Set external parameter of type STRING. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type STRING (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val Value will be stored here. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type STRING (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[in] val Value will be stored here. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_string_set(Evas_Object *obj, const char *part, const char *state, double value, const char *param, const char *val); /** Set external parameter of type CHOICE. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get external parameter of type CHOICE (not including the state value). - * @param value The state value. - * @param param The name of the paramter. - * @param val Value will be stored here. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get external parameter of type CHOICE (not including the state value). + * @param[in] value The state value. + * @param[in] param The name of the paramter. + * @param[in] val Value will be stored here. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if it was set, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_external_param_choice_set(Evas_Object *obj, const char *part, const char *state, double value, const char *param, const char *val); -/** Set the states step parameter values. - * - * Step parameter restricts resizing of each dimension to values divisibles by - * its value. This causes the part to jump from value to value while resizing. - * The default value is "0 0" disabling stepping. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal size - * relative value (not including the state value). - * @param value The state value. - * @param step_x The horizontal step value. - * @param step_y The vertical step value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_state_step_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_state_step_set(Evas_Object *obj, const char *part, const char *state, double value, int step_x, int step_y); - -/** Get the states step values. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set fill horizontal size - * relative value (not including the state value). - * @param value The state value. - * @param step_x The pointer to the variable where horizontal step value should be written. - * @param step_y The pointer to the variable where vertical step value should be written. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_state_step_set() - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_state_step_get(Evas_Object *obj, const char *part, const char *state, double value, int *step_x, int *step_y); - -/** Set the states limit parameter value. - * - * Set limit causes the emission of signals when the the size of part changes - * from zero or to a zero size in corresponding to the limit value. - * For example, the signals emitted on width changing are <i>'limit,width,over'</i> - * and <i>'limit,width,zero'</i> - * The availble values are: - * <ul> - * <li>NONE - 0 (the default value)</li> - * <li>WIDTH - 1</li> - * <li>HEIGHT - 2</li> - * <li>BOTH - 3</li> - * </ul> - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * @param limit The value that represents the states limit value in case of success. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_state_limit_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_state_limit_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char limit); - -/** Get the states limit value. - * - * Returns value that represents the states limit value: - * <ul> - * <li>NONE - 0 (the default value)</li> - * <li>WIDTH - 1</li> - * <li>HEIGHT - 2</li> - * <li>BOTH - 3</li> - * </ul> - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * - * @return The value that represents the states limit value in case of success, othervise returns 4. - * @see edje_edit_state_limit_set() - * @since 1.11 - */ -EAPI unsigned char edje_edit_state_limit_get(Evas_Object *obj, const char *part, const char *state, double value); - -//@} -/******************************************************************************/ -/************************** MAP API ************************************/ -/******************************************************************************/ -/** @name Map API - * Functions to deal with objects with rotation properties (see @ref edcref). - */ //@{ - -/** Get the flag which enables mapping for the part. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return @c EINA_TRUE in case if mapping allowed or @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_on_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** This enables mapping for the part. Default is 0. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param on The flag which allow mapping for the part. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_on_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool on); - -/** Get the part's name that is used as the 'perspective point'. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state to get perspective (not including the state value). - * @param value The state value. - * - * @return The name of the source part that is used as 'perspective point'. - * @since 1.11 - */ -EAPI const char * -edje_edit_state_map_perspective_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the part's name that is used as the 'perspective point'. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state to get perspective (not including the state value). - * @param value The state value. - * @param source_part The source part's name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_state_map_perspective_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source_part); - -/** Get the part's name that is used as the 'light' for calculating the brightness. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return The name of the source part that is used as 'light'. - * @since 1.11 - **/ -EAPI const char * -edje_edit_state_map_light_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the part that is used as the 'light'. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param source_part The source part's name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_light_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source_part); - -/** Get backface_cull value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return backface_cull value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_backface_cull_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set backface_cull value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param backface_cull New backface_cull value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_backface_cull_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool backface_cull); - -/** Get perspective_on value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return perspective_on value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_on_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set perspective_on value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param perspective_on New perspective_on value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_on_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool perspective_on); - -/** Get map.alpha value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return map.alpha value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_alpha_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set map.alpha value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param alpha New map.alpha value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_alpha_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool alpha); - -/** Get map.smooth value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return map.smooth value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_smooth_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set map.smooth value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param smooth New map.smooth value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_smooth_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool smooth); - -/** Get map.rotation of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param x x-rotation. - * @param y x-rotation. - * @param z z-rotation. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_rotation_get(Evas_Object *obj, const char *part, const char *state, double value, double *x, double *y, double *z); - -/** Set map.rotation of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param x x-rotation. - * @param y x-rotation. - * @param z z-rotation. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_rotation_set(Evas_Object *obj, const char *part, const char *state, double value, double x, double y, double z); - -/** Get map.perspective.focal value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return map.perspective.focal value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_focal_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set map.perspective.focal value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param focal New map.perspective.focal value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_focal_set(Evas_Object *obj, const char *part, const char *state, double value, int focal); - -/** Get map.perspective.zplane value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return map.perspective.zplane value of given part state. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_zplane_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set map.perspective.zplane value of given part state. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param zplane New map.perspective.zplane value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_perspective_zplane_set(Evas_Object *obj, const char *part, const char *state, double value, int zplane); - -/** Get the part's name that is used as the center rotation. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * - * @return The name of the source part that is used as center rotation. - * @since 1.11 - **/ -EAPI const char * -edje_edit_state_map_rotation_center_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** This sets the part that is used as the center of rotation when rotating the part with this description. If no center is given, the parts original center itself is used for the rotation center. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param source_part The source part's name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_rotation_center_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source_part); - -/** This sets the color for vertex/point of the current part. - * For more detailed information please @see evas_map_point_color_set(). - * - * In edje there is (currently) only 4 main point: - * - Top-Left (0), Top-Right (1), Bottom-Right (2), Bottom-Left (3). - * - * Default value is 255 255 255 255 for every point. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param idx The index of point. - * @param r The red value to set. - * @param g The green color value to set. - * @param b The blue color value to set. - * @param a The alpha color value to set. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_point_color_set(Evas_Object *obj, const char *part, const char *state, double value, int idx, int r, int g, int b, int a); - -/** This gets the color of given vertex/point of the current part. - * For more detailed information please @see evas_map_point_color_set(). - * - * In edje there is (currently) only 4 main point: - * - Top-Left (0), Top-Right (1), Bottom-Right (2), Bottom-Left (3). - * - * Default value is 255 255 255 255 for every point. - * - * @param obj Object being edited. - * @param part The name of the part. - * @param state The name of the state (not including the state value). - * @param value The state value. - * @param idx The index of point. - * @param r The red value to get. - * @param g The green color value to get. - * @param b The blue color value to get. - * @param a The alpha color value to get. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - **/ -EAPI Eina_Bool -edje_edit_state_map_point_color_get(Evas_Object *obj, const char *part, const char *state, double value, int idx, int *r, int *g, int *b, int *a); - -/** Set the source part for given part state. - * - * Set source causes the part to use another part content as the content - * of this part. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * @param source_name The name of part to be set as source. If NULL is passed, the source will be unset. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_state_proxy_source_get() - * @since 1.11 - */ -EAPI Eina_Bool -edje_edit_state_proxy_source_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source_name); - -/** Get the source name for given state of part. - * - * @note The returned string should be freed with @c eina_stringshare_del(). - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state. - * @param value The state value. - * - * @return The name of the source part in case of success. Otherwise returns NULL. - * @see edje_edit_state_proxy_source_set() - * @since 1.11 - */ -EAPI Eina_Stringshare * -edje_edit_state_proxy_source_get(Evas_Object *obj, const char *part, const char *state, double value); //@} /******************************************************************************/ @@ -4071,10 +2154,10 @@ edje_edit_state_proxy_source_get(Evas_Object *obj, const char *part, const char * * Remember to free the returned string with edje_edit_string_free(). * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get text (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get text (not including the state value). + * @param[in] value The state value. * * @return A newly allocated string containing the text for the given state. */ @@ -4082,22 +2165,20 @@ EAPI const char * edje_edit_state_text_get(Evas_Object *obj, const char *part, c /** Set the text of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set text (not including the state value). - * @param value The state value. - * @param text The new text to assign. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set text (not including the state value). + * @param[in] value The state value. + * @param[in] text The new text to assign. */ -EAPI Eina_Bool edje_edit_state_text_set(Evas_Object *obj, const char *part, const char *state, double value,const char *text); +EAPI void edje_edit_state_text_set(Evas_Object *obj, const char *part, const char *state, double value,const char *text); /** Get font name for a given part state. * - * @param obj Object being edited. - * @param part The name of the part to get the font of. - * @param state The state of the part to get the font of. - * @param value Value of the state. + * @param[in] obj Object being edited. + * @param[in] part The name of the part to get the font of. + * @param[in] state The state of the part to get the font of. + * @param[in] value Value of the state. * * @return Font used by the part or NULL if error or nothing is set. */ @@ -4109,22 +2190,20 @@ EAPI const char * edje_edit_state_font_get(Evas_Object *obj, const char *part, c * if it doesn't match any, Edje will look for a font with the given name * in the system fonts. * - * @param obj Object being edited. - * @param part Part to set the font of. - * @param state State in which the font is set. - * @param value Value of the state. - * @param font The font name to use. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part to set the font of. + * @param[in] state State in which the font is set. + * @param[in] value Value of the state. + * @param[in] font The font name to use. */ -EAPI Eina_Bool edje_edit_state_font_set(Evas_Object *obj, const char *part, const char *state, double value, const char *font); +EAPI void edje_edit_state_font_set(Evas_Object *obj, const char *part, const char *state, double value, const char *font); /** Get the text size of a part state * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get text size (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get text size (not including the state value). + * @param[in] value The state value. * * @return The text size or -1 on errors. */ @@ -4132,25 +2211,22 @@ EAPI int edje_edit_state_text_size_get(Evas_Object *obj, const char *part, const /** Set the text size of a part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set text size (not including the state value). - * @param value The state value. - * @param size The new font size to set (in pixel) - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set text size (not including the state value). + * @param[in] value The state value. + * @param[in] size The new font size to set (in pixel) */ -EAPI Eina_Bool edje_edit_state_text_size_set(Evas_Object *obj, const char *part, const char *state, double value, int size); +EAPI void edje_edit_state_text_size_set(Evas_Object *obj, const char *part, const char *state, double value, int size); /** Get the text horizontal align of a part state. * * The value range is from 0.0(right) to 1.0(left) - * If the value is between -1.0 and 0.0 then it uses align automatically. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the text horizontal align (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the text horizontal align (not including the state value). + * @param[in] value The state value. * * @return The text horizont align value */ @@ -4160,10 +2236,10 @@ EAPI double edje_edit_state_text_align_x_get(Evas_Object *obj, const char *part, * * The value range is from 0.0(top) to 1.0(bottom) * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the text vertical align (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the text vertical align (not including the state value). + * @param[in] value The state value. * * @return The text horizont align value */ @@ -4172,40 +2248,35 @@ EAPI double edje_edit_state_text_align_y_get(Evas_Object *obj, const char *part, /** Set the text horizontal align of a part state. * * The value range is from 0.0(right) to 1.0(left) - * If the value is between -1.0 and 0.0 then it uses align automatically. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the text horizontal align (not including the state value). - * @param value The state value. - * @param align The new text horizontal align value - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the text horizontal align (not including the state value). + * @param[in] value The state value. + * @param[in] align The new text horizontal align value */ -EAPI Eina_Bool edje_edit_state_text_align_x_set(Evas_Object *obj, const char *part, const char *state, double value, double align); +EAPI void edje_edit_state_text_align_x_set(Evas_Object *obj, const char *part, const char *state, double value, double align); /** Set the text vertical align of a part state. * * The value range is from 0.0(top) to 1.0(bottom) * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the text vertical align (not including the state value). - * @param value The state value. - * @param align The new text vertical align value - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the text vertical align (not including the state value). + * @param[in] value The state value. + * @param[in] align The new text vertical align value */ -EAPI Eina_Bool edje_edit_state_text_align_y_set(Evas_Object *obj, const char *part, const char *state, double value, double align); +EAPI void edje_edit_state_text_align_y_set(Evas_Object *obj, const char *part, const char *state, double value, double align); /** Get the text elipsis of a part state. * - * The value range is from 0.0(right) to 1.0(left), and -1.0 (if disabled) + * The value range is from 0.0(right) to 1.0(left) * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the text elipses value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the text elipses value (not including the state value). + * @param[in] value The state value. * * @return The text elipsis value */ @@ -4214,326 +2285,62 @@ EAPI double edje_edit_state_text_elipsis_get(Evas_Object *obj, const char *part, /** Set the text vertical align of a part state. * * The value range is from 0.0(right) to 1.0(left) - * If the value is in range from -1.0 to 0.0 then ellipsis is disabled. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the text elipses value (not including the state value). - * @param value The state value. - * @param balance The position where to cut the string * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the text elipses value (not including the state value). + * @param[in] value The state value. + * @param[in] balance The position where to cut the string */ -EAPI Eina_Bool edje_edit_state_text_elipsis_set(Evas_Object *obj, const char *part, const char *state, double value, double balance); +EAPI void edje_edit_state_text_elipsis_set(Evas_Object *obj, const char *part, const char *state, double value, double balance); /** Get if the text part fit it's container horizontally * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the if the text part fit it's container horizontally (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the if the text part fit it's container horizontally (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE If the part fit it's container horizontally, @c EINA_FALSE otherwise. + * @return EINA_TRUE If the part fit it's container horizontally, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_text_fit_x_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set if the text part should fit it's container horizontally * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the if the text part fit it's container horizontally (not including the state value). - * @param value The state value. - * @param fit EINA_TRUE to make the text fit it's container horizontally, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the if the text part fit it's container horizontally (not including the state value). + * @param[in] value The state value. + * @param[in] fit EINA_TRUE to make the text fit it's container horizontally, EINA_FALSE otherwise. */ -EAPI Eina_Bool edje_edit_state_text_fit_x_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fit); +EAPI void edje_edit_state_text_fit_x_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fit); /** Get if the text part fit it's container vertically * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the if the text part fit it's container vertically (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the if the text part fit it's container vertically (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE If the part fit it's container vertically, @c EINA_FALSE otherwise. + * @return EINA_TRUE If the part fit it's container vertically, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_text_fit_y_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set if the text part should fit it's container vertically * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the if the text part fit it's container vertically (not including the state value). - * @param value The state value. - * @param fit EINA_TRUE to make the text fit it's container vertically, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_fit_y_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fit); - -/** Get if the text part forces the minimum horizontal size of the container to be equal to the minimum horizontal size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the the minimum horizontal size of the container to be equal (not including the state value). - * @param value The state value. - * - * @return @c EINA_TRUE If the part forces container's minimum horizontal size, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_min_x_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Get if the text part forces the maximum horizontal size of the container to be equal to the maximum horizontal size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the the minimum horizontal size of the container to be equal (not including the state value). - * @param value The state value. - * - * @return @c EINA_TRUE If the part forces container's maximum horizontal size, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_max_x_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Get if the text part forces the minimum vertical size of the container to be equal to the minimum vertical size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the the minimum vertical size of the container to be equal (not including the state value). - * @param value The state value. - * - * @return @c EINA_TRUE If the part forces container's minimum vertical size, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_min_y_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Get if the text part forces the maximum vertical size of the container to be equal to the maximum vertical size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the the maximum vertical size of the container to be equal (not including the state value). - * @param value The state value. - * - * @return @c EINA_TRUE If the part forces container's maximum vertical size, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_max_y_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set if the text part forces the minimum horizontal size of the container to be equal to the minimum horizontal size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the minimum horizontal size of the container to be equal (not including the state value). - * @param value The state value. - * @param v EINA_TRUE to make the text force it's forces container's minimum horizontal size, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_min_x_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool v); - -/** Set if the text part forces the maximum horizontal size of the container to be equal to the maximum horizontal size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum horizontal size of the container to be equal (not including the state value). - * @param value The state value. - * @param v EINA_TRUE to make the text force it's forces container's maximum horizontal size, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_max_x_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool v); - -/** Set if the text part forces the minimum vertical size of the container to be equal to the minimum vertical size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the minimum vertical size of the container to be equal (not including the state value). - * @param value The state value. - * @param v EINA_TRUE to make the text force it's forces container's minimum vertical size, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_min_y_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool v); - -/** Set if the text part forces the maximum vertical size of the container to be equal to the maximum vertical size of the text part - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum vertical size of the container to be equal (not including the state value). - * @param value The state value. - * @param v EINA_TRUE to make the text force it's forces container's maximum vertical size, @c EINA_FALSE otherwise. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_state_text_max_y_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool v); - -/** Get style name for a given part state. - * - * @param obj Object being edited. - * @param part The name of the part to get the style of. - * @param state The state of the part to get the style of. - * @param value Value of the state. - * - * @return Style used by the part or NULL if error or nothing is set. - */ -EAPI const char * -edje_edit_state_text_style_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set style name for a given part state. - * - * Causes the part to use the default style and tags defined in the "style" block with the specified name. - * - * @param obj Object being edited. - * @param part Part to set the style of. - * @param state State in which the style is set. - * @param value Value of the state. - * @param style The style name to use. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_style_set(Evas_Object *obj, const char *part, const char *state, double value, const char *style); - -/** Get part name, which used as text source. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum vertical size of - * the container to be equal (not including the state value). - * @param value Value of the state. - * - * @return The name of part or NULL, if text_source param not a setted. - */ -EAPI const char * -edje_edit_state_text_text_source_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the source text part for a given part. - * Causes the part to display the content text of another part and update - * them as they change. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum vertical size of - * the container to be equal (not including the state value). - * @param value Value of the state. - * @param source The text source part name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_text_source_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source); - -/** Get part name, which used as style text source. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum vertical size of - * @param value Value of the state. - * the container to be equal (not including the state value). - * - * @return The name of part or NULL, if text_source param not a setted. - */ -EAPI const char * -edje_edit_state_text_source_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the source part which would be used as style for text for a given part. - * Causes the part to use the text properties (like font and size) of another - * part and update them as they change. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the the maximum vertical size of - * the container to be equal (not including the state value). - * @param value Value of the state. - * @param source The text source part name. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_source_set(Evas_Object *obj, const char *part, const char *state, double value, const char *source); - -/** Get the text class of the given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get text class (not including the state value). - * @param value The state value. - * - * @return The current text class. - */ -EAPI const char * -edje_edit_state_text_class_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the text class of the given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set text class (not including the state value). - * @param value The state value. - * @param text_class The text class to assign. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_class_set(Evas_Object *obj, const char *part, const char *state, double value, const char *text_class); - -/** Get the replacement character string of the given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get replacement character - * (not including the state value). - * @param value The state value. - * - * @return The current replacement character. - */ -EAPI const char * -edje_edit_state_text_repch_get(Evas_Object *obj, const char *part, const char *state, double value); - -/** Set the replacement character string of the given part state. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get replacement character - * (not including the state value). - * @param value The state value. - * @param repch The replacement character string to assign. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the if the text part fit it's container vertically (not including the state value). + * @param[in] value The state value. + * @param[in] fit EINA_TRUE to make the text fit it's container vertically, EINA_FALSE otherwise. */ -EAPI Eina_Bool -edje_edit_state_text_repch_set(Evas_Object *obj, const char *part, const char *state, double value, const char *repch); - -/** Get the min and max font size allowed for the text part. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state State in which the part is set. - * @param value Value of the state. - * @param min Minimal value of the font size in points (pt). - * @param max Maximum value of the font size in points (pt). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_size_range_min_max_get(Evas_Object *obj, const char *part, const char *state, double value, int *min, int *max); - -/** Set the min and max font size allowed for the text part. - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state State in which the part is set. - * @param value Value of the state. - * @param min Minimal value of the font size in points (pt). - * @param max Maximum value of the font size in points (pt). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_state_text_size_range_min_max_set(Evas_Object *obj, const char *part, const char *state, double value, int min, int max); +EAPI void edje_edit_state_text_fit_y_set(Evas_Object *obj, const char *part, const char *state, double value, Eina_Bool fit); /** Get the list of all the fonts in the given edje. * * Use edje_edit_string_list_free() when you don't need the list anymore. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return A list containing all the fonts names found in the edje file. */ @@ -4543,11 +2350,11 @@ EAPI Eina_List * edje_edit_fonts_list_get(Evas_Object *obj); * * The newly created font will be available to all the groups in the edje, not only the current one. * - * @param obj Object being edited. - * @param path The file path to load the font from. - * @param alias The alias for file, or NULL to use filename + * @param[in] obj Object being edited. + * @param[in] path The file path to load the font from. + * @param[in] alias The alias for file, or NULL to use filename * - * @return @c EINA_TRUE if font cat be loaded, @c EINA_FALSE otherwise. + * @return EINA_TRUE if font cat be loaded, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_font_add(Evas_Object *obj, const char *path, const char* alias); @@ -4555,10 +2362,10 @@ EAPI Eina_Bool edje_edit_font_add(Evas_Object *obj, const char *path, const char * * The font will be removed from all the groups in the edje, not only the current one. * - * @param obj Object being edited. - * @param alias The font alias + * @param[in] obj Object being edited. + * @param[in] alias The font alias * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.(including the + * @return EINA_TRUE if successful, EINA_FALSE otherwise (including the * case when the alias is not valid). */ EAPI Eina_Bool edje_edit_font_del(Evas_Object *obj, const char* alias); @@ -4567,8 +2374,8 @@ EAPI Eina_Bool edje_edit_font_del(Evas_Object *obj, const char* alias); * * Remember to free the string with edje_edit_string_free() * - * @param obj Object being edited. - * @param alias The font alias. + * @param[in] obj Object being edited. + * @param[in] alias The font alias. * * @return The path of the given font alias. */ @@ -4579,15 +2386,26 @@ EAPI const char *edje_edit_font_path_get(Evas_Object *obj, const char *alias); * * Remember to free the returned string using edje_edit_string_free(). * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the name of the font used (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the name of the font used (not including the state value). + * @param[in] value The state value. * * @return The name of the font used in the given part state. */ EAPI const char * edje_edit_state_font_get(Evas_Object *obj, const char *part, const char *state, double value); +/** Set font name for a given part state. + * + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the name of the font that will be used (not including the state value). + * @param[in] value The state value. + * @param[in] font The name of the font to use in the given part state. + */ +EAPI void edje_edit_state_font_set(Evas_Object *obj, const char *part, const char *state, double value, const char *font); + + //@} /******************************************************************************/ /************************** IMAGES API ************************************/ @@ -4599,7 +2417,7 @@ EAPI const char * edje_edit_state_font_get(Evas_Object *obj, const char *part, c /** Get the list of all the images in the given edje. * Use edje_edit_string_list_free() when you don't need the list anymore. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return A List containing all images names found in the edje file. */ @@ -4616,56 +2434,25 @@ EAPI Eina_List * edje_edit_images_list_get(Evas_Object *obj); * * The format of the image files that can be loaded depend on the evas engine on your system * - * @param obj Object being edited. - * @param path The name of the image file to include in the edje. + * @param[in] obj Object being edited. + * @param[in] path The name of the image file to include in the edje. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_image_add(Evas_Object *obj, const char *path); /** Delete an image from the image collection * * It actually write directly to the file so you don't have to save. - * Can't delete image if it is used by any part. * - * @param obj Object being edited. - * @param name The name of the image file to include in the edje. + * @param[in] obj Object being edited. + * @param[in] name The name of the image file to include in the edje. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.(including the - * case when the name is not valid or image is in use). + * @return EINA_TRUE if successful, EINA_FALSE otherwise (including the + * case when the name is not valid). */ EAPI Eina_Bool edje_edit_image_del(Evas_Object *obj, const char *name); -/** Replace one image in all descriptions - * - * @param obj Object being edited. - * @param name The name of the image to replace. - * @param new_name The new_name of the image to replace with. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.(including the - * case when one of the names is not valid) - */ -EAPI Eina_Bool edje_edit_image_replace(Evas_Object *obj, const char *name, const char *new_name); - -/** Get list of (Edje_Part_Image_Use *) - group-part-state triplets where given - * image is used - * - * Use edje_edit_image_usage_list_free() when you don't need it anymore. - * - * @param obj Object being edited. - * @param name The name of the image. - * @param first_only If EINA_TRUE, return only one triplete. - * - * @return Eina_List containing Edje_Part_Image_Use if successful, NULL otherwise - */ -EAPI Eina_List* edje_edit_image_usage_list_get(Evas_Object *obj, const char *name, Eina_Bool first_only); - -/** Free an Eina_List of (Edje_Part_Image_Use *) allocated by an edje_edit_image_usage_list_get() function. - * - * @param lst List of strings to free. - */ -EAPI void edje_edit_image_usage_list_free(Eina_List *lst); - /** Add an image entry to the image collection * * This function adds the given image entry to the edje image collection. The @@ -4674,20 +2461,20 @@ EAPI void edje_edit_image_usage_list_free(Eina_List *lst); * "name". Note that all the parts in the edje share the same image collection, * thus you can/must use the same image for different part. * - * @param obj Object being edited. - * @param name The image entry name. - * @param id The image id. + * @param[in] obj Object being edited. + * @param[in] name The image entry name. + * @param[in] id The image id. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_image_data_add(Evas_Object *obj, const char *name, int id); /** Get normal image name for a given part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the name that is being used (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the name that is being used (not including the state value). + * @param[in] value The state value. * * @return The name of the image used by state. */ @@ -4695,20 +2482,18 @@ EAPI const char * edje_edit_state_image_get(Evas_Object *obj, const char *part, /** Set normal image for a given part state. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the image that will be used (not including the state value). - * @param value The state value. - * @param image The name of the image (must be an image contained in the edje file). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the image that will be used (not including the state value). + * @param[in] value The state value. + * @param[in] image The name of the image (must be an image contained in the edje file). */ -EAPI Eina_Bool edje_edit_state_image_set(Evas_Object *obj, const char *part, const char *state, double value, const char *image); +EAPI void edje_edit_state_image_set(Evas_Object *obj, const char *part, const char *state, double value, const char *image); /** Get image id for a given image name. * - * @param obj Object being edited. - * @param image_name The image name. + * @param[in] obj Object being edited. + * @param[in] image_name The image name. * * @return The id of the given image name. */ @@ -4716,32 +2501,21 @@ EAPI int edje_edit_image_id_get(Evas_Object *obj, const char *image_name); /** Get compression type for the given image. * - * @param obj Object being edited. - * @param image The name of the image. + * @param[in] obj Object being edited. + * @param[in] image The name of the image. * * @return One of Image Compression types. - * (EDJE_EDIT_IMAGE_COMP_RAW, EDJE_EDIT_IMAGE_COMP_USER, EDJE_EDIT_IMAGE_COMP_COMP, EDJE_EDIT_IMAGE_COMP_LOSSY[_ETC1]). + * (EDJE_EDIT_IMAGE_COMP_RAW, EDJE_EDIT_IMAGE_COMP_USER, EDJE_EDIT_IMAGE_COMP_COMP, EDJE_EDIT_IMAGE_COMP_LOSSY). */ EAPI Edje_Edit_Image_Comp edje_edit_image_compression_type_get(Evas_Object *obj, const char *image); -/** Set compression type for the given image. - * - * @param obj Object being edited. - * @param image The name of the image. - * @param ic Edje_Edit_Image_Comp. - * (EDJE_EDIT_IMAGE_COMP_RAW, EDJE_EDIT_IMAGE_COMP_USER, EDJE_EDIT_IMAGE_COMP_COMP, EDJE_EDIT_IMAGE_COMP_LOSSY[_ETC1]). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_image_compression_type_set(Evas_Object *obj, const char *image, Edje_Edit_Image_Comp ic); - /** Get compression rate for the given image. * - * @param obj Object being edited. - * @param image The name of the image. + * @param[in] obj Object being edited. + * @param[in] image The name of the image. * * @return The compression rate (if the imnage is @c - * EDJE_EDIT_IMAGE_COMP_LOSSY[_ETC1]) or < 0, on errors. + * EDJE_EDIT_IMAGE_COMP_LOSSY) or < 0, on errors. */ EAPI int edje_edit_image_compression_rate_get(Evas_Object *obj, const char *image); @@ -4749,15 +2523,15 @@ EAPI int edje_edit_image_compression_rate_get(Evas_Object *obj, const char *imag * * Pass NULL to any of [r,g,b,a] to get only the others. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the image border (not + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the image border (not * including the state value). - * @param value The state value. - * @param l A pointer to store the left value - * @param r A pointer to store the right value - * @param t A pointer to store the top value - * @param b A pointer to store the bottom value + * @param[in] value The state value. + * @param[out] l A pointer to store the left value + * @param[out] r A pointer to store the right value + * @param[out] t A pointer to store the top value + * @param[out] b A pointer to store the bottom value */ EAPI void edje_edit_state_image_border_get(Evas_Object *obj, const char *part, const char *state, double value, int *l, int *r, int *t, int *b); @@ -4765,59 +2539,51 @@ EAPI void edje_edit_state_image_border_get(Evas_Object *obj, const char *part, c * * Pass -1 to any of [l,r,t,b] to leave the value untouched. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the image border (not + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the image border (not * including the state value). - * @param value The state value. - * @param l Left border value (or -1). - * @param r Right border value (or -1). - * @param t Top border value (or -1). - * @param b Bottom border value (or -1). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] value The state value. + * @param[in] l Left border value (or -1). + * @param[in] r Right border value (or -1). + * @param[in] t Top border value (or -1). + * @param[in] b Bottom border value (or -1). */ -EAPI Eina_Bool edje_edit_state_image_border_set(Evas_Object *obj, const char *part, const char *state, double value, int l, int r, int t, int b); +EAPI void edje_edit_state_image_border_set(Evas_Object *obj, const char *part, const char *state, double value, int l, int r, int t, int b); /** Get if the image center should be draw. * - * 1 or 2 means to draw the center, 0 to don't draw it. - * If 1 - then the center will apply alpha channel. - * If 2 (SOLID mode) - then the center of an image wont have alpha channel (Just black color). + * 1 means to draw the center, 0 to don't draw it. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the image border fill (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the image border fill (not including the state value). + * @param[in] value The state value. * - * @return 2 if the center of the bordered image is draw without alpha, 1 dawing with alpha and 0 not drawing the center. + * @return 1 if the center of the bordered image is draw, 0 otherwise. */ EAPI unsigned char edje_edit_state_image_border_fill_get(Evas_Object *obj, const char *part, const char *state, double value); /** Set if the image center should be draw. * - * 1 or 2 means to draw the center, 0 to don't draw it. - * If 1 - then the center will apply alpha channel. - * If 2 (SOLID mode) - then the center of an image wont have alpha channel (Just black color). - * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to set the image border fill (not including the state value). - * @param value The state value. - * @param fill Fill to be set. 1 or 2 if the center of the bordered image is draw, 0 otherwise. + * 1 means to draw the center, 0 to don't draw it. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to set the image border fill (not including the state value). + * @param[in] value The state value. + * @param[in] fill Fill to be se. 1 if the center of the bordered image is draw, 0 otherwise. */ -EAPI Eina_Bool edje_edit_state_image_border_fill_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char fill); +EAPI void edje_edit_state_image_border_fill_set(Evas_Object *obj, const char *part, const char *state, double value, unsigned char fill); /** Get the list of all the tweens images in the given part state. * * Use edje_edit_string_list_free() when you don't need it anymore. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to get the list of all the tweens images (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to get the list of all the tweens images (not including the state value). + * @param[in] value The state value. * * @return A string list containing all the image name that form a tween animation in the given part state. */ @@ -4827,13 +2593,13 @@ EAPI Eina_List * edje_edit_state_tweens_list_get(Evas_Object *obj, const char *p * * The tween param must be the name of an existing image. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to add a new tween frame (not including the state value). - * @param value The state value. - * @param tween The name of the image to add. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to add a new tween frame (not including the state value). + * @param[in] value The state value. + * @param[in] tween The name of the image to add. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_tween_add(Evas_Object *obj, const char *part, const char *state, double value, const char *tween); @@ -4841,196 +2607,16 @@ EAPI Eina_Bool edje_edit_state_tween_add(Evas_Object *obj, const char *part, con * * The image is not removed from the edje. * - * @param obj Object being edited. - * @param part Part that contain state. - * @param state The name of the state to del the tween (not including the state value). - * @param value The state value. - * @param tween The name of the image to del. + * @param[in] obj Object being edited. + * @param[in] part Part that contain state. + * @param[in] state The name of the state to del the tween (not including the state value). + * @param[in] value The state value. + * @param[in] tween The name of the image to del. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_tween_del(Evas_Object *obj, const char *part, const char *state, double value, const char *tween); -//@} -/******************************************************************************/ -/************************** SOUNDS API ************************************/ -/******************************************************************************/ -/** @name Sounds API - * Functions to deal with sound objects (see @ref edcref). - */ //@{ - -/** Get the list of all the sounds samples in the given edje. - * Use edje_edit_string_list_free() when you don't need the list anymore. - * - * @param obj Object being edited. - * - * @return A List containing all sounds samples names found in the edje file. - * @since 1.11 - */ -EAPI Eina_List * edje_edit_sound_samples_list_get(Evas_Object *obj); - -/** Get the list of all the sounds tones in the given edje. - * Use edje_edit_string_list_free() when you don't need the list anymore. - * - * @param obj Object being edited. - * - * @return A List containing all sounds tones names found in the edje file. - * @since 1.11 - */ -EAPI Eina_List * edje_edit_sound_tones_list_get(Evas_Object *obj); - -/** Add new sound sample to samples collection - * - * This function adds the given sound file to the edje collection. - * The added sound sample could be used by PLAY_SAMPLE action in any program - * of any group that is in the current collection. - * The quality of added sound by default is uncompressed (RAW). - * - * The available formats list of the sound files that can be loaded depends - * on the evas engine on your system. - * - * @param obj Object being edited. - * @param name The name that will identify sample. - * @param snd_src The name of the sound file to add. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_sound_sample_del() - * @since 1.11 - */ -Eina_Bool -edje_edit_sound_sample_add(Evas_Object *obj, const char* name, const char* snd_src); - -/** Delete sound sample from the collection - * - * Deletes sound sample from collection by its name. After successfull deletion - * all PLAY_SAMPLE actions in all programs of all groups of current collection - * that use deleted sound will be deleted. - * - * @param obj Object being edited. - * @param name The name of the sound to be deleted from the edje. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_sound_sample_add() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_sample_del(Evas_Object *obj, const char *name); - -/** Add new tone to the collection - * - * This function adds new tone with given frequency to the edje collection. - * The added sound sample could be used by PLAY_TONE action in any program - * of any group that is in the current collection. - * - * @param obj Object being edited. - * @param name The name that will identify tone. - * @param frequency Frequency of added tone. This value should be in range of 20 to 20000 inclusive. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - * @see edje_edit_sound_tone_del() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_tone_add(Evas_Object *obj, const char* name, int frequency); - -/** Delete tone from the collection - * - * Deletes tone from collection by its name. After successfull deletion - * all PLAY_TONE actions in all programs of all groups of current collection - * that use deleted sound will be deleted. - * - * @param obj Object being edited. - * @param name The name of the tone to be deleted from the edje. - * - * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise. - * @see edje_edit_sound_tone_add() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_tone_del(Evas_Object *obj, const char* name); - -/** Get the sound quality compression. - * - * @param obj Object being edited. - * @param sound The name of the sample. - * - * @return Quality of the compression of the sample sound. - * @since 1.11 - */ -EAPI double edje_edit_sound_compression_rate_get(Evas_Object *obj, const char* sound); - -/** Set the sound quality compression. - * - * @param obj Object being edited. - * @param sound The name of the sample. - * @param rate Quality of the compression. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_compression_rate_set(Evas_Object *obj, const char* sound, double rate); - -/** Set the frequency of tone. - * - * @param obj Object being edited. - * @param name The name of the tone. - * @param frequency The value of frequency of tone. This value has to be in range of 20 to 20000 inclusive. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @see edje_edit_sound_tone_frequency_get() - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_tone_frequency_set(Evas_Object *obj, const char *name, int frequency); - -/** Get the frequency of tone. - * - * @param obj Object being edited. - * @param name The name of the tone. - * - * @return The frequency of tone if succesful, otherwise returns -1. - * @see edje_edit_sound_tone_frequency_set() - * @since 1.11 - */ -EAPI int edje_edit_sound_tone_frequency_get(Evas_Object *obj, const char *name); - -/** Get the sound type compression. - * - * @param obj Object being edited. - * @param name The name of the sample. - * - * @return Compression type of the sample sound. - * @since 1.11 - */ -EAPI Edje_Edit_Sound_Comp edje_edit_sound_compression_type_get(Evas_Object *obj, const char* name); - -/** Set the sound type compression. - * - * @param obj Object being edited. - * @param name The name of the sample. - * @param sc Edje_Edit_Sound_Comp - * (@c EDJE_EDIT_SOUND_COMP_RAW, @c EDJE_EDIT_SOUND_COMP_COMP, @c EDJE_EDIT_SOUND_COMP_LOSSY, @c EDJE_EDIT_SOUND_COMP_AS_IS). - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - * @since 1.11 - */ -EAPI Eina_Bool edje_edit_sound_compression_type_set(Evas_Object *obj, const char* name, Edje_Edit_Sound_Comp sc); - -/** Get the certain sound data from the edje object. - * - * @param obj Object being edited. - * @param sample_name The name of the sound. - * - * @return buf The buffer that contains data of the sound. To free the resources use eina_binbuf_free(). - * @since 1.11 - */ -EAPI Eina_Binbuf *edje_edit_sound_samplebuffer_get(Evas_Object *obj, const char *sample_name); - -/** Get the name of sample source. - * - * @param obj Object being edited. - * @param sample_name The name of the sample. - * - * @return snd_src The sample source name. - * @since 1.11 - */ -EAPI const char *edje_edit_sound_samplesource_get(Evas_Object *obj, const char *sample_name); //@} /******************************************************************************/ @@ -5044,7 +2630,7 @@ EAPI const char *edje_edit_sound_samplesource_get(Evas_Object *obj, const char * * * Use edje_edit_string_list_free() when you don't need it anymore. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return A list containing all the spectra names. */ @@ -5052,36 +2638,36 @@ EAPI Eina_List * edje_edit_spectrum_list_get(Evas_Object *obj); /** Add a new spectra in the given edje object. * - * @param obj Object being edited. - * @param name The name of the spectra to include in the edje. + * @param[in] obj Object being edited. + * @param[in] name The name of the spectra to include in the edje. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_spectra_add(Evas_Object *obj, const char *name); /** Delete the given spectra from the edje object. * - * @param obj Object being edited. - * @param spectra The name of the spectra to delete. + * @param[in] obj Object being edited. + * @param[in] spectra The name of the spectra to delete. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_spectra_del(Evas_Object *obj, const char *spectra); /** Change the name of the given spectra. * - * @param obj Object being edited. - * @param spectra The name of the current spectra. - * @param name The new name to assign. + * @param[in] obj Object being edited. + * @param[in] spectra The name of the current spectra. + * @param[in] name The new name to assign. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_spectra_name_set(Evas_Object *obj, const char *spectra, const char *name); /** Get the number of stops in the given spectra. * - * @param obj Object being edited. - * @param spectra The name of the spectra. + * @param[in] obj Object being edited. + * @param[in] spectra The name of the spectra. * * @return The number of stops (or 0 on errors). */ @@ -5089,41 +2675,39 @@ EAPI int edje_edit_spectra_stop_num_get(Evas_Object *obj, const char *spectra); /** Set the number of stops in the given spectra. * - * @param obj Object being edited. - * @param spectra The name of the spectra. - * @param num The number of stops you want + * @param[in] obj Object being edited. + * @param[in] spectra The name of the spectra. + * @param[in] num The number of stops you want * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_spectra_stop_num_set(Evas_Object *obj, const char *spectra, int num); /** Get the colors of the given stop. * - * @param obj Object being edited. - * @param spectra The name of the spectra. - * @param stop_number The number of the stop, - * @param r Where to store the red color value, - * @param g Where to store the green color value, - * @param b Where to store the blue color value, - * @param a Where to store the alpha color value, - * @param d Where to store the delta stop value, + * @param[in] obj Object being edited. + * @param[in] spectra The name of the spectra. + * @param[in] stop_number The number of the stop, + * @param[out] r Where to store the red color value, + * @param[out] g Where to store the green color value, + * @param[out] b Where to store the blue color value, + * @param[out] a Where to store the alpha color value, + * @param[out] d Where to store the delta stop value, * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_spectra_stop_color_get(Evas_Object *obj, const char *spectra, int stop_number, int *r, int *g, int *b, int *a, int *d); /** Set the colors of the given stop. * - * @param obj Object being edited. - * @param spectra The name of the spectra. - * @param stop_number The number of the stops, - * @param r The red color value to set, - * @param g The green color value to set, - * @param b The blue color value to set, - * @param a The alpha color value to set, - * @param d The delta stop value to set, - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] spectra The name of the spectra. + * @param[in] stop_number The number of the stops, + * @param[in] r The red color value to set, + * @param[in] g The green color value to set, + * @param[in] b The blue color value to set, + * @param[in] a The alpha color value to set, + * @param[in] d The delta stop value to set, */ EAPI Eina_Bool edje_edit_spectra_stop_color_set(Evas_Object *obj, const char *spectra, int stop_number, int r, int g, int b, int a, int d); @@ -5140,10 +2724,10 @@ EAPI Eina_Bool edje_edit_spectra_stop_color_set(Evas_Object *obj, const char *sp * * Remember to free the string with edje_edit_string_free(). * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get the gradient type (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get the gradient type (not including the state value). + * @param[in] value The state value. * * @return The type of gradient used in state. * (linear, linear.diag, linear.codiag, radial, rectangular, angular, sinosoidal) @@ -5154,24 +2738,24 @@ EAPI const char * edje_edit_state_gradient_type_get(Evas_Object *obj, const char * * Gradient type can be on of the following: linear, linear.diag, linear.codiag, radial, rectangular, angular, sinusoidal * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set the gradient type (not including the state value). - * @param value The state value. - * @param type The type of gradient to use. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set the gradient type (not including the state value). + * @param[in] value The state value. + * @param[in] type The type of gradient to use. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_type_set(Evas_Object *obj, const char *part, const char *state, double value, const char *type); /** Get if the current gradient use the fill properties or the gradient_rel as params. * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set the gradient type (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set the gradient type (not including the state value). + * @param[in] value The state value. * - * @return @c EINA_TRUE if gradient use the fill properties, @c EINA_FALSE otherwise. + * @return EINA_TRUE if gradient use the fill properties, EINA_FALSE otherwise. * */ EAPI Eina_Bool edje_edit_state_gradient_use_fill_get(Evas_Object *obj, const char *part, const char *state, double value); @@ -5179,10 +2763,10 @@ EAPI Eina_Bool edje_edit_state_gradient_use_fill_get(Evas_Object *obj, const cha * * Remember to free the string with edje_edit_string_free(). * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get the spectra name used (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get the spectra name used (not including the state value). + * @param[in] value The state value. * * @return The spectra name used in state. */ @@ -5190,22 +2774,22 @@ EAPI const char * edje_edit_state_gradient_spectra_get(Evas_Object *obj, const c /** Set the spectra used by part state. * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set the spectra (not including the state value). - * @param value The state value. - * @param spectra The spectra name to assign + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set the spectra (not including the state value). + * @param[in] value The state value. + * @param[in] spectra The spectra name to assign * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_spectra_set(Evas_Object *obj, const char *part, const char *state, double value, const char *spectra); /** Get the angle of the gradient. * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get the angle (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get the angle (not including the state value). + * @param[in] value The state value. * * @return The angle of the gradient. */ @@ -5213,20 +2797,20 @@ EAPI int edje_edit_state_gradient_angle_get(Evas_Object *obj, const char *part, /** Set the angle of the gradient. * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set the angle (not including the state value). - * @param value The state value. - * @param angle The angle to set. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set the angle (not including the state value). + * @param[in] value The state value. + * @param[in] angle The angle to set. */ EAPI void edje_edit_state_gradient_angle_set(Evas_Object *obj, const char *part, const char *state, double value, int angle); /** Get the gradient rel1 horizontal relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel1 relative x value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel1 relative x value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel1 horizontal relative value. */ @@ -5234,10 +2818,10 @@ EAPI double edje_edit_state_gradient_rel1_relative_x_get(Evas_Object *obj, const /** Get the gradient rel1 vertical relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel1 relative y value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel1 relative y value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel1 vertical relative value. */ @@ -5245,10 +2829,10 @@ EAPI double edje_edit_state_gradient_rel1_relative_y_get(Evas_Object *obj, const /** Get the gradient rel2 horizontal relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel2 relative x value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel2 relative x value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel2 horizontal relative value. */ @@ -5256,10 +2840,10 @@ EAPI double edje_edit_state_gradient_rel2_relative_x_get(Evas_Object *obj, const /** Get the gradient rel2 vertical relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel2 relative y value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel2 relative y value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel2 vertical relative value. */ @@ -5268,59 +2852,59 @@ EAPI double edje_edit_state_gradient_rel2_relative_y_get(Evas_Object *obj, const /** Set the gradient rel1 horizontal relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel1 relative x value (not including the state value). - * @param value The state value. - * @param val The rel1 relative x to be set, + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel1 relative x value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel1 relative x to be set, * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.. + * @return EINA_TRUE if successful, EINA_FALSE otherwise.. */ EAPI Eina_Bool edje_edit_state_gradient_rel1_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double val); /** Set the gradient rel1 vertical relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel1 relative y value (not including the state value). - * @param value The state value. - * @param val The rel1 relative y to be set, + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel1 relative y value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel1 relative y to be set, * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.. + * @return EINA_TRUE if successful, EINA_FALSE otherwise.. */ EAPI Eina_Bool edje_edit_state_gradient_rel1_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double val); /** Set the gradient rel2 horizontal relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel2 relative x value (not including the state value). - * @param value The state value. - * @param val The rel2 relative x to be set, + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel2 relative x value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel2 relative x to be set, * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.. + * @return EINA_TRUE if successful, EINA_FALSE otherwise.. */ EAPI Eina_Bool edje_edit_state_gradient_rel2_relative_x_set(Evas_Object *obj, const char *part, const char *state, double value, double val); /** Set the gradient rel2 vertical relative value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel2 relative y value (not including the state value). - * @param value The state value. - * @param val The rel2 relative y to be set, + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel2 relative y value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel2 relative y to be set, * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise.. + * @return EINA_TRUE if successful, EINA_FALSE otherwise.. */ EAPI Eina_Bool edje_edit_state_gradient_rel2_relative_y_set(Evas_Object *obj, const char *part, const char *state, double value, double val); /** Get the gradient rel1 horizontal offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel1 offset x value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel1 offset x value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel1 horizontal offset value. */ @@ -5328,10 +2912,10 @@ EAPI int edje_edit_state_gradient_rel1_offset_x_get(Evas_Object *obj, const char /** Get the gradient rel1 vertical offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel1 offset y value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel1 offset y value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel1 vertical offset value. */ @@ -5339,10 +2923,10 @@ EAPI int edje_edit_state_gradient_rel1_offset_y_get(Evas_Object *obj, const char /** Get the gradient rel2 horizontal offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel2 offset x value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel2 offset x value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel2 horizontal offset value. */ @@ -5350,10 +2934,10 @@ EAPI int edje_edit_state_gradient_rel2_offset_x_get(Evas_Object *obj, const char /** Get the gradient rel2 vertical offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to get rel2 offset y value (not including the state value). - * @param value The state value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to get rel2 offset y value (not including the state value). + * @param[in] value The state value. * * @return The gradient rel2 vertical offset value. */ @@ -5361,49 +2945,49 @@ EAPI int edje_edit_state_gradient_rel2_offset_y_get(Evas_Object *obj, const char /** Set the gradient rel1 horizontal offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel1 offset x value (not including the state value). - * @param value The state value. - * @param val The rel1 offset x value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel1 offset x value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel1 offset x value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_rel1_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, int val); /** Set the gradient rel1 vertical offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel1 offset y value (not including the state value). - * @param value The state value. - * @param val The rel1 offset y value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel1 offset y value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel1 offset y value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_rel1_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, int val); /** Set the gradient rel2 horizontal offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel2 offset x value (not including the state value). - * @param value The state value. - * @param val The rel2 offset x value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel2 offset x value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel2 offset x value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_rel2_offset_x_set(Evas_Object *obj, const char *part, const char *state, double value, int val); /** Set the gradient rel2 vertical offset value * - * @param obj Object being edited. - * @param part The part that contain state. - * @param state The name of the state to set rel2 offset y value (not including the state value). - * @param value The state value. - * @param val The rel2 offset y value. + * @param[in] obj Object being edited. + * @param[in] part The part that contain state. + * @param[in] state The name of the state to set rel2 offset y value (not including the state value). + * @param[in] value The state value. + * @param[in] val The rel2 offset y value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_state_gradient_rel2_offset_y_set(Evas_Object *obj, const char *part, const char *state, double value, int val); @@ -5420,7 +3004,7 @@ EAPI Eina_Bool edje_edit_state_gradient_rel2_offset_y_set(Evas_Object *obj, cons * * Use edje_edit_string_list_free() when you don't need it anymore. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return A list containing all the program names. */ @@ -5430,67 +3014,47 @@ EAPI Eina_List * edje_edit_programs_list_get(Evas_Object *obj); * * If a program with the same name just exist the function will fail. * - * @param obj Object being edited. - * @param name The name of the new program. + * @param[in] obj Object being edited. + * @param[in] name The name of the new program. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_add(Evas_Object *obj, const char *name); /** Remove the given program from the edje file. * - * @param obj Object being edited. - * @param prog The name of the program to remove. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to remove. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_del(Evas_Object *obj, const char *prog); /** Check if a program with the given name exist in the edje object. * - * @param obj Object being edited. - * @param prog The prog of the program that will be searched. + * @param[in] obj Object being edited. + * @param[in] prog The prog of the program that will be searched. * - * @return @c EINA_TRUE if the program exist, @c EINA_FALSE otherwise. + * @return EINA_TRUE if the program exist, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_exist(Evas_Object *obj, const char *prog); /** Run the given program. * - * @param obj Object being edited. - * @param prog The name of the program to execute. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to execute. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_run(Evas_Object *obj, const char *prog); -/** Stop all running programs. - * - * @param obj Object being edited. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_program_stop_all(Evas_Object *obj); - -/** Set parts into intermediate state of programs transition. - * - * @param obj Object being edited. - * @param prog The name of the program to use. Program should have action STATE_SET. - * @param pos State of transition to be setted. Value from 0.0 to 1.0. - * 0.0 represents the start state, 1.0 - the final state. Other values will set - * parts to an intermediate state taking into account programs transition type. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_program_transition_state_set(Evas_Object *obj, const char *prog, double pos); - /** Set a new name for the given program * - * @param obj Object being edited. - * @param prog The current program name. - * @param new_name The new name to assign. + * @param[in] obj Object being edited. + * @param[in] prog The current program name. + * @param[in] new_name The new name to assign. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_name_set(Evas_Object *obj, const char *prog, const char *new_name); @@ -5498,8 +3062,8 @@ EAPI Eina_Bool edje_edit_program_name_set(Evas_Object *obj, const char *prog, co * * Remember to free the returned string using edje_edit_string_free(). * - * @param obj Object being edited. - * @param prog The name of the program to get source. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get source. * * @return The source value por program. */ @@ -5507,11 +3071,11 @@ EAPI const char * edje_edit_program_source_get(Evas_Object *obj, const char *pro /** Set source of the given program. * - * @param obj Object being edited. - * @param prog The name of the program to set source. - * @param source The new source value. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set source. + * @param[in] source The new source value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_source_set(Evas_Object *obj, const char *prog, const char *source); @@ -5519,8 +3083,8 @@ EAPI Eina_Bool edje_edit_program_source_set(Evas_Object *obj, const char *prog, * * Remember to free the returned string using edje_edit_string_free(). * - * @param obj Object being edited. - * @param prog The name of the program to get the signal. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the signal. * * @return The signal value for program. */ @@ -5528,18 +3092,18 @@ EAPI const char * edje_edit_program_signal_get(Evas_Object *obj, const char *pro /** Set signal of the given program. * - * @param obj Object being edited. - * @param prog The name of the program to set the signal. - * @param signal The new signal value. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the signal. + * @param[in] signal The new signal value. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_signal_set(Evas_Object *obj, const char *prog, const char *signal); /** Get in.from of a given program. * - * @param obj Object being edited. - * @param prog The name of the program to get the delay. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the delay. * * @return The delay. */ @@ -5547,18 +3111,17 @@ EAPI double edje_edit_program_in_from_get(Evas_Object *obj, const char *prog); /** Set in.from of a given program. * - * @param obj Object being edited. - * @param prog The name of the program to set the delay. - * @param seconds Number of seconds to delay the program execution + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the delay. + * @param[in] seconds Number of seconds to delay the program execution * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ + * */ EAPI Eina_Bool edje_edit_program_in_from_set(Evas_Object *obj, const char *prog, double seconds); /** Get in.range of a given program. * - * @param obj Object being edited. - * @param prog The name of the program to get random delay. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get random delay. * * @return The delay random. */ @@ -5566,18 +3129,18 @@ EAPI double edje_edit_program_in_range_get(Evas_Object *obj, const char *prog); /** Set in.range of a given program. * - * @param obj Object being edited. - * @param prog The name of the program to set random delay. - * @param seconds Max random number of seconds to delay. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set random delay. + * @param[in] seconds Max random number of seconds to delay. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_in_range_set(Evas_Object *obj, const char *prog, double seconds); /** Get the action of a given program. * - * @param obj Object being edited. - * @param prog The name of the program to get the action. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the action. * * @return The action type, or -1 on errors. * Action can be one of EDJE_ACTION_TYPE_NONE, _STATE_SET, ACTION_STOP, SIGNAL_EMIT, DRAG_VAL_SET, _DRAG_VAL_STEP, _DRAG_VAL_PAGE, _SCRIPT @@ -5588,11 +3151,11 @@ EAPI Edje_Action_Type edje_edit_program_action_get(Evas_Object *obj, const char * * Action can be one of EDJE_ACTION_TYPE_NONE, _STATE_SET, ACTION_STOP, SIGNAL_EMIT, DRAG_VAL_SET, _DRAG_VAL_STEP, _DRAG_VAL_PAGE, _SCRIPT * - * @param obj Object being edited. - * @param prog The name of the program to set the action. - * @param action The new action type. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the action. + * @param[in] action The new action type. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_action_set(Evas_Object *obj, const char *prog, Edje_Action_Type action); @@ -5600,8 +3163,8 @@ EAPI Eina_Bool edje_edit_program_action_set(Evas_Object *obj, const char *prog, * * Use edje_edit_string_list_free() when you don't need it anymore. * - * @param obj Object being edited. - * @param prog The name of the progrem to get the list of the targets. + * @param[in] obj Object being edited. + * @param[in] prog The name of the progrem to get the list of the targets. * * @return A list with all the targets names, or NULL on error. */ @@ -5614,11 +3177,11 @@ EAPI Eina_List * edje_edit_program_targets_get(Evas_Object *obj, const char *pro * EDJE_ACTION_TYPE_STATE_SET, then 'target' must be an existing part * name. * - * @param obj Object being edited. - * @param prog The name of the program to add a new target. - * @param target The name of the new target itself. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to add a new target. + * @param[in] target The name of the new target itself. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_target_add(Evas_Object *obj, const char *prog, const char *target); @@ -5627,20 +3190,20 @@ EAPI Eina_Bool edje_edit_program_target_add(Evas_Object *obj, const char *prog, * If program action is EDJE_ACTION_TYPE_ACTION_STOP then 'target' must be an existing program name. * If action is EDJE_ACTION_TYPE_STATE_SET then 'target' must be an existing part name. * - * @param obj Object being edited. - * @param prog The name of the program to del a target from the list of targets. - * @param target The name of another program or another part. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to del a target from the list of targets. + * @param[in] target The name of another program or another part. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_target_del(Evas_Object *obj, const char *prog, const char *target); /** Clear the 'targets' list of the given program * - * @param obj Object being edited. - * @param prog The name of the program to cleaar the 'targets' list. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to cleaar the 'targets' list. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_targets_clear(Evas_Object *obj, const char *prog); @@ -5648,8 +3211,8 @@ EAPI Eina_Bool edje_edit_program_targets_clear(Evas_Object *obj, const char *pro * * Use edje_edit_string_list_free() when you don't need it anymore. * - * @param obj Object being edited. - * @param prog The name of the program to get the list of actions + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the list of actions * * @return A list with all program names. or NULL on error. */ @@ -5659,30 +3222,30 @@ EAPI Eina_List * edje_edit_program_afters_get(Evas_Object *obj, const char *prog * * All the programs listed in 'afters' will be executed after program execution. * - * @param obj Object being edited. - * @param prog The name of the program that contains the list of afters - * @param after The name of another program to add to the afters list + * @param[in] obj Object being edited. + * @param[in] prog The name of the program that contains the list of afters + * @param[in] after The name of another program to add to the afters list * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_after_add(Evas_Object *obj, const char *prog, const char *after); /** Delete the given program from the list of 'afters' of the program. * - * @param obj Object being edited. - * @param prog The name of the program from where to remove the after. - * @param after The name of the program to remove from the list of afters. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program from where to remove the after. + * @param[in] after The name of the program to remove from the list of afters. * - * @return @c EINA_TRUE is successful or not in the list, @c EINA_FALSE otherwise. + * @return EINA_TRUE is successful or not in the list, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_after_del(Evas_Object *obj, const char *prog, const char *after); /** Clear the 'afters' list of the given program. * - * @param obj Object being edited. - * @param prog The name of the program to clear the 'afters' list. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to clear the 'afters' list. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_afters_clear(Evas_Object *obj, const char *prog); @@ -5691,8 +3254,8 @@ EAPI Eina_Bool edje_edit_program_afters_clear(Evas_Object *obj, const char *prog * In a STATE_SET action this is the name of state to set. * In a SIGNAL_EMIT action is the name of the signal to emit. * - * @param obj Object being edited. - * @param prog The name of the program to get the state. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the state. * * @return The name of the state. */ @@ -5700,8 +3263,8 @@ EAPI const char * edje_edit_program_state_get(Evas_Object *obj, const char *prog /** Get api's name of a program. * - * @param obj Object being edited. - * @param prog Name of program. + * @param[in] obj Object being edited. + * @param[in] prog Name of program. * * @return name of the api if successful, NULL otherwise. */ @@ -5709,8 +3272,8 @@ EAPI const char * edje_edit_program_api_name_get(Evas_Object *obj, const char *p /** Get api's description of a program. * - * @param obj Object being edited. - * @param prog Name of program. + * @param[in] obj Object being edited. + * @param[in] prog Name of program. * * @return description of the api if successful, NULL otherwise. */ @@ -5718,21 +3281,21 @@ EAPI const char * edje_edit_program_api_description_get(Evas_Object *obj, const /** Set api's name of a program. * - * @param obj Object being edited. - * @param prog Name of the part. - * @param name New name for the api property. + * @param[in] obj Object being edited. + * @param[in] prog Name of the part. + * @param[in] name New name for the api property. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_api_name_set(Evas_Object *obj, const char *prog, const char *name); /** Set api's description of a program. * - * @param obj Object being edited. - * @param prog Name of the program. - * @param description New description for the api property. + * @param[in] obj Object being edited. + * @param[in] prog Name of the program. + * @param[in] description New description for the api property. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_api_description_set(Evas_Object *obj, const char *prog, const char *description); @@ -5741,11 +3304,11 @@ EAPI Eina_Bool edje_edit_program_api_description_set(Evas_Object *obj, const cha * In a STATE_SET action this is the name of state to set. * In a SIGNAL_EMIT action is the name of the signal to emit. * - * @param obj Object being edited. - * @param prog The name of the program to set a state. - * @param state The nameo of the state to set (not including the state value) + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set a state. + * @param[in] state The nameo of the state to set (not including the state value) * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_state_set(Evas_Object *obj, const char *prog, const char *state); @@ -5754,8 +3317,8 @@ EAPI Eina_Bool edje_edit_program_state_set(Evas_Object *obj, const char *prog, c * In a STATE_SET action this is the value of state to set. * Not used on SIGNAL_EMIT action. * - * @param obj Object being edited. - * @param prog The name of the program to get the value of state. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the value of state. * * @return The value of state for the program. */ @@ -5766,11 +3329,11 @@ EAPI double edje_edit_program_value_get(Evas_Object *obj, const char *prog); * In a STATE_SET action this is the value of state to set. * Not used on SIGNAL_EMIT action. * - * @param obj Object being edited. - * @param prog The name of the program to set the value of state. - * @param value The vale to set. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the value of state. + * @param[in] value The vale to set. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_value_set(Evas_Object *obj, const char *prog, double value); @@ -5779,8 +3342,8 @@ EAPI Eina_Bool edje_edit_program_value_set(Evas_Object *obj, const char *prog, d * In a STATE_SET action is not used * In a SIGNAL_EMIT action is the source of the emitted signal. * - * @param obj Object being edited. - * @param prog The name of the program to get the state2. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the state2. * * @return The source to emit for the program. */ @@ -5791,18 +3354,18 @@ EAPI const char * edje_edit_program_state2_get(Evas_Object *obj, const char *pro * In a STATE_SET action is not used * In a SIGNAL_EMIT action is the source of the emitted signal. * - * @param obj Object being edited. - * @param prog The name of the program to set the state2. - * @param state2 The name of the state to set. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the state2. + * @param[in] state2 The name of the state to set. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_state2_set(Evas_Object *obj, const char *prog, const char *state2); /** Get the value of state2 for the given program. * - * @param obj Object being edited. - * @param prog The name of the program to get the state2 value. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the state2 value. * * @return The vale of the state2 for the program. */ @@ -5812,11 +3375,9 @@ EAPI double edje_edit_program_value2_get(Evas_Object *obj, const char *prog); * * This is used in DRAG_ACTION * - * @param obj Object being edited. - * @param prog The name of the program to set the state2 value. - * @param value The value of the state2 to set. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the state2 value. + * @param[in] value The value of the state2 to set. */ EAPI Eina_Bool edje_edit_program_value2_set(Evas_Object *obj, const char *prog, double value); @@ -5824,8 +3385,8 @@ EAPI Eina_Bool edje_edit_program_value2_set(Evas_Object *obj, const char *prog, * * Can be one of: EDJE_TWEEN_MODE_NONE, EDJE_TWEEN_MODE_LINEAR, EDJE_TWEEN_MODE_SINUSOIDAL, EDJE_TWEEN_MODE_ACCELERATE or EDJE_TWEEN_MODE_DECELERATE. * - * @param obj Object being edited. - * @param prog The name of the program to get the transition. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the transition. * * @return The type of transition used by program. */ @@ -5835,109 +3396,18 @@ EAPI Edje_Tween_Mode edje_edit_program_transition_get(Evas_Object *obj, const ch * * Can be one of: EDJE_TWEEN_MODE_NONE, EDJE_TWEEN_MODE_LINEAR, EDJE_TWEEN_MODE_SINUSOIDAL, EDJE_TWEEN_MODE_ACCELERATE or EDJE_TWEEN_MODE_DECELERATE. * - * @param obj Object being edited. - * @param prog The name of the program to set the transition. - * @param transition The transition type to set + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the transition. + * @param[in] transition The transition type to set * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_transition_set(Evas_Object *obj, const char *prog, Edje_Tween_Mode transition); -/** Get the interpolation value 1 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_ACCELERATE_FACTOR, EDJE_TWEEN_MODE_DECELERATE_FACTOR, EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR, EDJE_TWEEN_MODE_DIVISOR_INTERP, EDJE_TWEEN_MODE_BOUNCE or EDJE_TWEEN_MODE_SPRING. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 1. - * - * @return interpolation value 1. - */ -EAPI double -edje_edit_program_transition_value1_get(Evas_Object *obj, const char *prog); - -/** Set the interpolation value 1 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_ACCELERATE_FACTOR, EDJE_TWEEN_MODE_DECELERATE_FACTOR, EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR, EDJE_TWEEN_MODE_DIVISOR_INTERP, EDJE_TWEEN_MODE_BOUNCE or EDJE_TWEEN_MODE_SPRING. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 1. - * @param value The interpolation value 1 for the transition. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_program_transition_value1_set(Evas_Object *obj, const char *prog, double value); - -/** Get the interpolation value 2 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_DIVISOR_INTERP, EDJE_TWEEN_MODE_BOUNCE or EDJE_TWEEN_MODE_SPRING. - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 2. - * - * @return interpolation value 2. - */ -EAPI double -edje_edit_program_transition_value2_get(Evas_Object *obj, const char *prog); - -/** Set the interpolation value 2 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_DIVISOR_INTERP, EDJE_TWEEN_MODE_BOUNCE or EDJE_TWEEN_MODE_SPRING. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 2. - * @param value The interpolation value 2 for the transition. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_program_transition_value2_set(Evas_Object *obj, const char *prog, double value); - -/** Get the interpolation value 3 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_CUBIC_BEZIER. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 3. - * - * @return interpolation value 3. - */ -EAPI double -edje_edit_program_transition_value3_get(Evas_Object *obj, const char *prog); - -/** Set the interpolation value 3 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_CUBIC_BEZIER. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 3. - * @param value The interpolation value 3 for the transition. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_program_transition_value3_set(Evas_Object *obj, const char *prog, double value); - -/** Get the interpolation value 4 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_CUBIC_BEZIER. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 4. - * - * @return interpolation value 4. - */ -EAPI double -edje_edit_program_transition_value4_get(Evas_Object *obj, const char *prog); - -/** Set the interpolation value 4 of the transition. - * Can be used with one of transition type: EDJE_TWEEN_MODE_CUBIC_BEZIER. - * - * @param obj Object being edited. - * @param prog The name of the program to get the interpolation value 4. - * @param value The interpolation value 4 for the transition. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool -edje_edit_program_transition_value4_set(Evas_Object *obj, const char *prog, double value); - /** Get the duration of the transition in seconds. * - * @param obj Object being edited. - * @param prog The name of the program to get the transition time. + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to get the transition time. * * @return The duration of the transition. */ @@ -5945,52 +3415,17 @@ EAPI double edje_edit_program_transition_time_get(Evas_Object *obj, const char * /** Set the duration of the transition in seconds. * - * @param obj Object being edited. - * @param prog The name of the program to set the transition time. - * @param seconds The duration of the transition (in seconds). + * @param[in] obj Object being edited. + * @param[in] prog The name of the program to set the transition time. + * @param[in] seconds The duration of the transition (in seconds). * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @return EINA_TRUE if successful, EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_program_transition_time_set(Evas_Object *obj, const char *prog, double seconds); -/** Get filter part name of the program. - * - * @param obj Object being edited. - * @param prog The name of the program. - * - * @return const char* part_name on success, NULL otherwise. - */ EAPI const char * edje_edit_program_filter_part_get(Evas_Object *obj, const char *prog); - -/** Set filter part name of the program. - * - * @param obj Object being edited. - * @param prog The name of the program. - * @param filter_part The name of the part to be set as filter. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ EAPI Eina_Bool edje_edit_program_filter_part_set(Evas_Object *obj, const char *prog, const char *filter_part); -/** Get filter state of the program. - * - * @param obj Object being edited. - * @param prog The name of the program. - * - * @return const char* state_name on success, NULL otherwise. - */ -EAPI const char * edje_edit_program_filter_state_get(Evas_Object *obj, const char *prog); - -/** Set filter state of the program. - * - * @param obj Object being edited. - * @param prog The name of the program. - * @param filter_state New filter state value. - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. - */ -EAPI Eina_Bool edje_edit_program_filter_state_set(Evas_Object *obj, const char *prog, const char *filter_state); - //@} /******************************************************************************/ /************************** SCRIPTS API ***********************************/ @@ -6008,7 +3443,7 @@ EAPI Eina_Bool edje_edit_program_filter_state_set(Evas_Object *obj, const char * * the contents directly and they should remember to free() it when done. * NULL will be returned if there's no script or an error occurred. * - * @param obj Object being edited. + * @param[in] obj Object being edited. * * @return The shared script code for this group. */ @@ -6019,14 +3454,12 @@ EAPI char *edje_edit_script_get(Evas_Object *obj); * * Set the Embryo source code for the shared script of the edited group. * Note that changing the code itself will not update the running VM, you - * need to call @see edje_edit_script_compile() for it to get updated. + * need to call edje_edit_script_compile for it to get updated. * - * @param obj The object being edited - * @param code The Embryo source - * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj The object being edited + * @param[in] code The Embryo source */ -EAPI Eina_Bool edje_edit_script_set(Evas_Object *obj, const char *code); +EAPI void edje_edit_script_set(Evas_Object *obj, const char *code); /** * Get the Embryo script for the given program. @@ -6037,8 +3470,8 @@ EAPI Eina_Bool edje_edit_script_set(Evas_Object *obj, const char *code); * NULL will be returned if the program doesn't exist, doesn't have any * script or is not of type script. * - * @param obj Object being edited - * @param prog Program name + * @param[in] obj Object being edited + * @param[in] prog Program name * * @return The program script code */ @@ -6051,15 +3484,13 @@ EAPI char *edje_edit_script_program_get(Evas_Object *obj, const char *prog); * existing program of type EDJE_ACTION_TYPE_SCRIPT, or the function * will fail and do nothing. * Note that changing the code itself will not update the running VM, you - * need to call @see edje_edit_script_compile() for it to get updated. - * - * @param obj The object being edited - * @param prog The program name. - * @param code The Embryo source + * need to call edje_edit_script_compile for it to get updated. * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. + * @param[in] obj The object being edited + * @param[in] prog The program name. + * @param[in] code The Embryo source */ -EAPI Eina_Bool edje_edit_script_program_set(Evas_Object *obj, const char *prog, const char *code); +EAPI void edje_edit_script_program_set(Evas_Object *obj, const char *prog, const char *code); /** * Compile the Embryo script for the given object @@ -6068,9 +3499,8 @@ EAPI Eina_Bool edje_edit_script_program_set(Evas_Object *obj, const char *prog, * build the bytecode, updating the running Embryo VM Program if the build * is succesful. * - * @param obj The object being edited + * @param[in] obj The object being edited * - * @return @c EINA_TRUE in case of success, @c EINA_FALSE otherwise. */ EAPI Eina_Bool edje_edit_script_compile(Evas_Object *obj); @@ -6084,7 +3514,7 @@ EAPI Eina_Bool edje_edit_script_compile(Evas_Object *obj); * These errors can be the output of the embryo compiler, or internal errors * generated by Edje_Edit if the preprocessing of the scripts failed. * - * @param obj The object being edited + * @param[in] obj The object being edited * * @return A constant list of Edje_Edit_Script_Error, or NULL if there are none */ @@ -6092,31 +3522,6 @@ EAPI const Eina_List *edje_edit_script_error_list_get(Evas_Object *obj); //@} /******************************************************************************/ -/************************ SOURCE CODE API *********************************/ -/******************************************************************************/ -/** @name Scripts API - * Functions to deal with embryo scripts (see @ref edcref). - */ //@{ - -/** - * Return source code of the current edje edit object. - * - * Remember to free the string with edje_edit_string_free() - * - * This function will return source code of the whole group, loaded previously. - * This function also will collect all possible resources that is required and - * mentioned in description blocks. For example: all images, fonts, data, styles, - * and color_classes. - * - * @param obj The object being edited - * - * @return Source code containing all resources required by the object. - */ - -EAPI const char *edje_edit_source_generate(Evas_Object *obj); - -//@} -/******************************************************************************/ /************************** ERROR API ***********************************/ /******************************************************************************/ /** @name Error API diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h index b3451fa4fa..ade1023066 100644 --- a/src/lib/eet/Eet.h +++ b/src/lib/eet/Eet.h @@ -1,7 +1,11 @@ /** + * @internal + @defgroup Eet_Group Eet + @ingroup EFL_Group + @brief Eet Data Handling Library Public API Calls - These routines are used for Eet Library interaction + These routines are used for Eet Library interaction. @page eet_main Eet @@ -10,7 +14,6 @@ @section toc Table of Contents @li @ref eet_main_intro - @li @ref eet_main_compiling @li @ref eet_main_next_steps @li @ref eet_main_intro_example @@ -19,7 +22,7 @@ It is a tiny library designed to write an arbitrary set of chunks of data to a file and optionally compress each chunk (very much like a zip file) and allow fast random-access reading of the file later on. It does not - do zip as a zip itself has more complexity than is needed, and it was much + do zip, as a zip itself has more complexity than is needed, and it is much simpler to implement this once here. Eet is extremely fast, small and simple. Eet files can be very small and @@ -35,39 +38,19 @@ encoded in a platform independent way and can be written and read by any architecture. - @section eet_main_compiling How to compile - - Eet 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 eet` - @endverbatim - - Linking object files into a binary executable: - - @verbatim - gcc -o my_application main.o `pkg-config --libs eet` - @endverbatim - - See @ref pkgconfig - @section eet_main_next_steps Next Steps - After you understood what Eet is and installed it in your system - you should proceed understanding the programming interface. We'd - recommend you to take a while to learn @ref Eina as it is very - convenient and optimized, and Eet provides integration with it. + After you understood what Eet is and installed it in your system you + should understand the programming interface. We would recommend + you to take a while to learn @ref Eina_Group as it is very convenient and + optimized, and Eet provides integration with it. Recommended reading: @li @ref Eet_File_Group to know the basics to open and save files. @li @ref Eet_Data_Group to know the convenient way to serialize and - parse your data structures automatically. Just create your - descriptors and let Eet do the work for you. + parse your data structures automatically. Just create your + descriptors and let Eet do the work for you. @section eet_main_intro_example Introductory Examples @@ -97,7 +80,6 @@ #include <stdlib.h> #include <stdio.h> #include <Eina.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI @@ -130,23 +112,26 @@ extern "C" { #endif /* ifdef __cplusplus */ /** + * @internal * @file Eet.h * @brief The file that provides the eet functions. * - * This header provides the Eet management functions. + * @details This header provides the Eet management functions. * */ /** - * @def EET_VERSION_MAJOR - * The major number of eet version - */ -#define EET_VERSION_MAJOR EFL_VERSION_MAJOR -/** - * @def EET_VERSION_MINOR - * The minor number of eet version + * @internal + * @defgroup Eet_General_Group Top level functions + * @ingroup Eet_Group + * + * @brief This group provides functions that affect Eet as a whole. + * + * @{ */ -#define EET_VERSION_MINOR EFL_VERSION_MINOR + +#define EET_VERSION_MAJOR 1 +#define EET_VERSION_MINOR 8 /** * @typedef Eet_Version * @@ -172,38 +157,31 @@ extern "C" { */ typedef struct _Eet_Version { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < svn revision (0 if a proper release or the svn revision number Eet is built from) */ + int major; /**< Major (binary or source incompatible changes) */ + int minor; /**< Minor (new features, bugfixes, major improvements version) */ + int micro; /**< Micro (bugfix, internal improvements, no new features version) */ + int revision; /**< svn revision (@c 0 if a proper release or the svn revision number Eet is built from) */ } Eet_Version; EAPI extern Eet_Version *eet_version; /** - * @defgroup Eet_Group Top level functions - * @ingroup Eet - * Functions that affect Eet as a whole. - * - * @{ - */ - -/** + * @internal * @enum _Eet_Error - * All the error identifiers known by Eet. + * @brief Enumeration of all the error identifiers known by Eet. */ typedef enum _Eet_Error { - EET_ERROR_NONE, /**< No error, it's all fine! */ - EET_ERROR_BAD_OBJECT, /**< Given object or handle is NULL or invalid */ - EET_ERROR_EMPTY, /**< There was nothing to do */ + EET_ERROR_NONE, /**< No error, it is all fine! */ + EET_ERROR_BAD_OBJECT, /**< Given object or handle is @c NULL or invalid */ + EET_ERROR_EMPTY, /**< There is nothing to do */ EET_ERROR_NOT_WRITABLE, /**< Could not write to file or file is #EET_FILE_MODE_READ */ EET_ERROR_OUT_OF_MEMORY, /**< Could not allocate memory */ EET_ERROR_WRITE_ERROR, /**< Failed to write data to destination */ EET_ERROR_WRITE_ERROR_FILE_TOO_BIG, /**< Failed to write file since it is too big */ EET_ERROR_WRITE_ERROR_IO_ERROR, /**< Failed to write due a generic Input/Output error */ EET_ERROR_WRITE_ERROR_OUT_OF_SPACE, /**< Failed to write due out of space */ - EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file was closed */ + EET_ERROR_WRITE_ERROR_FILE_CLOSED, /**< Failed to write because file is closed */ EET_ERROR_MMAP_FAILED, /**< Could not mmap file */ EET_ERROR_X509_ENCODING_FAILED, /**< Could not encode using X509 */ EET_ERROR_SIGNATURE_FAILED, /**< Could not validate signature */ @@ -220,8 +198,10 @@ typedef enum _Eet_Error */ /** - * @defgroup Eet_Compression Eet Compression Levels - * @ingroup Eet + * @internal + * @defgroup Eet_Compression_Group Eet Compression Levels + * @ingroup Eet_General_Group + * * Compression modes/levels supported by Eet. * * @{ @@ -229,7 +209,7 @@ typedef enum _Eet_Error /** * @enum _Eet_Compression - * All the compression modes known by Eet. + * @brief Enumeration for the compression modes known by Eet. */ typedef enum _Eet_Compression @@ -242,11 +222,11 @@ typedef enum _Eet_Compression EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */ EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */ - EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */ - EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */ - EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */ - EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */ - EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */ + EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Do not use it @since 1.7 */ + EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Do not use it @since 1.7 */ + EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Do not use it @since 1.7 */ + EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Do not use it @since 1.7 */ + EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Do not use it @since 1.7 */ } Eet_Compression; /**< Eet compression modes @since 1.7 */ /** @@ -254,209 +234,209 @@ typedef enum _Eet_Compression */ /** - * Initialize the EET library. + * @brief Initializes the EET library. + * @since 1.0.0 * - * The first time this function is called, it will perform all the internal - * initialization required for the library to function properly and increment - * the initialization counter. Any subsequent call only increment this counter - * and return its new value, so it's safe to call this function more than once. + * @remarks The first time this function is called, it performs all the internal + * initialization required for the library to function properly and increment + * the initialization counter. Any subsequent call only increment this counter + * and return its new value. So it is safe to call this function more than once. * - * @return The new init count. Will be 0 if initialization failed. + * @return The new init count, \n + * otherwise @c 0 if initialization failed * - * @since 1.0.0 - * @ingroup Eet_Group + * @ingroup Eet_General_Group */ EAPI int eet_init(void); /** - * Shut down the EET library. - * - * If eet_init() was called more than once for the running application, - * eet_shutdown() will decrement the initialization counter and return its - * new value, without doing anything else. When the counter reaches 0, all - * of the internal elements will be shutdown and any memory used freed. + * @brief Shuts down the EET library. + * @since 1.0.0 * - * @return The new init count. + * @remarks If eet_init() is called more than once for the running application, + * eet_shutdown() decrements the initialization counter and return its + * new value, without doing anything else. When the counter reaches @c 0, all + * of the internal elements are shutdown and any memory used is freed. * - * @since 1.0.0 + * @return The new init count * @ingroup Eet_Group */ EAPI int eet_shutdown(void); /** - * Clear eet cache + * @brief Clears eet cache. + * @since 1.0.0 * - * For a faster access to previously accessed data, Eet keeps an internal - * cache of files. These files will be freed automatically only when - * they are unused and the cache gets full, in order based on the last time - * they were used. - * On systems with little memory this may present an unnecessary constraint, - * so eet_clearcache() is available for users to reclaim the memory used by - * files that are no longer needed. Those that were open using - * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications, - * will be written down to disk before flushing them from memory. + * @remarks For a faster access to previously accessed data, Eet keeps an internal + * cache of files. These files are freed automatically only when + * they are unused and the cache gets full, in order based on the last time + * they were used. On systems with little memory this may present an unnecessary + * constraint. So eet_clearcache() is available for users to reclaim the memory + * used by files that are no longer needed. Those that were open using + * ::EET_FILE_MODE_WRITE or ::EET_FILE_MODE_READ_WRITE and have modifications, + * are written down to disk before flushing them from memory. * - * @since 1.0.0 - * @ingroup Eet_Group + * @ingroup Eet_General_Group */ EAPI void eet_clearcache(void); /** + * @internal * @defgroup Eet_File_Group Eet File Main Functions - * @ingroup Eet + * @ingroup Eet_Group * - * Functions to create, destroy and do basic manipulation of - * #Eet_File handles. + * @brief This group provides functions to create, destroy, and do basic manipulation of + * #Eet_File handles. * * This sections explains how to use the most basic Eet functions, which - * are used to work with eet files, read data from them, store it back in or + * are used to work with eet files, read data from them, store it back in, or * take a look at what entries it contains, without making use of the * serialization capabilities explained in @ref Eet_Data_Group. * - * The following example will serve as an introduction to most, if not all, + * The following example serves as an introduction to most, if not all, * of these functions. * * If you are only using Eet, this is the only header you need to include. * @dontinclude eet-file.c * @skipline Eet.h * - * Now let's create ourselves an eet file to play with. The following function + * Now create an eet file to play with. The following function * shows step by step how to open a file and write some data in it. - * First, we define our file handler and some other things we'll put in it. + * First, define your file handler and some other things that you put in it. * @line static int * @skip Eet_File * @until "; * @skip eet_open * - * We open a new file in write mode, and if it fails, we just return, since - * there's not much more we can do about it.. + * Open a new file in write mode, and if it fails, just return, since + * there is not much more you can do about it. * @until return * - * Now, we need to write some data in our file. For now, strings will suffice, - * so let's just dump a bunch of them in there. + * Now, write some data in your file. For now, strings suffice. + * So just dump a bunch of them in there. * @until } * - * As you can see, we copied a string into our static buffer, which is a bit + * As you can see, you copied a string into your static buffer, which is a bit * bigger than the full length of the string, and then told Eet to write it * into the file, compressed, returning the size of the data written into the * file. - * This is all to show that Eet treats data as just data. It doesn't matter - * what that data represents (for now), it's all just bytes for it. As running - * the following code will show, we took a string of around 30 bytes and put it - * in a buffer of 1024 bytes, but the returned size won't be any of those. + * This is all to show that Eet treats data as just data. It does not matter + * what that data represents (for now). It is all just bytes for it. As running + * the following code shows, you took a string of around 30 bytes and put it + * in a buffer of 1024 bytes, but the returned size is not any of those. * @until printf * - * Next, we copy into our buffer our set of strings, including their null + * Next, copy into your buffer your set of strings, including their null * terminators and write them into the file. No error checking for the sake * of brevity. And a call to eet_sync() to make sure all out data is - * properly written down to disk, even though we haven't yet closed the file. + * properly written down to disk, even though you have not yet closed the file. * @until eet_sync * - * One more write, this time our large array of binary data and... well, I - * couldn't come up with a valid use of the last set of strings we stored, - * so let's take it out from the file with eet_delete(). + * One more write, this time your large array of binary data and... well, + * a valid use of the last set of strings you stored is not identified here, + * so take it out from the file with eet_delete(). * @until eet_delete * - * Finally, we close the file, saving any changes back to disk and return. - * Notice how, if there's any error closing the file or saving its contents, - * the return value from the function will be a false one, which later on - * will make the program exit with an error code. + * Finally, close the file, saving any changes back to disk and return. + * Notice how, if there is any error closing the file or saving its contents, + * the return value from the function is a false one, which later on + * makes the program exit with an error code. * @until return * - * Moving onto our main function, we will open the same file and read it back. - * Trivial, but it'll show how we can do so in more than one way. We'll skip - * the variable declarations, as they aren't very different from what we've + * Moving onto your main function, you open the same file and read it back. + * Trivial, but it shows how you can do so in more than one way. You skip + * the variable declarations, as they are not very different from what you have * seen already. * - * We start from the beginning by initializing Eet so things in general work. - * Forgetting to do so will result in weird results or crashes when calling + * You start from the beginning by initializing Eet so things in general work. + * Forgetting to do so results in weird results or crashes when calling * any eet function, so if you experience something like that, the first thing * to look at is whether eet_init() is missing. - * Then we call our @p create_eet_file function, described above, to make - * sure we have something to work with. If the function fails it will return - * 0 and we just exit, since nothing from here onwards will work anyway. + * Then call your @a create_eet_file function, described above, to make + * sure you have something to work with. If the function fails it returns + * @c 0 and just exits, since nothing from here onwards works anyway. * @skip eet_init * @until return * - * Let's take a look now at what entries our file has. For this, we use - * eet_list(), which will return a list of strings, each being the name of - * one entry. Since we skipped before, it may be worth noting that @p list - * is declared as a @p char **. - * The @p num parameter will, of course, have the number of entries contained + * Take a look now at what entries our file has. For this, use + * eet_list(), which returns a list of strings, each being the name of + * one entry. Since this is skipped before, it may be worth noting that @a list + * is declared as a @a char **. + * The @a num parameter, of course, has the number of entries contained * in our file. - * If everything's fine, we'll get our list and print it to the screen, and - * once done with it, we free the list. That's just the list, not its contents, - * as they are internal strings used by Eet and trying to free them will surely - * break things. + * If everything is fine, you get your list and print it to the screen, and + * once done with it, free the list. That is just the list, not its contents, + * as they are internal strings used by Eet and trying to free them surely + * breaks things. * @until } * * Reading back plain data is simple. Just a call to eet_read() with the file - * to read from, and the name of the entry we are interested in. We get back - * our data and the passed @p size parameter will contain the size of it. If - * the data was stored compressed, it will decompressed first. + * to read from, and the name of the entry you are interested in. You get back + * your data and the passed @a size parameter contains the size of it. If + * the data is stored compressed, it decompresses first. * @until } * * Another simple read for the set of strings from before, except those were - * deleted, so we should get a NULL return and continue normally. + * deleted, so you should get a @c NULL return and continue normally. * @until } * - * Finally, we'll get our binary data in the same way we got the strings. Once - * again, it makes no difference for Eet what the data is, it's up to us to + * Finally, you get your binary data in the same way you got the strings. Once + * again, it makes no difference for Eet what the data is, it is up to you to * know how to handle it. * @until { * - * Now some cheating, we know that this data is an Eet file because, well... - * we just know it. So we are going to open it and take a look at its insides. - * For this, eet_open() won't work, as it needs to have a file on disk to read - * from and all we have is some data in RAM. + * Now some cheating, you know that this data is an Eet file because, well... + * you just know it. So you are going to open it and take a look at its insides. + * For this, eet_open() does not work, as it needs to have a file on disk to read + * from and all you have is some data in RAM. * - * So how do we do? One way would be to create a normal file and write down - * our data, then open it with eet_open(). Another, faster and more efficient - * if all we want to do is read the file, is to use eet_memopen_read(). + * So how to do this? One way would be to create a normal file and write down + * your data, then open it with eet_open(). Another, faster and more efficient way, + * if all you want to do is read the file, is to use eet_memopen_read(). * @until memopen * - * As you can see, the size we got from our previous read was put to good use - * this time. Unlike the first one where all we had were strings, the size - * of the data read only serves to demonstrate that we are reading back the - * entire size of our original @p buf variable. + * As you can see, the size you got from your previous read is put to good use + * this time. Unlike the first one where all you had were strings, the size + * of the data read only serves to demonstrate that you are reading back the + * entire size of your original @a buf variable. * * A little peeking to see how many entries the file has and to make an - * example of eet_num_entries() to get that number when we don't care about + * example of eet_num_entries() to get that number when you do not care about * their names. * @until printf * - * More cheating follows. Just like we knew this was an Eet file, we also know - * what key to read from, and ontop of that we know that the data in it is not + * More cheating follows. Just like you knew this is an Eet file, you also know + * what key to read from, and on top of that you know that the data in it is not * compressed. - * Knowing all this allows us to take some shortcuts. + * Knowing all this allows you to take some shortcuts. * @until read_direct * - * That's a direct print of our data, whatever that data is. We don't want - * to worry about having to free it later, so we just used eet_direct_read() + * That is a direct print of your data, whatever that data is. We do not want + * to worry about having to free it later, so just used eet_direct_read() * to tell Eet to gives a pointer to the internal data in the file, without - * duplicating it. Since we said that data was not compressed, we shouldn't - * worry about printing garbage to the screen (and yes, we also know the data + * duplicating it. Since you said that data is not compressed, you should not + * worry about printing garbage to the screen (and yes, you also know the data * is yet another string). - * We also don't care about the size of the data as it was stored in the file, - * so we passed NULL as the size parameter. - * One very important note about this, however, is that we don't care about + * You also do not care about the size of the data as it is stored in the file, + * so you passed @c NULL as the size parameter. + * One very important note about this, however, is that you do not care about * the size parameter because the data in the file contains the null * terminator for the string. So when using Eet to store strings this way, - * it's very important to consider whether you will keep that final null + * it is very important to consider whether you keep that final null * byte, or to always get the size read and do the necessary checks and copies. - * It's up to the user and the particular use cases to decide how this will - * be done. + * It is up to the user and the particular use cases to decide how this is + * done. * * With everything done, close this second file and free the data used to open - * it. And this is important, we can't free that data until we are done with + * it. And this is important, you cannot free that data until you are done with * the file, as Eet is using it. When opening with eet_memopen_read(), the data * passed to it must be available for as long as the the file is open. * @until } * - * Finally, we close the first file, shutdown all internal resources used by + * Finally, close the first file, shutdown all internal resources used by * Eet and leave our main function, thus terminating our program. * @until return * @@ -466,20 +446,20 @@ eet_clearcache(void); /** * @enum _Eet_File_Mode - * Modes that a file can be opened. + * @brief Enumeration for modes in which a file can be opened. */ typedef enum _Eet_File_Mode { EET_FILE_MODE_INVALID = -1, - EET_FILE_MODE_READ, /**< File is read-only. */ - EET_FILE_MODE_WRITE, /**< File is write-only. */ + EET_FILE_MODE_READ, /**< File is read-only */ + EET_FILE_MODE_WRITE, /**< File is write-only */ EET_FILE_MODE_READ_WRITE /**< File is for both read and write */ -} Eet_File_Mode; /**< Modes that a file can be opened. */ +} Eet_File_Mode; /**< Modes that a file can be opened */ /** * @enum _Eet_Image_Encoding - * Specify lossy encoding for image - * @since 1.10 + * @brief Enumeration for lossy encoding for image. + * @remarks Backported from EFL 1.10 and EFL 1.11 */ typedef enum _Eet_Image_Encoding { @@ -503,12 +483,12 @@ typedef enum _Eet_Colorspace /** * @typedef Eet_File - * Opaque handle that defines an Eet file (or memory). + * @brief The structure type containing an opaque handle that defines an Eet file (or memory). * - * This handle will be returned by the functions eet_open() and + * This handle is returned by the functions eet_open() and * eet_memopen_read() and is used by every other function that affects the * file in any way. When you are done with it, call eet_close() to close it - * and, if the file was open for writing, write down to disk any changes made + * and, if the file is open for writing, write down to disk any changes made * to it. * * @see eet_open() @@ -519,147 +499,97 @@ typedef struct _Eet_File Eet_File; /** * @typedef Eet_Dictionary - * Opaque handle that defines a file-backed (mmaped) dictionary of strings. + * @brief The structure type containing an opaque handle that defines a file-backed (mmaped) dictionary of strings. */ typedef struct _Eet_Dictionary Eet_Dictionary; /** - * @typedef Eet_Entries - * Eet files may contains multiple Entries per file, this handle describe them. You can get that handle from an iterator given by eet_list_entries(). - * - * @see eet_list_entries() - * @since 1.8.0 - */ -typedef struct _Eet_Entry Eet_Entry; -struct _Eet_Entry -{ - const char *name; /**< The entry name */ - - int offset; /**< Where it start in the file */ - int size; /**< The size on disk */ - int data_size; /**< The decompressed size if relevant */ - - Eina_Bool compression; /**< Is this data compressed ? */ - Eina_Bool ciphered; /**< Is it ciphered ? */ - Eina_Bool alias; /**< Is it an alias ? */ -}; - -/** - * @} - */ - -/** - * Open an eet file on disk, and returns a handle to it. - * @param file The file path to the eet file. eg: @c "/tmp/file.eet". - * @param mode The mode for opening. Either #EET_FILE_MODE_READ, - * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE. - * @return An opened eet file handle. - * @ingroup Eet_File_Group - * - * This function will open an exiting eet file for reading, and build - * the directory table in memory and return a handle to the file, if it - * exists and can be read, and no memory errors occur on the way, otherwise - * NULL will be returned. - * - * It will also open an eet file for writing. This will, if successful, - * delete the original file and replace it with a new empty file, till - * the eet file handle is closed or flushed. If it cannot be opened for - * writing or a memory error occurs, NULL is returned. - * - * You can also open the file for read/write. If you then write a key that - * does not exist it will be created, if the key exists it will be replaced - * by the new data. - * - * If the same file is opened multiple times, then the same file handle will - * be returned as eet maintains an internal list of all currently open - * files. Note that it considers files opened for read only and those opened - * for read/write and write only as 2 separate sets. Those that do not write - * to the file and those that do. Eet will allow 2 handles to the same file - * if they are in the 2 separate lists/groups. That means opening a file for - * read only looks in the read only set, and returns a handle to that file - * handle and increments its reference count. If you open a file for read/write - * or write only it looks in the write set and returns a handle after - * incrementing the reference count. You need to close an eet file handle - * as many times as it has been opened to maintain correct reference counts. - * Files whose modified timestamp or size do not match those of the existing - * referenced file handles will not be returned and a new handle will be - * returned instead. - * - * @since 1.0.0 + * @brief Opens an eet file on disk, and returns a handle to it. + * @since 1.0.0 + * + * @remarks This function opens an exiting eet file for reading, and build + * the directory table in memory and return a handle to the file, if it + * exists and can be read, and no memory errors occur on the way, otherwise + * @c NULL is returned. + * + * @remarks It also opens an eet file for writing. This, if successful, + * deletes the original file and replace it with a new empty file, till + * the eet file handle is closed or flushed. If it cannot be opened for + * writing or a memory error occurs, @c NULL is returned. + * + * @remarks You can also open the file for read/write. If you then write a key that + * does not exist it is created, if the key exists it is replaced + * by the new data. + * + * @remarks If the same file is opened multiple times, then the same file handle + * is returned as eet maintains an internal list of all currently open + * files. Note that it considers files opened for read only and those opened + * for read/write and write only as two separate sets. Those that do not write + * to the file and those that do. Eet allows two handles to the same file + * if they are in the two separate lists/groups. That means opening a file for + * read only looks in the read only set, and returns a handle to that file + * handle and increments its reference count. If you open a file for read/write + * or write only, it looks in the write set and returns a handle after + * incrementing the reference count. You need to close an eet file handle + * as many times as it has been opened to maintain correct reference counts. + * Files whose modified timestamp or size do not match those of the existing + * referenced file handles are not returned and a new handle is returned instead. + * + * @param[in] file The file path to the eet file. eg: @c "/tmp/file.eet" + * @param[in] mode The mode for opening. Either #EET_FILE_MODE_READ, + * #EET_FILE_MODE_WRITE or #EET_FILE_MODE_READ_WRITE + * @return An opened eet file handle */ EAPI Eet_File * eet_open(const char *file, Eet_File_Mode mode); /** - * Open an eet file on disk from an Eina_File handle, and returns a handle to it. - * @param file The Eina_File handle to map to an eet file. - * @return An opened eet file handle. - * @ingroup Eet_File_Group + * @brief Opens an eet file directly from a memory location. * - * This function will open an exiting eet file for reading, and build - * the directory table in memory and return a handle to the file, if it - * exists and can be read, and no memory errors occur on the way, otherwise - * NULL will be returned. + * @since 1.1.0 * - * This function can't open file for writing only read only mode is supported for now. + * @remarks The data is not copied, so you must keep it around + * as long as the eet file is open. There is + * currently no cache for this kind of Eet_File, + * so it is reopened every time you use eet_memopen_read. * - * If the same file is opened multiple times, then the same file handle will - * be returned as eet maintains an internal list of all currently open - * files. That means opening a file for read only looks in the read only set, - * and returns a handle to that file handle and increments its reference count. - * You need to close an eet file handle as many times as it has been opened to - * maintain correct reference counts. + * @remarks Files opened this way are always in read-only mode. * - * @since 1.8.0 - */ -EAPI Eet_File * -eet_mmap(const Eina_File *file); - -/** - * Open an eet file directly from a memory location. The data is not copied, - * so you must keep it around as long as the eet file is open. There is - * currently no cache for this kind of Eet_File, so it's reopened every time - * you use eet_memopen_read. - * @param data Address of file in memory. - * @param size Size of memory to be read. - * @return A handle to the file. - * - * Files opened this way will always be in read-only mode. - * - * @since 1.1.0 - * @ingroup Eet_File_Group + * @param[in] data The address of file in memory + * @param[in] size The size of memory to be read + * @return A handle to the file */ EAPI Eet_File * eet_memopen_read(const void *data, size_t size); /** - * Get the mode an Eet_File was opened with. - * @param ef A valid eet file handle. - * @return The mode ef was opened with. + * @brief Gets the mode an Eet_File is opened with. * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @since 1.0.0 + * + * @param[in] ef A valid eet file handle + * @return The mode ef is opened with */ EAPI Eet_File_Mode eet_mode_get(Eet_File *ef); /** - * Close an eet file handle and flush pending writes. - * @param ef A valid eet file handle. - * @return An eet error identifier. + * @brief Closes an eet file handle and flush pending writes. * - * This function will flush any pending writes to disk if the eet file - * was opened for write, and free all data associated with the file handle - * and file, and close the file. If it was opened for read (or read/write), - * the file handle may still be held open internally for caching purposes. - * To flush speculatively held eet file handles use eet_clearcache(). + * @details This function flushes any pending writes to disk if the eet file + * is opened for write, and free all data associated with the file handle + * and file, and close the file. If it is opened for read (or read/write), + * the file handle may still be held open internally for caching purposes. + * To flush speculatively held eet file handles use eet_clearcache(). * - * If the eet file handle is not valid nothing will be done. + * @since 1.0.0 * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @remarks If the eet file handle is not valid nothing is done. + * + * @param[in] ef A valid eet file handle + * @return An eet error identifier * * @see eet_clearcache() */ @@ -667,90 +597,89 @@ EAPI Eet_Error eet_close(Eet_File *ef); /** - * Sync content of an eet file handle, flushing pending writes. - * @param ef A valid eet file handle. - * @return An eet error identifier. + * @brief Syncs content of an eet file handle, flushing pending writes. + * @details This function flushes any pending writes to disk. The eet file must + * be opened for write. * - * This function will flush any pending writes to disk. The eet file must - * be opened for write. + * @since 1.2.4 * - * If the eet file handle is not valid nothing will be done. + * @remarks If the eet file handle is not valid nothing is done. * - * @since 1.2.4 - * @ingroup Eet_File_Group + * @param[in] ef A valid eet file handle + * @return An eet error identifier */ EAPI Eet_Error eet_sync(Eet_File *ef); /** - * Return a handle to the shared string dictionary of the Eet file - * @param ef A valid eet file handle. - * @return A handle to the dictionary of the file + * @brief Gets a handle to the shared string dictionary of the Eet file. * - * This function returns a handle to the dictionary of an Eet file whose - * handle is @p ef, if a dictionary exists. NULL is returned otherwise or - * if the file handle is known to be invalid. + * @details This function returns a handle to the dictionary of an Eet file whose + * handle is @a ef, if a dictionary exists. @c NULL is returned otherwise or + * if the file handle is known to be invalid. * + * @since 1.0.0 + * + * @param[in] ef A valid eet file handle + * @return A handle to the dictionary of the file * @see eet_dictionary_string_check() to know if given string came - * from the dictionary or it was dynamically allocated using + * from the dictionary or it is dynamically allocated using * the #Eet_Data_Descriptor_Class instructions. - * - * @since 1.0.0 - * @ingroup Eet_File_Group */ EAPI Eet_Dictionary * eet_dictionary_get(Eet_File *ef); /** - * Check if a given string comes from a given dictionary - * @param ed A valid dictionary handle - * @param string A valid 0 byte terminated C string - * @return 1 if it is in the dictionary, 0 otherwise + * @brief Checks whether a given string comes from a given dictionary. * - * This checks the given dictionary to see if the given string is actually - * inside that dictionary (i.e. comes from it) and returns 1 if it does. - * If the dictionary handle is invalid, the string is NULL or the string is - * not in the dictionary, 0 is returned. + * @details This checks the given dictionary to see if the given string is actually + * inside that dictionary (i.e. comes from it) and returns @c 1 if it does. + * If the dictionary handle is invalid, the string is @c NULL or the string is + * not in the dictionary, @c 0 is returned. * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @since 1.0.0 + * + * @param[in] ed A valid dictionary handle + * @param[in] string A valid @c 0 byte terminated C string + * @return @c 1 if it is in the dictionary, \n + * otherwise @c 0 if it is not in the dictionary */ EAPI int eet_dictionary_string_check(Eet_Dictionary *ed, const char *string); /** - * Return the number of strings inside a dictionary - * @param ed A valid dictionary handle - * @return the number of strings inside a dictionary + * @brief Gets the number of strings inside a dictionary. + * @since 1.6.0 * - * @since 1.6.0 - * @ingroup Eet_File_Group + * @param[in] ed A valid dictionary handle + * @return The number of strings inside a dictionary */ EAPI int eet_dictionary_count(const Eet_Dictionary *ed); /** - * Read a specified entry from an eet file and return data - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param size_ret Number of bytes read from entry and returned. - * @return The data stored in that entry in the eet file. + * @brief Reads a specified entry from an eet file and returns data. * - * This function finds an entry in the eet file that is stored under the - * name specified, and returns that data, decompressed, if successful. - * NULL is returned if the lookup fails or if memory errors are - * encountered. It is the job of the calling program to call free() on - * the returned data. The number of bytes in the returned data chunk are - * placed in size_ret. + * @details This function finds an entry in the eet file that is stored under the + * name specified, and returns that data, decompressed, if successful. + * @c NULL is returned if the lookup fails or if memory errors are + * encountered. It is the job of the calling program to call free() on + * the returned data. The number of bytes in the returned data chunk are + * placed in size_ret. * - * If the eet file handle is not valid NULL is returned and size_ret is - * filled with 0. + * @since 1.0.0 * - * @see eet_read_cipher() + * @remarks If the eet file handle is not valid @c NULL is returned and @a size_ret is + * filled with @c 0. * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[out] size_ret The number of bytes read from entry and returned + * @return The data stored in that entry in the eet file + * + * @see eet_read_cipher() */ EAPI void * eet_read(Eet_File *ef, @@ -758,24 +687,23 @@ eet_read(Eet_File *ef, int *size_ret); /** - * Read a specified entry from an eet file and return data - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param size_ret Number of bytes read from entry and returned. - * @return The data stored in that entry in the eet file. - * - * This function finds an entry in the eet file that is stored under the - * name specified, and returns that data if not compressed and successful. - * NULL is returned if the lookup fails or if memory errors are - * encountered or if the data is compressed. The calling program must never - * call free() on the returned data. The number of bytes in the returned - * data chunk are placed in size_ret. + * @brief Reads a specified entry from an eet file and returns the data. * - * If the eet file handle is not valid NULL is returned and size_ret is - * filled with 0. + * @details This function finds an entry in the eet file that is stored under the + * name specified, and returns that data if not compressed and successful. + * @c NULL is returned if the lookup fails or if memory errors are + * encountered or if the data is compressed. The calling program must never + * call free() on the returned data. The number of bytes in the returned + * data chunk are placed in size_ret. + * @since 1.0.0 * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @remarks If the eet file handle is not valid, @c NULL is returned and @a size_ret is + * filled with @a 0. + * @param[in] ef A valid eet file handle opened for reading. + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[out] size_ret The number of bytes read from entry and returned + * @return The data stored in that entry in the eet file */ EAPI const void * eet_read_direct(Eet_File *ef, @@ -783,32 +711,34 @@ eet_read_direct(Eet_File *ef, int *size_ret); /** - * Write a specified entry to an eet file handle - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param data Pointer to the data to be stored. - * @param size Length in bytes in the data to be stored. - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @return bytes written on successful write, 0 on failure. + * @brief Writes a specified entry to an eet file handle. * - * This function will write the specified chunk of data to the eet file - * and return greater than 0 on success. 0 will be returned on failure. + * @details This function writes the specified chunk of data to the eet file + * and return greater than @c 0 on success. @c 0 is returned on failure. * - * The eet file handle must be a valid file handle for an eet file opened - * for writing. If it is not, 0 will be returned and no action will be - * performed. + * @since 1.0.0 * - * Name, and data must not be NULL, and size must be > 0. If these - * conditions are not met, 0 will be returned. + * @remarks The eet file handle must be a valid file handle for an eet file opened + * for writing. If it is not, @c 0 is returned and no action is + * performed. * - * The data will be copied (and optionally compressed) in ram, pending - * a flush to disk (it will stay in ram till the eet file handle is - * closed though). + * @remarks Name and data must not be @c NULL, and size must be > @c 0. If these + * conditions are not met, @c 0 is returned. * - * @see eet_write_cipher() + * @remarks The data is copied (and optionally compressed) in RAM, pending + * a flush to disk (it stays in RAM till the eet file handle is + * closed though). * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] data The pointer to the data to be stored + * @param[in] size The length in bytes in the data to be stored + * @param[in] compress The compression flags (1 = compress, 0 = do not compress) + * @return The bytes written on successful write, \n + * otherwise @c 0 on failure + * + * @see eet_write_cipher() */ EAPI int eet_write(Eet_File *ef, @@ -818,41 +748,45 @@ eet_write(Eet_File *ef, int compress); /** - * Delete a specified entry from an Eet file being written or re-written - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @return Success or failure of the delete. + * @brief Deletes a specified entry from an Eet file being written or re-written. * - * This function will delete the specified chunk of data from the eet file - * and return greater than 0 on success. 0 will be returned on failure. + * @details This function deletes the specified chunk of data from the eet file + * and return greater than @c 0 on success. @c 0 is returned on failure. * - * The eet file handle must be a valid file handle for an eet file opened - * for writing. If it is not, 0 will be returned and no action will be - * performed. + * @since 1.0.0 * - * Name, must not be NULL, otherwise 0 will be returned. + * @remarks The eet file handle must be a valid file handle for an eet file opened + * for writing. If it is not, @c 0 is returned and no action is performed. * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @remarks Name must not be @c NULL, otherwise @c 0 is returned. + * + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @return A number > @c 0 if the entry is deleted successfully, \n + * otherwise @c 0 on failure */ EAPI int eet_delete(Eet_File *ef, const char *name); /** - * Alias a specific section to another one. Destination may exist or not, - * no checks are done. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the new entry. eg: "/base/file_i_want". - * @param destination Actual source of the aliased entry eg: "/base/the_real_stuff_i_want". - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @return EINA_TRUE on success, EINA_FALSE on failure. + * @brief Aliases a specific section to another one. + * @since 1.3.3 * - * Name and Destination must not be NULL, otherwise EINA_FALSE will be returned. - * The equivalent of this would be calling 'ln -s destination name' + * @remarks Destination may exist or not, no checks are done. * - * @since 1.3.3 - * @ingroup Eet_File_Group + * @remarks Name and Destination must not be @c NULL, otherwise @c EINA_FALSE is returned. + * The equivalent of this would be calling 'ln -s destination name'. + * + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the new entry \n + * For example: "/base/file_i_want". + * @param[in] destination The actual source of the aliased entry \n + * For example: "/base/the_real_stuff_i_want". + * @param[in] compress The compression flags (1 == compress, 0 = do not compress) + * @return @c EINA_TRUE if it is aliased successfully, \n + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool eet_alias(Eet_File *ef, @@ -861,62 +795,64 @@ eet_alias(Eet_File *ef, int compress); /** - * Retrieve the filename of an Eet_File - * @param ef A valid eet file handle opened for writing. - * @return The stringshared file string opened with eet_open(), or NULL on error + * @brief Gets the filename of an Eet_File. + * @since 1.6 * - * @note This function will return NULL for files opened with eet_memopen_read() + * @remarks This function returns @c NULL for files opened with eet_memopen_read() * - * @since 1.6 - * @ingroup Eet_File_Group + * @param[in] ef A valid eet file handle opened for writing + * @return The stringshared file string opened with eet_open(), \n + * otherwise @c NULL on error */ EAPI const char * eet_file_get(Eet_File *ef); /** - * Retrieve the destination name of an alias - * @param ef A valid eet file handle opened for writing - * @param name Name of the entry. eg: "/base/file_i_want" - * @return Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure + * @brief Gets the destination name of an alias. * - * Name must not be NULL, otherwise NULL will be returned. + * @since 1.5 * - * @since 1.5 - * @ingroup Eet_File_Group + * @remarks Name must not be @c NULL, otherwise @c NULL is returned. + * + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want" + * @return The destination of the alias, example: "/base/the_real_stuff_i_want", \n + * otherwise @c NULL on failure */ EAPI const char * eet_alias_get(Eet_File *ef, const char *name); /** - * List all entries in eet file matching shell glob. - * @param ef A valid eet file handle. - * @param glob A shell glob to match against. - * @param count_ret Number of entries found to match. - * @return Pointer to an array of strings. + * @brief Lists all entries in eet file matching shell glob. * - * This function will list all entries in the eet file matching the - * supplied shell glob and return an allocated list of their names, if - * there are any, and if no memory errors occur. + * @details This function lists all entries in the eet file matching the + * supplied shell glob and return an allocated list of their names, if + * there are any, and if no memory errors occur. * - * The eet file handle must be valid and glob must not be NULL, or NULL - * will be returned and count_ret will be filled with 0. + * @since 1.0.0 * - * The calling program must call free() on the array returned, but NOT - * on the string pointers in the array. They are taken as read-only - * internals from the eet file handle. They are only valid as long as - * the file handle is not closed. When it is closed those pointers in the - * array are now not valid and should not be used. + * @remarks The eet file handle must be valid and glob must not be @c NULL, or @c NULL + * is returned and @a count_ret is filled with @c 0. * - * On success the array returned will have a list of string pointers - * that are the names of the entries that matched, and count_ret will have - * the number of entries in this array placed in it. + * @remarks The calling program must call free() on the array returned, but NOT + * on the string pointers in the array. They are taken as read-only + * internals from the eet file handle. They are only valid as long as + * the file handle is not closed. When it is closed those pointers in the + * array are now not valid and should not be used. * - * Hint: an easy way to list all entries in an eet file is to use a glob - * value of "*". + * @remarks On success the array returned has a list of string pointers + * that are the names of the entries that matched, and @a count_ret has + * the number of entries in this array placed in it. * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @remarks Hint: an easy way to list all entries in an eet file is to use a glob + * value of "*". + * + * @param[in] ef A valid eet file handle + * @param[in] glob A shell glob to match against + * @param[out] count_ret The number of entries found to match + * @return The pointer to an array of strings */ EAPI char ** eet_list(Eet_File *ef, @@ -924,61 +860,56 @@ eet_list(Eet_File *ef, int *count_ret); /** - * Return an iterator that will describe each entry of an Eet_File. - * @param ef A valid eet file handle. - * @return An interator of Eet_Entry. + * @brief Gets the number of entries in the specified eet file. + * @since 1.0.0 * - * @since 1.8.0 - * @ingroup Eet_File_Group + * @param[in] ef A valid eet file handle + * @return The number of entries in ef, \n + * otherwise @c -1 if the number of entries cannot be read due to open mode restrictions */ - -EAPI Eina_Iterator *eet_list_entries(Eet_File *ef); +EAPI int +eet_num_entries(Eet_File *ef); /** - * Return the number of entries in the specified eet file. - * @param ef A valid eet file handle. - * @return Number of entries in ef or -1 if the number of entries - * cannot be read due to open mode restrictions. - * - * @since 1.0.0 - * @ingroup Eet_File_Group + * @} */ -EAPI int -eet_num_entries(Eet_File *ef); /** + * @internal * @defgroup Eet_File_Cipher_Group Eet File Ciphered Main Functions + * @ingroup Eet_File_Group * * Most of the @ref Eet_File_Group have alternative versions that * accounts for ciphers to protect their content. * * @see @ref Eet_Cipher_Group * - * @ingroup Eet_File_Group + * @{ */ /** - * Read a specified entry from an eet file and return data using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param size_ret Number of bytes read from entry and returned. - * @param cipher_key The key to use as cipher. - * @return The data stored in that entry in the eet file. + * @brief Reads a specified entry from an eet file and returns the data using a cipher. * - * This function finds an entry in the eet file that is stored under the - * name specified, and returns that data, decompressed, if successful. - * NULL is returned if the lookup fails or if memory errors are - * encountered. It is the job of the calling program to call free() on - * the returned data. The number of bytes in the returned data chunk are - * placed in size_ret. + * @details This function finds an entry in the eet file that is stored under the + * name specified, and returns that data, decompressed, if successful. + * @c NULL is returned if the lookup fails or if memory errors are + * encountered. It is the job of the calling program to call free() on + * the returned data. The number of bytes in the returned data chunk are + * placed in size_ret. + * @since 1.0.0 * - * If the eet file handle is not valid NULL is returned and size_ret is - * filled with 0. + * @remarks If the eet file handle is not valid, @c NULL is returned and @a size_ret is + * filled with @c 0. * - * @see eet_read() + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[out] size_ret The number of bytes read from entry and returned + * @param[in] cipher_key The key to use as cipher + * @return The data stored in that entry in the eet file, \n + * otherwise @c NULL on error * - * @since 1.0.0 - * @ingroup Eet_File_Cipher_Group + * @see eet_read() */ EAPI void * eet_read_cipher(Eet_File *ef, @@ -987,33 +918,33 @@ eet_read_cipher(Eet_File *ef, const char *cipher_key); /** - * Write a specified entry to an eet file handle using a cipher. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param data Pointer to the data to be stored. - * @param size Length in bytes in the data to be stored. - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @param cipher_key The key to use as cipher. - * @return bytes written on successful write, 0 on failure. + * @brief Writes a specified entry to an eet file handle using a cipher. * - * This function will write the specified chunk of data to the eet file - * and return greater than 0 on success. 0 will be returned on failure. + * @details This function writes the specified chunk of data to the eet file + * and return greater than @c 0 on success. @c 0 is returned on failure. + * @since 1.0.0 * - * The eet file handle must be a valid file handle for an eet file opened - * for writing. If it is not, 0 will be returned and no action will be - * performed. + * @remarks The eet file handle must be a valid file handle for an eet file opened + * for writing. If it is not, @c 0 is returned and no action is performed. * - * Name, and data must not be NULL, and size must be > 0. If these - * conditions are not met, 0 will be returned. + * @remarks @a name and @a data must not be @c NULL, and size must be > @c 0. If these + * conditions are not met, @c 0 is returned. * - * The data will be copied (and optionally compressed) in ram, pending - * a flush to disk (it will stay in ram till the eet file handle is - * closed though). + * @remarks The data is copied (and optionally compressed) in RAM, pending + * a flush to disk (it stays in RAM till the eet file handle is + * closed though). * - * @see eet_write() + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] data The pointer to the data to be stored + * @param[in] size The length in bytes in the data to be stored + * @param[in] compress The compression flags (1 == compress, 0 = do not compress) + * @param[in] cipher_key The key to use as cipher + * @return The bytes written on successful write, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_File_Cipher_Group + * @see eet_write() */ EAPI int eet_write_cipher(Eet_File *ef, @@ -1024,60 +955,71 @@ eet_write_cipher(Eet_File *ef, const char *cipher_key); /** + * @} + */ + +/** + * @internal * @defgroup Eet_File_Image_Group Image Store and Load - * @ingroup Eet + * @ingroup Eet_File_Group + * + * @brief This group provides functions for image storing and loading. * * Eet efficiently stores and loads images, including alpha * channels and lossy compressions. * * Eet can handle both lossy compression with different levels of quality and - * non-lossy compression with different compression levels. It's also possible, + * non-lossy compression with different compression levels. It is also possible, * given an image data, to only read its header to get the image information * without decoding the entire content for it. * - * The encode family of functions will take an image raw buffer and its + * The encode family of functions takes an image raw buffer and its * parameters and compress it in memory, returning the new buffer. - * Likewise, the decode functions will read from the given location in memory + * Likewise, the decode functions reads from the given location in memory * and return the uncompressed image. * - * The read and write functions will, respectively, encode and decode to or + * The read and write functions, respectively, encode and decode to or * from an Eet file, under the specified key. * * These functions are fairly low level and the same functionality can be * achieved using Evas and Edje, making it much easier to work with images * as well as not needing to worry about things like scaling them. + * + * @{ */ /** - * Read just the header data for an image and dont decode the pixels. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on successful decode, 0 otherwise + * @brief Reads the header data for an image but does not decode the pixels. * - * Reads and decodes the image header data stored under the given key and - * Eet file. + * @details This function reads and decodes the image header data stored under + * the given key and Eet file. * - * The information decoded is placed in each of the parameters, which must be - * provided. The width and height, measured in pixels, will be stored under - * the variables pointed by @p w and @p h, respectively. If the read or - * decode of the header fails, this values will be 0. The @p alpha parameter - * will be 1 or 0, denoting if the alpha channel of the image is used or not. - * If the image was losslessly compressed, the @p compress parameter will hold - * the compression amount used, ranging from 0 to 9 and @p lossy will be 0. - * In the case of lossy compression, @p lossy will be 1, and the compression - * quality will be placed under @p quality, with a value ranging from 0 to 100. + * @since 1.0.0 + * + * @remarks The information decoded is placed in each of the parameters, which must be + * provided. The width and height, measured in pixels, is stored under + * the variables pointed by @a w and @a h, respectively. If the read or + * decode of the header fails, this value is @c 0. The @a alpha parameter + * is @c 1 or @c 0, denoting if the alpha channel of the image is used or not. + * If the image is losslessly compressed, the @a compress parameter holds + * the compression amount used, ranging from @c 0 to @c 9 and @a lossy is @c 0. + * In the case of lossy compression, @a lossy is @c 1, and the compression + * quality is placed under @a quality, with a value ranging from @c 0 to @c 100. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if decoded successfully, \n + * otherwise @c 0 otherwise * * @see eet_data_image_header_decode() * @see eet_data_image_header_read_cipher() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI int eet_data_image_header_read(Eet_File *ef, @@ -1090,39 +1032,39 @@ eet_data_image_header_read(Eet_File *ef, Eet_Image_Encoding *lossy); /** - * Read image data from the named key in the eet file. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return The image pixel data decoded + * @brief Reads the image data from the named key in the eet file. + * + * @details This function reads and decodes the image stored in the given Eet file under the named key. * - * Reads and decodes the image stored in the given Eet file under the named - * key. + * @since 1.0.0 * - * The returned pixel data is a linear array of pixels starting from the - * top-left of the image, scanning row by row from left to right. Each pile - * is a 32bit value, with the high byte being the alpha channel, the next being - * red, then green, and the low byte being blue. + * @remarks The returned pixel data is a linear array of pixels starting from the + * top-left of the image, scanning row by row from left to right. Each pile + * is a 32bit value, with the high byte being the alpha channel, the next being + * red, then green, and the low byte being blue. * - * The rest of the parameters are the same as in eet_data_image_header_read(). + * @remarks The rest of the parameters are the same as in eet_data_image_header_read(). * - * On success the function returns a pointer to the image data decoded. The - * calling application is responsible for calling free() on the image data - * when it is done with it. On failure NULL is returned and the parameter - * values may not contain any sensible data. + * @remarks On success, the function returns a pointer to the image data decoded. The + * calling application is responsible for calling free() on the image data + * when it is done with it. On failure @c NULL is returned and the parameter + * values may not contain any sensible data. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return The image pixel data decoded * * @see eet_data_image_header_read() * @see eet_data_image_decode() * @see eet_data_image_read_cipher() * @see eet_data_image_read_to_surface() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI void * eet_data_image_read(Eet_File *ef, @@ -1135,52 +1077,54 @@ eet_data_image_read(Eet_File *ef, Eet_Image_Encoding *lossy); /** - * Read image data from the named key in the eet file and store it in the given buffer. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. - * - * Reads and decodes the image stored in the given Eet file, placing the - * resulting pixel data in the buffer pointed by the user. - * - * Like eet_data_image_read(), it takes the image data stored under the - * @p name key in the @p ef file, but instead of returning a new buffer with - * the pixel data, it places the result in the buffer pointed by @p d, which - * must be provided by the user and of sufficient size to hold the requested - * portion of the image. - * - * The @p src_x and @p src_y parameters indicate the top-left corner of the - * section of the image to decode. These have to be higher or equal than 0 and - * less than the respective total width and height of the image. The width - * and height of the section of the image to decode are given in @p w and @p h - * and also can't be higher than the total width and height of the image. - * - * The @p row_stride parameter indicates the length in bytes of each line in - * the destination buffer and it has to be at least @p w * 4. - * - * All the other parameters are the same as in eet_data_image_read(). - * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @brief Reads image data from the named key in the eet file and stores it in the given buffer. + * + * @details This function reads and decodes the image stored in the given Eet file, placing the + * resulting pixel data in the buffer pointed by the user. + * + * @since 1.0.2 + * + * @remarks Like eet_data_image_read(), it takes the image data stored under the + * @a name key in the @a ef file, but instead of returning a new buffer with + * the pixel data, it places the result in the buffer pointed by @a d, which + * must be provided by the user and of sufficient size to hold the requested + * portion of the image. + * + * @remarks The @a src_x and @a src_y parameters indicate the top-left corner of the + * section of the image to decode. These have to be higher or equal than @c 0 and + * less than the respective total width and height of the image. The width + * and height of the section of the image to decode are given in @a w and @a h + * and also cannot be higher than the total width and height of the image. + * + * @remarks The @a row_stride parameter indicates the length in bytes of each line in + * the destination buffer and it has to be at least @a w * 4. + * + * @remarks All the other parameters are the same as in eet_data_image_read(). + * + * @remarks On success, the function returns @c 1, and @c 0 on failure. On failure, the + * parameter values may not contain any sensible data. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if the image data is read and stored successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_read() * @see eet_data_image_decode() * @see eet_data_image_decode_to_surface() * @see eet_data_image_read_to_surface_cipher() * @see eet_data_image_decode_to_cspace_surface_cipher() - * - * @since 1.0.2 - * @ingroup Eet_File_Image_Group */ EAPI int eet_data_image_read_to_surface(Eet_File *ef, @@ -1197,41 +1141,43 @@ eet_data_image_read_to_surface(Eet_File *ef, Eet_Image_Encoding *lossy); /** - * Write image data to the named key in an eet file. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param data A pointer to the image pixel data. - * @param w The width of the image in pixels. - * @param h The height of the image in pixels. - * @param alpha The alpha channel flag. - * @param compress The compression amount. - * @param quality The quality encoding amount. - * @param lossy The lossiness flag. - * @return Success if the data was encoded and written or not. - * - * This function takes image pixel data and encodes it in an eet file - * stored under the supplied name key, and returns how many bytes were - * actually written to encode the image data. - * - * The data expected is the same format as returned by eet_data_image_read. - * If this is not the case weird things may happen. Width and height must - * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning - * the alpha values are not useful and 1 meaning they are). Compress can - * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). - * This is only used if the image is not lossily encoded. Quality is used on - * lossy compression and should be a value from 0 to 100. The lossy flag - * can be 0 or 1. 0 means encode losslessly and 1 means to encode with - * image quality loss (but then have a much smaller encoding). - * - * On success this function returns the number of bytes that were required - * to encode the image data, or on failure it returns 0. + * @brief Writes image data to the named key in an eet file. + * + * @details This function takes image pixel data and encodes it in an eet file + * stored under the supplied name key, and returns how many bytes were + * actually written to encode the image data. + * + * @since 1.0.0 + * + * @remarks The data expected is the same format as returned by eet_data_image_read. + * If this is not the case, weird things may happen. Width and height must + * be between @c 1 and @c 8000 pixels. The alpha flags can be @c 0 or @c 1 (@c 0 meaning + * the alpha values are not useful and @c 1 meaning they are). Compress can + * be from @c 0 to @c 9 (@c 0 meaning no compression, @c 9 meaning full compression). + * This is only used if the image is not lossily encoded. Quality is used on + * lossy compression and should be a value from @c 0 to @c 100. The lossy flag + * can be @c 0 or @c 1. @c 0 means encode losslessly and @c 1 means to encode with + * image quality loss (but then have a much smaller encoding). + * + * @remarks On success, this function returns the number of bytes that were required + * to encode the image data, or on failure it returns @c 0. + * + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] data A pointer to the image pixel data + * @param[in] w The width of the image in pixels + * @param[in] h The height of the image in pixels + * @param[in] alpha The alpha channel flag + * @param[in] compress The compression amount + * @param[in] quality The quality encoding amount + * @param[in] lossy The lossiness flag + * @return The number of bytes to encode the image data, \n + * otherwise @c 0 on failure * * @see eet_data_image_read() * @see eet_data_image_encode() * @see eet_data_image_write_cipher() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI int eet_data_image_write(Eet_File *ef, @@ -1245,29 +1191,30 @@ eet_data_image_write(Eet_File *ef, Eet_Image_Encoding lossy); /** - * Decode Image data header only to get information. - * @param data The encoded pixel data. - * @param size The size, in bytes, of the encoded pixel data. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 on failure. + * @brief Decodes image data header to get information. + * + * @details This function works exactly like eet_data_image_header_read(), but instead + * of reading from an Eet file, it takes the buffer of size @a size pointed + * by @a data, which must be a valid Eet encoded image. * - * This function works exactly like eet_data_image_header_read(), but instead - * of reading from an Eet file, it takes the buffer of size @p size pointed - * by @p data, which must be a valid Eet encoded image. + * @since 1.0.0 * - * On success the function returns 1 indicating the header was read and - * decoded properly, or 0 on failure. + * @remarks On success, the function returns @c 1 indicating the header is read and + * decoded properly, or @c 0 on failure. + * + * @param[in] data The encoded pixel data + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if the image data header is decoded successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_header_read() * @see eet_data_image_header_decode_cipher() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI int eet_data_image_header_decode(const void *data, @@ -1280,34 +1227,34 @@ eet_data_image_header_decode(const void *data, Eet_Image_Encoding *lossy); /** - * Decode Image data into pixel data. - * @param data The encoded pixel data. - * @param size The size, in bytes, of the encoded pixel data. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return The image pixel data decoded + * @brief Decodes image data into pixel data. + * + * @details This function takes encoded pixel data and decodes it into raw RGBA + * pixels on success. + * @since 1.0.0 * - * This function takes encoded pixel data and decodes it into raw RGBA - * pixels on success. + * @remarks It works exactly like eet_data_image_read(), but it takes the encoded + * data in the @a data buffer of size @a size, instead of reading from a file. + * All the others parameters are also the same. * - * It works exactly like eet_data_image_read(), but it takes the encoded - * data in the @p data buffer of size @p size, instead of reading from a file. - * All the others parameters are also the same. + * @remarks On success, the function returns a pointer to the image data decoded. The + * calling application is responsible for calling free() on the image data + * when it is done with it. On failure, @c NULL is returned and the parameter + * values may not contain any sensible data. * - * On success the function returns a pointer to the image data decoded. The - * calling application is responsible for calling free() on the image data - * when it is done with it. On failure NULL is returned and the parameter - * values may not contain any sensible data. + * @param[in] data The encoded pixel data + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return The image pixel data decoded, \n + * @c otherwise @c NULL on failure * * @see eet_data_image_read() * @see eet_data_image_decode_cipher() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI void * eet_data_image_decode(const void *data, @@ -1320,32 +1267,32 @@ eet_data_image_decode(const void *data, Eet_Image_Encoding *lossy); /** - * Decode Image data into pixel data and stores in the given buffer. - * @param data The encoded pixel data. - * @param size The size, in bytes, of the encoded pixel data. - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. + * @brief Decodes image data into pixel data and stores in the given buffer. + * @since 1.0.2 * - * Like eet_data_image_read_to_surface(), but reading the given @p data buffer - * instead of a file. + * @remarks Like eet_data_image_read_to_surface(), but reading the given @a data buffer + * instead of a file. * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @remarks On success, the function returns @c 1, and @c 0 on failure. On failure, the + * parameter values may not contain any sensible data. + * + * @param[in] data The encoded pixel data + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if the image is decoded successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_read_to_surface() * @see eet_data_image_decode_to_surface_cipher() - * - * @since 1.0.2 - * @ingroup Eet_File_Image_Group */ EAPI int eet_data_image_decode_to_surface(const void *data, @@ -1362,34 +1309,33 @@ eet_data_image_decode_to_surface(const void *data, Eet_Image_Encoding *lossy); /** - * Encode image data for storage or transmission. - * @param data A pointer to the image pixel data. - * @param size_ret A pointer to an int to hold the size of the returned data. - * @param w The width of the image in pixels. - * @param h The height of the image in pixels. - * @param alpha The alpha channel flag. - * @param compress The compression amount. - * @param quality The quality encoding amount. - * @param lossy The lossiness flag. - * @return The encoded image data. + * @brief Encodes image data for storage or transmission. + * + * @details This function encodes image pixel data with compression and + * possible loss of quality (as a trade off for size) for storage or + * transmission to another system. + * @since 1.0.0 * - * This function stakes image pixel data and encodes it with compression and - * possible loss of quality (as a trade off for size) for storage or - * transmission to another system. + * @remarks It works like eet_data_image_write(), but instead of writing the encoded + * image into an Eet file, it allocates a new buffer of the size required and + * returns the encoded data in it. * - * It works like eet_data_image_write(), but instead of writing the encoded - * image into an Eet file, it allocates a new buffer of the size required and - * returns the encoded data in it. + * @remarks On success, this function returns a pointer to the encoded data that you + * can free with free() when no longer needed. * - * On success this function returns a pointer to the encoded data that you - * can free with free() when no longer needed. + * @param[in] data A pointer to the image pixel data + * @param[out] size_ret A pointer to an int to hold the size of the returned data + * @param[in] w The width of the image in pixels + * @param[in] h The height of the image in pixels + * @param[in] alpha The alpha channel flag + * @param[in] compress The compression amount + * @param[in] quality The quality encoding amount + * @param[in] lossy The lossiness flag + * @return The encoded image data * * @see eet_data_image_write() * @see eet_data_image_read() * @see eet_data_image_encode_cipher() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Group */ EAPI void * eet_data_image_encode(const void *data, @@ -1402,52 +1348,81 @@ eet_data_image_encode(const void *data, Eet_Image_Encoding lossy); /** + * @brief Gets the colorspace that Eet can decode into of a given eet image resource. + * + * @since 1.10.0 + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] cspaces The returned pointer by Eet to a list of possible decoding colorspace + * finished by @c EET_COLORSPACE_ARGB8888 \n + * If @c NULL, only EET_COLORSPACE_ARGB8888 is supported. + * @return @c 1 if the colorspace is obtained successfully, \n + * otherwise @c 0 on failure + */ +EAPI int +eet_data_image_colorspace_get(Eet_File *ef, + const char *name, + const char *cipher_key, + const Eet_Colorspace **cspaces); + +/** + * @} + */ + +/** + * @internal * @defgroup Eet_File_Image_Cipher_Group Image Store and Load using a Cipher + * @ingroup Eet_File_Image_Group * * Most of the @ref Eet_File_Image_Group have alternative versions * that accounts for ciphers to protect their content. * * @see @ref Eet_Cipher_Group * - * @ingroup Eet_File_Image_Group + * @{ */ /** - * Read just the header data for an image and dont decode the pixels using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on successful decode, 0 otherwise - * - * This function reads an image from an eet file stored under the named - * key in the eet file and return a pointer to the decompressed pixel data. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1 indicating the header was read and - * decoded properly, or 0 on failure. + * @brief Reads only the header data for an image and does not decode the pixels using a cipher. * - * @see eet_data_image_header_read() + * @details This function reads an image from an eet file stored under the named + * key in the eet file and returns a pointer to the decompressed pixel data. + * + * @since 1.0.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success the function returns @c 1 indicating the header is read and + * decoded properly, or @c 0 on failure. * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 is the image is read successfully, \n + * otherwise @c 0 on failure + * + * @see eet_data_image_header_read() */ EAPI int eet_data_image_header_read_cipher(Eet_File *ef, @@ -1461,61 +1436,44 @@ eet_data_image_header_read_cipher(Eet_File *ef, Eet_Image_Encoding *lossy); /** - * Get the colorspace Eet can decode into of a given eet image ressource - * - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param cspaces Returned pointer by Eet to a list of possible decoding colorspace finished by @c EET_COLORSPACE_ARGB8888. If @c NULL, only EET_COLORSPACE_ARGB8888 is supported. - * @return 1 on successful get, 0 otherwise. - * - * @since 1.10.0 - * @ingroup Eet_File_Image_Group - */ -EAPI int -eet_data_image_colorspace_get(Eet_File *ef, - const char *name, - const char *cipher_key, - const Eet_Colorspace **cspaces); - -/** - * Read image data from the named key in the eet file using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return The image pixel data decoded - * - * This function reads an image from an eet file stored under the named - * key in the eet file and return a pointer to the decompressed pixel data. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns a pointer to the image data decoded. The - * calling application is responsible for calling free() on the image data - * when it is done with it. On failure NULL is returned and the parameter - * values may not contain any sensible data. + * @brief Reads image data from the named key in the eet file using a cipher. + * + * @details This function reads an image from an eet file stored under the named + * key in the eet file and return a pointer to the decompressed pixel data. + * + * @since 1.0.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success, the function returns a pointer to the image data decoded. The + * calling application is responsible for calling free() on the image data + * when it is done with it. On failure, @c NULL is returned and the parameter + * values may not contain any sensible data. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return The image pixel data decoded * * @see eet_data_image_read() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI void * eet_data_image_read_cipher(Eet_File *ef, @@ -1529,47 +1487,49 @@ eet_data_image_read_cipher(Eet_File *ef, Eet_Image_Encoding *lossy); /** - * Read image data from the named key in the eet file using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. - * - * This function reads an image from an eet file stored under the named - * key in the eet file and store the decompressed pixel data in the provided - * surface with an @c EET_COLORSPACE_ARGB8888 colorspace. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @brief Reads image data from the named key in the eet file using a cipher. + * + * @details This function reads an image from an eet file stored under the named + * key in the eet file and store the decompressed pixel data in the provided + * surface with an @c EET_COLORSPACE_ARGB8888 colorspace. + * + * @since 1.0.2 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value/amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success, the function returns @c 1, and @c 0 on failure. On failure, the + * parameter values may not contain any sensible data. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if image data is read successfully, + * otherwise @c 0 on failure * * @see eet_data_image_read_to_surface() * @see eet_data_image_decode_to_cspace_surface_cipher() - * - * @since 1.0.2 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int eet_data_image_read_to_surface_cipher(Eet_File *ef, @@ -1588,49 +1548,51 @@ eet_data_image_read_to_surface_cipher(Eet_File *ef, /** - * Read image data from the named key in the eet file using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param cspace The color space of the pixels bsurface. - * @param alpha A pointer to the int to hold the alpha flag. - * @param comp A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. - * - * This function reads an image from an eet file stored under the named - * key in the eet file and store the decompressed pixel data in the provided - * surface colorspace. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @brief Reads image data from the named key in the eet file using a cipher. + * + * @details This function reads an image from an eet file stored under the named + * key in the eet file and store the decompressed pixel data in the provided + * surface colorspace. + * + * @since 1.10.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value/amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success the function returns @c 1, and @c 0 on failure. On failure the + * parameter values may not contain any sensible data. + * + * @param[in] ef A valid eet file handle opened for reading + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[in] cspace The color space of the pixels bsurface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] comp A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if image data is read successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_read_to_surface() * @see eet_data_image_decode_to_cspace_surface_cipher() * @see eet_data_image_read_to_surface_cipher() - * - * @since 1.10.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int eet_data_image_read_to_cspace_surface_cipher(Eet_File *ef, @@ -1650,48 +1612,49 @@ eet_data_image_read_to_cspace_surface_cipher(Eet_File *ef, /** - * Read image data from the named key in the eet file using a cipher. - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param cspace The color space of the pixel surface - * @param alpha A pointer to the int to hold the alpha flag. - * @param comp A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. - * - * This function reads an image from an eet file stored under the named - * key in the eet file and store the decompressed pixels in the specified - * color space inside the given surface. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @brief Reads image data from the named key in the eet file using a cipher. + * + * @details This function reads an image from an eet file stored under the named + * key in the eet file and store the decompressed pixels in the specified + * color space inside the given surface. + * + * @since 1.10.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success the function returns @c 1, and @c 0 on failure. On failure the + * parameter values may not contain any sensible data. + * + * @param[in] data A pointer to the image pixel data + * @param[in] cipher_key The key to use as cipher + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[in] cspace The color space of the pixel surface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] comp A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if image data is read successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_read_to_surface() * @see eet_data_image_read_to_surface_cipher() - * - * @since 1.10.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int @@ -1711,40 +1674,41 @@ eet_data_image_decode_to_cspace_surface_cipher(const void *data, Eet_Image_Encoding *lossy); /** - * Write image data to the named key in an eet file using a cipher. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param data A pointer to the image pixel data. - * @param w The width of the image in pixels. - * @param h The height of the image in pixels. - * @param alpha The alpha channel flag. - * @param compress The compression amount. - * @param quality The quality encoding amount. - * @param lossy The lossiness flag. - * @return Success if the data was encoded and written or not. - * - * This function takes image pixel data and encodes it in an eet file - * stored under the supplied name key, and returns how many bytes were - * actually written to encode the image data. - * - * The data expected is the same format as returned by eet_data_image_read. - * If this is not the case weird things may happen. Width and height must - * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning - * the alpha values are not useful and 1 meaning they are). Compress can - * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). - * This is only used if the image is not lossily encoded. Quality is used on - * lossy compression and should be a value from 0 to 100. The lossy flag - * can be 0 or 1. 0 means encode losslessly and 1 means to encode with - * image quality loss (but then have a much smaller encoding). - * - * On success this function returns the number of bytes that were required - * to encode the image data, or on failure it returns 0. + * @brief Writes image data to the named key in an eet file using a cipher. + * + * @details This function takes image pixel data and encodes it in an eet file + * stored under the supplied name key, and returns how many bytes were + * actually written to encode the image data. + * @since 1.0.0 + * + * @remarks The data expected is the same format as returned by eet_data_image_read. + * If this is not the case weird things may happen. Width and height must + * be between @c 1 and @c 8000 pixels. The alpha flags can be @c 0 or @c 1 (@c 0 meaning + * the alpha values are not useful and @c 1 meaning they are). Compress can + * be from @c 0 to @c 9 (@c 0 meaning no compression, @c 9 meaning full compression). + * This is only used if the image is not lossily encoded. Quality is used on + * lossy compression and should be a value from @c 0 to @c 100. The lossy flag + * can be @c 0 or @c 1. @c 0 means encode losslessly and @c 1 means to encode with + * image quality loss (but then have a much smaller encoding). + * + * @remarks On success, this function returns the number of bytes that were required + * to encode the image data, or on failure it returns @c 0. + * + * @param[in] ef A valid eet file handle opened for writing + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] data A pointer to the image pixel data + * @param[in] w The width of the image in pixels + * @param[in] h The height of the image in pixels + * @param[in] alpha The alpha channel flag + * @param[in] compress The compression amount + * @param[in] quality The quality encoding amount + * @param[in] lossy The lossiness flag + * @return The number of bytes to encode the image data, \n + * otherwise @c 0 on failure * * @see eet_data_image_write() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int eet_data_image_write_cipher(Eet_File *ef, @@ -1759,41 +1723,41 @@ eet_data_image_write_cipher(Eet_File *ef, Eet_Image_Encoding lossy); /** - * Decode Image data header only to get information using a cipher. - * @param data The encoded pixel data. - * @param cipher_key The key to use as cipher. - * @param size The size, in bytes, of the encoded pixel data. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 on failure. - * - * This function takes encoded pixel data and decodes it into raw RGBA - * pixels on success. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1 indicating the header was read and - * decoded properly, or 0 on failure. + * @brief Decodes image data header only to get information using a cipher. + * + * @details This function takes encoded pixel data and decodes it into raw RGBA + * pixels on success. + * @since 1.0.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success, the function returns @c 1 indicating the header is read and + * decoded properly, or @c 0 on failure. + * + * @param[in] data The encoded pixel data + * @param[in] cipher_key The key to use as cipher + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if the header is decoded successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_header_decode() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int eet_data_image_header_decode_cipher(const void *data, @@ -1807,43 +1771,43 @@ eet_data_image_header_decode_cipher(const void *data, Eet_Image_Encoding *lossy); /** - * Decode Image data into pixel data using a cipher. - * @param data The encoded pixel data. - * @param cipher_key The key to use as cipher. - * @param size The size, in bytes, of the encoded pixel data. - * @param w A pointer to the unsigned int to hold the width in pixels. - * @param h A pointer to the unsigned int to hold the height in pixels. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return The image pixel data decoded - * - * This function takes encoded pixel data and decodes it into raw RGBA - * pixels on success. - * - * The other parameters of the image (width, height etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns a pointer to the image data decoded. The - * calling application is responsible for calling free() on the image data - * when it is done with it. On failure NULL is returned and the parameter - * values may not contain any sensible data. + * @brief Decodes image data into pixel data using a cipher. + * + * @details This function takes encoded pixel data and decodes it into raw RGBA + * pixels on success. + * @since 1.0.0 + * + * @remarks The other parameters of the image (width, height etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success, the function returns a pointer to the image data decoded. The + * calling application is responsible for calling free() on the image data + * when it is done with it. On failure, @c NULL is returned and the parameter + * values may not contain any sensible data. + * + * @param[in] data The encoded pixel data + * @param[in] cipher_key The key to use as cipher + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[out] w A pointer to the unsigned int to hold the width in pixels + * @param[out] h A pointer to the unsigned int to hold the height in pixels + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return The image pixel data decoded, \n + * otherwise @c NULL on failure * * @see eet_data_image_decode() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI void * eet_data_image_decode_cipher(const void *data, @@ -1857,45 +1821,45 @@ eet_data_image_decode_cipher(const void *data, Eet_Image_Encoding *lossy); /** - * Decode Image data into pixel data using a cipher. - * @param data The encoded pixel data. - * @param cipher_key The key to use as cipher. - * @param size The size, in bytes, of the encoded pixel data. - * @param src_x The starting x coordinate from where to dump the stream. - * @param src_y The starting y coordinate from where to dump the stream. - * @param d A pointer to the pixel surface. - * @param w The expected width in pixels of the pixel surface to decode. - * @param h The expected height in pixels of the pixel surface to decode. - * @param row_stride The length of a pixels line in the destination surface. - * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. - * @param quality A pointer to the int to hold the quality amount. - * @param lossy A pointer to the int to hold the lossiness flag. - * @return 1 on success, 0 otherwise. - * - * This function takes encoded pixel data and decodes it into raw RGBA - * pixels on success. - * - * The other parameters of the image (alpha, compress etc.) are placed into - * the values pointed to (they must be supplied). The pixel data is a linear - * array of pixels starting from the top-left of the image scanning row by - * row from left to right. Each pixel is a 32bit value, with the high byte - * being the alpha channel, the next being red, then green, and the low byte - * being blue. The width and height are measured in pixels and will be - * greater than 0 when returned. The alpha flag is either 0 or 1. 0 denotes - * that the alpha channel is not used. 1 denotes that it is significant. - * Compress is filled with the compression value/amount the image was - * stored with. The quality value is filled with the quality encoding of - * the image file (0 - 100). The lossy flags is either 0 or 1 as to if - * the image was encoded lossily or not. - * - * On success the function returns 1, and 0 on failure. On failure the - * parameter values may not contain any sensible data. + * @brief Decodes image data into pixel data using a cipher. + * + * @details This function takes encoded pixel data and decodes it into raw RGBA + * pixels on success. + * @since 1.0.2 + * + * @remarks The other parameters of the image (alpha, compress etc.) are placed into + * the values pointed to (they must be supplied). The pixel data is a linear + * array of pixels starting from the top-left of the image scanning row by + * row from left to right. Each pixel is a 32bit value, with the high byte + * being the alpha channel, the next being red, then green, and the low byte + * being blue. The width and height are measured in pixels and is + * greater than @c 0 when returned. The alpha flag is either @c 0 or @c 1. @c 0 denotes + * that the alpha channel is not used. @c 1 denotes that it is significant. + * Compress is filled with the compression value or amount the image is + * stored with. The quality value is filled with the quality encoding of + * the image file (0 - 100). The lossy flags is either @c 0 or @c 1 as to if + * the image is encoded lossily or not. + * + * @remarks On success, the function returns @c 1, and @c 0 on failure. On failure, the + * parameter values may not contain any sensible data. + * + * @param[in] data The encoded pixel data + * @param[in] cipher_key The key to use as cipher + * @param[in] size The size, in bytes, of the encoded pixel data + * @param[in] src_x The starting x coordinate from where to dump the stream + * @param[in] src_y The starting y coordinate from where to dump the stream + * @param[out] d A pointer to the pixel surface + * @param[in] w The expected width in pixels of the pixel surface to decode + * @param[in] h The expected height in pixels of the pixel surface to decode + * @param[in] row_stride The length of a pixels line in the destination surface + * @param[out] alpha A pointer to the int to hold the alpha flag + * @param[out] compress A pointer to the int to hold the compression amount + * @param[out] quality A pointer to the int to hold the quality amount + * @param[out] lossy A pointer to the int to hold the lossiness flag + * @return @c 1 if the image data is decoded successfully, \n + * otherwise @c 0 on failure * * @see eet_data_image_decode_to_surface() - * - * @since 1.0.2 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI int eet_data_image_decode_to_surface_cipher(const void *data, @@ -1913,39 +1877,38 @@ eet_data_image_decode_to_surface_cipher(const void *data, Eet_Image_Encoding *lossy); /** - * Encode image data for storage or transmission using a cipher. - * @param data A pointer to the image pixel data. - * @param cipher_key The key to use as cipher. - * @param size_ret A pointer to an int to hold the size of the returned data. - * @param w The width of the image in pixels. - * @param h The height of the image in pixels. - * @param alpha The alpha channel flag. - * @param compress The compression amount. - * @param quality The quality encoding amount. - * @param lossy The lossiness flag. - * @return The encoded image data. - * - * This function stakes image pixel data and encodes it with compression and - * possible loss of quality (as a trade off for size) for storage or - * transmission to another system. - * - * The data expected is the same format as returned by eet_data_image_read. - * If this is not the case weird things may happen. Width and height must - * be between 1 and 8000 pixels. The alpha flags can be 0 or 1 (0 meaning - * the alpha values are not useful and 1 meaning they are). Compress can - * be from 0 to 9 (0 meaning no compression, 9 meaning full compression). - * This is only used if the image is not lossily encoded. Quality is used on - * lossy compression and should be a value from 0 to 100. The lossy flag - * can be 0 or 1. 0 means encode losslessly and 1 means to encode with - * image quality loss (but then have a much smaller encoding). - * - * On success this function returns a pointer to the encoded data that you - * can free with free() when no longer needed. + * @brief Encodes image data for storage or transmission using a cipher. + * + * @details This function encodes image pixel data with compression and + * possible loss of quality (as a trade off for size) for storage or + * transmission to another system. + * @since 1.0.0 + * + * @remarks The data expected is the same format as returned by eet_data_image_read. + * If this is not the case weird things may happen. Width and height must + * be between @c 1 and @c 8000 pixels. The alpha flags can be @c 0 or @c 1 (@c 0 meaning + * the alpha values are not useful and @c 1 meaning they are). Compress can + * be from @c 0 to @c 9 (@c 0 meaning no compression, @c 9 meaning full compression). + * This is only used if the image is not lossily encoded. Quality is used on + * lossy compression and should be a value from @c 0 to @c 100. The lossy flag + * can be @c 0 or @c 1. @c 0 means encode losslessly and @c 1 means to encode with + * image quality loss (but then have a much smaller encoding). + * + * @remarks On success, this function returns a pointer to the encoded data that you + * can free with free() when no longer needed. + * + * @param[in] data A pointer to the image pixel data + * @param[in] cipher_key The key to use as cipher + * @param[in] size_ret A pointer to an int to hold the size of the returned data + * @param[in] w The width of the image in pixels + * @param[in] h The height of the image in pixels + * @param[in] alpha The alpha channel flag + * @param[in] compress The compression amount + * @param[in] quality The quality encoding amount + * @param[in] lossy The lossiness flag + * @return The encoded image data * * @see eet_data_image_encode() - * - * @since 1.0.0 - * @ingroup Eet_File_Image_Cipher_Group */ EAPI void * eet_data_image_encode_cipher(const void *data, @@ -1959,11 +1922,16 @@ eet_data_image_encode_cipher(const void *data, int *size_ret); /** + * @} + */ + +/** + * @internal * @defgroup Eet_Cipher_Group Cipher, Identity and Protection Mechanisms - * @ingroup Eet + * @ingroup Eet_Group * * Eet allows one to protect entries of an #Eet_File - * individually. This may be used to ensure data was not tampered or + * individually. This may be used to ensure data is not tampered or * that third party does not read your data. * * @see @ref Eet_File_Cipher_Group @@ -1980,40 +1948,38 @@ eet_data_image_encode_cipher(const void *data, typedef struct _Eet_Key Eet_Key; /** - * @} - */ - -/** - * Callback used to request if needed the password of a private key. - * - * @param buffer the buffer where to store the password. - * @param size the maximum password size (size of buffer, including '@\0'). - * @param rwflag if the buffer is also readable or just writable. - * @param data currently unused, may contain some context in future. - * @return 1 on success and password was set to @p buffer, 0 on failure. + * @brief Callback to request whether a password is needed for a private key. + * @since 1.2.0 * - * @since 1.2.0 + * @param buffer The buffer to store the password + * @param size The maximum password size \n + * The size of buffer, including '@\0'. + * @param rwflag Indicator for the buffer mode \n + * Whether it is also readable or just writeable. + * @param data Currently unused, may contain some context in future + * @return @c 1 on success and password is set to @a buffer, \n + * otherwise @c 0 on failure * @ingroup Eet_Cipher_Group */ typedef int (*Eet_Key_Password_Callback)(char *buffer, int size, int rwflag, void *data); /** - * Create an Eet_Key needed for signing an eet file. + * @brief Creates an Eet_Key needed for signing an eet file. + * @since 1.2.0 * - * The certificate should provide the public that match the private key. - * No verification is done to ensure that. + * @remarks The certificate should provide the public key that matches the private key. + * No verification is done to ensure that. * - * @param certificate_file The file where to find the certificate. - * @param private_key_file The file that contains the private key. - * @param cb Function to callback if password is required to unlock - * private key. - * @return A key handle to use, or @c NULL on failure. + * @remarks You need to compile signature support in EET. * - * @see eet_identity_close() + * @param[in] certificate_file The file to find the certificate + * @param[in] private_key_file The file that contains the private key + * @param[in] cb The callback to check whether password is required to unlock + * private key + * @return A key handle to use, \n + * otherwise @c NULL on failure * - * @warning You need to compile signature support in EET. - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @see eet_identity_close() */ EAPI Eet_Key * eet_identity_open(const char *certificate_file, @@ -2021,114 +1987,114 @@ eet_identity_open(const char *certificate_file, Eet_Key_Password_Callback cb); /** - * Close and release all resource used by an Eet_Key. An - * reference counter prevent it from being freed until all file - * using it are also closed. + * @brief Closes and releases all resources used by an Eet_Key. + * @since 1.2.0 * - * @param key the key handle to close and free resources. + * @remarks A reference counter prevents it from being freed until all the files + * using it are also closed. * - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] key The key handle to close and free resources */ EAPI void eet_identity_close(Eet_Key *key); /** - * Set a key to sign a file - * - * @param ef the file to set the identity. - * @param key the key handle to set as identity. - * @return #EET_ERROR_BAD_OBJECT if @p ef is invalid or - * #EET_ERROR_NONE on success. + * @brief Sets a key to sign a file. + * @since 1.2.0 * - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] ef The file to set the identity + * @param[in] key The key handle to set as identity + * @return #EET_ERROR_NONE is the key is set successfully, \n + * otherwise #EET_ERROR_BAD_OBJECT if @a ef is invalid */ EAPI Eet_Error eet_identity_set(Eet_File *ef, Eet_Key *key); /** - * Display both private and public key of an Eet_Key. + * @brief Displays both private and public key of an Eet_Key. + * @since 1.2.0 * - * @param key the handle to print. - * @param out where to print. + * @remarks You need to compile signature support in EET. * - * @warning You need to compile signature support in EET. - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] key The handle to print + * @param[in] out The output destination to print */ EAPI void eet_identity_print(Eet_Key *key, FILE *out); /** - * Get the x509 der certificate associated with an Eet_File. Will return NULL - * if the file is not signed. + * @brief Gets the x509 der certificate associated with an Eet_File. + * @details This function returns @c NULL if the file is not signed. + * @since 1.2.0 * - * @param ef The file handle to query. - * @param der_length The length of returned data, may be @c NULL. - * @return the x509 certificate or @c NULL on error. - * - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] ef The file handle to query + * @param[out] der_length The length of returned data \n + * This may be @c NULL. + * @return The x509 certificate, \n + * otherwise @c NULL on error */ EAPI const void * eet_identity_x509(Eet_File *ef, int *der_length); /** - * Get the raw signature associated with an Eet_File. Will return NULL - * if the file is not signed. + * @brief Gets the raw signature associated with an Eet_File. + * @details This function returns @c NULL if the file is not signed. * - * @param ef The file handle to query. - * @param signature_length The length of returned data, may be @c NULL. - * @return the raw signature or @c NULL on error. - * - * @ingroup Eet_Cipher_Group + * @param[in] ef The file handle to query + * @param[out] signature_length The length of returned data \n + * This may be @c NULL + * @return The raw signature, \n + * otherwise @c NULL on error */ EAPI const void * eet_identity_signature(Eet_File *ef, int *signature_length); /** - * Get the SHA1 associated with a file. Could be the one used to - * sign the data or if the data where not signed, it will be the - * SHA1 of the file. + * @brief Gets the SHA1 associated with a file. + * @since 1.2.0 * - * @param ef The file handle to query. - * @param sha1_length The length of returned data, may be @c NULL. - * @return the associated SHA1 or @c NULL on error. + * @remarks This could be used to sign the data or if the data where not signed, + * it is the SHA1 of the file. * - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] ef The file handle to query + * @param[out] sha1_length The length of returned data \n + * This may be @c NULL. + * @return The associated SHA1, \n + * otherwise @c NULL on error */ EAPI const void * eet_identity_sha1(Eet_File *ef, int *sha1_length); /** - * Display the x509 der certificate to out. + * @brief Displays the x509 der certificate on @a out. + * @since 1.2.0 * - * @param certificate the x509 certificate to print - * @param der_length The length the certificate. - * @param out where to print. + * @remarks You need to compile signature support in EET. * - * @warning You need to compile signature support in EET. - * @since 1.2.0 - * @ingroup Eet_Cipher_Group + * @param[in] certificate The x509 certificate to print + * @param[in] der_length The length of the certificate + * @param[in] out The output destination */ EAPI void eet_identity_certificate_print(const unsigned char *certificate, int der_length, FILE *out); +/** + * @} + */ /** + * @internal * @defgroup Eet_Data_Group Eet Data Serialization - * @ingroup Eet + * @ingroup Eet_Group * - * Convenience functions to serialize and parse complex data - * structures to binary blobs. + * @brief This group provides convenience functions to serialize and parse complex data + * structures to binary blobs. * * While Eet core just handles binary blobs, it is often required * to save some structured data of different types, such as @@ -2148,93 +2114,93 @@ eet_identity_certificate_print(const unsigned char *certificate, * defined. * * Given that C provides no introspection, this process can be - * quite cumbersome, so we provide lots of macros and convenience - * functions to aid creating the types. + * quite cumbersome, so lots of macros and convenience + * functions are provided to aid creating the types. * - * We make now a quick overview of some of the most commonly used elements + * The following is a quick overview of some of the most commonly used elements * of this part of the library. A simple example of a configuration system - * will work as a somewhat real life example that is still simple enough to + * works as a somewhat real life example that is still simple enough to * follow. - * Only the relevant sections will be shown here, but you can get the full + * Only the relevant sections are shown here, but you can get the full * code @ref eet-data-simple.c "here". * - * Ignoring the included headers, we'll begin by defining our configuration + * Ignoring the included headers, you begin by defining your configuration * struct. * @dontinclude eet-data-simple.c * @skip typedef * @until } * - * When using Eet, you don't think in matters of what data the program needs - * to run and which you would like to store. It's all the same and if it makes - * more sense to keep them together, it's perfectly fine to do so. At the time + * When using Eet, you do not think in matters of what data the program needs + * to run and which you would like to store. It is all the same and if it makes + * more sense to keep them together, it is perfectly fine to do so. At the time * of telling Eet how your data is comprised you can leave out the things * that are runtime only and let Eet take care of the rest for you. * * The key used to store the config follows, as well as the variable used to - * store our data descriptor. - * This last one is very important. It's the one thing that Eet will use to + * store the data descriptor. + * This last one is very important. It is the one thing that Eet uses to * identify your data, both at the time of writing it to the file and when * loading from it. * @skipline MY_CONF * @skipline Eet_Data_Descriptor * - * Now we'll see how to create this descriptor, so Eet knows how to handle - * our data later on. - * Begin our function by declaring an Eet_Data_Descriptor_Class, which is + * Now you see how to create this descriptor, so Eet knows how to handle + * your data later on. + * Begin the function by declaring an Eet_Data_Descriptor_Class, which is * used to create the actual descriptor. This class contains the name of - * our data type, its size and several functions that dictate how Eet should - * handle memory to allocate the necessary bits to bring our data to life. - * You, as a user, will very hardly set this class' contents directly. The + * your data type, its size and several functions that dictate how Eet should + * handle memory to allocate the necessary bits to bring your data to life. + * You, as a user, very hardly set this class' contents directly. The * most common scenario is to use one of the provided macros that set it using - * the Eina data types, so that's what we'll be doing across all our examples. + * the Eina data types, so that is what you are doing across all your examples. * @skip static void * @until eet_data_descriptor_stream_new * - * Now that we have our descriptor, we need to make it describe something. - * We do so by telling it which members of our struct we want it to know about + * Now that you have your descriptor, you need to make it describe something. + * Do so by telling it which members of your struct you want it to know about * and their types. - * The eet_data_descriptor_element_add() function takes care of this, but it's + * The eet_data_descriptor_element_add() function takes care of this, but it is * too cumbersome for normal use, so several macros are provided that make * it easier to handle. Even with them, however, code can get very repetitive - * and it's not uncommon to define custom macros using them to save on typing. + * and it is not uncommon to define custom macros using them to save on typing. * @skip #define * @until } * - * Now our descriptor knows about the parts of our structure that we are + * Now your descriptor knows about the parts of your structure that you are * interesting in saving. You can see that not all of them are there, yet Eet - * will find those that need saving and do the right thing. When loading our - * data, any non-described fields in the structure will be zeroed, so there's + * finds those that need saving and do the right thing. When loading your + * data, any non-described fields in the structure are zeroed, so there is * no need to worry about garbage memory in them. - * Refer to the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand - * what our macro does. + * See the documentation of #EET_DATA_DESCRIPTOR_ADD_BASIC to understand + * what your macro does. * - * We are done with our descriptor init function and it's proper to have the + * You are done with your descriptor init function and it is proper to have the * relevant shutdown. Proper coding guidelines indiciate that all memory - * allocated should be freed when the program ends, and since you will most - * likely keep your descriptor around for the life or your application, it's + * allocated should be freed when the program ends, and since you must most + * likely keep your descriptor around for the life or your application, it is * only right to free it at the end. * @skip static void * @until } * * Not listed here, but included in the full example are functions to create - * a blank configuration and free it. The first one will only be used when + * a blank configuration and free it. The first one is only used when * no file exists to load from, or nothing is found in it, but the latter is - * used regardless of where our data comes from. Unless you are reading direct - * data from the Eet file, you will be in charge of freeing anything loaded + * used regardless of where your data comes from. Unless you are reading direct + * data from the Eet file, you are in charge of freeing anything loaded * from it. * - * Now it's time to look at how we can load our config from some file. + * Now it is time to look at how you can load your config from some file. * Begin by opening the Eet file normally. * @skip static My_Conf_Type * @until } * - * And now we need to read the data from the file and decode it using our - * descriptor. Fortunately, that's all done in one single step. + * And now you need to read the data from the file and decode it using your + * descriptor. Fortunately, that is all done in one single step. * @until goto * - * And that's it for all Eet cares about. But since we are dealing with a + * And that is it for all Eet cares about. But since you are dealing with a * common case, as is save and load of user configurations, the next fragment - * of code shows why we have a version field in our struct, and how you can + * of code shows why you have a version field in our struct, and how you can * use it to load older configuration files and update them as needed. * @until } * @@ -2253,10 +2219,10 @@ eet_identity_certificate_print(const unsigned char *certificate, * @skip return * @until } * - * To close, our main function, which doesn't do much. Just take some arguments + * To close, your main function, which does not do much. Just take some arguments * from the command line with the name of the file to load and another one - * where to save again. If input file doesn't exist, a new config structure - * will be created and saved to our output file. + * where to save again. If input file does not exist, a new config structure + * is created and saved to our output file. * @skip int main * @until return ret * @until } @@ -2266,20 +2232,23 @@ eet_identity_certificate_print(const unsigned char *certificate, * @li @ref eet_data_file_descriptor * @li @ref Example_Eet_Data_File_Descriptor_02 * @li @ref Example_Eet_Data_Cipher_Decipher + * + * @{ */ /** + * @internal * @page eet_data_nested_example Nested structures and Eet Data Descriptors * - * We've seen already a simple example of how to use Eet Data Descriptors - * to handle our structures, but it didn't show how this works when you + * You have seen already a simple example of how to use Eet Data Descriptors + * to handle your structures, but it did not show how this works when you * have structures inside other structures. * - * Now, there's a very simple case of this, for when you have inline structs - * to keep your big structure more organized, you don't need anything else + * Now, there is a very simple case of this, for when you have inline structs + * to keep your big structure more organized, you do not need anything else * besides what @ref eet-data-simple.c "this simple example does". - * Just use something like @p some_struct.sub_struct.member when adding the - * member to the descriptor and it will work. + * Just use something like @a some_struct.sub_struct.member when adding the + * member to the descriptor and it works. * * For example: * @code @@ -2309,20 +2278,20 @@ eet_identity_certificate_print(const unsigned char *certificate, * } * @endcode * - * But this is not what we are here for today. When we talk about nested - * structures, what we really want are things like lists and hashes to be + * But this is not what you are going to do. When you talk about nested + * structures, what you really want are things like lists and hashes to be * taken into consideration automatically, and all their contents saved and * loaded just like ordinary integers and strings are. * * And of course, Eet can do that, and considering the work it saves you as a - * programmer, we could say it's even easier to do than handling just integers. + * programmer, you could say it is even easier to do than handling just integers. * - * Let's begin with our example then, which is not all too different from the + * Let us begin with your example then, which is not all too different from the * simple one introduced earlier. * - * We won't ignore the headers this time to show how easy it is to use Eina - * data types with Eet, but we'll still skip most of the code that is not - * pertinent to what we want to show now, but as usual, you can get it full + * You do not ignore the headers this time to show how easy it is to use Eina + * data types with Eet, but you still skip most of the code that is not + * pertinent to what you want to show now, but as usual, you can get it full * by following @ref eet-data-nested.c "this link". * * @dontinclude eet-data-nested.c @@ -2331,123 +2300,124 @@ eet_identity_certificate_print(const unsigned char *certificate, * @skip typedef struct * @until } My_Conf_Subtype * - * Extremely similar to our previous example. Just a new struct in there, and - * a pointer to a list in the one we already had. Handling a list of subtypes - * is easy on our program, but now we'll see what Eet needs to work with them + * Extremely similar to your previous example. Just a new struct in there, and + * a pointer to a list in the one you already had. Handling a list of subtypes + * is easy on your program, but now you see what Eet needs to work with them * (Hint: it's easy too). * @skip _my_conf_descriptor * @until _my_conf_sub_descriptor * - * Since we have two structures now, it's only natural that we'll need two - * descriptors. One for each, which will be defined exactly as before. + * Since you have two structures now, it is only natural that you need two + * descriptors. One for each, which are defined exactly as before. * @skip static void * @until eddc * @skip EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET * @until _my_conf_sub_descriptor * - * We create our descriptors, each for one type, and as before, we are going to + * Create your descriptors, each for one type, and as before, you are going to * use a simple macro to set their contents, to save on typing. * @skip #define * @until EET_T_UCHAR * - * So far, nothing new. We have our descriptors and we know already how to - * save them separately. But what we want is to link them together, and even - * more so, we want our main type to hold a list of more than one of the new - * sub type. So how do we do that? + * So far, nothing new. You have your descriptors and you know already how to + * save them separately. But what you want is to link them together, and even + * more so, you want your main type to hold a list of more than one of the new + * sub type. So how do you do that? * - * Simple enough, we tell Eet that our main descriptor will hold a list, of - * which each node will point to some type described by our new descriptor. + * Simple enough, you tell Eet that your main descriptor holds a list, of + * which each node points to some type described by your new descriptor. * @skip EET_DATA_DESCRIPTOR_ADD_LIST * @until _my_conf_sub_descriptor * - * And that's all. We are closing the function now so as to not leave dangling - * curly braces, but there's nothing more to show in this example. Only other - * additions are the necessary code to free our new data, but you can see it + * And that is all. You are closing the function now so as to not leave dangling + * curly braces, but there is nothing more to show in this example. Only other + * additions are the necessary code to free your new data, but you can see it * in the full code listing. * @until } */ /** + * @internal * @page eet_data_file_descriptor Advanced use of Eet Data Descriptors * * A real life example is usually the best way to see how things are used, * but they also involve a lot more code than what needs to be shown, so - * instead of going that way, we'll be borrowing some pieces from one in - * the following example. It's been slightly modified from the original - * source to show more of the varied ways in which Eet can handle our data. + * instead of going that way, you are borrowing some pieces from one in + * the following example. It is slightly modified from the original + * source to show more of the varied ways in which Eet can handle your data. * * @ref eet-data-file_descriptor_01.c "This example" shows a cache of user - * accounts and messages received, and it's a bit more interactive than + * accounts and messages received, and it is a bit more interactive than * previous examples. * - * Let's begin by looking at the structures we'll be using. First we have - * one to define the messages the user receives and one for the one he posts. + * Begin by looking at the structures that you are using. First you have + * one to define the messages the user receives and one for the one the user posts. * Straight forward and nothing new here. * @dontinclude eet-data-file_descriptor_01.c * @skip typedef * @until My_Post * - * One more to declare the account itself. This one will contain a list of - * all messages received, and the posts we make ourselves will be kept in an + * One more to declare the account itself. This one contains a list of + * all messages received, and the posts you make ourselves are kept in an * array. No special reason other than to show how to use arrays with Eet. * @until My_Account * - * Finally, the main structure to hold our cache of accounts. We'll be looking - * for these accounts by their names, so let's keep them in a hash, using + * Finally, the main structure to hold your cache of accounts. You are looking + * for these accounts by their names, so keep them in a hash, using * that name as the key. * @until My_Cache * - * As explained before, we need one descriptor for each struct we want Eet - * to handle, but this time we also want to keep around our Eet file and its - * string dictionary. You will see why in a moment. + * As explained before, you need one descriptor for each struct that you want Eet + * to handle, but this time you also want to keep around your Eet file and its + * string dictionary. You see why in a moment. * @skip Eet_Data_Descriptor * @until _my_post_descriptor * @skip Eet_File * @until Eet_Dictionary * - * The differences begin now. They aren't much, but we'll be creating our - * descriptors differently. Things can be added to our cache, but we won't - * be modifying the current contents, so we can consider the data read from + * The differences begin now. They are not much, but you are creating your + * descriptors differently. Things can be added to your cache, but you are not + * modifying the current contents, so you can consider the data read from * it to be read-only, and thus allow Eet to save time and memory by not - * duplicating thins unnecessary. + * duplicating things unnecessarily. * @skip static void * @until _my_post_descriptor * - * As the comment in the code explains, we are asking Eet to give us strings + * As the comment in the code explains, you are asking Eet to give strings * directly from the mapped file, which avoids having to load it in memory * and data duplication. * Of course, there are things to take into account when doing things this - * way, and they will be mentioned as we encounter those special cases. + * way, and they are mentioned as you encounter those special cases. * - * Next comes the actual description of our data, just like we did in the + * Next comes the actual description of your data, just like you did in the * previous examples. * @skip #define * @until #undef * @until #define * @until #undef * - * And the account struct's description doesn't add much new, but it's worth + * And the account struct's description does not add much new, but it is worth * commenting on it. * @skip #define * @until _my_post_descriptor * - * How to add a list we've seen before, but now we are also adding an array. - * There's nothing really special about it, but it's important to note that + * You have seen before how to add a list, but now you are also adding an array. + * There is nothing really special about it, but it is important to note that * the EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY is used to add arrays of variable - * length to a descriptor. That is, arrays just like the one we defined. - * Since there's no way in C to know how long they are, we need to keep - * track of the count ourselves and Eet needs to know how to do so as well. - * That's what the @p posts_count member of our struct is for. When adding - * our array member, this macro will look for another variable in the struct - * named just like the array, but with @p _count attached to the end. - * When saving our data, Eet will know how many elements the array contains + * length to a descriptor. That is, arrays just like the one you defined. + * Since there is no way in C to know how long they are, you need to keep + * track of the count yourselves and Eet needs to know how to do so as well. + * That is what the @a posts_count member of your struct is for. When adding + * your array member, this macro looks for another variable in the struct + * named just like the array, but with @a _count attached to the end. + * When saving your data, Eet knows how many elements the array contains * by looking into this count variable. When loading back from a file, this - * variable will be set to the right number of elements. + * variable is set to the right number of elements. * * Another option for arrays is to use EET_DATA_DESCRIPTOR_ADD_ARRAY, which * takes care of fixed sized arrays. - * For example, let's suppose that we want to keep track of only the last - * ten posts the user sent, and we declare our account struct as follows + * For example, suppose that you want to keep track of only the last + * ten posts the user sent, and declare your account struct as follows: * @code * typedef struct * { @@ -2457,92 +2427,88 @@ eet_identity_certificate_print(const unsigned char *certificate, * My_Post posts[10]; * } My_Account; * @endcode - * Then we would add the array to our descriptor with + * Then add the array to your descriptor with * @code * EET_DATA_DESCRIPTOR_ADD_ARRAY(_my_account_descriptor, My_Account, "posts", * posts, _my_post_descriptor); * @endcode * - * Notice how this time we don't have a @p posts_count variable in our struct. - * We could have it for the program to keep track of how many posts the - * array actually contains, but Eet no longer needs it. Being defined that - * way the array is already taking up all the memory needed for the ten - * elements, and it is possible in C to determine how much it is in code. - * When saving our data, Eet will just dump the entire memory blob into the - * file, regardless of how much of it is really used. So it's important to + * Notice how this time you do not have a @a posts_count variable in your struct. + * You could have it for the program to keep track of how many posts the + * array actually contains, but Eet no longer needs it. Having defined + * the way the array is already taking up all the memory needed for the ten + * elements, it is possible in C to determine how much it is in code. + * When saving your data, Eet just dumps the entire memory blob into the + * file, regardless of how much of it is really used. So it is important to * take into consideration this kind of things when defining your data types. - * Each has its uses, its advantages and disadvantages and it's up to you + * Each has its uses, its advantages and disadvantages and it is up to you * to decide which to use. * - * Now, going back to our example, we have to finish adding our data to the + * Now, going back to your example, you have to finish adding your data to the * descriptors. We are only missing the main one for the cache, which - * contains our hash of accounts. + * contains your hash of accounts. * Unless you are using your own hash functions when setting the descriptor * class, always use hashes with string type keys. * @skip #define * @until } * - * If you remember, we told Eet not to duplicate memory when possible at the - * time of loading back our data. But this doesn't mean everything will be - * loaded straight from disk and we don't have to worry about freeing it. + * If you remember, you told Eet not to duplicate memory when possible at the + * time of loading back your data. But this does not mean everything is + * loaded straight from disk and you do not have to worry about freeing it. * Data in the Eet file is compressed and encoded, so it still needs to be - * decoded and memory will be allocated to convert it back into something we - * can use. We also need to take care of anything we add in the current + * decoded and memory is allocated to convert it back into something that you + * can use. You also need to take care of anything you add in the current * instance of the program. - * To summarize, any string we get from Eet is likely to be a pointer to the - * internal dictionary, and trying to free it will, in the best case, crash - * our application right away. + * To summarize, any string you get from Eet is likely to be a pointer to the + * internal dictionary, and trying to free it, in the best case, crashes + * your application right away. * - * So how do we know if we have to free a string? We check if it's part of - * the dictionary, and if it's not there we can be sure it's safe to get + * So how do you know if you have to free a string? You check if it is part of + * the dictionary, and if it is not there, you can be sure it is safe to get * rid of it. * @skip static void * @skip } * @skip static void * @until } * - * See how this is used when adding a new message to our cache. + * See how this is used when adding a new message to your cache. * @skip static My_Message * @until return msg * @until free(msg) * @until } * - * Skipping all the utility functions used by our program (remember you can - * look at the full example @ref eet-data-file_descriptor_01.c "here") we get to - * our cache loading code. Nothing out of the ordinary at first, just the - * same old open file, read data using our main descriptor to decode it - * into something we can use and check version of loaded data and if it doesn't + * Skipping all the utility functions used by your program (remember you can + * look at the full example @ref eet-data-file_descriptor_01.c "here") you get to + * your cache loading code. Nothing out of the ordinary at first, just the + * same old open file, read data using your main descriptor to decode it + * into something you can use and check version of loaded data and if it does not * match, do something accordingly. * @skip static My_Cache * @until } * @until } * @until } * - * Then comes the interesting part. Remember how we kept two more global - * variables with our descriptors? One of them we already used to check if - * it was right to free a string or not, but we didn't know where it came from. - * Loading our data straight from the mmapped file means that we can't close - * it until we are done using it, so we need to keep its handler around until - * then. It also means that any changes done to the file can, and will, - * invalidate all our pointers to the file backed data, so if we add something - * and save the file, we need to reload our cache. - * - * Thus our load function checks if we had an open file, if there is it gets - * closed and our variable is updated to the new handler. Then we get the - * string dictionary we use to check if a string is part of it or not. - * Updating any references to the cache data is up you as a programmer to - * handle properly, there's nothing Eet can do in this situation. + * Then comes the interesting part. Remember how you kept two more global + * variables with your descriptors? One of them you already used to check if + * it is right to free a string or not, but you did not know where it came from. + * Loading your data straight from the mmapped file means that you cannot close + * it until you are done using it, so you need to keep its handler around until + * then. It also means that any changes done to the file can, and do, + * invalidate all your pointers to the file backed data, so if you add something + * and save the file, you need to reload your cache. + * + * Thus your load function checks if you had an open file, if there is, it gets + * closed and your variable is updated to the new handler. Then you get the + * string dictionary you use to check whether a string is part of it or not. + * Updating any references to the cache data is up to you as a programmer to + * handle properly; there is nothing Eet can do in this situation. * @until } * - * The save function doesn't have anything new, and all that's left after it - * is the main program, which doesn't really have anything of interest within - * the scope of what we are learning. + * The save function does not have anything new, and all that is left after it + * is the main program, which does not really have anything of interest within + * the scope of what you are learning. */ -/** - * @addtogroup Eet_Data_Group - * @{ - */ #define EET_T_UNKNOW 0 /**< Unknown data encoding type */ #define EET_T_CHAR 1 /**< Data type: char */ #define EET_T_SHORT 2 /**< Data type: short */ @@ -2560,8 +2526,7 @@ eet_identity_certificate_print(const unsigned char *certificate, #define EET_T_F32P32 14 /**< Data type: fixed point 32.32 */ #define EET_T_F16P16 15 /**< Data type: fixed point 16.16 */ #define EET_T_F8P24 16 /**< Data type: fixed point 8.24 */ -#define EET_T_VALUE 17 /**< Data type: pointer to Eina_Value @since 1.8 */ -#define EET_T_LAST 18 /**< Last data type */ +#define EET_T_LAST 17 /**< Last data type */ #define EET_G_UNKNOWN 100 /**< Unknown group data encoding type */ #define EET_G_ARRAY 101 /**< Fixed size array group type */ @@ -2570,20 +2535,19 @@ eet_identity_certificate_print(const unsigned char *certificate, #define EET_G_HASH 104 /**< Hash table group type */ #define EET_G_UNION 105 /**< Union group type */ #define EET_G_VARIANT 106 /**< Selectable subtype group */ -#define EET_G_UNKNOWN_NESTED 107 /**< Unknown nested group type. @since 1.8 */ -#define EET_G_LAST 108 /**< Last group type */ +#define EET_G_LAST 107 /**< Last group type */ #define EET_I_LIMIT 128 /**< Other type exist but are reserved for internal purpose. */ /** * @typedef Eet_Data_Descriptor * - * Opaque handle that have information on a type members. + * @brief The structure type containing an opaque handle that have information on a type members. * * Descriptors are created using an #Eet_Data_Descriptor_Class, and they - * describe the contents of the structure that will be serialized by Eet. - * Not all members need be described by it, just those that should be handled - * by Eet. This way it's possible to have one structure with both data to be + * describe the contents of the structure that is serialized by Eet. + * Not all members need to be described by it, just those that should be handled + * by Eet. This way it is possible to have one structure with both data to be * saved to a file, like application configuration, and runtime information * that would be meaningless to store, but is appropriate to keep together * during the program execution. @@ -2600,262 +2564,115 @@ typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor; /** * @def EET_DATA_DESCRIPTOR_CLASS_VERSION - * The version of #Eet_Data_Descriptor_Class at the time of the - * distribution of the sources. One should define this to its - * version member so it is compatible with abi changes, or at least - * will not crash with them. + * @brief Definition of the version of #Eet_Data_Descriptor_Class at the time of the + * distribution of the sources. One should define this to its + * version member so it is compatible with API changes, or at least + * do not crash with them. */ #define EET_DATA_DESCRIPTOR_CLASS_VERSION 4 /** * @typedef Eet_Data_Descriptor_Class * - * Instructs Eet about memory management for different needs under - * serialization and parse process. + * @brief The structure type that instructs Eet about memory management for different needs under + * serialization and parse process. */ typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class; -/** - * @typedef (*Eet_Descriptor_Hash_Foreach_Callback_Callback) - * - * Callback prototype for Eet_Descriptor_Hash_Foreach_Callback - * @param h the hash - * @param k the key - * @param dt the data - * @param fdt the data passed to the callback - * @return an integer - */ typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt); -/** - * @typedef (*Eet_Descriptor_Mem_Alloc_Callback) - * - * Callback prototype for Eet_Descriptor_Mem_Alloc - * @param size is the size of memory to alloc on call of the callback - */ typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size); - -/** - * @typedef (*Eet_Descriptor_Mem_Free_Callback) - * - * Callback prototype for Eet_Descriptor_Mem_Alloc - * @param mem must be a pointer to free on call of the callback - */ typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem); - -/** - * @typedef (*Eet_Descriptor_Str_Alloc_Callback) - * - * Callback prototype for Eet_Descriptor_Str_Alloc - * @param str must be the string to alloc - * @return have must be an allocated char * for the given string - */ typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str); - -/** - * @typedef (*Eet_Descriptor_Str_Free_Callback) - * - * Callback prototype for Eet_Descriptor_Str_Free - * @param str must be an allocated string to free - */ typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str); - -/** - * @typedef (*Eet_Descriptor_List_Next_Callback) - * - * Callback prototype for Eet_Descriptor_List_Next - * @param l must be a pointer to the list - * @return must be a pointer to the list - */ typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l); - -/** - * @typedef (*Eet_Descriptor_List_Append_Callback) - * - * Callback prototype for Eet_Descriptor_List_Append - * @param l must be a pointer to the list - * @param d the data to append to the list - * @return must be a pointer to the list - */ typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d); - - -/** - * @typedef (*Eet_Descriptor_List_Data_Callback) - * - * Callback prototype for Eet_Descriptor_List_Data - * @param l must be a pointer to the list - * @return must be a pointer to the list - */ typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l); - -/** - * @typedef (*Eet_Descriptor_List_Free_Callback) - * - * Callback prototype for Eet_Descriptor_List_Free - * @param l must be a pointer to the list to free - */ typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l); - -/** - * @typedef (*Eet_Descriptor_Hash_Foreach_Callback) - * - * Callback for Eet_Descriptor_Hash_Foreach - * @param h the hash - * @param func the function callback to call on each iteration - * @param fdt the data to pass to the callbac setted in param func - */ typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt); - -/** - * @typedef (*Eet_Descriptor_Hash_Add_Callback) - * - * Callback prototype for Eet_Descriptor_Hash_Add - * @param h the hash - * @param k the key - * @param d the data to associate with the 'k' key - */ typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d); - -/** - * @typedef (*Eet_Descriptor_Hash_Free_Callback) - * - * Callback prototype for Eet_Descriptor_Hash_Free - * @param h the hash to free - */ typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h); - -/** - * @typedef (*Eet_Descriptor_Str_Alloc_Callback) - * - * Callback prototype for Eet_Descriptor_Str_Alloc - * @param str the string to allocate - * @return an allocated pointer to the string - */ typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str); - -/** - * @typedef (*Eet_Descriptor_Str_Free_Callback) - * - * Callback prototype for Eet_Descriptor_Str_Free - * @param str the string to free - */ typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str); - - -/** - * @typedef (*Eet_Descriptor_Type_Get_Callback) - * - * Callback prototype for Eet_Descriptor_Type_Get - * @param data data to pass to the callback - * @param unknow Eina_Bool __FIXME__ - */ typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow); - -/** - * @typedef (*Eet_Descriptor_Type_Set_Callback) - * - * Callback prototype for Eet_Descriptor_Type_Set - * @param type the type to set - * @param data to pass to the callback - * @param unknow Eina_Bool __FIXME__ - */ typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow); - - -/** - * @typedef (*Eet_Descriptor_Array_Alloc_Callback) - * - * Callback prototype for Eet_Descriptor_Array_Alloc - * @param size The size of the array - */ typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size); - -/** - * @typedef (*Eet_Descriptor_Array_Free_Callback) - * - * Callback prototype for Eet_Descriptor_Array_Free - * @param size The size of the array - */ typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem); + /** + * @internal * @struct _Eet_Data_Descriptor_Class * - * Instructs Eet about memory management for different needs under - * serialization and parse process. + * @brief The structure type that instructs Eet about memory management for different needs under + * serialization and parse process. * * The list and hash methods match the Eina API, so for a more detailed * reference on them, look at the Eina_List and Eina_Hash documentation, * respectively. - * For the most part these will be used with the standard Eina functions, + * For the most part these are used with the standard Eina functions, * so using EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() and - * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() will set up everything + * EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET() set up everything * accordingly. */ struct _Eet_Data_Descriptor_Class { - int version; /**< ABI version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */ + int version; /**< API version. Should always be set to #EET_DATA_DESCRIPTOR_CLASS_VERSION */ const char *name; /**< Name of the user data type to be serialized */ int size; /**< Size in bytes of the user data type to be serialized */ struct { - Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< how to allocate memory (usually malloc()) */ - Eet_Descriptor_Mem_Free_Callback mem_free; /**< how to free memory (usually free()) */ - Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< how to allocate a string */ - Eet_Descriptor_Str_Free_Callback str_free; /**< how to free a string */ - Eet_Descriptor_List_Next_Callback list_next; /**< how to iterate to the next element of a list. Receives and should return the list node. */ - Eet_Descriptor_List_Append_Callback list_append; /**< how to append data @p d to list which head node is @p l */ - Eet_Descriptor_List_Data_Callback list_data; /**< retrieves the data from node @p l */ - Eet_Descriptor_List_Free_Callback list_free; /**< free all the nodes from the list which head node is @p l */ - Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< iterates over all elements in the hash @p h in no specific order */ - Eet_Descriptor_Hash_Add_Callback hash_add; /**< add a new data @p d with key @p k in hash @p h */ - Eet_Descriptor_Hash_Free_Callback hash_free; /**< free all entries from the hash @p h */ - Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< how to allocate a string directly from file backed/mmaped region pointed by @p str */ - Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< how to free a string returned by str_direct_alloc */ - Eet_Descriptor_Type_Get_Callback type_get; /**< get the type, as used in the union or variant mapping, that should be used to store the given data into the eet file. */ - Eet_Descriptor_Type_Set_Callback type_set; /**< called when loading a mapped type with the given @p type used to describe the type in the descriptor */ - Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< how to allocate memory for array (usually malloc()) */ - Eet_Descriptor_Array_Free_Callback array_free; /**< how to free memory for array (usually free()) */ + Eet_Descriptor_Mem_Alloc_Callback mem_alloc; /**< Called when allocating memory (usually malloc()) */ + Eet_Descriptor_Mem_Free_Callback mem_free; /**< Called when freeing memory (usually free()) */ + Eet_Descriptor_Str_Alloc_Callback str_alloc; /**< Called when allocating a string */ + Eet_Descriptor_Str_Free_Callback str_free; /**< Called when freeing a string */ + Eet_Descriptor_List_Next_Callback list_next; /**< Called when iterating to the next element of a list. Receives and should return the list node. */ + Eet_Descriptor_List_Append_Callback list_append; /**< Called when appending data @a d to list with head node @a l */ + Eet_Descriptor_List_Data_Callback list_data; /**< Called when retrieving the data from node @a l */ + Eet_Descriptor_List_Free_Callback list_free; /**< Called when freeing all the nodes from the list with head node @a l */ + Eet_Descriptor_Hash_Foreach_Callback hash_foreach; /**< Called when iterating over all elements in the hash @a h in no specific order */ + Eet_Descriptor_Hash_Add_Callback hash_add; /**< Called when adding a new data @a d with key @a k in hash @a h */ + Eet_Descriptor_Hash_Free_Callback hash_free; /**< Called when freeing all entries from the hash @a h */ + Eet_Descriptor_Str_Direct_Alloc_Callback str_direct_alloc; /**< Called when allocating a string directly from file backed or mmaped region pointed by @a str */ + Eet_Descriptor_Str_Direct_Free_Callback str_direct_free; /**< Called when freeing a string returned by str_direct_alloc */ + Eet_Descriptor_Type_Get_Callback type_get; /**< Called when getting the type, as used in the union or variant mapping, that should be used to store the given data into the eet file */ + Eet_Descriptor_Type_Set_Callback type_set; /**< Called when loading a mapped type with the given @a type used to describe the type in the descriptor */ + Eet_Descriptor_Array_Alloc_Callback array_alloc; /**< Called when allocating memory for array (usually malloc()) */ + Eet_Descriptor_Array_Free_Callback array_free; /**< Called when freeing memory for array (usually free()) */ } func; }; /** - * @} - */ - -/** - * Create a new empty data structure descriptor. - * @param name The string name of this data structure (most be a - * global constant and never change). - * @param size The size of the struct (in bytes). - * @param func_list_next The function to get the next list node. - * @param func_list_append The function to append a member to a list. - * @param func_list_data The function to get the data from a list node. - * @param func_list_free The function to free an entire linked list. - * @param func_hash_foreach The function to iterate through all - * hash table entries. - * @param func_hash_add The function to add a member to a hash table. - * @param func_hash_free The function to free an entire hash table. - * @return A new empty data descriptor. - * - * This function creates a new data descriptor and returns a handle to the - * new data descriptor. On creation it will be empty, containing no contents - * describing anything other than the shell of the data structure. - * - * You add structure members to the data descriptor using the macros - * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and - * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are - * adding to the description. - * - * Once you have described all the members of a struct you want loaded, or - * saved eet can load and save those members for you, encode them into - * endian-independent serialised data chunks for transmission across a - * a network or more. - * - * The function pointers to the list and hash table functions are only - * needed if you use those data types, else you can pass NULL instead. + * @brief Creates a new empty data structure descriptor. + * + * @details This function creates a new data descriptor and returns a handle to the + * new data descriptor. On creation it is empty, containing no contents + * describing anything other than the shell of the data structure. + * @since 1.0.0 + * @remarks You add structure members to the data descriptor using the macros + * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and + * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are + * adding to the description. + * + * @remarks Once you have described all the members of a struct you want loaded, or + * saved eet can load and save those members for you, encode them into + * endian-independent serialised data chunks for transmission across a + * a network or more. + * + * @remarks The function pointers to the list and hash table functions are only + * needed if you use those data types, else you can pass @c NULL instead. + * + * @param name The string name of this data structure \n + * A global constant and never changes. + * @param size The size of the struct (in bytes) + * @param func_list_next The function to get the next list node + * @param func_list_append The function to append a member to a list + * @param func_list_data The function to get the data from a list node + * @param func_list_free The function to free an entire linked list + * @param func_hash_foreach The function to iterate through all hash table entries + * @param func_hash_add The function to add a member to a hash table + * @param func_hash_free The function to free an entire hash table + * @return A new empty data descriptor * - * @since 1.0.0 * @ingroup Eet_Data_Group * * @deprecated use eet_data_descriptor_stream_new() or @@ -2874,7 +2691,7 @@ eet_data_descriptor_new(const char *name, /* * FIXME: * - * moving to this api from the old above. this will break things when the + * Moving to this API from the old above. this breaks things when the * move happens - but be warned */ EINA_DEPRECATED EAPI Eet_Data_Descriptor * @@ -2883,61 +2700,64 @@ EINA_DEPRECATED EAPI Eet_Data_Descriptor * eet_data_descriptor3_new(const Eet_Data_Descriptor_Class *eddc); /** - * This function creates a new data descriptor and returns a handle to the - * new data descriptor. On creation it will be empty, containing no contents - * describing anything other than the shell of the data structure. - * @param eddc The class from where to create the data descriptor. - * @return A handle to the new data descriptor. + * @brief Creates a new data descriptor and returns a handle to the + * new data descriptor. * - * You add structure members to the data descriptor using the macros - * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and - * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are - * adding to the description. + * @since 1.2.3 * - * Once you have described all the members of a struct you want loaded or - * saved, eet can load and save those members for you, encode them into - * endian-independent serialised data chunks for transmission across a - * network or more. + * @remarks On creation it is empty, containing no contents + * describing anything other than the shell of the data structure. * - * This function specially ignores str_direct_alloc and str_direct_free. It - * is useful when the eet_data you are reading doesn't have a dictionary, - * like network stream or IPC. It also mean that all string will be allocated - * and duplicated in memory. + * @remarks You add structure members to the data descriptor using the macros + * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and + * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are + * adding to the description. * - * @since 1.2.3 - * @ingroup Eet_Data_Group + * @remarks Once you have described all the members of a struct you want loaded or + * saved, eet can load and save those members for you, encode them into + * endian-independent serialised data chunks for transmission across a + * network or more. + * + * @remarks This function specially ignores str_direct_alloc and str_direct_free. It + * is useful when the eet_data you are reading does not have a dictionary, + * like network stream or IPC. It also means that all strings are allocated + * and duplicated in memory. + * + * @param[in] eddc The class from where to create the data descriptor + * @return A handle to the new data descriptor */ EAPI Eet_Data_Descriptor * eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc); /** - * This function creates a new data descriptor and returns a handle to the - * new data descriptor. On creation it will be empty, containing no contents - * describing anything other than the shell of the data structure. - * @param eddc The class from where to create the data descriptor. - * @return A handle to the new data descriptor. - * - * You add structure members to the data descriptor using the macros - * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and - * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are - * adding to the description. - * - * Once you have described all the members of a struct you want loaded or - * saved, eet can load and save those members for you, encode them into - * endian-independent serialised data chunks for transmission across a - * a network or more. - * - * This function uses str_direct_alloc and str_direct_free. It is - * useful when the eet_data you are reading come from a file and - * have a dictionary. This will reduce memory use and improve the - * possibility for the OS to page this string out. - * However, the load speed and memory saving comes with some drawbacks to keep - * in mind. If you never modify the contents of the structures loaded from - * the file, all you need to remember is that closing the eet file will make - * the strings go away. On the other hand, should you need to free a string, - * before doing so you have to verify that it's not part of the eet dictionary. - * You can do this in the following way, assuming @p ef is a valid Eet_File - * and @p str is a string loaded from said file. + * @brief Creates a new data descriptor and returns a handle to the + * new data descriptor. + * @since 1.2.3 + * + * @remarks On creation it is empty, containing no contents + * describing anything other than the shell of the data structure. + * + * @remarks You add structure members to the data descriptor using the macros + * EET_DATA_DESCRIPTOR_ADD_BASIC(), EET_DATA_DESCRIPTOR_ADD_SUB() and + * EET_DATA_DESCRIPTOR_ADD_LIST(), depending on what type of member you are + * adding to the description. + * + * @remarks Once you have described all the members of a struct you want loaded or + * saved, eet can load and save those members for you, encode them into + * endian-independent serialised data chunks for transmission across a + * a network or more. + * + * @remarks This function uses str_direct_alloc and str_direct_free. It is + * useful when the eet_data you are reading come from a file and + * have a dictionary. This reduces memory use and improve the + * possibility for the OS to page this string out. + * However, the load speed and memory saving comes with some drawbacks to keep + * in mind. If you never modify the contents of the structures loaded from + * the file, all you need to remember is that closing the eet file makes + * the strings go away. On the other hand, should you need to free a string, + * before doing so you have to verify that it is not part of the eet dictionary. + * You can do this in the following way, assuming @a ef is a valid Eet_File + * and @a str is a string loaded from said file. * * @code * void eet_string_free(Eet_File *ef, const char *str) @@ -2949,34 +2769,34 @@ eet_data_descriptor_stream_new(const Eet_Data_Descriptor_Class *eddc); * // of it, so we can't free it, just return. * return; * } - * // We assume eina_stringshare was used on the descriptor + * // We assume eina_stringshare is used on the descriptor * eina_stringshare_del(str); * } * @endcode * - * @since 1.2.3 - * @ingroup Eet_Data_Group + * @param[in] eddc The class from where to create the data descriptor + * @return A handle to the new data descriptor */ EAPI Eet_Data_Descriptor * eet_data_descriptor_file_new(const Eet_Data_Descriptor_Class *eddc); /** - * This function is an helper that set all the parameters of an - * Eet_Data_Descriptor_Class correctly when you use Eina data type - * with a stream. - * @param eddc The Eet_Data_Descriptor_Class you want to set. - * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time. - * @param name The name of the structure described by this class. - * @param size The size of the structure described by this class. - * @return EINA_TRUE if the structure was correctly set (The only - * reason that could make it fail is if you did give wrong - * parameter). + * @brief Sets all the parameters of an Eet_Data_Descriptor_Class correctly + * when you use Eina data type with a stream. * - * @note Unless there's a very specific reason to use this function directly, - * the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET macro is recommended. + * @details This function is a helper. + * @since 1.2.3 * - * @since 1.2.3 - * @ingroup Eet_Data_Group + * @remarks Unless there is a very specific reason to use this function directly, + * use the EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET() macro. + * + * @param[in] eddc The Eet_Data_Descriptor_Class you want to set + * @param[in] eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time + * @param[in] name The name of the structure described by this class + * @param[in] size The size of the structure described by this class + * @return @c EINA_TRUE if the structure is correctly set, \n + * otherwise @c EINA_FALSE on failure \n + * The only reason that could make it fail is if you did give wrong parameter. */ EAPI Eina_Bool eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, @@ -2985,39 +2805,39 @@ eet_eina_stream_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, int size); /** - * This macro is an helper that set all the parameter of an - * Eet_Data_Descriptor_Class correctly when you use Eina data type - * with stream. - * @param clas The Eet_Data_Descriptor_Class you want to set. - * @param type The type of the structure described by this class. - * @return EINA_TRUE if the structure was correctly set (The only - * reason that could make it fail is if you did give wrong - * parameter). + * @brief Sets all the parameter of an Eet_Data_Descriptor_Class correctly + * when you use Eina data type with stream. + * + * @details This is a macro. + * @since 1.2.3 + * + * @param clas The Eet_Data_Descriptor_Class you want to set + * @param type The type of the structure described by this class + * @return @c EINA_TRUE if the structure is correctly set, \n + * otherwise @c EINA_FALSE on failure \n + * The only reason that could make it fail is if you did give wrong parameter. * * @see eet_data_descriptor_stream_new - * @since 1.2.3 - * @ingroup Eet_Data_Group */ #define EET_EINA_STREAM_DATA_DESCRIPTOR_CLASS_SET(clas, type) \ (eet_eina_stream_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type))) /** - * This function is an helper that set all the parameter of an - * Eet_Data_Descriptor_Class correctly when you use Eina data type - * with a file. - * @param eddc The Eet_Data_Descriptor_Class you want to set. - * @param eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time. - * @param name The name of the structure described by this class. - * @param size The size of the structure described by this class. - * @return EINA_TRUE if the structure was correctly set (The only - * reason that could make it fail is if you did give wrong - * parameter). + * @brief Sets all the parameter of an Eet_Data_Descriptor_Class correctly + * when you use Eina data type with a file. + * @details This is a helper function. + * @since 1.2.3 * - * @note Unless there's a very specific reason to use this function directly, - * the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro is recommended. + * @remarks Unless there is a very specific reason to use this function directly, + * use the EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET macro. * - * @since 1.2.3 - * @ingroup Eet_Data_Group + * @param[in] eddc The Eet_Data_Descriptor_Class you want to set + * @param[in] eddc_size The size of the Eet_Data_Descriptor_Class at the compilation time + * @param[in] name The name of the structure described by this class + * @param[in] size The size of the structure described by this class + * @return @c EINA_TRUE if the structure is correctly set, \n + * otherwise @c EINA_FALSE on failure \n + * The only reason that could make it fail is if you did give wrong parameter. */ EAPI Eina_Bool eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, @@ -3026,69 +2846,60 @@ eet_eina_file_data_descriptor_class_set(Eet_Data_Descriptor_Class *eddc, int size); /** - * This macro is an helper that set all the parameter of an - * Eet_Data_Descriptor_Class correctly when you use Eina data type - * with file. - * @param clas The Eet_Data_Descriptor_Class you want to set. - * @param type The type of the structure described by this class. - * @return EINA_TRUE if the structure was correctly set (The only - * reason that could make it fail is if you did give wrong - * parameter). + * @brief Sets all the parameter of an Eet_Data_Descriptor_Class correctly + * when you use Eina data type with file. + * + * @details This macro is a helper. + * @since 1.2.3 + * + * @param clas The Eet_Data_Descriptor_Class you want to set + * @param type The type of the structure described by this class + * @return @c EINA_TRUE if the structure is correctly set, \n + * otherwise @c EINA_FALSE on failure \n + * The only reason that could make it fail is if you did give wrong parameter. * * @see eet_data_descriptor_file_new - * @since 1.2.3 - * @ingroup Eet_Data_Group */ #define EET_EINA_FILE_DATA_DESCRIPTOR_CLASS_SET(clas, type) \ (eet_eina_file_data_descriptor_class_set(clas, sizeof (*(clas)), # type, sizeof(type))) /** - * This function frees a data descriptor when it is not needed anymore. - * @param edd The data descriptor to free. + * @brief Frees a data descriptor when it is not needed anymore. * - * This function takes a data descriptor handle as a parameter and frees all - * data allocated for the data descriptor and the handle itself. After this - * call the descriptor is no longer valid. + * @details This function takes a data descriptor handle as a parameter and frees all + * data allocated for the data descriptor and the handle itself. After this + * call the descriptor is no longer valid. + * @since 1.0.0 * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param[in] edd The data descriptor to free */ EAPI void eet_data_descriptor_free(Eet_Data_Descriptor *edd); /** - * This function returns the name of a data descriptor. - * - * @since 1.8.0 - * @ingroup Eet_Data_Group - */ -EAPI const char *eet_data_descriptor_name_get(const Eet_Data_Descriptor *edd); - -/** - * This function is an internal used by macros. + * @brief This function is an internal used by macros. * - * This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(), - * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). It is - * complex to use by hand and should be left to be used by the macros, and - * thus is not documented. + * @details This function is used by macros EET_DATA_DESCRIPTOR_ADD_BASIC(), + * EET_DATA_DESCRIPTOR_ADD_SUB() and EET_DATA_DESCRIPTOR_ADD_LIST(). + * @since 1.0.0 * - * @param edd The data descriptor handle to add element (member). - * @param name The name of element to be serialized. - * @param type The type of element to be serialized, like - * #EET_T_INT. If #EET_T_UNKNOW, then it is considered to be a - * group, list or hash. - * @param group_type If element type is #EET_T_UNKNOW, then the @p - * group_type will specify if it is a list (#EET_G_LIST), - * array (#EET_G_ARRAY) and so on. If #EET_G_UNKNOWN, then - * the member is a subtype (pointer to another type defined by - * another #Eet_Data_Descriptor). - * @param offset byte offset inside the source memory to be serialized. - * @param count number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY). - * @param counter_name variable that defines the name of number of elements. - * @param subtype If contains a subtype, then its data descriptor. + * @remarks It is complex to use by hand and should be left to be used by the macros, and + * thus is not documented. * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param[in] edd The data descriptor handle to add element (member) + * @param[in] name The name of element to be serialized + * @param[in] type The type of element to be serialized, like #EET_T_INT \n + * If #EET_T_UNKNOW, then it is considered to be a + * group, list or hash. + * @param[in] group_type If element type is #EET_T_UNKNOW, then the @a + * group_type specifies if it is a list (#EET_G_LIST), + * array (#EET_G_ARRAY) and so on \n + * If #EET_G_UNKNOWN, then the member is a subtype (pointer + * to another type defined by another #Eet_Data_Descriptor). + * @param[in] offset The byte offset inside the source memory to be serialized + * @param[in] count The number of elements (if #EET_G_ARRAY or #EET_G_VAR_ARRAY) + * @param[in] counter_name The number of elements + * @param[in] subtype The data descriptor, if this contains a subtype */ EAPI void eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, @@ -3102,31 +2913,30 @@ eet_data_descriptor_element_add(Eet_Data_Descriptor *edd, Eet_Data_Descriptor *subtype); /** - * Read a data structure from an eet file and decodes it. - * @param ef The eet file handle to read from. - * @param edd The data descriptor handle to use when decoding. - * @param name The key the data is stored under in the eet file. - * @return A pointer to the decoded data structure. + * @brief Reads a data structure from an eet file and decodes it. + * @since 1.0.0 * - * This function decodes a data structure stored in an eet file, returning - * a pointer to it if it decoded successfully, or NULL on failure. This - * can save a programmer dozens of hours of work in writing configuration - * file parsing and writing code, as eet does all that work for the program - * and presents a program-friendly data structure, just as the programmer - * likes. Eet can handle members being added or deleted from the data in - * storage and safely zero-fills unfilled members if they were not found - * in the data. It checks sizes and headers whenever it reads data, allowing - * the programmer to not worry about corrupt data. + * @remarks This function decodes a data structure stored in an eet file, returning + * a pointer to it if it decoded successfully, or @c NULL on failure. This + * can save a programmer dozens of hours of work in writing configuration + * file parsing and writing code, as eet does all that work for the program + * and presents a program-friendly data structure, just as the programmer + * likes. Eet can handle members being added or deleted from the data in + * storage and safely zero-fills unfilled members if they were not found + * in the data. It checks sizes and headers whenever it reads data, allowing + * the programmer to not worry about corrupt data. * - * Once a data structure has been described by the programmer with the - * fields they wish to save or load, storing or retrieving a data structure - * from an eet file, or from a chunk of memory is as simple as a single - * function call. + * @remarks Once a data structure has been described by the programmer with the + * fields they wish to save or load, storing or retrieving a data structure + * from an eet file, or from a chunk of memory is as simple as a single + * function call. * - * @see eet_data_read_cipher() + * @param[in] ef The eet file handle to read from + * @param[in] edd The data descriptor handle to use when decoding + * @param[in] name The key the data is stored under in the eet file + * @return A pointer to the decoded data structure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_read_cipher() */ EAPI void * eet_data_read(Eet_File *ef, @@ -3134,23 +2944,24 @@ eet_data_read(Eet_File *ef, const char *name); /** - * Write a data structure from memory and store in an eet file. - * @param ef The eet file handle to write to. - * @param edd The data descriptor to use when encoding. - * @param name The key to store the data under in the eet file. - * @param data A pointer to the data structure to save and encode. - * @param compress Compression flags for storage. - * @return bytes written on successful write, 0 on failure. + * @brief Writes a data structure from memory and store in an eet file. * - * This function is the reverse of eet_data_read(), saving a data structure - * to an eet file. The file must have been opening in write mode and the data - * will be kept in memory until the file is either closed or eet_sync() is - * called to flush any unwritten changes. + * @since 1.0.0 * - * @see eet_data_write_cipher() + * @remarks This function is the reverse of eet_data_read(), saving a data structure + * to an eet file. The file must have been opening in write mode and the data + * is kept in memory until the file is either closed or eet_sync() is + * called to flush any unwritten changes. * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param[in] ef The eet file handle to write to + * @param[in] edd The data descriptor to use when encoding + * @param[in] name The key to store the data under in the eet file + * @param[in] data A pointer to the data structure to save and encode + * @param[in] compress The compression flags for storage + * @return The bytes written on successful write, \n + * otherwise @c 0 on failure + * + * @see eet_data_write_cipher() */ EAPI int eet_data_write(Eet_File *ef, @@ -3159,35 +2970,20 @@ eet_data_write(Eet_File *ef, const void *data, int compress); -/** - * @typedef Eet_Data_Descriptor_Class - * - * Callback protoype for Eet_Dump - * - * @param data to passe to the callback - * @param str the string to dump - * - */ typedef void (*Eet_Dump_Callback)(void *data, const char *str); /** - * Dump an eet encoded data structure into ascii text - * @param data_in The pointer to the data to decode into a struct. - * @param size_in The size of the data pointed to in bytes. - * @param dumpfunc The function to call passed a string when new - * data is converted to text - * @param dumpdata The data to pass to the @p dumpfunc callback. - * @return 1 on success, 0 on failure + * @brief Dumps an eet encoded data structure into ascii text. + * @details This function takes a chunk of data encoded by + * eet_data_descriptor_encode() and convert it into human readable + * ascii text. It does this by calling the @a dumpfunc callback + * for all new text that is generated. This callback should append + * to any existing text buffer and is passed the pointer @a + * dumpdata as a parameter as well as a string with new text to be + * appended. + * @since 1.0.0 * - * This function will take a chunk of data encoded by - * eet_data_descriptor_encode() and convert it into human readable - * ascii text. It does this by calling the @p dumpfunc callback - * for all new text that is generated. This callback should append - * to any existing text buffer and will be passed the pointer @p - * dumpdata as a parameter as well as a string with new text to be - * appended. - * - * Example: + * @remarks The following is an example: * * @code * void output(void *data, const char *string) @@ -3212,10 +3008,15 @@ typedef void (*Eet_Dump_Callback)(void *data, const char *str); * } * @endcode * - * @see eet_data_text_dump_cipher() + * @param[in] data_in The pointer to the data to decode into a struct + * @param[in] size_in The size of the data pointed to in bytes + * @param[in] dumpfunc The function to call passed a string when new + * data is converted to text + * @param[in] dumpdata The data to pass to the @a dumpfunc callback + * @return @c 1 if the data structure is dumped into ascii successfully, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_text_dump_cipher() */ EAPI int eet_data_text_dump(const void *data_in, @@ -3224,23 +3025,23 @@ eet_data_text_dump(const void *data_in, void *dumpdata); /** - * Take an ascii encoding from eet_data_text_dump() and re-encode in binary. - * @param text The pointer to the string data to parse and encode. - * @param textlen The size of the string in bytes (not including 0 - * byte terminator). - * @param size_ret This gets filled in with the encoded data blob - * size in bytes. - * @return The encoded data on success, NULL on failure. + * @brief Takes an ascii encoding from eet_data_text_dump() and re-encodes in binary. * - * This function will parse the string pointed to by @p text and return - * an encoded data lump the same way eet_data_descriptor_encode() takes an - * in-memory data struct and encodes into a binary blob. @p text is a normal - * C string. + * @details This function parses the string pointed to by @a text and return + * an encoded data lump the same way eet_data_descriptor_encode() takes an + * in-memory data struct and encodes into a binary blob. @a text is a normal + * C string. + * @since 1.0.0 * - * @see eet_data_text_undump_cipher() + * @param[in] text The pointer to the string data to parse and encode + * @param[in] textlen The size of the string in bytes (not including @c 0 + * byte terminator) + * @param[out] size_ret This gets filled in with the encoded data blob + * size in bytes + * @return The encoded data on success, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_text_undump_cipher() */ EAPI void * eet_data_text_undump(const char *text, @@ -3248,27 +3049,28 @@ eet_data_text_undump(const char *text, int *size_ret); /** - * Dump an eet encoded data structure from an eet file into ascii text - * @param ef A valid eet file handle. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param dumpfunc The function to call passed a string when new - * data is converted to text - * @param dumpdata The data to pass to the @p dumpfunc callback. - * @return 1 on success, 0 on failure + * @brief Dumps an eet encoded data structure from an eet file into ascii text. * - * This function will take an open and valid eet file from - * eet_open() request the data encoded by - * eet_data_descriptor_encode() corresponding to the key @p name - * and convert it into human readable ascii text. It does this by - * calling the @p dumpfunc callback for all new text that is - * generated. This callback should append to any existing text - * buffer and will be passed the pointer @p dumpdata as a parameter - * as well as a string with new text to be appended. + * @details This function takes an open and valid eet file from + * eet_open() request the data encoded by + * eet_data_descriptor_encode() corresponding to the key @a name + * and convert it into human readable ascii text. It does this by + * calling the @a dumpfunc callback for all new text that is + * generated. This callback should append to any existing text + * buffer and is passed the pointer @a dumpdata as a parameter + * as well as a string with new text to be appended. + * @since 1.0.0 * - * @see eet_data_dump_cipher() + * @param[in] ef A valid eet file handle + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] dumpfunc The function to call passed a string when new + * data is converted to text + * @param[in] dumpdata The data to pass to the @a dumpfunc callback + * @return @c 1 if the data structure is dumped into ascii text successfully, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_dump_cipher() */ EAPI int eet_data_dump(Eet_File *ef, @@ -3277,26 +3079,27 @@ eet_data_dump(Eet_File *ef, void *dumpdata); /** - * Take an ascii encoding from eet_data_dump() and re-encode in binary. - * @param ef A valid eet file handle. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param text The pointer to the string data to parse and encode. - * @param textlen The size of the string in bytes (not including 0 - * byte terminator). - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @return 1 on success, 0 on failure + * @brief Takes an ascii encoding from eet_data_dump() and re-encodes in binary. * - * This function will parse the string pointed to by @p text, - * encode it the same way eet_data_descriptor_encode() takes an - * in-memory data struct and encodes into a binary blob. + * @details This function parses the string pointed to by @a text, + * encode it the same way eet_data_descriptor_encode() takes an + * in-memory data struct and encodes into a binary blob. + * @since 1.0.0 * - * The data (optionally compressed) will be in ram, pending a flush to - * disk (it will stay in ram till the eet file handle is closed though). + * @remarks The data (optionally compressed) is in RAM, pending a flush to + * disk (it stays in RAM till the eet file handle is closed though). * - * @see eet_data_undump_cipher() + * @param[in] ef A valid eet file handle + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] text The pointer to the string data to parse and encode + * @param[in] textlen The size of the string in bytes (not including @c 0 + * byte terminator) + * @param[in] compress The compression flags (1 = compress, 0 = do not compress) + * @return @c 1 if the ascii encoding is re-encoded successfully, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_undump_cipher() */ EAPI int eet_data_undump(Eet_File *ef, @@ -3306,31 +3109,31 @@ eet_data_undump(Eet_File *ef, int compress); /** - * Decode a data structure from an arbitrary location in memory. - * @param edd The data descriptor to use when decoding. - * @param data_in The pointer to the data to decode into a struct. - * @param size_in The size of the data pointed to in bytes. - * @return NULL on failure, or a valid decoded struct pointer on success. + * @brief Decodes a data structure from an arbitrary location in memory. * - * This function will decode a data structure that has been encoded using - * eet_data_descriptor_encode(), and return a data structure with all its - * elements filled out, if successful, or NULL on failure. + * @details This function decodes a data structure that has been encoded using + * eet_data_descriptor_encode(), and return a data structure with all its + * elements filled out, if successful, or @c NULL on failure. + * @since 1.0.0 * - * The data to be decoded is stored at the memory pointed to by @p data_in, - * and is described by the descriptor pointed to by @p edd. The data size is - * passed in as the value to @p size_in, ande must be greater than 0 to - * succeed. + * @remarks The data to be decoded is stored at the memory pointed to by @a data_in, + * and is described by the descriptor pointed to by @a edd. The data size is + * passed in as the value to @a size_in, and must be greater than @c 0 to + * succeed. * - * This function is useful for decoding data structures delivered to the - * application by means other than an eet file, such as an IPC or socket - * connection, raw files, shared memory etc. + * @remarks This function is useful for decoding data structures delivered to the + * application by means other than an eet file, such as an IPC or socket + * connection, raw files, and shared memory. * - * Please see eet_data_read() for more information. + * @remarks See eet_data_read() for more information. * - * @see eet_data_descriptor_decode_cipher() + * @param[in] edd The data descriptor to use when decoding + * @param[in] data_in The pointer to the data to decode into a struct + * @param[in] size_in The size of the data pointed to in bytes + * @return A valid decoded struct pointer on success, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_descriptor_decode_cipher() */ EAPI void * eet_data_descriptor_decode(Eet_Data_Descriptor *edd, @@ -3338,33 +3141,33 @@ eet_data_descriptor_decode(Eet_Data_Descriptor *edd, int size_in); /** - * Encode a dsata struct to memory and return that encoded data. - * @param edd The data descriptor to use when encoding. - * @param data_in The pointer to the struct to encode into data. - * @param size_ret pointer to the an int to be filled with the decoded size. - * @return NULL on failure, or a valid encoded data chunk on success. + * @brief Encodes a data struct to memory and returns that encoded data. * - * This function takes a data structutre in memory and encodes it into a - * serialised chunk of data that can be decoded again by - * eet_data_descriptor_decode(). This is useful for being able to transmit - * data structures across sockets, pipes, IPC or shared file mechanisms, - * without having to worry about memory space, machine type, endianness etc. + * @details This function takes a data structutre in memory and encodes it into a + * serialised chunk of data that can be decoded again by + * eet_data_descriptor_decode(). This is useful for being able to transmit + * data structures across sockets, pipes, IPC or shared file mechanisms, + * without having to worry about memory space, machine type, endianness, and so on. + * @since 1.0.0 * - * The parameter @p edd must point to a valid data descriptor, and - * @p data_in must point to the right data structure to encode. If not, the - * encoding may fail. + * @remarks The parameter @a edd must point to a valid data descriptor, and + * @a data_in must point to the right data structure to encode. If not, the + * encoding may fail. * - * On success a non NULL valid pointer is returned and what @p size_ret - * points to is set to the size of this decoded data, in bytes. When the - * encoded data is no longer needed, call free() on it. On failure NULL is - * returned and what @p size_ret points to is set to 0. + * @remarks On success, a non-NULL valid pointer is returned and what @a size_ret + * points to is set to the size of this decoded data, in bytes. When the + * encoded data is no longer needed, call free() on it. On failure @c NULL is + * returned and what @a size_ret points to is set to @c 0. * - * Please see eet_data_write() for more information. + * @remarks See eet_data_write() for more information. * - * @see eet_data_descriptor_encode_cipher() + * @param[in] edd The data descriptor to use when encoding + * @param[in] data_in The pointer to the struct to encode into data + * @param[out] size_ret The pointer to the an int to be filled with the decoded size + * @return A valid encoded data chunk on success, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @see eet_data_descriptor_encode_cipher() */ EAPI void * eet_data_descriptor_encode(Eet_Data_Descriptor *edd, @@ -3372,27 +3175,26 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, int *size_ret); /** - * Add a basic data element to a data descriptor. - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param type The type of the member to encode. - * - * This macro is a convenience macro provided to add a member to - * the data descriptor @p edd. The type of the structure is - * provided as the @p struct_type parameter (for example: struct - * my_struct). The @p name parameter defines a string that will be - * used to uniquely name that member of the struct (it is suggested - * to use the struct member itself). The @p member parameter is - * the actual struct member itself (for example: values), and @p type is the - * basic data type of the member which must be one of: EET_T_CHAR, EET_T_SHORT, - * EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, - * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING. - * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @brief Adds a basic data element to a data descriptor. + * + * @details This macro is a convenience macro provided to add a member to + * the data descriptor @a edd. The type of the structure is + * provided as the @a struct_type parameter (for example: struct + * my_struct). The @a name parameter defines a string that is + * used to uniquely name that member of the struct (it is suggested + * to use the struct member itself). The @a member parameter is + * the actual struct member itself (for example: values), and @a type is the + * basic data type of the member. The valid values for @a type are: EET_T_CHAR, EET_T_SHORT, + * EET_T_INT, EET_T_LONG_LONG, EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, + * EET_T_USHORT, EET_T_UINT, EET_T_ULONG_LONG or EET_T_STRING. + * @since 1.0.0 + * + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never change. + * @param member The struct member itself to be encoded + * @param type The type of the member to encode */ #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \ do { \ @@ -3404,22 +3206,21 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while(0) /** - * Add a sub-element type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of sub-type struct to add. + * @brief Adds a sub-element type to a data descriptor. * - * This macro lets you easily add a sub-type (a struct that's pointed to - * by this one). All the parameters are the same as for - * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception. - * This must be the data descriptor of the struct that is pointed to by - * this element. + * @details This macro lets you easily add a sub-type (a struct that is pointed to + * by this one). All the parameters are the same as for + * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @a subtype being the exception. + * This must be the data descriptor of the struct that is pointed to by + * this element. + * @since 1.0.0 * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param subtype The type of sub-type struct to add */ #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \ do { \ @@ -3431,47 +3232,20 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a nested sub-element type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of sub-type struct to add. + * @brief Adds a linked list type to a data descriptor. * - * This macro lets you easily add a sub-type: a struct that is nested into - * this one. If your data is pointed by this element instead of being nested, - * you should use EET_DATA_DESCRIPTOR_ADD_SUB(). - * All the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_SUB(). + * @details This macro lets you easily add a linked list of other data types. All the + * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the + * @a subtype being the exception. This must be the data descriptor of the + * element that is in each member of the linked list to be stored. + * @since 1.0.0 * - * @since 1.8.0 - * @ingroup Eet_Data_Group - */ -#define EET_DATA_DESCRIPTOR_ADD_SUB_NESTED(edd, struct_type, name, member, subtype) \ - do { \ - struct_type ___ett; \ - eet_data_descriptor_element_add(edd, name, EET_T_UNKNOW, EET_G_UNKNOWN_NESTED, \ - (char *)(& (___ett.member)) - \ - (char *)(& (___ett)), \ - 0, /* 0, */ NULL, subtype); \ - } while (0) - -/** - * Add a linked list type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of linked list member to add. - * - * This macro lets you easily add a linked list of other data types. All the - * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the - * @p subtype being the exception. This must be the data descriptor of the - * element that is in each member of the linked list to be stored. - * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param subtype The type of linked list member to add */ #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \ do { \ @@ -3483,18 +3257,17 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a linked list of string to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. + * @brief Adds a linked list of string to a data descriptor. * - * This macro lets you easily add a linked list of char *. All the - * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). + * @details This macro lets you easily add a linked list of char *. All the + * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). + * @since 1.5.0 * - * @since 1.5.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded */ #define EET_DATA_DESCRIPTOR_ADD_LIST_STRING(edd, struct_type, name, member) \ do { \ @@ -3506,22 +3279,21 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a hash type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of hash member to add. + * @brief Adds a hash type to a data descriptor. * - * This macro lets you easily add a hash of other data types. All the - * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the - * @p subtype being the exception. This must be the data descriptor of the - * element that is in each member of the hash to be stored. - * The hash keys must be strings. + * @details This macro lets you easily add a hash of other data types. All the + * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the + * @a subtype being the exception. This must be the data descriptor of the + * element that is in each member of the hash to be stored. + * The hash keys must be strings. + * @since 1.0.0 * - * @since 1.0.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param subtype The type of hash member to add */ #define EET_DATA_DESCRIPTOR_ADD_HASH(edd, struct_type, name, member, subtype) \ do { \ @@ -3533,18 +3305,17 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a hash of string to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. + * @brief Adds a hash of string to a data descriptor. * - * This macro lets you easily add a hash of string elements. All the - * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH(). + * @details This macro lets you easily add a hash of string elements. All the + * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_HASH(). + * @since 1.3.4 * - * @since 1.3.4 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded */ #define EET_DATA_DESCRIPTOR_ADD_HASH_STRING(edd, struct_type, name, member) \ do { \ @@ -3556,22 +3327,21 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add an array of basic data elements to a data descriptor. - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param type The type of the member to encode. + * @brief Adds an array of basic data elements to a data descriptor. * - * This macro lets you easily add a fixed size array of basic data - * types. All the parameters are the same as for - * EET_DATA_DESCRIPTOR_ADD_BASIC(). - * The array must be defined with a fixed size in the declaration of the - * struct containing it. + * @details This macro lets you easily add a fixed size array of basic data + * types. All the parameters are the same as for + * EET_DATA_DESCRIPTOR_ADD_BASIC(). + * The array must be defined with a fixed size in the declaration of the + * struct containing it. + * @since 1.5.0 * - * @since 1.5.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param type The type of the member to encode */ #define EET_DATA_DESCRIPTOR_ADD_BASIC_ARRAY(edd, struct_type, name, member, type) \ do { \ @@ -3585,24 +3355,23 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while(0) /** - * Add a variable array of basic data elements to a data descriptor. - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param type The type of the member to encode. + * @brief Adds a variable array of basic data elements to a data descriptor. * - * This macro lets you easily add a variable size array of basic data - * types. All the parameters are the same as for - * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have - * a struct member (of type EET_T_INT) called member_count (note the - * _count appended to the member) that holds the number of items in - * the array. This array will be allocated separately to the struct it - * is in. + * @details This macro lets you easily add a variable size array of basic data + * types. All the parameters are the same as for + * EET_DATA_DESCRIPTOR_ADD_BASIC(). This assumes you have + * a struct member (of type EET_T_INT) called member_count (note the + * _count appended to the member) that holds the number of items in + * the array. This array is allocated separately to the struct it is in. * - * @since 1.6.0 - * @ingroup Eet_Data_Group + * @since 1.6.0 + * + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param type The type of the member to encode */ #define EET_DATA_DESCRIPTOR_ADD_BASIC_VAR_ARRAY(edd, struct_type, name, member, type) \ do { \ @@ -3617,24 +3386,23 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while(0) /** - * Add a fixed size array type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of hash member to add. + * @brief Adds a fixed size array type to a data descriptor. * - * This macro lets you easily add a fixed size array of other data - * types. All the parameters are the same as for - * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the - * exception. This must be the data descriptor of the element that - * is in each member of the array to be stored. - * The array must be defined with a fixed size in the declaration of the - * struct containing it. + * @details This macro lets you easily add a fixed size array of other data + * types. All the parameters are the same as for + * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @a subtype being the + * exception. This must be the data descriptor of the element that + * is in each member of the array to be stored. + * The array must be defined with a fixed size in the declaration of the + * struct containing it. + * @since 1.0.2 * - * @since 1.0.2 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param subtype The type of hash member to add */ #define EET_DATA_DESCRIPTOR_ADD_ARRAY(edd, struct_type, name, member, subtype) \ do { \ @@ -3647,26 +3415,24 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a variable size array type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param subtype The type of hash member to add. - * - * This macro lets you easily add a variable size array of other data - * types. All the parameters are the same as for - * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the - * exception. This must be the data descriptor of the element that - * is in each member of the array to be stored. This assumes you have - * a struct member (of type EET_T_INT) called member_count (note the - * _count appended to the member) that holds the number of items in - * the array. This array will be allocated separately to the struct it - * is in. - * - * @since 1.0.2 - * @ingroup Eet_Data_Group + * @brief Adds a variable size array type to a data descriptor. + * + * @details This macro lets you easily add a variable size array of other data + * types. All the parameters are the same as for + * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @a subtype being the + * exception. This must be the data descriptor of the element that + * is in each member of the array to be stored. This assumes you have + * a struct member (of type EET_T_INT) called member_count (note the + * _count appended to the member) that holds the number of items in + * the array. This array is allocated separately to the struct it is in. + * @since 1.0.2 + * + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param subtype The type of hash member to add */ #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY(edd, struct_type, name, member, subtype) \ do { \ @@ -3684,18 +3450,17 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a variable size array type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. + * @brief Adds a variable size array type to a data descriptor. * - * This macro lets you easily add a variable size array of strings. All - * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). + * @details This macro lets you easily add a variable size array of strings. All + * the parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(). + * @since 1.4.0 * - * @since 1.4.0 - * @ingroup Eet_Data_Group + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded */ #define EET_DATA_DESCRIPTOR_ADD_VAR_ARRAY_STRING(edd, struct_type, name, member) \ do { \ @@ -3713,22 +3478,22 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add an union type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param type_member The member that give hints on what is in the union. - * @param unified_type Describe all possible type the union could handle. + * @brief Adds a union type to a data descriptor. * - * This macro lets you easily add an union with a member that specify what is inside. - * The @p unified_type is an Eet_Data_Descriptor, but only the entry that match the name - * returned by type_get will be used for each serialized data. The type_get and type_set - * callback of unified_type should be defined. + * @details This macro lets you easily add a union with a member that specifies what is inside. + * The @a unified_type is an Eet_Data_Descriptor, but only the entry that matches the name + * returned by type_get is used for each serialized data. The type_get and type_set + * callback of @a unified_type should be defined. + * @since 1.2.4 + * + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded + * @param type_member The member that give hints on what is in the union + * @param unified_type The union type * - * @since 1.2.4 - * @ingroup Eet_Data_Group * @see Eet_Data_Descriptor_Class */ #define EET_DATA_DESCRIPTOR_ADD_UNION(edd, struct_type, name, member, type_member, unified_type) \ @@ -3743,24 +3508,24 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a automatically selectable type to a data descriptor - * @param edd The data descriptor to add the type to. - * @param struct_type The type of the struct. - * @param name The string name to use to encode/decode this member - * (must be a constant global and never change). - * @param member The struct member itself to be encoded. - * @param type_member The member that give hints on what is in the union. - * @param unified_type Describe all possible type the union could handle. + * @brief Adds an automatically selectable type to a data descriptor. * - * This macro lets you easily define what the content of @p member points to depending of - * the content of @p type_member. The type_get and type_set callback of unified_type should - * be defined. If the the type is not know at the time of restoring it, eet will still call - * type_set of @p unified_type but the pointer will be set to a serialized binary representation - * of what eet know. This make it possible, to save this pointer again by just returning the string - * given previously and telling it by setting unknow to EINA_TRUE. + * @details This macro lets you easily define what the content of @a member points to depending of + * the content of @a type_member. The type_get and type_set callback of @a unified_type should + * be defined. If the the type is not known at the time of restoring it, eet still calls + * type_set of @a unified_type but the pointer is set to a serialized binary representation + * of what eet know. This makes it possible, to save this pointer again by just returning the string + * given previously and telling it by setting unknown to @c EINA_TRUE. + * @since 1.2.4 + * + * @param edd The data descriptor to add the type to + * @param struct_type The type of the struct + * @param name The string name to use to encode or decode this member \n + * This must be a constant global and never changes. + * @param member The struct member itself to be encoded. + * @param type_member The member that give hints on what is in the union. + * @param unified_type Describe all possible type the union could handle. * - * @since 1.2.4 - * @ingroup Eet_Data_Group * @see Eet_Data_Descriptor_Class */ #define EET_DATA_DESCRIPTOR_ADD_VARIANT(edd, struct_type, name, member, type_member, unified_type) \ @@ -3775,13 +3540,11 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, } while (0) /** - * Add a mapping to a data descriptor that will be used by union, variant or inherited type - * @param unified_type The data descriptor to add the mapping to. - * @param name The string name to get/set type. - * @param subtype The matching data descriptor. - * - * @since 1.2.4 - * @ingroup Eet_Data_Group + * brief Adds a mapping to a data descriptor that is used by union, variant or inherited type. + * @since 1.2.4 + * @param unified_type The data descriptor to add the mapping to + * @param name The string name to get/set type + * @param subtype The matching data descriptor * @see Eet_Data_Descriptor_Class */ #define EET_DATA_DESCRIPTOR_ADD_MAPPING(unified_type, name, subtype) \ @@ -3795,62 +3558,48 @@ eet_data_descriptor_encode(Eet_Data_Descriptor *edd, subtype) /** - * Add a mapping of a basic type to a data descriptor that will be used by a union type. - * @param unified_type The data descriptor to add the mapping to. - * @param name The string name to get/set type. - * @param basic_type The matching basic type. - * - * @since 1.8 - * @ingroup Eet_Data_Group - * @see Eet_Data_Descriptor_Class + * @} */ -#define EET_DATA_DESCRIPTOR_ADD_MAPPING_BASIC(unified_type, name, basic_type) \ - eet_data_descriptor_element_add(unified_type, \ - name, \ - basic_type, \ - EET_G_UNKNOWN, \ - 0, \ - 0, \ - NULL, \ - NULL) + /** + * @internal * @defgroup Eet_Data_Cipher_Group Eet Data Serialization using A Ciphers + * @ingroup Eet_Data_Group * * Most of the @ref Eet_Data_Group have alternative versions that * accounts for ciphers to protect their content. * * @see @ref Eet_Cipher_Group * - * @ingroup Eet_Data_Group + * @{ */ /** - * Read a data structure from an eet file and decodes it using a cipher. - * @param ef The eet file handle to read from. - * @param edd The data descriptor handle to use when decoding. - * @param name The key the data is stored under in the eet file. - * @param cipher_key The key to use as cipher. - * @return A pointer to the decoded data structure. + * @brief Reads a data structure from an eet file and decodes it using a cipher. * - * This function decodes a data structure stored in an eet file, returning - * a pointer to it if it decoded successfully, or NULL on failure. This - * can save a programmer dozens of hours of work in writing configuration - * file parsing and writing code, as eet does all that work for the program - * and presents a program-friendly data structure, just as the programmer - * likes. Eet can handle members being added or deleted from the data in - * storage and safely zero-fills unfilled members if they were not found - * in the data. It checks sizes and headers whenever it reads data, allowing - * the programmer to not worry about corrupt data. + * @details This function decodes a data structure stored in an eet file, returning + * a pointer to it if it decoded successfully, or @c NULL on failure. This + * can save a programmer dozens of hours of work in writing configuration + * file parsing and writing code, as eet does all that work for the program + * and presents a program-friendly data structure, just as the programmer + * likes. Eet can handle members being added or deleted from the data in + * storage and safely zero-fills unfilled members if they were not found + * in the data. It checks sizes and headers whenever it reads data, allowing + * the programmer to not worry about corrupt data. + * @since 1.0.0 * - * Once a data structure has been described by the programmer with the - * fields they wish to save or load, storing or retrieving a data structure - * from an eet file, or from a chunk of memory is as simple as a single - * function call. + * @remarks Once a data structure has been described by the programmer with the + * fields they wish to save or load, storing or retrieving a data structure + * from an eet file, or from a chunk of memory is as simple as a single + * function call. * - * @see eet_data_read() + * @param[in] ef The eet file handle to read from + * @param[in] edd The data descriptor handle to use when decoding + * @param[in] name The key the data is stored under in the eet file + * @param[in] cipher_key The key to use as cipher + * @return A pointer to the decoded data structure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_read() */ EAPI void * eet_data_read_cipher(Eet_File *ef, @@ -3859,34 +3608,34 @@ eet_data_read_cipher(Eet_File *ef, const char *cipher_key); /** - * Read a data structure from an eet file and decodes it into a buffer using a cipher, - * @param ef The eet file handle to read from. - * @param edd The data descriptor handle to use when decoding. - * @param name The key the data is stored under in the eet file. - * @param cipher_key The key to use as cipher. - * @param buffer Buffer. - * @param buffer_size The buffer size. - * @return A pointer to buffer if successful and NULL on error. - * - * This function decodes a data structure stored in an eet file, returning - * a pointer to it if it decoded successfully, or NULL on failure. This - * can save a programmer dozens of hours of work in writing configuration - * file parsing and writing code, as eet does all that work for the program - * and presents a program-friendly data structure, just as the programmer - * likes. Eet can handle members being added or deleted from the data in - * storage and safely zero-fills unfilled members if they were not found - * in the data. It checks sizes and headers whenever it reads data, allowing - * the programmer to not worry about corrupt data. - * - * Once a data structure has been described by the programmer with the - * fields they wish to save or load, storing or retrieving a data structure - * from an eet file, or from a chunk of memory is as simple as a single - * function call. + * @brief Reads a data structure from an eet file and decodes it into a buffer using a cipher. + * + * @details This function decodes a data structure stored in an eet file, returning + * a pointer to it if it decoded successfully, or NULL on failure. This + * can save a programmer dozens of hours of work in writing configuration + * file parsing and writing code, as eet does all that work for the program + * and presents a program-friendly data structure, just as the programmer + * likes. Eet can handle members being added or deleted from the data in + * storage and safely zero-fills unfilled members if they were not found + * in the data. It checks sizes and headers whenever it reads data, allowing + * the programmer to not worry about corrupt data. + * @since 1.10.0 + * + * @remarks Once a data structure has been described by the programmer with the + * fields they wish to save or load, storing or retrieving a data structure + * from an eet file, or from a chunk of memory is as simple as a single + * function call. + * + * @param[in] ef The eet file handle to read from + * @param[in] edd The data descriptor handle to use when decoding + * @param[in] name The key the data is stored under in the eet file + * @param[in] cipher_key The key to use as cipher + * @param[in] buffer The buffer + * @param[in] buffer_size The buffer size + * @return A pointer to buffer if successful, \n + * otherwise @c NULL on error * * @see eet_data_read_cipher() - * - * @since 1.10.0 - * @ingroup Eet_Data_Cipher_Group */ EAPI void * eet_data_read_cipher_buffer(Eet_File *ef, @@ -3897,27 +3646,27 @@ eet_data_read_cipher_buffer(Eet_File *ef, int buffer_size); /** - * Read a data structure from an eet extended attribute and decodes it using a cipher. - * @param filename The file to extract the extended attribute from. - * @param attribute The attribute to get the data from. - * @param edd The data descriptor handle to use when decoding. - * @param cipher_key The key to use as cipher. - * @return A pointer to the decoded data structure. + * @brief Reads a data structure from an eet extended attribute and decodes it using a cipher. * - * This function decodes a data structure stored in an eet extended attribute, - * returning a pointer to it if it decoded successfully, or NULL on failure. - * Eet can handle members being added or deleted from the data in - * storage and safely zero-fills unfilled members if they were not found - * in the data. It checks sizes and headers whenever it reads data, allowing - * the programmer to not worry about corrupt data. + * @details This function decodes a data structure stored in an eet extended attribute, + * returning a pointer to it if it decoded successfully, or @c NULL on failure. + * Eet can handle members being added or deleted from the data in + * storage and safely zero-fills unfilled members if they were not found + * in the data. It checks sizes and headers whenever it reads data, allowing + * you to not worry about corrupt data. + * @since 1.5.0 * - * Once a data structure has been described by the programmer with the - * fields they wish to save or load, storing or retrieving a data structure - * from an eet file, from a chunk of memory or from an extended attribute - * is as simple as a single function call. + * @remarks Once you have described a data structure with the + * fields you wish to save or load, storing or retrieving a data structure + * from an eet file, from a chunk of memory or from an extended attribute + * is as simple as a single function call. * - * @since 1.5.0 - * @ingroup Eet_Data_Cipher_Group + * @param[in] filename The file to extract the extended attribute from + * @param[in] attribute The attribute to get the data from + * @param[in] edd The data descriptor handle to use when decoding + * @param[in] cipher_key The key to use as cipher + * @return A pointer to the decoded data structure, \n + * otherwise @c NULL on failure */ EAPI void * eet_data_xattr_cipher_get(const char *filename, @@ -3926,21 +3675,22 @@ eet_data_xattr_cipher_get(const char *filename, const char *cipher_key); /** - * Write a data structure from memory and store in an eet file - * using a cipher. - * @param ef The eet file handle to write to. - * @param edd The data descriptor to use when encoding. - * @param name The key to store the data under in the eet file. - * @param cipher_key The key to use as cipher. - * @param data A pointer to the data structure to save and encode. - * @param compress Compression flags for storage. - * @return bytes written on successful write, 0 on failure. + * @brief Writes a data structure from memory and store in an eet file + * using a cipher. * - * This function is the reverse of eet_data_read_cipher(), saving a data structure - * to an eet file. + * @details This function is the reverse of eet_data_read_cipher(), saving a data structure + * to an eet file. * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @since 1.0.0 + * + * @param[in] ef The eet file handle to write to + * @param[in] edd The data descriptor to use when encoding + * @param[in] name The key to store the data under in the eet file + * @param[in] cipher_key The key to use as cipher + * @param[in] data A pointer to the data structure to save and encode + * @param[in] compress The compression flags for storage + * @return The bytes written on successful write, \n + * otherwise @c 0 on failure */ EAPI int eet_data_write_cipher(Eet_File *ef, @@ -3951,21 +3701,21 @@ eet_data_write_cipher(Eet_File *ef, int compress); /** - * Write a data structure from memory and store in an eet extended attribute - * using a cipher. - * @param filename The file to write the extended attribute to. - * @param attribute The attribute to store the data to. - * @param edd The data descriptor to use when encoding. - * @param cipher_key The key to use as cipher. - * @param data A pointer to the data structure to save and encode. - * @param flags The policy to use when setting the data. - * @return EINA_TRUE on success, EINA_FALSE on failure. + * @brief Writes a data structure from memory and store in an eet extended attribute + * using a cipher. * - * This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure - * to an eet extended attribute. + * @details This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure + * to an eet extended attribute. + * @since 1.5.0 * - * @since 1.5.0 - * @ingroup Eet_Data_Cipher_Group + * @param[in] filename The file to write the extended attribute to + * @param[in] attribute The attribute to store the data to + * @param[in] edd The data descriptor to use when encoding + * @param[in] cipher_key The key to use as cipher + * @param[in] data A pointer to the data structure to save and encode + * @param[in] flags The policy to use when setting the data + * @return @c EINA_TRUE if structure is written successfully, \n + * otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool eet_data_xattr_cipher_set(const char *filename, @@ -3976,24 +3726,18 @@ eet_data_xattr_cipher_set(const char *filename, Eina_Xattr_Flags flags); /** - * Dump an eet encoded data structure into ascii text using a cipher. - * @param data_in The pointer to the data to decode into a struct. - * @param cipher_key The key to use as cipher. - * @param size_in The size of the data pointed to in bytes. - * @param dumpfunc The function to call passed a string when new - * data is converted to text - * @param dumpdata The data to pass to the @p dumpfunc callback. - * @return 1 on success, 0 on failure + * @brief Dumps an eet encoded data structure into ascii text using a cipher. * - * This function will take a chunk of data encoded by - * eet_data_descriptor_encode() and convert it into human readable - * ascii text. It does this by calling the @p dumpfunc callback - * for all new text that is generated. This callback should append - * to any existing text buffer and will be passed the pointer @p - * dumpdata as a parameter as well as a string with new text to be - * appended. + * @details This function takes a chunk of data encoded by + * eet_data_descriptor_encode() and convert it into human readable + * ascii text. It does this by calling the @a dumpfunc callback + * for all new text that is generated. This callback should append + * to any existing text buffer and is passed the pointer @a + * dumpdata as a parameter as well as a string with new text to be + * appended. + * @since 1.0.0 * - * Example: + * @remarks The following is an example: * * @code * void output(void *data, const char *string) @@ -4018,10 +3762,16 @@ eet_data_xattr_cipher_set(const char *filename, * } * @endcode * - * @see eet_data_text_dump() + * @param[in] data_in The pointer to the data to decode into a struct + * @param[in] cipher_key The key to use as cipher + * @param[in] size_in The size of the data pointed to in bytes + * @param[in] dumpfunc The function to call passed a string when new + * data is converted to text + * @param[in] dumpdata The data to pass to the @a dumpfunc callback + * @return @c 1 if the structure is dumped into ascii successfully, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_text_dump() */ EAPI int eet_data_text_dump_cipher(const void *data_in, @@ -4031,25 +3781,23 @@ eet_data_text_dump_cipher(const void *data_in, void *dumpdata); /** - * Take an ascii encoding from eet_data_text_dump() and re-encode - * in binary using a cipher. - * @param text The pointer to the string data to parse and encode. - * @param cipher_key The key to use as cipher. - * @param textlen The size of the string in bytes (not including 0 - * byte terminator). - * @param size_ret This gets filled in with the encoded data blob - * size in bytes. - * @return The encoded data on success, NULL on failure. + * @brief Takes an ascii encoding from eet_data_text_dump() and re-encodes + * in binary using a cipher. * - * This function will parse the string pointed to by @p text and return - * an encoded data lump the same way eet_data_descriptor_encode() takes an - * in-memory data struct and encodes into a binary blob. @p text is a normal - * C string. + * @details This function parses the string pointed to by @a text and return + * an encoded data lump the same way eet_data_descriptor_encode() takes an + * in-memory data struct and encodes into a binary blob. @a text is a normal + * C string. + * @since 1.0.0 * - * @see eet_data_text_undump() + * @param[in] text The pointer to the string data to parse and encode + * @param[in] cipher_key The key to use as cipher + * @param[in] textlen The size of the string in bytes (not including @c 0 byte terminator) + * @param[out] size_ret This gets filled in with the encoded data blob size in bytes + * @return The encoded data, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_text_undump() */ EAPI void * eet_data_text_undump_cipher(const char *text, @@ -4058,29 +3806,30 @@ eet_data_text_undump_cipher(const char *text, int *size_ret); /** - * Dump an eet encoded data structure from an eet file into ascii - * text using a cipher. - * @param ef A valid eet file handle. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param dumpfunc The function to call passed a string when new - * data is converted to text - * @param dumpdata The data to pass to the @p dumpfunc callback. - * @return 1 on success, 0 on failure - * - * This function will take an open and valid eet file from - * eet_open() request the data encoded by - * eet_data_descriptor_encode() corresponding to the key @p name - * and convert it into human readable ascii text. It does this by - * calling the @p dumpfunc callback for all new text that is - * generated. This callback should append to any existing text - * buffer and will be passed the pointer @p dumpdata as a parameter - * as well as a string with new text to be appended. + * @brief Dumps an eet encoded data structure from an eet file into ascii + * text using a cipher. + * + * @details This function takes an open and valid eet file from + * eet_open() request the data encoded by + * eet_data_descriptor_encode() corresponding to the key @a name + * and convert it into human readable ascii text. It does this by + * calling the @a dumpfunc callback for all new text that is + * generated. This callback should append to any existing text + * buffer and is passed the pointer @a dumpdata as a parameter + * as well as a string with new text to be appended. + * @since 1.0.0 + * + * @param[in] ef A valid eet file handle + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] dumpfunc The function to call passed a string when new + * data is converted to text + * @param[in] dumpdata The data to pass to the @a dumpfunc callback + * @return @c 1 if the encoded data structure is dumped successfully, \n + * otherwise @c 0 on failure * * @see eet_data_dump() - * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group */ EAPI int eet_data_dump_cipher(Eet_File *ef, @@ -4090,28 +3839,28 @@ eet_data_dump_cipher(Eet_File *ef, void *dumpdata); /** - * Take an ascii encoding from eet_data_dump() and re-encode in - * binary using a cipher. - * @param ef A valid eet file handle. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param text The pointer to the string data to parse and encode. - * @param textlen The size of the string in bytes (not including 0 - * byte terminator). - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @return 1 on success, 0 on failure + * @brief Takes an ascii encoding from eet_data_dump() and re-encodes in + * binary using a cipher. * - * This function will parse the string pointed to by @p text, - * encode it the same way eet_data_descriptor_encode() takes an - * in-memory data struct and encodes into a binary blob. + * @details This function parses the string pointed to by @a text, + * encode it the same way eet_data_descriptor_encode() takes an + * in-memory data struct and encodes into a binary blob. + * @since 1.0.0 * - * The data (optionally compressed) will be in ram, pending a flush to - * disk (it will stay in ram till the eet file handle is closed though). + * @remarks The data (optionally compressed) is in RAM, pending a flush to + * disk (it stays in RAM till the eet file handle is closed though). * - * @see eet_data_undump() + * @param[in] ef A valid eet file handle + * @param[in] name The name of the entry \n + * For example: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher + * @param[in] text The pointer to the string data to parse and encode + * @param[in] textlen The size of the string in bytes (not including @c 0 byte terminator) + * @param[in] compress The compression flags (1 = compress, 0 = do not compress) + * @return @c 1 if the ascii encoding is re-encoded successfully, \n + * otherwise @c 0 on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_undump() */ EAPI int eet_data_undump_cipher(Eet_File *ef, @@ -4122,33 +3871,32 @@ eet_data_undump_cipher(Eet_File *ef, int compress); /** - * Decode a data structure from an arbitrary location in memory - * using a cipher. - * @param edd The data descriptor to use when decoding. - * @param data_in The pointer to the data to decode into a struct. - * @param cipher_key The key to use as cipher. - * @param size_in The size of the data pointed to in bytes. - * @return NULL on failure, or a valid decoded struct pointer on success. + * @brief Decodes a data structure from an arbitrary location in memory + * using a cipher. * - * This function will decode a data structure that has been encoded using - * eet_data_descriptor_encode(), and return a data structure with all its - * elements filled out, if successful, or NULL on failure. + * @details This function decodes a data structure that has been encoded using + * eet_data_descriptor_encode(), and return a data structure with all its + * elements filled out, if successful, or @c NULL on failure. + * @since 1.0.0 * - * The data to be decoded is stored at the memory pointed to by @p data_in, - * and is described by the descriptor pointed to by @p edd. The data size is - * passed in as the value to @p size_in, ande must be greater than 0 to - * succeed. + * @remarks The data to be decoded is stored at the memory pointed to by @a data_in, + * and is described by the descriptor pointed to by @a edd. The data size is + * passed in as the value to @a size_in, and must be greater than @c 0 to succeed. * - * This function is useful for decoding data structures delivered to the - * application by means other than an eet file, such as an IPC or socket - * connection, raw files, shared memory etc. + * @remarks This function is useful for decoding data structures delivered to the + * application by means other than an eet file, such as an IPC or socket + * connection, raw files, and shared memory. * - * Please see eet_data_read() for more information. + * @remarks See eet_data_read() for more information. * - * @see eet_data_descriptor_decode() + * @param[in] edd The data descriptor to use when decoding + * @param[in] data_in The pointer to the data to decode into a struct + * @param[in] cipher_key The key to use as cipher + * @param[in] size_in The size of the data pointed to in bytes + * @return A valid decoded struct pointer on success, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_descriptor_decode() */ EAPI void * eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, @@ -4157,35 +3905,35 @@ eet_data_descriptor_decode_cipher(Eet_Data_Descriptor *edd, int size_in); /** - * Encode a data struct to memory and return that encoded data - * using a cipher. - * @param edd The data descriptor to use when encoding. - * @param data_in The pointer to the struct to encode into data. - * @param cipher_key The key to use as cipher. - * @param size_ret pointer to the an int to be filled with the decoded size. - * @return NULL on failure, or a valid encoded data chunk on success. + * @brief Encodes a data struct to memory and return that encoded data + * using a cipher. * - * This function takes a data structutre in memory and encodes it into a - * serialised chunk of data that can be decoded again by - * eet_data_descriptor_decode(). This is useful for being able to transmit - * data structures across sockets, pipes, IPC or shared file mechanisms, - * without having to worry about memory space, machine type, endianess etc. + * @details This function takes a data structure in memory and encodes it into a + * serialised chunk of data that can be decoded again by + * eet_data_descriptor_decode(). This is useful for being able to transmit + * data structures across sockets, pipes, IPC or shared file mechanisms, + * without having to worry about memory space, machine type, endianess, and so on. + * @since 1.0.0 * - * The parameter @p edd must point to a valid data descriptor, and - * @p data_in must point to the right data structure to encode. If not, the - * encoding may fail. + * @remarks The parameter @a edd must point to a valid data descriptor, and + * @a data_in must point to the right data structure to encode. If not, the + * encoding may fail. * - * On success a non NULL valid pointer is returned and what @p size_ret - * points to is set to the size of this decoded data, in bytes. When the - * encoded data is no longer needed, call free() on it. On failure NULL is - * returned and what @p size_ret points to is set to 0. + * @remarks On success a non NULL valid pointer is returned and what @a size_ret + * points to is set to the size of this decoded data, in bytes. When the + * encoded data is no longer needed, call free() on it. On failure @c NULL is + * returned and what @a size_ret points to is set to @c 0. * - * Please see eet_data_write() for more information. + * @remarks See eet_data_write() for more information. * - * @see eet_data_descriptor_encode() + * @param[in] edd The data descriptor to use when encoding + * @param[in] data_in The pointer to the struct to encode into data + * @param[in] cipher_key The key to use as cipher + * @param[out] size_ret The pointer to the an int to be filled with the decoded size + * @return A valid encoded data chunk, \n + * otherwise @c NULL on failure * - * @since 1.0.0 - * @ingroup Eet_Data_Cipher_Group + * @see eet_data_descriptor_encode() */ EAPI void * eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, @@ -4194,30 +3942,36 @@ eet_data_descriptor_encode_cipher(Eet_Data_Descriptor *edd, int *size_ret); /** + * @} + */ + +/** + * @internal * @defgroup Eet_Node_Group Low-level Serialization Structures. - * @ingroup Eet + * @ingroup Eet_Group * - * Functions that create, destroy and manipulate serialization nodes - * used by @ref Eet_Data_Group. + * @brief This group provides functions that create, destroy and manipulate serialization nodes + * used by @ref Eet_Data_Group. * * @{ */ /** * @typedef Eet_Node - * Opaque handle to manage serialization node. + * @brief The structure type containing an opaque handle to manage serialization node. */ typedef struct _Eet_Node Eet_Node; /** * @typedef Eet_Node_Data - * Contains an union that can fit any kind of node. + * @brief The structure type containing a union that can fit any kind of node. */ typedef struct _Eet_Node_Data Eet_Node_Data; /** + * @internal * @struct _Eet_Node_Data - * Contains an union that can fit any kind of node. + * @brief The structure type containing a union that can fit any kind of node. */ struct _Eet_Node_Data { @@ -4237,168 +3991,104 @@ struct _Eet_Node_Data }; /** - * @} - */ - -/** - * Create a new character node. - * @param name Name of the node. - * @param c Character value. - * @return A new character node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_char_new(const char *name, char c); /** - * Create a new short node. - * @param name Name of the node. - * @param s short value. - * @return A new short node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_short_new(const char *name, short s); /** - * Create a new integer node. - * @param name Name of the node. - * @param i integer value. - * @return A new integer node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_int_new(const char *name, int i); /** - * Create a new long long integer node. - * @param name Name of the node. - * @param l long long integer value. - * @return A new long long integer node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_long_long_new(const char *name, long long l); /** - * Create a new float node. - * @param name Name of the node. - * @param f float value. - * @return A new float node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_float_new(const char *name, float f); /** - * Create a new double node. - * @param name Name of the node. - * @param d double value. - * @return A new double node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_double_new(const char *name, double d); /** - * Create a new unsigned character node. - * @param name Name of the node. - * @param uc unsigned char value. - * @return A new unsigned char node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_unsigned_char_new(const char *name, unsigned char uc); /** - * Create a new unsigned short node. - * @param name Name of the node. - * @param us unsigned short value. - * @return A new unsigned short node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_unsigned_short_new(const char *name, unsigned short us); /** - * Create a new unsigned integer node. - * @param name Name of the node. - * @param ui unsigned integer value. - * @return A new unsigned integer node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_unsigned_int_new(const char *name, unsigned int ui); /** - * Create a new unsigned long long integer node. - * @param name Name of the node. - * @param l unsigned long long integer value. - * @return A new unsigned long long integer node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_unsigned_long_long_new(const char *name, unsigned long long l); /** - * Create a new string node. - * @param name Name of the node. - * @param str string value. - * @return A new string node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_string_new(const char *name, const char *str); /** - * Create a new inlined string node. - * @param name Name of the node. - * @param str string value. - * @return A new inlined string node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_inlined_string_new(const char *name, const char *str); /** - * Create a new empty node. - * @param name Name of the node. - * @return A new empty node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_null_new(const char *name); /** - * Create a new list node. - * @param name Name of the node. - * @param nodes list of nodes. - * @return A new list node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_list_new(const char *name, Eina_List *nodes); /** - * Create a new array node. - * @param name Name of the node. - * @param count number of nodes - * @param nodes list of nodes. - * @return A new array node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_array_new(const char *name, @@ -4406,11 +4096,7 @@ eet_node_array_new(const char *name, Eina_List *nodes); /** - * Create a new variable array node. - * @param name Name of the node. - * @param nodes list of nodes. - * @return A new variable array node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_var_array_new(const char *name, @@ -4418,14 +4104,6 @@ eet_node_var_array_new(const char *name, /** * TODO FIX ME - * @ingroup Eet_Node_Group - */ -/** - * Create a new short node. - * @param name Name of the node. - * @param s short value. - * @return A new short node. - * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_node_hash_new(const char *name, @@ -4433,11 +4111,7 @@ eet_node_hash_new(const char *name, Eet_Node *node); /** - * Create a new struct node. - * @param name Name of the node. - * @param nodes list of nodes. - * @return A new struct node. - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI Eet_Node * eet_node_struct_new(const char *name, @@ -4445,51 +4119,45 @@ eet_node_struct_new(const char *name, /** * TODO FIX ME - * @ingroup Eet_Node_Group - */ -/** - * Create a new short node. - * @param name Name of the node. - * @param s short value. - * @return A new short node. - * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_node_struct_child_new(const char *parent, Eet_Node *child); /** - * @brief Get a node's child nodes - * @param node The node - * @return The first child node which contains a pointer to the - * next child node and the parent. - * @since 1.5 + * @brief Gets a node's child nodes. + * @since 1.5 + * + * @param[in] node The node + * @return The first child node which contains a pointer to the + * next child node and the parent */ EAPI Eet_Node * eet_node_children_get(Eet_Node *node); /** - * @brief Get the next node in a list of nodes - * @param node The node - * @return A node which contains a pointer to the - * next child node and the parent. - * @since 1.5 + * @brief Gets the next node in a list of nodes. + * @since 1.5 + * + * @param[in] node The node + * @return A node which contains a pointer to the + * next child node and the parent */ EAPI Eet_Node * eet_node_next_get(Eet_Node *node); /** - * @brief Get the parent node of a node - * @param node The node - * @return The parent node of @p node - * @since 1.5 + * @brief Gets the parent node of a node. + * @since 1.5 + * + * @param[in] node The node + * @return The parent node of @a node */ EAPI Eet_Node * eet_node_parent_get(Eet_Node *node); /** - * @brief Append a "list" node TODO FIX ME - * @ingroup Eet_Node_Group + * TODO FIX ME */ EAPI void eet_node_list_append(Eet_Node *parent, @@ -4498,7 +4166,6 @@ eet_node_list_append(Eet_Node *parent, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI void eet_node_struct_append(Eet_Node *parent, @@ -4507,7 +4174,6 @@ eet_node_struct_append(Eet_Node *parent, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI void eet_node_hash_add(Eet_Node *parent, @@ -4517,7 +4183,6 @@ eet_node_hash_add(Eet_Node *parent, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI void eet_node_dump(Eet_Node *n, @@ -4526,33 +4191,33 @@ eet_node_dump(Eet_Node *n, void *dumpdata); /** - * @brief Return the type of a node - * @param node The node - * @return The node's type (EET_T_$TYPE) - * @since 1.5 + * @brief Gets the type of a node. + * @since 1.5 + * + * @param[in] node The node + * @return The node's type (EET_T_$TYPE) */ EAPI int eet_node_type_get(Eet_Node *node); /** - * @brief Return the node's data - * @param node The node - * @return The data contained in the node - * @since 1.5 + * @brief Gets the node's data. + * @since 1.5 + * + * @param[in] node The node + * @return The data contained in the node */ EAPI Eet_Node_Data * eet_node_value_get(Eet_Node *node); /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI void eet_node_del(Eet_Node *n); /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI void * eet_data_node_encode_cipher(Eet_Node *node, @@ -4561,7 +4226,6 @@ eet_data_node_encode_cipher(Eet_Node *node, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_data_node_decode_cipher(const void *data_in, @@ -4570,7 +4234,6 @@ eet_data_node_decode_cipher(const void *data_in, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_data_node_read_cipher(Eet_File *ef, @@ -4579,7 +4242,6 @@ eet_data_node_read_cipher(Eet_File *ef, /** * TODO FIX ME - * @ingroup Eet_Node_Group */ EAPI int eet_data_node_write_cipher(Eet_File *ef, @@ -4592,41 +4254,13 @@ eet_data_node_write_cipher(Eet_File *ef, /** * @typedef Eet_Node_Walk - * Describes how to walk trees of #Eet_Node. + * @brief The structure type that describes how to walk trees of #Eet_Node. */ typedef struct _Eet_Node_Walk Eet_Node_Walk; -/** - * @typedef (*Eet_Node_Walk_Struct_Alloc_Callback) - * - * Callback prototype for Eet_Node_Walk_Struct_Alloc - * @param type The allocation type - * @param user_data the data passed by the user to the callback - */ typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data); - -/** - * @typedef (*Eet_Node_Walk_Struct_Add_Callback) - * - * Callback prototype for Eet_Node_Walk_Struct_Add - * @param parent The parent node - * @param name the name for the new node - * @param child the child node - * @param user_data the data passed by the user to the callback - */ typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data); - -/** - * @typedef (*Eet_Node_Walk_Array_Callback) - * - * Callback prototype for Eet_Node_Walk_Array - * @param variable EINA_TRUE or EINA_FALSE - * @param name a name - * @param count a counter - * @param user_data the data passed by the user to the callback - */ typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data); - typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data); typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data); typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data); @@ -4634,8 +4268,9 @@ typedef void * (*Eet_Node_Walk_Hash_Callback)(void *parent, const c typedef void * (*Eet_Node_Walk_Simple_Callback)(int type, Eet_Node_Data *data, void *user_data); /** + * @internal * @struct _Eet_Node_Walk - * Describes how to walk trees of #Eet_Node. + * @brief The structure type that describes how to walk trees of #Eet_Node. */ struct _Eet_Node_Walk { @@ -4656,51 +4291,49 @@ eet_node_walk(void *parent, Eet_Node_Walk *cb, void *user_data); -/*******/ +/** + * @} + */ /** + * @internal * @defgroup Eet_Connection_Group Helper function to use eet over a network link - * @ingroup Eet + * @ingroup Eet_Group * - * Function that reconstruct and prepare packet of @ref Eet_Data_Group to be send. + * @remarks This group provides function that reconstructs and prepares packet of @ref Eet_Data_Group to be send. * + * @{ */ /** * @typedef Eet_Connection - * Opaque handle to track paquet for a specific connection. - * - * @ingroup Eet_Connection_Group + * @brief The structure type containing an opaque handle to track packet for a specific connection. */ typedef struct _Eet_Connection Eet_Connection; /** * @typedef Eet_Read_Cb - * Called back when an @ref Eet_Data_Group has been received completely and could be used. - * - * @ingroup Eet_Connection_Group + * @brief Called when an @ref Eet_Data_Group has been received completely and could be used. */ typedef Eina_Bool Eet_Read_Cb (const void *eet_data, size_t size, void *user_data); /** * @typedef Eet_Write_Cb - * Called back when a packet containing @ref Eet_Data_Group data is ready to be send. - * - * @ingroup Eet_Connection_Group + * @brief Called when a packet containing @ref Eet_Data_Group data is ready to be sent. */ typedef Eina_Bool Eet_Write_Cb (const void *data, size_t size, void *user_data); /** - * Instanciate a new connection to track. - * @param eet_read_cb Function to call when one Eet_Data packet has been fully assemble. - * @param eet_write_cb Function to call when one Eet_Data packet is ready to be send over the wire. - * @param user_data Pointer provided to both functions to be used as a context handler. - * @return NULL on failure, or a valid Eet_Connection handler. + * @brief Instantiates a new connection to track. + * @since 1.2.4 * - * For every connection to track you will need a separate Eet_Connection provider. + * @remarks For every connection to track, you need a separate Eet_Connection provider. * - * @since 1.2.4 - * @ingroup Eet_Connection_Group + * @param[in] eet_read_cb The function to call when one Eet_Data packet has been fully assembled + * @param[in] eet_write_cb The function to call when one Eet_Data packet is ready to be sent over the wire + * @param[in] user_data The pointer provided to both functions to be used as a context handler + * @return A valid Eet_Connection handler, \n + * otherwise @c NULL on failure */ EAPI Eet_Connection * eet_connection_new(Eet_Read_Cb *eet_read_cb, @@ -4708,18 +4341,19 @@ eet_connection_new(Eet_Read_Cb *eet_read_cb, const void *user_data); /** - * Process a raw packet received over the link - * @param conn Connection handler to track. - * @param data Raw data packet. - * @param size The size of that packet. - * @return 0 on complete success, any other value indicate where in the stream it got wrong (It could be before that packet). + * @brief Processes a raw packet received over the link. + * @since 1.2.4 * - * Every time you receive a packet related to your connection, you should pass - * it to that function so that it could process and assemble packet has you - * receive it. It will automatically call Eet_Read_Cb when one is fully received. + * @remarks Every time you receive a packet related to your connection, you should pass + * it to that function so that it could process and assemble packet that you + * receive. It automatically calls Eet_Read_Cb when one is fully received. * - * @since 1.2.4 - * @ingroup Eet_Connection_Group + * @param[in] conn The connection handler to track + * @param[in] data The raw data packet + * @param[in] size The size of that packet + * @return @c 0 on complete success, \n + * otherwise any other value which indicates the stream it got wrong \n + * It could be before that packet. */ EAPI int eet_connection_received(Eet_Connection *conn, @@ -4727,35 +4361,34 @@ eet_connection_received(Eet_Connection *conn, size_t size); /** - * Tell if the Eet_Connection as received some partial data. - * @param conn Connection handler to request. - * @return EINA_TRUE if there is some data pending inside, EINA_FALSE otherwise. - * - * Eet_Connection buffer data until the received data can be unserialized correctly. This - * function let you know if there is some data inside that buffer waiting for more data to - * be received before being processed. + * @brief Checks whether the Eet_Connection has received some partial data. + * @since 1.7 * - * @since 1.7 - * @ingroup Eet_Connection_Group + * @remarks Eet_Connection buffer data until the received data can be unserialized correctly. This + * function lets you know if there is some data inside that buffer waiting for more data to + * be received before being processed. + * @param[in] conn The connection handler to request + * @return @c EINA_TRUE if there is some data pending inside, \n + * otherwise @c EINA_FALSE */ EAPI Eina_Bool eet_connection_empty(Eet_Connection *conn); /** - * Convert a complex structure and prepare it to be send. - * @param conn Connection handler to track. - * @param edd The data descriptor to use when encoding. - * @param data_in The pointer to the struct to encode into data. - * @param cipher_key The key to use as cipher. - * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't. + * @brief Converts a complex structure and prepares it to be send. * - * This function serialize data_in with edd, assemble the packet and call - * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated - * and will vanish just after the return of the callback. + * @details This function serializes data_in with edd, assembles the packet and calls + * Eet_Write_Cb when ready. The data passed Eet_Write_Cb is temporary allocated + * and vanishes just after the return of the callback. + * @since 1.2.4 * - * @see eet_data_descriptor_encode_cipher + * @param[in] conn The connection handler to track + * @param[in] edd The data descriptor to use when encoding + * @param[in] data_in The pointer to the struct to encode into data + * @param[in] cipher_key The key to use as cipher + * @return @c EINA_TRUE if the complex structure is converted successfully, \n + * otherwise @c EINA_FALSE on failure * - * @since 1.2.4 - * @ingroup Eet_Connection_Group + * @see eet_data_descriptor_encode_cipher */ EAPI Eina_Bool eet_connection_send(Eet_Connection *conn, @@ -4764,20 +4397,20 @@ eet_connection_send(Eet_Connection *conn, const char *cipher_key); /** - * Convert a Eet_Node tree and prepare it to be send. - * @param conn Connection handler to track. - * @param node The data tree to use when encoding. - * @param cipher_key The key to use as cipher. - * @return EINA_TRUE if the data where correctly send, EINA_FALSE if they don't. + * @brief Converts a Eet_Node tree and prepares it to be send. * - * This function serialize node, assemble the packet and call - * Eet_Write_Cb when ready. The data passed Eet_Write_Cb are temporary allocated - * and will vanish just after the return of the callback. + * @details This function serializes node, assembles the packet and calls + * Eet_Write_Cb when ready. The data passed Eet_Write_Cb is temporary allocated + * and vanishes just after the return of the callback. + * @since 1.2.4 * - * @see eet_data_node_encode_cipher + * @param[in] conn The connection handler to track + * @param[in] node The data tree to use when encoding + * @param[in] cipher_key The key to use as cipher + * @return @c EINA_TRUE if the tree is converted successfully, \n + * otherwise @c EINA_FALSE on failure * - * @since 1.2.4 - * @ingroup Eet_Connection_Group + * @see eet_data_node_encode_cipher */ EAPI Eina_Bool eet_connection_node_send(Eet_Connection *conn, @@ -4785,19 +4418,20 @@ eet_connection_node_send(Eet_Connection *conn, const char *cipher_key); /** - * Close a connection and lost its track. - * @param conn Connection handler to close. - * @param on_going Signal if a partial packet wasn't completed. - * @return the user_data passed to both callback. + * @brief Closes a connection and loses its track. + * @since 1.2.4 * - * @since 1.2.4 - * @ingroup Eet_Connection_Group + * @param[in] conn The connection handler to close + * @param[in] on_going The signal if a partial packet is not completed + * @return The user_data passed to both callback */ EAPI void * eet_connection_close(Eet_Connection *conn, Eina_Bool *on_going); -/***************************************************************************/ +/** + * @} + */ #ifdef __cplusplus } diff --git a/src/lib/efreet/Efreet.h b/src/lib/efreet/Efreet.h index 419e5ff531..fdf1003e87 100644 --- a/src/lib/efreet/Efreet.h +++ b/src/lib/efreet/Efreet.h @@ -2,26 +2,31 @@ #define EFREET_H /** + * @internal * @file Efreet.h + * * @brief The file that must be included by any project wishing to use - * Efreet. Efreet.h provides all of the necessary headers and includes to - * work with Efreet. + * Efreet. Efreet.h provides all the necessary headers and includes to + * work with Efreet. */ /** + * @internal + * @defgroup Efreet_Group Efreet + * @ingroup EFL_Group + * * @page efreet_main Efreet * * @section toc Table of Contents * * @li @ref efreet_main_intro - * @li @ref efreet_main_compiling * @li @ref efreet_main_next_steps * * @section efreet_main_intro Introduction * - * Efreet is a library designed to help apps work several of the - * Freedesktop.org standards regarding Icons, Desktop files and Menus. To - * that end it implements the following specifications: + * @brief Efreet is a library designed to help applications work with several of the + * Freedesktop.org standards regarding Icons, Desktop files, and Menus. On the + * same lines it implements the following specifications: * * @li XDG Base Directory Specification * @li Icon Theme Specification @@ -31,28 +36,6 @@ * @li Shared Mime Info Specification * @li Trash Specification * - * @section efreet_main_compiling How to compile - * - * Efreet is a library your application links to. The procedure for - * this is very simple. You simply have to compile your application - * with the appropriate compiler flags that the @c pkg-config script - * outputs. Mime and Thrash are separated modules. For example, to - * compile with mime support: - * - * Compiling C or C++ files into object files: - * - * @verbatim - gcc -c -o main.o main.c `pkg-config --cflags efreet efreet-mime` - @endverbatim - * - * Linking object files into a binary executable: - * - * @verbatim - gcc -o my_application main.o `pkg-config --libs efreet efreet-mime` - @endverbatim - * - * See @ref pkgconfig - * * @section efreet_main_next_steps Next Steps * * After you understood what Efreet is and installed it in your system @@ -60,19 +43,19 @@ * * Recommended reading: * - * @li @ref Efreet_Base for base directory specification (XDG variables). + * @li @ref Efreet_Base_Group for base directory specification (XDG variables). * @li @ref Efreet_Desktop to access .desktop files * @li @ref Efreet_Menu to access menus of .desktop files - * @li @ref Efreet_Mime to identify files based on extension or header. - * @li @ref Efreet_Trash to access file trash implementation. + * @li @ref Efreet_Mime_Group to identify files based on extension or header. + * @li @ref Efreet_Trash_Group to access file trash implementation. * @li @ref Efreet_Ini for parsing INI-like key-value files. * @li @ref Efreet_Uri for URI parsing and encoding. - * @li @ref Efreet_Utils general utilities. + * @li @ref Efreet_Utils_Group general utilities. * + * @{ */ #include <Eina.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI @@ -104,22 +87,19 @@ extern "C" { #endif -#define EFREET_VERSION_MAJOR EFL_VERSION_MAJOR -#define EFREET_VERSION_MINOR EFL_VERSION_MINOR - /** - * @typedef Efreet_Version - * Represents the current version of Efreet - */ - typedef struct _Efreet_Version - { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Efreet is built from) */ - } Efreet_Version; - - EAPI extern Efreet_Version *efreet_version; +#define EFREET_VERSION_MAJOR 1 +#define EFREET_VERSION_MINOR 8 +typedef struct _Efreet_Version + { + int major; + int minor; + int micro; + int revision; + } Efreet_Version; + +EAPI extern Efreet_Version *efreet_version; + #include "efreet_base.h" #include "efreet_ini.h" #include "efreet_icon.h" @@ -129,26 +109,31 @@ extern "C" { #include "efreet_uri.h" /** - * @return Value > @c 0 if the initialization was successful, @c 0 otherwise. - * @brief Initializes the Efreet system + * @brief Initializes the Efreet system. + * + * @return The value > @c 0 if the initialization is successful, otherwise @c 0 */ EAPI int efreet_init(void); /** + * @brief Shuts down Efreet if a balanced number of init/shutdown calls have been made. + * * @return The number of times the init function has been called minus the - * corresponding init call. - * @brief Shuts down Efreet if a balanced number of init/shutdown calls have - * been made + * corresponding init call */ EAPI int efreet_shutdown(void); /** - * @brief Resets language dependent variables and resets language dependent - * caches This must be called whenever the locale is changed. + * @brief Resets the language dependent variables and resets the language dependent + * caches. This must be called whenever the locale is changed. * @since 1.7 */ EAPI void efreet_lang_reset(void); +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/src/lib/efreet/Efreet_Mime.h b/src/lib/efreet/Efreet_Mime.h index cbde578876..23b26c3a9c 100644 --- a/src/lib/efreet/Efreet_Mime.h +++ b/src/lib/efreet/Efreet_Mime.h @@ -2,15 +2,20 @@ #define EFREET_MIME_H /** + * @internal * @file Efreet_Mime.h - * @brief The file that must be included by any project wishing to use - * @addtogroup Efreet_Mime Efreet_Mime: The XDG Shared Mime Info standard - * Efreet Mime is a library designed to help apps work with the + * + * @brief The file that must be included by any project wishing to use Efreet_Mime. + * + * @internal + * @defgroup Efreet_Mime_Group Efreet_Mime: The XDG Shared Mime Info standard + * @ingroup Efreet_Group + * + * Efreet Mime is a library designed to help applications work with the * Freedesktop.org Shared Mime Info standard. - * Efreet_Mime.h provides all of the necessary headers and + * Efreet_Mime.h provides all the necessary headers and * includes to work with Efreet_Mime. * - * @ingroup Efreet * @{ */ @@ -19,7 +24,7 @@ #endif #ifdef _WIN32 -# ifdef EFL_EFREET_BUILD +# ifdef EFL_EFREET_MIME_BUILD # ifdef DLL_EXPORT # define EAPI __declspec(dllexport) # else @@ -46,75 +51,83 @@ extern "C" { /** - * @return @c 1 on success or @c 0 on failure. - * @brief Initializes the efreet mime settings + * @brief Initializes the efreet mime settings. + * + * @return @c 1 on success, otherwise @c 0 on failure */ EAPI int efreet_mime_init(void); /** + * @brief Shuts down the Efreet mime settings system if a balanced number of + * init/shutdown calls have been made. + * * @return The number of times the init function has been called minus the - * corresponding init call. - * @brief Shuts down Efreet mime settings system if a balanced number of - * init/shutdown calls have been made + * corresponding init call */ EAPI int efreet_mime_shutdown(void); /** - * @param file The file to find the mime type - * @return Mime type as a string. - * @brief Retrieve the mime type of a file + * @brief Gets the mime type of a file. + * + * @param[in] file The file to find the mime type of + * @return The mime type as a string */ EAPI const char *efreet_mime_type_get(const char *file); /** - * @param file The file to check the mime type - * @return Mime type as a string. - * @brief Retrieve the mime type of a file using magic + * @brief Gets the mime type of a file using magic. + * + * @param[in] file The file to check the mime type of + * @return The mime type as a string */ EAPI const char *efreet_mime_magic_type_get(const char *file); /** - * @param file The file to check the mime type - * @return Mime type as a string. - * @brief Retrieve the mime type of a file using globs + * @brief Gets the mime type of a file using globs. + * + * @param[in] file The file to check the mime type of + * @return The mime type as a string */ EAPI const char *efreet_mime_globs_type_get(const char *file); /** - * @param file The file to check the mime type - * @return Mime type as a string. - * @brief Retrieve the special mime type of a file + * @brief Gets the special mime type of a file. + * + * @param[in] file The file to check the mime type of + * @return The mime type as a string */ EAPI const char *efreet_mime_special_type_get(const char *file); /** - * @param file The file to check the mime type - * @return Mime type as a string. - * @brief Retrieve the fallback mime type of a file. + * @brief Gets the fallback mime type of a file. + * + * @param[in] file The file to check the mime type of + * @return The mime type as a string */ EAPI const char *efreet_mime_fallback_type_get(const char *file); /** - * @param mime The name of the mime type - * @param theme The name of the theme to search icons in - * @param size The wanted size of the icon - * @return Mime type icon path as a string. - * @brief Retrieve the mime type icon for a file. + * @brief Gets the mime type icon for a file. + * + * @param[in] mime The name of the mime type + * @param[in] theme The name of the theme to search icons in + * @param[in] size The required size of the icon + * @return The mime type icon path as a string */ EAPI const char *efreet_mime_type_icon_get(const char *mime, const char *theme, unsigned int size); /** - * @brief Clear mime icons mapping cache + * @brief Clears the mime icons mapping cache. */ EAPI void efreet_mime_type_cache_clear(void); /** - * @brief Flush mime icons mapping cache + * @brief Flushes the mime icons mapping cache. * - * Flush timeout is defined at compile time by - * EFREET_MIME_ICONS_FLUSH_TIMEOUT + * @remarks Flush timeout is defined at compile time by + * EFREET_MIME_ICONS_FLUSH_TIMEOUT. */ EAPI void efreet_mime_type_cache_flush(void); diff --git a/src/lib/efreet/Efreet_Trash.h b/src/lib/efreet/Efreet_Trash.h index 64af9ea74c..5cda3ab368 100644 --- a/src/lib/efreet/Efreet_Trash.h +++ b/src/lib/efreet/Efreet_Trash.h @@ -6,7 +6,7 @@ #endif #ifdef _WIN32 -# ifdef EFL_EFREET_BUILD +# ifdef EFL_EFREET_TRASH_BUILD # ifdef DLL_EXPORT # define EAPI __declspec(dllexport) # else @@ -33,63 +33,76 @@ extern "C" { /** * @file Efreet_Trash.h + * * @brief Contains the methods used to support the FDO trash specification. - * @addtogroup Efreet_Trash Efreet_Trash: The XDG Trash Specification - * Efreet_Trash.h provides all of the necessary headers and includes to + * + * @internal + * @defgroup Efreet_Trash_Group Efreet_Trash: The XDG Trash Specification + * @ingroup Efreet_Group + * + * Efreet_Trash.h provides all the necessary headers and includes to * work with Efreet_Trash. * - * @ingroup Efreet * @{ */ /** - * @return @c 1 on success or @c 0 on failure. - * @brief Initializes the efreet trash system + * @brief Initializes the efreet trash system. + * + * @return @c 1 on success, otherwise @c 0 on failure */ EAPI int efreet_trash_init(void); /** - * @return No value. - * @brief Cleans up the efreet trash system + * @brief Cleans up the efreet trash system. + * + * @return No value */ EAPI int efreet_trash_shutdown(void); /** - * @return The XDG Trash local directory or @c NULL on errors. - * Return value must be freed with eina_stringshare_del. - * @brief Retrieves the XDG Trash local directory + * @brief Gets the XDG Trash local directory. + * + * @remarks The return value must be freed using eina_stringshare_del. + * + * @return The XDG Trash local directory, otherwise @c NULL on errors */ EAPI const char *efreet_trash_dir_get(const char *for_file); /** - * @param uri The local uri to move in the trash - * @param force_delete If you set this to @c 1 than files on different filesystems - * will be deleted permanently - * @return @c 1 on success, @c 0 on failure or @c -1 in case the uri is not on - * the same filesystem and force_delete is not set. - * @brief This function try to move the given uri to the trash. Files on - * different filesystem can't be moved to trash. If force_delete - * is @c 0 than non-local files will be ignored and @c -1 is returned, if you set - * force_delete to @c 1 non-local files will be deleted without asking. + * @brief Tries to move the given URI to the trash. + * + * @remarks Files on a different filesystem can't be moved to trash. If force_delete + * is @c 0 then non-local files are ignored and @c -1 is returned, if you set + * @a force_delete to @c 1 non-local files are deleted without asking. + * + * @param[in] uri The local URI to move to the trash + * @param[in] force_delete If @c 1 then files on a different filesystem are deleted permanently + * + * @return @c 1 on success, otherwise @c 0 on failure or @c -1 if the uri is not on + * the same filesystem and force_delete is not set */ EAPI int efreet_trash_delete_uri(Efreet_Uri *uri, int force_delete); /** - * @return A list of strings with filename (remember to free the list - * when you don't need anymore). - * @brief List all the files and directory currently inside the trash. + * @brief Lists all the files and directories currently inside the trash. + * + * @return A list of strings with a filename (remember to free the list + * when you don't need it anymore) */ EAPI Eina_List *efreet_trash_ls(void); /** - * @return @c 1 if the trash is empty or @c 0 if some file are in. - * @brief Check if the trash is currently empty + * @brief Checks whether the trash is currently empty. + * + * @return @c 1 if the trash is empty, otherwise @c 0 if some files are present in it */ EAPI int efreet_trash_is_empty(void); /** - * @return @c 1 on success or @c 0 on failure. - * @brief Delete all the files inside the trash. + * @brief Deletes all the files inside the trash. + * + * @return @c 1 on success, otherwise @c 0 on failure */ EAPI int efreet_trash_empty_trash(void); diff --git a/src/lib/efreet/efreet_base.h b/src/lib/efreet/efreet_base.h index ca011d95a3..46351bc57c 100644 --- a/src/lib/efreet/efreet_base.h +++ b/src/lib/efreet/efreet_base.h @@ -4,12 +4,11 @@ * @file efreet_base.h * @brief Contains the methods used to support the FDO base directory * specification. - * @addtogroup Efreet_Base Efreet_Base: The XDG Base Directory Specification - * functions - * @ingroup Efreet * - * @see http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html - * @see http://0pointer.de/blog/projects/tmp.html + * @internal + * @defgroup Efreet_Base_Group Efreet_Base: The XDG Base Directory Specification + * functions + * @ingroup Efreet_Group * * @{ */ @@ -18,9 +17,6 @@ /** * @return Returns the XDG Data Home directory * @brief Retrieves the XDG Data Home directory - * - * This is where user-specific data files should be written - * ($XDG_DATA_HOME or $HOME/.local/share). */ EAPI const char *efreet_data_home_get(void); @@ -28,9 +24,6 @@ EAPI const char *efreet_data_home_get(void); * @return Returns the Eina_List of preference ordered extra data directories * @brief Returns the Eina_List of preference ordered extra data directories * - * Ordered base directories relative to which data files should be - * searched ($XDG_DATA_DIRS or /usr/local/share/:/usr/share/) - * * @note The returned list is static inside Efreet. If you add/remove from the * list then the next call to efreet_data_dirs_get() will return your * modified values. DO NOT free this list. @@ -41,151 +34,21 @@ EAPI Eina_List *efreet_data_dirs_get(void); /** * @return Returns the XDG Config Home directory * @brief Retrieves the XDG Config Home directory - * - * This is where user-specific configuration files should be - * written ($XDG_CONFIG_HOME or $HOME/.config). */ EAPI const char *efreet_config_home_get(void); /** * @return Returns the XDG Desktop directory * @brief Retrieves the XDG Desktop directory - * - * This is where user-specific desktop files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * * @since 1.3 */ EAPI const char *efreet_desktop_dir_get(void); /** - * @return Returns the XDG Download directory - * @brief Retrieves the XDG Download directory - * - * This is where user-specific download files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * It's meant for large download or in-progress downloads, it's - * private for the user but may be shared among different - * machines. It's not automatically cleaned up. - * - * @see efreet_cache_home_get() - * @see efreet_runtime_dir_get() - * @see http://0pointer.de/blog/projects/tmp.html - * - * @since 1.8 - */ -EAPI const char *efreet_download_dir_get(void); - -/** - * @return Returns the XDG Templates directory - * @brief Retrieves the XDG Templates directory - * - * This is where user-specific template files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * @see efreet_documents_dir_get() - * @see efreet_music_dir_get() - * @see efreet_pictures_dir_get() - * @see efreet_videos_dir_get() - * - * @since 1.8 - */ -EAPI const char *efreet_templates_dir_get(void); - -/** - * @return Returns the XDG Public Share directory - * @brief Retrieves the XDG Public Share directory - * - * This is where user-specific public shareable files should be - * located. It's localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * Usually local file servers should look here (Apache, Samba, FTP). - * - * @since 1.8 - */ -EAPI const char *efreet_public_share_dir_get(void); - -/** - * @return Returns the XDG Documents directory - * @brief Retrieves the XDG Documents directory - * - * This is where user-specific documents files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * @see efreet_templates_dir_get() - * @see efreet_music_dir_get() - * @see efreet_pictures_dir_get() - * @see efreet_videos_dir_get() - * - * @since 1.8 - */ -EAPI const char *efreet_documents_dir_get(void); - -/** - * @return Returns the XDG Music directory - * @brief Retrieves the XDG Music directory - * - * This is where user-specific music files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * @see efreet_templates_dir_get() - * @see efreet_download_dir_get() - * @see efreet_pictures_dir_get() - * @see efreet_videos_dir_get() - * - * @since 1.8 - */ -EAPI const char *efreet_music_dir_get(void); - -/** - * @return Returns the XDG Pictures directory - * @brief Retrieves the XDG Pictures directory - * - * This is where user-specific pictures files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * @see efreet_templates_dir_get() - * @see efreet_documents_dir_get() - * @see efreet_music_dir_get() - * @see efreet_videos_dir_get() - * - * @since 1.8 - */ -EAPI const char *efreet_pictures_dir_get(void); - -/** - * @return Returns the XDG Videos directory - * @brief Retrieves the XDG Videos directory - * - * This is where user-specific video files should be located. It's - * localized (translated) to current user locale - * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs). - * - * @see efreet_templates_dir_get() - * @see efreet_documents_dir_get() - * @see efreet_music_dir_get() - * @see efreet_pictures_dir_get() - * - * @since 1.8 - */ -EAPI const char *efreet_videos_dir_get(void); - -/** * @return Returns the Eina_List of preference ordered extra config directories * @brief Returns the Eina_List of preference ordered extra config * directories * - * Ordered base directories relative to which configuration files - * should be searched ($XDG_CONFIG_DIRS or /etc/xdg) - * * @note The returned list is static inside Efreet. If you add/remove from the * list then the next call to efreet_config_dirs_get() will return your * modified values. DO NOT free this list. @@ -196,65 +59,10 @@ EAPI Eina_List *efreet_config_dirs_get(void); /** * @return Returns the XDG Cache Home directory * @brief Retrieves the XDG Cache Home directory - * - * This is the base directory relative to which user specific - * non-essential data files should be stored ($XDG_CACHE_HOME or - * $HOME/.cache). - * - * @see efreet_runtime_dir_get() - * @see efreet_download_dir_get() - * @see efreet_config_home_get() */ EAPI const char *efreet_cache_home_get(void); /** - * @return Returns the XDG User Runtime directory. - * @brief Retrieves the XDG User Runtime directory. - * - * This is the base directory relative to which user-specific - * non-essential runtime files and other file objects (such as - * sockets, named pipes, ...) should be stored. The directory @b must - * be owned by the user, and he @b must be the only one having read - * and write access to it. Its Unix access mode @b must be 0700. - * - * The lifetime of this directory @b must be bound to the user being - * logged in. It @b must be created when the user first logs in and if - * the user fully logs out the directory @b must be removed. If the - * user logs in more than once he should get pointed to the same - * directory, and it is mandatory that the directory continues to - * exist from his first login to his last logout on the system, and - * not removed in between. Files in the directory @b must not survive - * reboot or a full logout/login cycle. - * - * The directory @b must be on a local file system and not shared with - * any other system. The directory @b must by fully-featured by the - * standards of the operating system. More specifically, on Unix-like - * operating systems AF_UNIX sockets, symbolic links, hard links, - * proper permissions, file locking, sparse files, memory mapping, - * file change notifications, a reliable hard link count must be - * supported, and no restrictions on the file name character set - * should be imposed. Files in this directory @b may be subjected to - * periodic clean-up. To ensure that your files are not removed, they - * should have their access time timestamp modified at least once - * every 6 hours of monotonic time or the 'sticky' bit should be set - * on the file. - * - * If @c NULL applications should fall back to a replacement directory - * with similar capabilities and print a warning message. Applications - * should use this directory for communication and synchronization - * purposes and should not place larger files in it, since it might - * reside in runtime memory and cannot necessarily be swapped out to - * disk. - * - * @note this directory is similar to @c /run and is often created in - * tmpfs (memory-only/RAM filesystem). It is created, managed and - * cleaned automatically by systemd. - * - * @since 1.8 - */ -EAPI const char *efreet_runtime_dir_get(void); - -/** * @return Returns the current hostname * @brief Returns the current hostname or empty string if not found */ @@ -271,7 +79,7 @@ typedef struct _Efreet_Event_Cache_Update Efreet_Event_Cache_Update; */ struct _Efreet_Event_Cache_Update { - int error; + int dummy; }; /** diff --git a/src/lib/efreet/efreet_desktop.h b/src/lib/efreet/efreet_desktop.h index 8f2c30a4e6..fe95124654 100644 --- a/src/lib/efreet/efreet_desktop.h +++ b/src/lib/efreet/efreet_desktop.h @@ -5,9 +5,11 @@ * @file efreet_desktop.h * @brief Contains the structures and methods used to support the * FDO desktop entry specificiation. - * @addtogroup Efreet_Desktop Efreet_Desktop: The FDO Desktop Entry - * Specification functions and structures - * @ingroup Efreet + * + * @internal + * @defgroup Efreet_Desktop_Group Efreet_Desktop: The FDO Desktop Entry + * Specification functions and structures + * @ingroup Efreet_Group * * @{ */ @@ -30,12 +32,6 @@ EAPI extern int EFREET_EVENT_DESKTOP_CACHE_UPDATE; EAPI extern int EFREET_EVENT_DESKTOP_CACHE_BUILD; /** - * Efreet_Desktop_Action - * @since 1.12 - */ -typedef struct _Efreet_Desktop_Action Efreet_Desktop_Action; - -/** * Efreet_Desktop */ typedef struct _Efreet_Desktop Efreet_Desktop; @@ -68,25 +64,11 @@ typedef void (*Efreet_Desktop_Type_Save_Cb) (Efreet_Desktop *desktop, Efreet_Ini typedef void *(*Efreet_Desktop_Type_Free_Cb) (void *data); /** - * Efreet_Desktop_Action - * @brief an action described in a .desktop file - * @since 1.12 - */ -struct _Efreet_Desktop_Action -{ - char *key; /**< Key to identify the action */ - char *name; /**< Specific name of the action */ - char *icon; /**< Icon to display */ - char *exec; /**< Program to execute */ -}; - -/** * Efreet_Desktop * @brief a parsed representation of a .desktop file */ struct _Efreet_Desktop { - /* Desktop Spec 1.0 */ int type; /**< type of desktop file */ int ref; /**< reference count - internal */ @@ -122,19 +104,10 @@ struct _Efreet_Desktop Eina_Hash *x; /**< Keep track of all user extensions, keys that begin with X- */ void *type_data; /**< Type specific data for custom types */ - - /* Desktop Spec 1.1 */ - unsigned char dbus_activatable; /**< Activate application by dbus, not Exec. @since 1.12 */ - Eina_List *actions; /**< List of Efreet_Desktop_Actions, application actions. @since 1.12 */ - Eina_List *implements; /**< Interfaces which is file implements. @since 1.12 */ - Eina_List *keywords; /**< Keywords which describe this entry. @since 1.12 */ }; /** - * @param file The file to get the Efreet_Desktop from - * @return Returns a reference to a cached Efreet_Desktop on success, NULL - * on failure * @brief Gets a reference to an Efreet_Desktop structure representing the * contents of @a file or NULL if @a file is not a valid .desktop file. * @@ -145,27 +118,30 @@ struct _Efreet_Desktop * event, if the application is to keep the reference. When the event fires * the Efreet_Desktop struct should be invalidated and reloaded from a new * cache file. + * + * @param[in] file The file to get the Efreet_Desktop from + * @return Returns a reference to a cached Efreet_Desktop on success, NULL + * on failure */ EAPI Efreet_Desktop *efreet_desktop_get(const char *file); /** - * @param desktop The Efreet_Desktop to ref - * @return Returns the new reference count * @brief Increases reference count on desktop + * + * @param[in] desktop The Efreet_Desktop to ref + * @return Returns the new reference count */ EAPI int efreet_desktop_ref(Efreet_Desktop *desktop); /** + * @brief Creates a new empty Efreet_Desktop structure or NULL on failure + * * @param file The file to create the Efreet_Desktop from * @return Returns a new empty_Efreet_Desktop on success, NULL on failure - * @brief Creates a new empty Efreet_Desktop structure or NULL on failure */ EAPI Efreet_Desktop *efreet_desktop_empty_new(const char *file); /** - * @param file The file to get the Efreet_Desktop from - * @return Returns a reference to a cached Efreet_Desktop on success, NULL - * on failure * @brief Gets a reference to an Efreet_Desktop structure representing the * contents of @a file or NULL if @a file is not a valid .desktop file. * @@ -173,12 +149,14 @@ EAPI Efreet_Desktop *efreet_desktop_empty_new(const char *file); * event, if the application is to keep the reference. When the event fires * the Efreet_Desktop struct should be invalidated and reloaded from a new * cache file. + * + * @param[in] file The file to get the Efreet_Desktop from + * @return Returns a reference to a cached Efreet_Desktop on success, NULL + * on failure */ EAPI Efreet_Desktop *efreet_desktop_new(const char *file); /** - * @param file The file to create the Efreet_Desktop from - * @return Returns a new Efreet_Desktop on success, NULL on failure * @brief Creates a new Efreet_Desktop structure initialized from the * contents of @a file or NULL on failure * @@ -187,13 +165,17 @@ EAPI Efreet_Desktop *efreet_desktop_new(const char *file); * * Data in the structure is allocated with strdup, so use free and strdup to * change values. + * + * @param[in] file The file to create the Efreet_Desktop from + * @return Returns a new Efreet_Desktop on success, NULL on failure */ EAPI Efreet_Desktop *efreet_desktop_uncached_new(const char *file); /** - * @param desktop The Efreet_Desktop to work with - * @return Returns no value * @brief Frees the Efreet_Desktop structure and all of it's data + * + * @param[in] desktop The Efreet_Desktop to work with + * @return Returns no value */ EAPI void efreet_desktop_free(Efreet_Desktop *desktop); @@ -205,59 +187,65 @@ EAPI void efreet_desktop_free(Efreet_Desktop *desktop); /** - * @param desktop The desktop file to save - * @return Returns 1 on success or 0 on failure * @brief Saves any changes made to @a desktop back to the file on the * filesystem + * + * @param[in] desktop The desktop file to save + * @return Returns 1 on success or 0 on failure */ EAPI int efreet_desktop_save(Efreet_Desktop *desktop); /** - * @param desktop The desktop file to save - * @param file The filename to save as - * @return Returns 1 on success or 0 on failure * @brief Saves @a desktop to @a file * * Please use efreet_desktop_uncached_new() on an existing file * before using efreet_desktop_save_as() + * + * @param[in] desktop The desktop file to save + * @param[in] file The filename to save as + * @return Returns 1 on success or 0 on failure */ EAPI int efreet_desktop_save_as(Efreet_Desktop *desktop, const char *file); /** - * @param desktop The desktop file to work with - * @param files The files to be substituted into the exec line - * @param data The data pointer to pass - * @brief Parses the @a desktop exec line and runs the command. + * @brief Parses the @a desktop exec line and returns an Ecore_Exe. + * + * @param[in] desktop The desktop file to work with + * @param[in] files The files to be substituted into the exec line + * @param[in] data The data pointer to pass + * @return Returns the Ecore_Exce for @a desktop */ EAPI void efreet_desktop_exec(Efreet_Desktop *desktop, Eina_List *files, void *data); /** - * @param environment the environment name * @brief sets the global desktop environment name + * + * @param[in] environment the environment name */ EAPI void efreet_desktop_environment_set(const char *environment); /** + * @brief sets the global desktop environment name + * * @return environment the environment name - * @brief gets the global desktop environment name - * (e.g. "Enlightenment" or "Gnome") */ EAPI const char *efreet_desktop_environment_get(void); /** - * @param desktop the desktop entry - * @param files an eina list of file names to execute, as either absolute paths, - * relative paths, or uris - * @param cb_command a callback to call for each prepared command line - * @param cb_prog a callback to get progress for the downloads - * @param data user data passed to the callback - * @return Returns 1 on success or 0 on failure * @brief Get a command to use to execute a desktop entry, and receive progress * updates for downloading of remote URI's passed in. + * + * @param[in] desktop the desktop entry + * @param[in] files an eina list of file names to execute, as either absolute paths, + * relative paths, or uris + * @param[in] cb_command a callback to call for each prepared command line + * @param[in] cb_prog a callback to get progress for the downloads + * @param[in] data user data passed to the callback + * @return Returns 1 on success or 0 on failure */ EAPI void *efreet_desktop_command_progress_get(Efreet_Desktop *desktop, Eina_List *files, @@ -265,13 +253,14 @@ EAPI void *efreet_desktop_command_progress_get(Efreet_Desktop *deskt Efreet_Desktop_Progress_Cb cb_prog, void *data); /** - * @param desktop the desktop entry - * @param files an eina list of file names to execute, as either absolute paths, + * @brief Get a command to use to execute a desktop entry. + * + * @param[in] desktop the desktop entry + * @param[in] files an eina list of file names to execute, as either absolute paths, * relative paths, or uris - * @param func a callback to call for each prepared command line - * @param data user data passed to the callback + * @param[in] func a callback to call for each prepared command line + * @param[in] data user data passed to the callback * @return Returns the return value of @p func on success or NULL on failure - * @brief Get a command to use to execute a desktop entry. */ EAPI void *efreet_desktop_command_get(Efreet_Desktop *desktop, Eina_List *files, @@ -279,37 +268,41 @@ EAPI void *efreet_desktop_command_get(Efreet_Desktop *desktop, void *data); /** - * @param desktop the desktop entry - * @param files an eina list of local files, as absolute paths, local paths, or file// uris (or NULL to get exec string with no files appended) - * @return Returns an eina list of exec strings * @brief Get the command to use to execute a desktop entry * * The returned list and each of its elements must be freed. + * + * @param[in] desktop the desktop entry + * @param[in] files an eina list of local files, as absolute paths, local paths, or file// uris (or NULL to get exec string with no files appended) + * @return Returns an eina list of exec strings */ EAPI Eina_List * efreet_desktop_command_local_get(Efreet_Desktop *desktop, Eina_List *files); /** - * @param desktop The desktop to work with - * @return Returns the number of categories assigned to this desktop * @brief Retrieves the number of categories the given @a desktop belongs * too + * + * @param[in] desktop The desktop to work with + * @return Returns the number of categories assigned to this desktop */ EAPI unsigned int efreet_desktop_category_count_get(Efreet_Desktop *desktop); /** - * @param desktop the desktop - * @param category the category name * @brief add a category to a desktop + * + * @param[in] desktop the desktop + * @param[in] category the category name */ EAPI void efreet_desktop_category_add(Efreet_Desktop *desktop, const char *category); /** - * @param desktop the desktop - * @param category the category name * @brief removes a category from a desktop + * + * @param[in] desktop the desktop + * @param[in] category the category name * @return 1 if the desktop had his category listed, 0 otherwise */ EAPI int efreet_desktop_category_del(Efreet_Desktop *desktop, @@ -317,12 +310,13 @@ EAPI int efreet_desktop_category_del(Efreet_Desktop *desktop, /** - * @param type The type to add to the list of matching types - * @param parse_func a function to parse out custom fields - * @param save_func a function to save data returned from @a parse_func - * @param free_func a function to free data returned from @a parse_func - * @return Returns the id of the new type * @brief Adds the given type to the list of types in the system + * + * @param[in] type The type to add to the list of matching types + * @param[in] parse_func a function to parse out custom fields + * @param[in] save_func a function to save data returned from @a parse_func + * @param[in] free_func a function to free data returned from @a parse_func + * @return Returns the id of the new type */ EAPI int efreet_desktop_type_add(const char *type, Efreet_Desktop_Type_Parse_Cb parse_func, @@ -331,8 +325,9 @@ EAPI int efreet_desktop_type_add(const char *type, /** * @brief Add an alias for an existing desktop type. - * @param from_type the type to alias (e.g. EFREE_DESKTOP_TYPE_APPLICATION) - * @param alias the alias + * + * @param[in] from_type the type to alias (e.g. EFREE_DESKTOP_TYPE_APPLICATION) + * @param[in] alias the alias * @return the new type id, or -1 if @p from_type was not valid * * This allows applications to add non-standard types that behave exactly as standard types. @@ -342,32 +337,36 @@ EAPI int efreet_desktop_type_alias (int from_type, /** * @brief get type specific data for custom desktop types - * @param desktop the desktop + * + * @param[in] desktop the desktop * @return type specific data, or NULL if there is none */ EAPI void *efreet_desktop_type_data_get(Efreet_Desktop *desktop); /** - * @param string the raw string list - * @return an Eina_List of ecore string's * @brief Parse ';' separate list of strings according to the desktop spec + * + * @param[in] string the raw string list + * @return an Eina_List of ecore string's */ EAPI Eina_List *efreet_desktop_string_list_parse(const char *string); /** - * @param list Eina_List with strings - * @return a raw string list * @brief Create a ';' separate list of strings according to the desktop spec + * + * @param[in] list Eina_List with strings + * @return a raw string list */ EAPI char *efreet_desktop_string_list_join(Eina_List *list); /** * @brief Set the value for a X- field (Non spec) in the structure - * @param desktop the desktop - * @param key the key name to set - * @param data the value to set + * + * @param[in] desktop the desktop + * @param[in] key the key name to set + * @param[in] data the value to set * @return EINA_TRUE on success * * The key has to start with "X-" @@ -376,16 +375,18 @@ EAPI Eina_Bool efreet_desktop_x_field_set(Efreet_Desktop *desktop, const /** * @brief Get the value for a X- field (Non spec) in the structure - * @param desktop the desktop - * @param key the key + * + * @param[in] desktop the desktop + * @param[in] key the key * @return The value referenced by the key, or NULL if the key does not exist */ EAPI const char * efreet_desktop_x_field_get(Efreet_Desktop *desktop, const char *key); /** * @brief Delete the key and value for a X- field (Non spec) in the structure - * @param desktop the desktop - * @param key the key + * + * @param[in] desktop the desktop + * @param[in] key the key * @return EINA_TRUE if the key existed */ EAPI Eina_Bool efreet_desktop_x_field_del(Efreet_Desktop *desktop, const char *key); diff --git a/src/lib/efreet/efreet_icon.h b/src/lib/efreet/efreet_icon.h index 0495622d9b..89a657cdd6 100644 --- a/src/lib/efreet/efreet_icon.h +++ b/src/lib/efreet/efreet_icon.h @@ -5,10 +5,12 @@ * @file efreet_icon.h * @brief Contains the structures and methods used to support the FDO icon * theme specificiation. - * @addtogroup Efreet_Icon Efreet_Icon: The FDO Icon Theme - * Specification functions and structures * - * @ingroup Efreet + * @internal + * @defgroup Efreet_Icon_Group Efreet_Icon: The FDO Icon Theme + * Specification functions and structures + * @ingroup Efreet_Group + * * @{ */ @@ -141,77 +143,86 @@ struct Efreet_Icon_Point }; /** - * @return Returns the user icon directory * @brief Returns the user icon directory + * + * @return Returns the user icon directory */ EAPI const char *efreet_icon_user_dir_get(void); /** - * @return Returns the deprecated user icon directory * @brief Returns the deprecated user icon directory + * + * @return Returns the deprecated user icon directory */ EAPI const char *efreet_icon_deprecated_user_dir_get(void); /** - * @param ext The extension to add to the list of checked extensions - * @return Returns no value. * @brief Adds the given extension to the list of possible icon extensions + * + * @param[in] ext The extension to add to the list of checked extensions + * @return Returns no value. */ EAPI void efreet_icon_extension_add(const char *ext); /** - * @return Returns a list of strings that are paths to other icon directories * @brief Gets the list of all extra directories to look for icons. These * directories are used to look for icons after looking in the user icon dir * and before looking in standard system directories. The order of search is * from first to last directory in this list. the strings in the list should * be created with eina_stringshare_add(). + * + * @return Returns a list of strings that are paths to other icon directories */ EAPI Eina_List **efreet_icon_extra_list_get(void); /** - * @return Returns a list of strings that are icon extensions to look for * @brief Gets the list of all icon extensions to look for + * + * @return Returns a list of strings that are icon extensions to look for */ EAPI Eina_List *efreet_icon_extensions_list_get(void); /** - * @return Returns a list of Efreet_Icon structs for all the non-hidden icon - * themes * @brief Retrieves all of the non-hidden icon themes available on the system. * The returned list must be freed. Do not free the list data. + * + * @return Returns a list of Efreet_Icon structs for all the non-hidden icon + * themes */ EAPI Eina_List *efreet_icon_theme_list_get(void); /** - * @param theme_name The theme to look for + * @brief Tries to get the icon theme structure for the given theme name + * + * @param[in] theme_name The theme to look for * @return Returns the icon theme related to the given theme name or NULL if * none exists. - * @brief Tries to get the icon theme structure for the given theme name */ EAPI Efreet_Icon_Theme *efreet_icon_theme_find(const char *theme_name); /** - * @param theme_name The icon theme to look for - * @param icon The icon to look for - * @param size The icon size to look for + * @brief Retrieves all of the information about the given icon. + * + * @param[in] theme_name The icon theme to look for + * @param[in] icon The icon to look for + * @param[in] size The icon size to look for * @return Returns the Efreet_Icon structure representing this icon or NULL * if the icon is not found - * @brief Retrieves all of the information about the given icon. */ EAPI Efreet_Icon *efreet_icon_find(const char *theme_name, const char *icon, unsigned int size); /** - * @param theme_name The icon theme to look for - * @param icons List of icons to look for - * @param size; The icon size to look for - * @return Returns the path representing first found icon or - * NULL if none of the icons are found * @brief Retrieves all of the information about the first found icon in * the list. + * + * @param[in] theme_name The icon theme to look for + * @param[in] icons List of icons to look for + * @param[in] size; The icon size to look for + * @return Returns the path representing first found icon or + * NULL if none of the icons are found * @note This function will search the given theme for all icons before falling * back. This is useful when searching for mimetype icons. * @@ -223,12 +234,13 @@ EAPI const char *efreet_icon_list_find(const char *theme_name, unsigned int size); /** - * @param theme_name The icon theme to look for - * @param icon The icon to look for - * @param size; The icon size to look for - * @return Returns the path to the given icon or NULL if none found * @brief Retrives the path to the given icon. * + * @param[in] theme_name The icon theme to look for + * @param[in] icon The icon to look for + * @param[in] size; The icon size to look for + * @return Returns the path to the given icon or NULL if none found + * * There is no guarantee for how long the pointer to the path will be valid. * If the pointer is to be kept, the user must create a copy of the path. */ @@ -237,9 +249,10 @@ EAPI const char *efreet_icon_path_find(const char *theme_name, unsigned int size); /** - * @param icon The Efreet_Icon to cleanup - * @return Returns no value. * @brief Free's the given icon and all its internal data. + * + * @param[in] icon The Efreet_Icon to cleanup + * @return Returns no value. */ EAPI void efreet_icon_free(Efreet_Icon *icon); diff --git a/src/lib/efreet/efreet_ini.h b/src/lib/efreet/efreet_ini.h index 2dec08aece..2c242b3745 100644 --- a/src/lib/efreet/efreet_ini.h +++ b/src/lib/efreet/efreet_ini.h @@ -5,8 +5,9 @@ * @internal * @file efreet_ini.h * @brief A simple and fast INI parser - * @addtogroup Efreet_Ini Efreet_Ini: An INI parser - * @ingroup Efreet + * + * @defgroup Efreet_Ini Efreet_Ini: An INI parser + * @ingroup Efreet_Group * * @{ */ @@ -28,150 +29,166 @@ struct Efreet_Ini /** - * @param file The file to parse - * @return Returns a new Efreet_Ini structure initialized with the contents - * of @a file, or NULL on memory allocation failure * @brief Creates and initializes a new Ini structure with the contents of * @a file, or NULL on failure + * + * @param[in] file The file to parse + * @return Returns a new Efreet_Ini structure initialized with the contents + * of @a file, or NULL on memory allocation failure */ EAPI Efreet_Ini *efreet_ini_new(const char *file); /** - * @param ini The Efreet_Ini to work with - * @return Returns no value * @brief Frees the given Efree_Ini structure. + * + * @param[in] ini The Efreet_Ini to work with + * @return Returns no value */ EAPI void efreet_ini_free(Efreet_Ini *ini); /** - * @param ini The Efreet_Ini to work with - * @param file The file to load - * @return Returns no value * @brief Saves the given Efree_Ini structure. + * + * @param[in] ini The Efreet_Ini to work with + * @param[in] path The file path to load + * @return Returns no value */ EAPI int efreet_ini_save(Efreet_Ini *ini, const char *path); /** - * @param ini The Efreet_Ini to work with - * @param section The section of the ini file we want to get values from - * @return Returns 1 if the section exists, otherwise 0 * @brief Sets the current working section of the ini file to @a section + * + * @param[in] ini The Efreet_Ini to work with + * @param[in] section The section of the ini file we want to get values from + * @return Returns 1 if the section exists, otherwise 0 */ EAPI int efreet_ini_section_set(Efreet_Ini *ini, const char *section); /** - * @param ini The Efreet_Ini to work with - * @param section The section of the ini file we want to add - * @return Returns no value * @brief Adds a new working section of the ini file to @a section + * + * @param[in] ini The Efreet_Ini to work with + * @param[in] section The section of the ini file we want to add + * @return Returns no value */ EAPI void efreet_ini_section_add(Efreet_Ini *ini, const char *section); /** - * @param ini The Efree_Ini to work with - * @param key The key to lookup + * @brief Retrieves the value for the given key or NULL if none found. + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to lookup * @return Returns the string associated with the given key or NULL if not * found. - * @brief Retrieves the value for the given key or NULL if none found. */ EAPI const char *efreet_ini_string_get(Efreet_Ini *ini, const char *key); /** - * @param ini The Efree_Ini to work with - * @param key The key to use - * @param value The value to set - * @return Returns no value * @brief Sets the value for the given key + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to use + * @param[in] value The value to set + * @return Returns no value */ EAPI void efreet_ini_string_set(Efreet_Ini *ini, const char *key, const char *value); /** - * @param ini The ini struct to work with - * @param key The key to search for + * @brief Retrieves the utf8 encoded string associated with @a key in the current locale or NULL if none found + * + * @param[in] ini The ini struct to work with + * @param[in] key The key to search for * @return Returns the utf8 encoded string associated with @a key, or NULL * if none found - * @brief Retrieves the utf8 encoded string associated with @a key in the current locale or NULL if none found */ EAPI const char *efreet_ini_localestring_get(Efreet_Ini *ini, const char *key); /** - * @param ini The ini struct to work with - * @param key The key to use - * @param value The value to set - * @return Returns no value * @brief Sets the value for the given key + * + * @param[in] ini The ini struct to work with + * @param[in] key The key to use + * @param[in] value The value to set + * @return Returns no value */ EAPI void efreet_ini_localestring_set(Efreet_Ini *ini, const char *key, const char *value); /** - * @param ini The ini struct to work with - * @param key The key to search for - * @return Returns 1 if the boolean is true, 0 otherwise * @brief Retrieves the boolean value at key @a key from the ini @a ini + * + * @param[in] ini The ini struct to work with + * @param[in] key The key to search for + * @return Returns 1 if the boolean is true, 0 otherwise */ EAPI unsigned int efreet_ini_boolean_get(Efreet_Ini *ini, const char *key); /** - * @param ini The ini struct to work with - * @param key The key to use - * @param value The value to set - * @return Returns no value * @brief Sets the value for the given key + * + * @param[in] ini The ini struct to work with + * @param[in] key The key to use + * @param[in] value The value to set + * @return Returns no value */ EAPI void efreet_ini_boolean_set(Efreet_Ini *ini, const char *key, unsigned int value); /** - * @param ini The Efree_Ini to work with - * @param key The key to lookup + * @brief Retrieves the value for the given key or -1 if none found. + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to lookup * @return Returns the integer associated with the given key or -1 if not * found. - * @brief Retrieves the value for the given key or -1 if none found. */ EAPI int efreet_ini_int_get(Efreet_Ini *ini, const char *key); /** - * @param ini The Efree_Ini to work with - * @param key The key to use - * @param value The value to set - * @return Returns no value * @brief Sets the value for the given key + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to use + * @param[in] value The value to set + * @return Returns no value */ EAPI void efreet_ini_int_set(Efreet_Ini *ini, const char *key, int value); /** - * @param ini The Efree_Ini to work with - * @param key The key to lookup + * @brief Retrieves the value for the given key or -1 if none found. + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to lookup * @return Returns the double associated with the given key or -1 if not * found. - * @brief Retrieves the value for the given key or -1 if none found. */ EAPI double efreet_ini_double_get(Efreet_Ini *ini, const char *key); /** - * @param ini The Efree_Ini to work with - * @param key The key to use - * @param value The value to set - * @return Returns no value * @brief Sets the value for the given key + * + * @param[in] ini The Efree_Ini to work with + * @param[in] key The key to use + * @param[in] value The value to set + * @return Returns no value */ EAPI void efreet_ini_double_set(Efreet_Ini *ini, const char *key, double value); /** - * @param ini The ini struct to work with - * @param key The key to remove - * @return Returns no value * @brief Remove the given key from the ini struct + * + * @param[in] ini The ini struct to work with + * @param[in] key The key to remove + * @return Returns no value */ EAPI void efreet_ini_key_unset(Efreet_Ini *ini, const char *key); diff --git a/src/lib/efreet/efreet_menu.h b/src/lib/efreet/efreet_menu.h index b7f123ac82..de852199ae 100644 --- a/src/lib/efreet/efreet_menu.h +++ b/src/lib/efreet/efreet_menu.h @@ -5,9 +5,11 @@ * @file efreet_menu.h * @brief Contains the structures and methods to support the Desktop * Menu Specification. - * @addtogroup Efreet_Menu Efreet_Menu: The FDO Desktop Menu Specification - * functions and structures - * @ingroup Efreet + * + * @internal + * @defgroup Efreet_Menu_Group Efreet_Menu: The FDO Desktop Menu Specification + * functions and structures + * @ingroup Efreet_Group * * @{ */ @@ -42,34 +44,30 @@ struct Efreet_Menu Efreet_Desktop *desktop; /**< The desktop we refer too */ Eina_List *entries; /**< The menu items */ - int references; /**< refcount (keeps menu util ref is at 0) @since 1.11 */ }; -/** - * A callback used with efreet_menu_async_get() and efreet_menu_async_parse() - * - * @since 1.8 - */ -typedef void (*Efreet_Menu_Cb) (void *data, Efreet_Menu *menu); /** - * @return Returns no value * @brief Initialize legacy kde support. This function blocks while * the kde-config script is run. + * + * @return Returns no value */ EAPI int efreet_menu_kde_legacy_init(void); /** - * @param name The internal name of the menu + * @brief Creates a new menu + * + * @param[in] name The internal name of the menu * @return Returns the Efreet_Menu on success or * NULL on failure - * @brief Creates a new menu */ EAPI Efreet_Menu *efreet_menu_new(const char *name); /** * @brief Override which file is used for menu creation - * @param file The file to use for menu creation + * + * @param[in] file The file to use for menu creation * * This file is only used if it exists, else the standard files will be used * for the menu. @@ -77,103 +75,72 @@ EAPI Efreet_Menu *efreet_menu_new(const char *name); EAPI void efreet_menu_file_set(const char *file); /** - * Creates the Efreet_Menu representation of the default menu or - * NULL if none found and returns it in the callback. - * @param func function to call when menu is created - * @param data user data to return in callback + * @brief Creates the default menu representation * - * @since 1.8 - */ -EAPI void efreet_menu_async_get(Efreet_Menu_Cb func, const void *data); - -/** - * @return Returns the Efreet_Menu representation of the default menu or + * @return Returns the Efreet_Menu_Internal representation of the default menu or * NULL if none found - * @brief Creates the default menu representation */ EAPI Efreet_Menu *efreet_menu_get(void); /** - * Parses the given .menu file and creates the menu representation, and - * returns it in the callback - * @param path The path of the menu to load - * @param func function to call when menu is created - * @param data user data to return in callback + * @brief Parses the given .menu file and creates the menu representation * - * @since 1.8 - */ -EAPI void efreet_menu_async_parse(const char *path, Efreet_Menu_Cb func, const void *data); - -/** - * @param path The path of the menu to load - * @return Returns the Efreet_Menu representation on success or NULL on + * @param[in] path The path of the menu to load + * @return Returns the Efreet_Menu_Internal representation on success or NULL on * failure - * @brief Parses the given .menu file and creates the menu representation */ EAPI Efreet_Menu *efreet_menu_parse(const char *path); /** - * @param menu The menu to work with - * @param path The path where the menu should be saved - * @return Returns 1 on success, 0 on failure * @brief Saves the menu to file + * + * @param[in] menu The menu to work with + * @param[in] path The path where the menu should be saved + * @return Returns 1 on success, 0 on failure */ EAPI int efreet_menu_save(Efreet_Menu *menu, const char *path); /** - * @param menu The Efreet_Menu to free + * @brief Frees the given structure + * + * @param[in] menu The Efreet_Menu to free * @return Returns no value - * @brief Frees the given structure (if refcount at 1 at the time of this call) */ EAPI void efreet_menu_free(Efreet_Menu *menu); -/** - * @param menu The Efreet_Menu to reference - * @return Returns no value - * @brief Incriments refcount for the menu - * @since 1.11 - */ -EAPI void efreet_menu_ref(Efreet_Menu *menu); - /** - * @param menu The Efreet_Menu to unreference - * @return Returns no value - * @brief Decrements refcount for the menu, and on 0 frees - * @since 1.11 - */ -EAPI void efreet_menu_unref(Efreet_Menu *menu); - - -/** - * @param menu The menu to work with - * @param desktop The desktop to insert - * @param pos The position to place the new desktop - * @return Returns 1 on success, 0 on failure * @brief Insert a desktop element in a menu structure. Only accepts desktop files * in default directories. + * + * @param[in] menu The menu to work with + * @param[in] desktop The desktop to insert + * @param[in] pos The position to place the new desktop + * @return Returns 1 on success, 0 on failure */ EAPI int efreet_menu_desktop_insert(Efreet_Menu *menu, Efreet_Desktop *desktop, int pos); /** - * @param menu The menu to work with - * @param desktop The desktop to remove - * @return Returns 1 on success, 0 on failure * @brief Remove a desktop element in a menu structure. Only accepts desktop files * in default directories. + * + * @param[in] menu The menu to work with + * @param[in] desktop The desktop to remove + * @return Returns 1 on success, 0 on failure */ EAPI int efreet_menu_desktop_remove(Efreet_Menu *menu, Efreet_Desktop *desktop); /** - * @param menu The menu to work with - * @param menu The menu to work with - * @param indent The indent level to print the menu at - * @return Returns no value * @brief Dumps the contents of the menu to the command line + * + * @param[in] menu The menu to work with + * @param[in] menu The menu to work with + * @param[in] indent The indent level to print the menu at + * @return Returns no value */ EAPI void efreet_menu_dump(Efreet_Menu *menu, const char *indent); diff --git a/src/lib/efreet/efreet_uri.h b/src/lib/efreet/efreet_uri.h index 32b1f51ad2..4b59c37ea7 100644 --- a/src/lib/efreet/efreet_uri.h +++ b/src/lib/efreet/efreet_uri.h @@ -4,8 +4,11 @@ /** * @file efreet_uri.h * @brief Contains the methods used to support the FDO URI specification. - * @addtogroup Efreet_Uri Efreet_Uri: The FDO URI Specification functions - * @ingroup Efreet + * + * @internal + * @defgroup Efreet_Uri_Group Efreet_Uri: The FDO URI Specification functions + * @ingroup Efreet_Group + * * @{ */ @@ -30,28 +33,31 @@ struct Efreet_Uri /** - * @param uri Create an URI string from an Efreet_Uri struct - * @return The string rapresentation of uri (ex: 'file:///home/my%20name') * @brief Get the string rapresentation of the given uri struct escaping * illegal caracters. Remember to free the string with eina_stringshare_del() * when you don't need it anymore. + * + * @param[in] uri Create an URI string from an Efreet_Uri struct + * @return The string rapresentation of uri (ex: 'file:///home/my%20name') * @note The resulting string will contain the protocol and the path but not * the hostname, as many apps doesn't handle it. */ EAPI const char *efreet_uri_encode(Efreet_Uri *uri); /** - * @param val a valid uri string to parse - * @return Return The corresponding Efreet_Uri structure. Or NULL on errors. * @brief Read a single uri and return an Efreet_Uri struct. If there's no * hostname in the uri then the hostname parameter will be NULL. All the uri * escaped chars will be converted to normal. + * + * @param[in] val a valid uri string to parse + * @return Return The corresponding Efreet_Uri structure. Or NULL on errors. */ EAPI Efreet_Uri *efreet_uri_decode(const char *val); /** - * @param uri The uri to free * @brief Free the given uri structure. + * + * @param[in] uri The uri to free */ EAPI void efreet_uri_free(Efreet_Uri *uri); diff --git a/src/lib/efreet/efreet_utils.h b/src/lib/efreet/efreet_utils.h index aef0511eea..5af80554bd 100644 --- a/src/lib/efreet/efreet_utils.h +++ b/src/lib/efreet/efreet_utils.h @@ -5,8 +5,10 @@ * @file efreet_utils.h * @brief Contains utility functions to ease usage of Efreet. * FDO desktop entry specificiation. - * @addtogroup Efreet_Utils Efreet utilities for FDO - * @ingroup Efreet + * + * @internal + * @defgroup Efreet_Utils_Group Efreet utilities for FDO + * @ingroup Efreet_Group * * @{ */ @@ -16,7 +18,7 @@ * Returns the fdo file id for a given path. If the file isn't inside * a default fdo path it will return NULL. * - * @param path The path to find the file id for + * @param[in] path The path to find the file id for * * @return File id for path or NULL */ @@ -28,7 +30,7 @@ EAPI const char *efreet_util_path_to_file_id(const char *path); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param mime the mime type + * @param[in] mime the mime type * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_mime_list(const char *mime); @@ -39,8 +41,8 @@ EAPI Eina_List *efreet_util_desktop_mime_list(const char *mime); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param wmname the wm name - * @param wmclass the wm class + * @param[in] wmname the wm name + * @param[in] wmclass the wm class * @return a list of desktops */ EAPI Efreet_Desktop *efreet_util_desktop_wm_class_find(const char *wmname, const char *wmclass); @@ -50,7 +52,7 @@ EAPI Efreet_Desktop *efreet_util_desktop_wm_class_find(const char *wmname, const * * return value must be freed by efreet_desktop_free * - * @param file_id the file id + * @param[in] file_id the file id * @return a desktop */ EAPI Efreet_Desktop *efreet_util_desktop_file_id_find(const char *file_id); @@ -60,7 +62,7 @@ EAPI Efreet_Desktop *efreet_util_desktop_file_id_find(const char *file_id); * * return value must be freed by efreet_desktop_free * - * @param exec the exec name + * @param[in] exec the exec name * @return a desktop */ EAPI Efreet_Desktop *efreet_util_desktop_exec_find(const char *exec); @@ -70,7 +72,7 @@ EAPI Efreet_Desktop *efreet_util_desktop_exec_find(const char *exec); * * return value must be freed by efreet_desktop_free * - * @param name the name + * @param[in] name the name * @return a desktop */ EAPI Efreet_Desktop *efreet_util_desktop_name_find(const char *name); @@ -80,7 +82,7 @@ EAPI Efreet_Desktop *efreet_util_desktop_name_find(const char *name); * * return value must be freed by efreet_desktop_free * - * @param generic_name the generic name + * @param[in] generic_name the generic name * @return a desktop */ EAPI Efreet_Desktop *efreet_util_desktop_generic_name_find(const char *generic_name); @@ -91,7 +93,7 @@ EAPI Efreet_Desktop *efreet_util_desktop_generic_name_find(const char *generic_n * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param glob the pattern to match + * @param[in] glob the pattern to match * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_name_glob_list(const char *glob); @@ -101,7 +103,7 @@ EAPI Eina_List *efreet_util_desktop_name_glob_list(const char *glob); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param glob the pattern to match + * @param[in] glob the pattern to match * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_exec_glob_list(const char *glob); @@ -111,7 +113,7 @@ EAPI Eina_List *efreet_util_desktop_exec_glob_list(const char *glob); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param glob the pattern to match + * @param[in] glob the pattern to match * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_generic_name_glob_list(const char *glob); @@ -121,7 +123,7 @@ EAPI Eina_List *efreet_util_desktop_generic_name_glob_list(const char *glob); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param glob the pattern to match + * @param[in] glob the pattern to match * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_comment_glob_list(const char *glob); @@ -140,7 +142,7 @@ EAPI Eina_List *efreet_util_desktop_categories_list(void); * * This list must be freed using EINA_LIST_FREE / efreet_desktop_free * - * @param category the category name + * @param[in] category the category name * @return a list of desktops */ EAPI Eina_List *efreet_util_desktop_category_list(const char *category); @@ -148,21 +150,12 @@ EAPI Eina_List *efreet_util_desktop_category_list(const char *category); /** * Returns a list of .menu files found in the various config dirs. + * * @return An eina list of menu file paths (const char *). This must be freed with EINA_LIST_FREE. */ EAPI Eina_List *efreet_util_menus_find(void); /** - * Find all known desktop environments - * This list must be freed using EINA_LIST_FREE - * @since 1.12 - * - * @return an Eina_List of desktop environments names (const char *) - */ -EAPI Eina_List *efreet_util_desktop_environments_list(void); - - -/** * @} */ #endif diff --git a/src/lib/eina/eina_array.h b/src/lib/eina/eina_array.h index 07234cd70b..da046d786f 100644 --- a/src/lib/eina/eina_array.h +++ b/src/lib/eina/eina_array.h @@ -1,7 +1,7 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. @@ -29,139 +29,31 @@ #include "eina_accessor.h" #include "eina_magic.h" - -/** - * @page eina_array_01_example_page Basic array usage - * @dontinclude eina_array_01.c - * - * For this example we add stdlib.h, stdio.h and string.h for some - * convenience functions. The first thing to do to be able to use an - * @ref Eina_Array is to include Eina.h: - * @skip #include - * @until Eina.h - * - * Here we have a callback that prints the element given to it: - * @until } - * - * Now we create our entry point and declare some variables, nothing especial: - * @until unsigned - * - * Before we can start using any array function we need to initialize eina: - * @until eina_init - * - * So now to actually create our array. The only interesting thing here is the - * argument given to the eina_array_new() function. This argument sets how fast - * the array grows. - * @until array_new - * - * If you know before hand how big the array will need to be you should set the - * step to that. In our case we can set it to the number of strings we have and - * since we didn't do that in the eina_array_new() we can do it now: - * @until array_step_set - * - * Now let us populate our array with some strings: - * @until push - * @note Notice we use strdup, so we will have to free that memory later on. - * - * Now lets check the size of the array: - * @until printf - * - * And now we call a function on every member of our array to print it: - * @until foreach - * - * One of the strengths of @ref Eina_Array over @ref Eina_List is that it has - * very fast random access to elements, so this is very efficient: - * @until printf - * - * And now we free up the memory allocated with the strdup()s: - * @until free - * - * And the array memory itself: - * @until array_free - * - * And finally shutdown eina and exit: - * @until } - * - * The full source code can be found in the examples folder - * in the @ref eina_array_01_c "eina_array_01.c" file. - */ - -/** - * @page eina_array_01_c Basic array usage example - * - * @include eina_array_01.c - * @example eina_array_01.c - */ - -/** - * @page eina_array_02_example_page Removing array elements - * @dontinclude eina_array_02.c - * - * Just the usual includes: - * @skip #include - * @until Eina.h - * - * This the callback we are going to use to decide which strings stay on the - * array and which will be removed. We use something simple, but this can be as - * complex as you like: - * @until } - * - * This is the same code we used before to populate the list with the slight - * difference of not using strdup: - * @until array_push - * - * So we have added all our elements to the array, but it turns out that is not - * the elements we wanted, so let's empty the array and add the correct strings: - * @until array_push - * - * It seems we made a little mistake in one of our strings so we need to replace - * it, here is how: - * @until data_set - * - * Now that there is a populated array we can remove elements from it easily: - * @until array_remove - * - * And check that the elements were actually removed: - * @until printf - * - * Since this time we didn't use strdup we don't need to free each string: - * @until } - * - * The full source code can be found in the examples folder - * in the @ref eina_array_02_c "eina_array_02.c" file. - */ - /** - * @page eina_array_02_c Basic array usage example - * - * @include eina_array_02.c - * @example eina_array_02.c - */ - -/** - * @addtogroup Eina_Array_Group Array + * @defgroup Eina_Array_Group Array + * @ingroup Eina_Containers_Group * - * @brief These functions provide array management. + * @brief This group discusses the functions to provide array management. * * The Array data type in Eina is designed to have very fast access to * its data (compared to the Eina @ref Eina_List_Group). On the other hand, * data can be added or removed only at the end of the array. To insert - * data at any position, the Eina @ref Eina_List_Group is the correct container + * data at any place, the Eina @ref Eina_List_Group is the correct container * to use. * * To use the array data type, eina_init() must be called before any - * other array functions. When no more eina array functions are used, + * other array function. When no more eina array functions are used, * eina_shutdown() must be called to free all the resources. * * An array must be created with eina_array_new(). It allocates all * the necessary data for an array. When not needed anymore, an array - * is freed with eina_array_free(). This frees the memory used by the Eina_Array - * itself, but does not free any memory used to store the data of each element. - * To free that memory you must iterate over the array and free each data element - * individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT. - * An example of that pattern is given in the description of @ref EINA_ARRAY_ITER_NEXT. + * is freed with eina_array_free(). This function does not free any + * allocated memory used to store the data of each element. For that, + * just iterate over the array to free them. A convenient way to do + * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given + * in the description of this macro. * - * @warning Functions do not check if the used array is valid or not. It's up to + * Functions do not check if the used array is valid or not. It's up to * the user to be sure of that. It is designed like that for performance * reasons. * @@ -173,157 +65,157 @@ * * Eina_Array is different from a conventional C array in a number of ways, most * importantly they grow and shrink dynamically, this means that if you add an - * element to a full array it grows and that when you remove an element from an + * element to a full array it grows and when you remove an element from an * array it @b may shrink. * - * Allocating memory is expensive, so when the array needs to grow it allocates - * enough memory to hold @p step additonal elements, not just the element - * currently being added. Similarly if you remove elements, it won't free space - * until you have removed @p step elements. + * When the array needs to grow it allocates memory not just for the element + * currently being added, since that would mean allocating memory(which is + * computationally expensive) often, instead it grows to be able to hold @a step + * more elements. Similarly, if you remove elements in such a way that the + * array is left holding its capacity, @a step elements shrink. * * The following image illustrates how an Eina_Array grows: * * @image html eina_array-growth.png - * @image latex eina_array-growth.eps "" width=\textwidth - * - * Eina_Array only stores pointers but it can store data of any type in the form - * of void pointers. + * @image latex eina_array-growth.eps "eina array growth" width=\textwidth * - * See here some examples: - * @li @ref eina_array_01_example_page - * @li @ref eina_array_02_example_page - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** - * @defgroup Eina_Array_Group Array + * @remarks Eina_Array only stores pointers, but it can store data of any type in the form + * of void pointers. * * @{ */ /** * @typedef Eina_Array - * Type for a generic vector. + * @brief The structure type for a generic vector. */ typedef struct _Eina_Array Eina_Array; /** * @typedef Eina_Array_Iterator - * Type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT. + * @brief The structure type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT. */ typedef void **Eina_Array_Iterator; /** * @struct _Eina_Array - * Type for an array of data. + * @brief The structure type for an array of data. */ struct _Eina_Array { #define EINA_ARRAY_VERSION 1 - int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */ + int version; /**< Should match EINA_ARRAY_VERSION used when compiling your apps, provided for ABI compatibility */ - void **data; /**< Pointer to a vector of pointer to payload */ - unsigned int total; /**< Number of allocated slots in the vector */ - unsigned int count; /**< Number of slots in the vector that actually point to data */ - unsigned int step; /**< Number of slots to grow or shrink the vector */ + void **data; /**< Pointer to a vector of a pointer to payload */ + unsigned int total; /**< Total number of slots in the vector */ + unsigned int count; /**< Number of active slots in the vector */ + unsigned int step; /**< To what extent must we grow the vector when it is full */ EINA_MAGIC }; /** - * @brief Create a new array. + * @brief Creates a new array. * - * @param step The count of pointers to add when increasing the array size. - * @return @c NULL on failure, non @c NULL otherwise. + * @details This function creates a new array. When adding an element, the array + * allocates @a step elements. When that buffer is full, adding + * another element increases the buffer by @a step elements again. * - * This function creates a new array. When adding an element, the array - * allocates @p step elements. When that buffer is full, then adding - * another element will increase the buffer by @p step elements again. + * @since_tizen 2.3 + * + * @remarks This function returns a valid array on success, or @c NULL if memory + * allocation fails. In that case, the error is set + * to #EINA_ERROR_OUT_OF_MEMORY. + * + * @param[in] step The count of pointers to add when increasing the array size + * @return @c NULL on failure, otherwise a non @c NULL value * - * This function return a valid array on success, or @c NULL if memory - * allocation fails. */ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free an array. + * @brief Frees an array. + * + * @details This function frees @a array. It calls first eina_array_flush() then + * frees the memory of the pointer. It does not free the memory + * allocated for the elements of @a array. To free them, + * use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check + * on @a array. + * + * @since_tizen 2.3 * - * @param array The array to free. + * @param[in] array The array to free * - * This function frees @p array. It calls first eina_array_flush() then - * free the memory of the pointer. It does not free the memory - * allocated for the elements of @p array. To free them, walk the array with - * #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check - * of @p array. */ EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @brief Set the step of an array. + * @brief Sets the step of an array. * - * @param array The array. - * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). - * @param step The count of pointers to add when increasing the array size. + * @details This function sets the step of @a array to @a step. For performance + * reasons, there is no check on @a array. If it is @c NULL or + * invalid, the program may crash. * - * This function sets the step of @p array to @p step. For performance - * reasons, there is no check of @p array. If it is @c NULL or - * invalid, the program may crash. + * @since_tizen 2.3 + * + * @remarks This function can @b only be called on uninitialized arrays. + * + * @param[in] array The array + * @param[in] sizeof_eina_array The value returned by sizeof(Eina_Array) + * @param[in] step The count of pointers to add when increasing the array size * - * @warning This function can @b only be called on uninitialized arrays. */ EAPI void eina_array_step_set(Eina_Array *array, unsigned int sizeof_eina_array, unsigned int step) EINA_ARG_NONNULL(1); /** - * @brief Clean an array. + * @brief Cleans an array. + * + * @details This function sets the count member of @a array to 0. However, it doesn't free + * any space. This is particularly useful if you need to empty the array and + * add lots of elements quickly. For performance reasons, there is no check on + * @a array. If it is @c NULL or invalid, the program may crash. * - * @param array The array to clean. + * @since_tizen 2.3 + * + * @param[in] array The array to clean * - * This function sets the count member of @p array to 0, however it doesn't free - * any space. This is particularly useful if you need to empty the array and - * add lots of elements quickly. For performance reasons, there is no check of - * @p array. If it is @c NULL or invalid, the program may crash. */ static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @brief Flush an array. + * @brief Flushes an array. + * + * @details This function sets the count and total members of @a array to 0, + * frees and sets its data member to @c NULL. For performance reasons, + * there is no check on @a array. If it is @c NULL or invalid, the + * program may crash. * - * @param array The array to flush. + * @since_tizen 2.3 + * + * @param[in] array The array to flush * - * This function sets the count and total members of @p array to 0, - * frees and set to NULL its data member. For performance reasons, - * there is no check of @p array. If it is @c NULL or invalid, the - * program may crash. */ EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @brief Rebuild an array by specifying the data to keep. + * @brief Rebuilds an array by specifying the data to keep. * - * @param array The array. - * @param keep The functions which selects the data to keep. - * @param gdata The data to pass to the function keep. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function rebuilds @a array by specifying the elements to keep with the + * function @a keep. No empty/invalid fields are left in the array. @a gdata is + * an additional data to pass to @a keep. For performance reasons, there is no + * check on @a array. If it is @c NULL or invalid, the program may crash. * - * This function rebuilds @p array be specifying the elements to keep with the - * function @p keep. No empty/invalid fields are left in the array. @p gdata is - * an additional data to pass to @p keep. For performance reasons, there is no - * check of @p array. If it is @c NULL or invalid, the program may crash. + * @since_tizen 2.3 + * + * @remarks If it isn't able to remove items due to an allocation failure, it + * returns @c EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY. + * + * @param[in] array The array + * @param[in] keep The functions that selects the data to keep + * @param[in] gdata The data to pass to the function @a keep + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * If it wasn't able to remove items due to an allocation failure, it will - * return #EINA_FALSE. */ EAPI Eina_Bool eina_array_remove(Eina_Array * array, Eina_Bool (*keep)(void *data, void *gdata), @@ -332,15 +224,17 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array, /** * @brief Append a data to an array. * - * @param array The array. - * @param data The data to add. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function appends @p data to @p array. For performance + * reasons, there is no check of @p array. If it is @c NULL or + * invalid, the program may crash. If @p data is @c NULL, or if an + * allocation is necessary and fails, #EINA_FALSE is returned + * Otherwise, #EINA_TRUE is returned. * - * This function appends @p data to @p array. For performance - * reasons, there is no check of @p array. If it is @c NULL or - * invalid, the program may crash. If @p data is @c NULL, or if an - * allocation is necessary and fails, #EINA_FALSE is returned - * Otherwise, #EINA_TRUE is returned. + * @since_tizen 2.3 + * + * @param[in] array The array. + * @param[in] data The data to add. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_array_push(Eina_Array *array, const void *data) EINA_ARG_NONNULL(1, 2); @@ -348,55 +242,66 @@ static inline Eina_Bool eina_array_push(Eina_Array *array, /** * @brief Remove the last data of an array. * - * @param array The array. - * @return The retrieved data. + * @details This function removes the last data of @p array, decreases the count + * of @p array and returns the data. For performance reasons, there + * is no check of @p array. If it is @c NULL or invalid, the program + * may crash. If the count member is less or equal than 0, @c NULL is + * returned. + * + * @since_tizen 2.3 * - * This function removes the last data of @p array, decreases the count - * of @p array and returns the data. For performance reasons, there - * is no check of @p array. If it is @c NULL or invalid, the program - * may crash. If the count member is less or equal than 0, @c NULL is - * returned. + * @param[in] array The array. + * @return The retrieved data. */ static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @brief Return the data at a given position in an array. + * @brief Sets the data at the given position in an array. * - * @param array The array. - * @param idx The potition of the data to retrieve. - * @return The retrieved data. + * @details This function sets the data at the position @a idx in @a + * array to @a data, this effectively replaces the previously held data, you + * must therefore get a pointer to it first if you need to free it. For + * performance reasons, there is no check on @a array or @a idx. If it is + * @c NULL or invalid, the program may crash. + * + * @since_tizen 2.3 * - * This function returns the data at the position @p idx in @p - * array. For performance reasons, there is no check of @p array or @p - * idx. If it is @c NULL or invalid, the program may crash. + * @param[in] array The array + * @param[in] idx The position of the data to set */ static inline void *eina_array_data_get(const Eina_Array *array, unsigned int idx) EINA_ARG_NONNULL(1); /** - * @brief Set the data at a given position in an array. - * - * @param array The array. - * @param idx The position of the data to set. - * @param data The data to set. - * - * This function sets the data at the position @p idx in @p - * array to @p data, this effectively replaces the previously held data, you - * must therefore get a pointer to it first if you need to free it. For - * performance reasons, there is no check of @p array or @p idx. If it is @c - * NULL or invalid, the program may crash. -*/ + * @brief Sets the data at the given position in an array. + * + * @details This function sets the data at the position @a idx in @a + * array to @a data, this effectively replaces the previously held data, you + * must therefore get a pointer to it first if you need to free it. For + * performance reasons, there is no check on @a array or @a idx. If it is + * @c NULL or invalid, the program may crash. + * + * @since_tizen 2.3 + * + * @param[in] array The array + * @param[in] idx The position of the data to set + * @param[in] data The data to set + * + */ static inline void eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data) EINA_ARG_NONNULL(1); + /** * @brief Return the number of elements in an array. * - * @param array The array. - * @return The number of elements. + * @details This function returns the number of elements in @p array (array->count). For + * performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. + * + * @since_tizen 2.3 * - * This function returns the number of elements in @p array (array->count). For - * performance reasons, there is no check of @p array. If it is - * @c NULL or invalid, the program may crash. + * @param[in] array The array. + * @return The number of elements. * * @deprecated use eina_array_count() */ @@ -405,74 +310,82 @@ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_AR /** * @brief Return the number of elements in an array. * - * @param array The array. - * @return The number of elements. + * @details This function returns the number of elements in @p array (array->count). + * For performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. * - * This function returns the number of elements in @p array (array->count). For - * performance reasons, there is no check of @p array. If it is - * @c NULL or invalid, the program may crash. + * @since_tizen 2.3 + * + * @param[in] array The array. + * @return The number of elements. */ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Get a new iterator associated to an array. + * @brief Returns a new iterator associated to an array. + * + * @details This function returns a newly allocated iterator associated to + * @a array. If @a array is @c NULL or the count member of @a array is + * less than or equal to 0, this function returns @c NULL. If the memory cannot + * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, a valid iterator is returned. * - * @param array The array. - * @return A new iterator. + * @since_tizen 2.3 + * + * @param[in] array The array + * @return A new iterator * - * This function returns a newly allocated iterator associated to - * @p array. If @p array is @c NULL or the count member of @p array is - * less or equal than 0, this function returns @c NULL. If the memory can - * not be allocated, @c NULL is returned. Otherwise, a valid iterator is returned. */ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Get a new accessor associated to an array. + * @brief Returns a new accessor associated to an array. + * + * @details This function returns a newly allocated accessor associated to + * @a array. If @a array is @c NULL or the count member of @a array is + * less than or equal to @c 0, this function returns @c NULL. If the memory cannot + * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, a valid accessor is returned. + * + * @since_tizen 2.3 * - * @param array The array. - * @return A new accessor. + * @param[in] array The array + * @return A new accessor * - * This function returns a newly allocated accessor associated to - * @p array. If @p array is @c NULL or the count member of @p array is - * less or equal than 0, this function returns @c NULL. If the memory can - * not be allocated, @c NULL is returned. Otherwise, a valid accessor is - * returned. */ EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Provide a safe way to iterate over an array + * @brief Provides a safe way to iterate over an array. * - * @param array The array to iterate over. - * @param cb The callback to call for each item. - * @param fdata The user data to pass to the callback. - * @return #EINA_TRUE if it successfully iterate all items of the array. + * @details This function provides a safe way to iterate over an array. @a cb should + * return @c EINA_TRUE as long as you want the function to continue iterating, + * by returning @c EINA_FALSE it stops and returns @c EINA_FALSE as a result. + * + * @since_tizen 2.3 + * + * @param[in] array The array to iterate over + * @param[in] cb The callback to call for each item + * @param[in] fdata The user data to pass to the callback + * @return @c EINA_TRUE if it successfully iterates all the items of the array, otherwise @c EINA_FALSE * - * This function provides a safe way to iterate over an array. @p cb should - * return #EINA_TRUE as long as you want the function to continue iterating. - * If @p cb returns #EINA_FALSE, iterations will stop and the function will also - * return #EINA_FALSE. */ static inline Eina_Bool eina_array_foreach(Eina_Array *array, Eina_Each_Cb cb, void *fdata); /** * @def EINA_ARRAY_ITER_NEXT - * @brief Macro to iterate over an array easily. + * @brief Definition of the macro to iterate over an array easily. * - * @param array The array to iterate over. - * @param index The integer number that is increased while iterating. - * @param item The data - * @param iterator The iterator + * @details This macro allows the iteration over @a array in an easy way. It + * iterates from the first element to the last one. @a index is an + * integer that increases from 0 to the number of elements. @a item is + * the data of each element of @a array, so it is a pointer to a type + * chosen by the user. @a iterator is of type #Eina_Array_Iterator. * - * This macro allows the iteration over @p array in an easy way. It - * iterates from the first element to the last one. @p index is an - * integer that increases from 0 to the number of elements. @p item is - * the data of each element of @p array, so it is a pointer to a type - * chosen by the user. @p iterator is of type #Eina_Array_Iterator. + * @since_tizen 2.3 * - * This macro can be used for freeing the data of an array, like in - * the following example: + * @remarks This macro can be used for freeing the data of an array, like in + * the following example: * * @code * Eina_Array *array; @@ -487,6 +400,12 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array, * EINA_ARRAY_ITER_NEXT(array, i, item, iterator) * free(item); * @endcode + * + * @param array The array to iterate over + * @param index The integer number that is increased while iterating + * @param item The data + * @param iterator The iterator + * */ #define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \ for (index = 0, iterator = (array)->data; \ @@ -499,12 +418,4 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array, * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_benchmark.h b/src/lib/eina/eina_benchmark.h index 8c0c5988da..1633aa569c 100644 --- a/src/lib/eina/eina_benchmark.h +++ b/src/lib/eina/eina_benchmark.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -21,286 +21,15 @@ #include "eina_array.h" - - -/** - * @page tutorial_benchmark_page Benchmark Tutorial - * - * The Benchmark module allows you to write easily benchmarks - * framework in a project for timing critical part and detect slow - * parts of code. In addition it automatically creates data files of - * these benchmark, as well as a gnuplot file which can display the - * comparison curves of the benchmarks. - * - * @section tutorial_benchmark_basic_usage Basic Usage - * - * To create a basic benchmark, you have to follow these steps: - * - * @li Create a new benchmark - * @li Write the functions that wraps the functions you want to - * benchmark. - * @li Register these wrappers functions. - * @li Run the benchmark. - * @li Free the memory. - * - * Here is a basic example of benchmark which creates two functions - * that will be run. These functions just print a message. - * - * @code - * #include <stdlib.h> - * #include <stdio.h> - * - * #include <Eina.h> - * - * static - * void work1(int request) - * { - * printf ("work1 in progress... Request: %d\n", request); - * } - * - * static - * void work2(int request) - * { - * printf ("work2 in progress... Request: %d\n", request); - * } - * - * int main() - * { - * Eina_Benchmark *test; - * Eina_Array *ea; - * - * if (!eina_init()) - * return EXIT_FAILURE; - * - * test = eina_benchmark_new("test", "run"); - * if (!test) - * goto shutdown_eina; - * - * eina_benchmark_register(test, "work-1", EINA_BENCHMARK(work1), 200, 300, 10); - * eina_benchmark_register(test, "work-2", EINA_BENCHMARK(work2), 100, 150, 5); - * - * ea = eina_benchmark_run(test); - * - * eina_benchmark_free(test); - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * - * shutdown_eina: - * eina_shutdown(); - * - * return EXIT_FAILURE; - * } - * @endcode - * - * As "test", "run" are passed to eina_benchmark_new() and as the tests - * "work-1" and "work-2" are registered, the data files - * bench_test_run.work-1.data and bench_test_run.work-2.data will be - * created after the eina_benchmark_run() call. They contain four - * columns. The file bench_test_run.work-1.data contains for example: - * - * @code - * # specimen experiment time starting time ending time - * 200 23632 2852446 2876078 - * 210 6924 2883046 2889970 - * 220 6467 2895962 2902429 - * 230 6508 2908271 2914779 - * 240 6278 2920610 2926888 - * 250 6342 2932830 2939172 - * 260 6252 2944954 2951206 - * 270 6463 2956978 2963441 - * 280 6347 2969548 2975895 - * 290 6457 2981702 2988159 - * @endcode - * - * The first column (specimen) is the integer passed to the work1() - * function when the test is run. The second column (experiment time) - * is the time, in nanosecond, that work1() takes. The third and - * fourth columnd are self-explicit. - * - * You can see that the integer passed work1() starts from 200 and - * finishes at 290, with a step of 10. These values are computed withe - * last 3 values passed to eina_benchmark_register(). See the document - * of that function for the detailed behavior. - * - * The gnuplot file will be named bench_test_run.gnuplot. Just run: - * - * @code - * gnuplot bench_test_run.gnuplot - * @endcode - * - * to create the graphic of the comparison curves. The image file is - * named output_test_run.png. - * - * @section tutorial_benchmark_advanced_usage More Advanced Usage - * - * In this section, several test will be created and run. The idea is - * exactly the same than in the previous section, but with some basic - * automatic way to run all the benchmarks. The following code - * benchmarks some Eina converts functions, and some Eina containers - * types: - * - * @code - * #include <stdlib.h> - * #include <stdio.h> - * #include <time.h> - * - * #include <Eina.h> - * - * static void bench_convert(Eina_Benchmark *bench); - * static void bench_container(Eina_Benchmark *bench); - * - * typedef struct _Benchmark_Case Benchmark_Case; - * - * struct _Benchmark_Case - * { - * const char *bench_case; - * void (*build)(Eina_Benchmark *bench); - * }; - * - * static const Benchmark_Case benchmarks[] = { - * { "Bench 1", bench_convert }, - * { "Bench 2", bench_container }, - * { NULL, NULL } - * }; - * - * static - * void convert1(int request) - * { - * char tmp[128]; - * int i; - * - * srand(time(NULL)); - * - * for (i = 0; i < request; ++i) - * eina_convert_itoa(rand(), tmp); - * } - * - * static - * void convert2(int request) - * { - * char tmp[128]; - * int i; - * - * srand(time(NULL)); - * - * for (i = 0; i < request; ++i) - * eina_convert_xtoa(rand(), tmp); - * } - * - * static void - * bench_convert(Eina_Benchmark *bench) - * { - * eina_benchmark_register(bench, "convert-1", EINA_BENCHMARK(convert1), 200, 400, 10); - * eina_benchmark_register(bench, "convert-2", EINA_BENCHMARK(convert2), 200, 400, 10); - * } - * - * static - * void array(int request) - * { - * Eina_Array *array; - * Eina_Array_Iterator it; - * int *data; - * int i; - * - * srand(time(NULL)); - * - * array = eina_array_new(64); - * - * for (i = 0; i < request; ++i) - * { - * data = (int *)malloc(sizeof(int)); - * if (!data) continue; - * *data = rand(); - * eina_array_push(array, data); - * } - * - * EINA_ARRAY_ITER_NEXT(array, i, data, it) - * free(data); - * - * eina_array_free(array); - * } - * - * static - * void list(int request) - * { - * Eina_List *l = NULL; - * int *data; - * int i; - * - * srand(time(NULL)); - * - * for (i = 0; i < request; ++i) - * { - * data = (int *)malloc(sizeof(int)); - * if (!data) continue; - * *data = rand(); - * l = eina_list_prepend(l, data); - * } - * - * while (l) - * { - * free(eina_list_data_get(l)); - * l = eina_list_remove_list(l, l); - * } - * } - * - * static void - * bench_container(Eina_Benchmark *bench) - * { - * eina_benchmark_register(bench, "array", EINA_BENCHMARK(array), 200, 300, 10); - * eina_benchmark_register(bench, "list", EINA_BENCHMARK(list), 200, 300, 10); - * } - * - * int main() - * { - * Eina_Benchmark *test; - * Eina_Array *ea; - * unsigned int i; - * - * if (!eina_init()) - * return EXIT_FAILURE; - * - * for (i = 0; benchmarks[i].bench_case != NULL; ++i) - * { - * test = eina_benchmark_new(benchmarks[i].bench_case, "Benchmark example"); - * if (!test) - * continue; - * - * benchmarks[i].build(test); - * - * ea = eina_benchmark_run(test); - * - * eina_benchmark_free(test); - * } - * - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * gnuplot can be used to see how are performed the convert functions - * together, as well as how are performed the containers. So it is now - * easy to see that the hexadecimal convert function is faster than - * the decimal one, and that arrays are faster than lists. - * - * You can improve all that by executing automatically gnuplot in your - * program, or integrate the Eina benchmark framework in an autotooled - * project. See that - * <a href="http://trac.enlightenment.org/e/wiki/AutotoolsIntegration#Benchmark">page</a> - * for more informations. - * - */ - - /** - * @addtogroup Eina_Benchmark_Group Benchmark + * @internal + * @defgroup Eina_Benchmark_Group Benchmark + * @ingroup Eina_Tools_Group * - * These functions allow you to add benchmark framework in a project - * for timing critical part and detect slow parts of code. It is used - * in Eina to compare the time used by eina, glib, evas and ecore data - * types. + * @brief This group discusses the functions that allow you to add the benchmark framework in a project + * for timing critical part and detecting slow parts of a code. It is used + * in Eina to compare the time used by eina, glib, evas, and ecore data + * types. * * To use the benchmark module, Eina must be initialized with * eina_init() and later shut down with eina_shutdown(). A benchmark @@ -308,102 +37,102 @@ * eina_benchmark_free(). * * eina_benchmark_register() adds a test to a benchmark. That test can - * be run a certain amount of times. Adding more than one test to be + * be run a certain number of times. Adding more than one test to be * executed allows the comparison between several parts of a program, * or different implementations. * * eina_benchmark_run() runs all the tests registered with - * eina_benchmark_register(). The amount of time of each test is + * eina_benchmark_register(). The amount of time for each test is * written in a gnuplot file. * - * For more information, you can look at the @ref tutorial_benchmark_page. - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** - * @defgroup Eina_Benchmark_Group Benchmark - * * @{ */ /** * @typedef Eina_Benchmark - * Type for a benchmark. + * @brief The structure type for a benchmark. */ typedef struct _Eina_Benchmark Eina_Benchmark; /** * @typedef Eina_Benchmark_Specimens - * Type for a test function to be called when running a benchmark. + * @brief The structure type for a test function to be called when running a benchmark. */ typedef void (*Eina_Benchmark_Specimens)(int request); /** * @def EINA_BENCHMARK - * @brief cast to an #Eina_Benchmark_Specimens. + * @brief Definition to cast to an #Eina_Benchmark_Specimens. + * + * @details This macro casts @a function to Eina_Benchmark_Specimens. * - * @param function The function to cast. + * @param function The function to cast * - * This macro casts @p function to Eina_Benchmark_Specimens. */ #define EINA_BENCHMARK(function) ((Eina_Benchmark_Specimens)function) - /** - * @brief Create a new array. + * @brief Creates a new array. + * + * @details This function creates a new benchmark. @a name and @a run are used + * to name the gnuplot file that eina_benchmark_run() creates. * - * @param name The name of the benchmark. - * @param run The name of the run. - * @return @c NULL on failure, non @c NULL otherwise. + * @since_tizen 2.3 * - * This function creates a new benchmark. @p name and @p run are used - * to name the gnuplot file that eina_benchmark_run() will create. + * @remarks This function returns a valid benchmark on success, or @c NULL if + * memory allocation fails. In that case, the error is set + * to #EINA_ERROR_OUT_OF_MEMORY. + * + * @remarks When the new module is not needed anymore, use + * eina_benchmark_free() to free the allocated memory. + * + * @param[in] name The name of the benchmark + * @param[in] run The name of the run + * @return @c NULL on failure, otherwise a non @c NULL value * - * This function return a valid benchmark on success, or @c NULL if - * memory allocation fails. - * - * When the new module is not needed anymore, use - * eina_benchmark_free() to free the allocated memory. */ EAPI Eina_Benchmark *eina_benchmark_new(const char *name, const char *run); /** - * @brief Free a benchmark object. + * @brief Frees a benchmark object. + * + * @details This function removes all the benchmark tests that have been + * registered and frees @a bench. If @a bench is @c NULL, this + * function returns immediately. + * + * @since_tizen 2.3 * - * @param bench The benchmark to free. + * @param[in] bench The benchmark to free * - * This function removes all the benchmark tests that have been - * registered and frees @p bench. If @p bench is @c NULL, this - * function returns immediately. */ EAPI void eina_benchmark_free(Eina_Benchmark *bench); /** - * @brief Add a test to a benchmark. - * - * @param bench The benchmark. - * @param name The name of the test. - * @param bench_cb The test function to be called. - * @param count_start The start data to be passed to @p bench_cb. - * @param count_end The end data to be passed to @p bench_cb. - * @param count_step The step data to be passed to @p bench_cb. - * @return #EINA_FALSE on failure, #EINA_TRUE otherwise. - * - * This function adds the test named @p name to @p benchmark. @p - * bench_cb is the function called when the test is executed. That - * test can be executed a certain amount of time. @p count_start, @p count_end and - * @p count_step define a loop with a step increment. The integer that is - * increasing by @p count_step from @p count_start to @p count_end is passed to @p - * bench_cb when eina_benchmark_run() is called. - * - * If @p bench is @c NULL, this function returns immediately. - * This function returns #EINA_FALSE on failure, #EINA_TRUE otherwise. + * @brief Adds a test to a benchmark. + * + * @details This function adds the test named @a name to @a benchmark. @a + * bench_cb is the function called when the test is executed. That + * test can be executed for a certain amount of time. @a count_start, @a count_end, and + * @a count_step define a loop with a step increment. The integer that is + * increasing by @a count_step from @a count_start to @a count_end is passed to @a + * bench_cb when eina_benchmark_run() is called. + * + * @since_tizen 2.3 + * + * @remarks If @a bench is @c NULL, this function returns immediately. If the + * allocation of the memory of the test to add fails, the error is set + * to #EINA_ERROR_OUT_OF_MEMORY. This function returns @c EINA_FALSE + * on failure, otherwise it returns @c EINA_TRUE. + * + * @param[in] bench The benchmark + * @param[in] name The name of the test + * @param[in] bench_cb The test function to be called + * @param[in] count_start The start data to be passed to @a bench_cb + * @param[in] count_end The end data to be passed to @a bench_cb + * @param[in] count_step The step data to be passed to @a bench_cb + * @return @c EINA_FALSE on failure, otherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, const char *name, @@ -413,29 +142,32 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, int count_step); /** - * @brief Run the benchmark tests that have been registered. - * - * @param bench The benchmark. - * @return The list of names of the test files. + * @brief Runs the benchmark tests that have been registered. * - * This function runs all the tests that as been registered with - * eina_benchmark_register() and save the result in a gnuplot - * file. The name of the file has the following format: + * @details This function runs all the tests that have been registered with + * eina_benchmark_register() and saves the result in a gnuplot + * file. The name of the file has the following format: * * @code * bench_[name]_[run]%s.gnuplot * @endcode * - * where [name] and [run] are the values passed to - * eina_benchmark_new(). + * where [name] and [run] are the values passed to + * eina_benchmark_new(). + * + * @since_tizen 2.3 + * + * @remarks Each registered test is executed and timed. The time is written to + * the gnuplot file. The number of times each test is executed is + * controlled by the parameters passed to eina_benchmark_register(). + * + * @remarks If @a bench is @c NULL, this functions returns @c NULL + * immediately. Otherwise, it returns the list of names of each + * test. * - * Each registered test is executed and timed. The time is written to - * the gnuplot file. The number of times each test is executed is - * controlled by the parameters passed to eina_benchmark_register(). + * @param[in] bench The benchmark + * @return The list of names of the test files * - * If @p bench is @c NULL, this functions returns @c NULL - * immediately. Otherwise, it returns the list of the names of each - * test. */ EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench); @@ -443,8 +175,4 @@ EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench); * @} */ -/** - * @} - */ - #endif /* EINA_BENCHMARK_H_ */ diff --git a/src/lib/eina/eina_binbuf.h b/src/lib/eina/eina_binbuf.h index 32f3b1ebfe..71216479b1 100644 --- a/src/lib/eina/eina_binbuf.h +++ b/src/lib/eina/eina_binbuf.h @@ -7,39 +7,33 @@ #include "eina_types.h" /** - * @addtogroup Eina_Binary_Buffer_Group Binary Buffer + * @defgroup Eina_Binary_Buffer_Group Binary Buffer + * @ingroup Eina_Data_Types_Group * - * @brief These functions provide string buffers management. + * @brief This group discusses the functions that provide string buffers management. * * The Binary Buffer data type is designed to be a mutable string, - * allowing to append, prepend or insert a string to a buffer. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Binary_Buffer_Group Binary Buffer + * allowing to append, prepend, or insert a string into a buffer. * * @{ */ /** * @typedef Eina_Binbuf - * Type for a string buffer. + * @brief The structure type for a string buffer. */ typedef struct _Eina_Strbuf Eina_Binbuf; /** - * @brief Create a new string buffer. + * @brief Creates a new string buffer. * - * @return Newly allocated string buffer instance. + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_binbuf_free(). + * + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_binbuf_free(). + * @return Newly allocated string buffer instance. * * @see eina_binbuf_free() * @see eina_binbuf_append() @@ -48,76 +42,67 @@ typedef struct _Eina_Strbuf Eina_Binbuf; EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_binbuf_string_steal . The passed string must be malloced. - * - * @param str the string to manage - * @param length the length of the string. - * @return Newly allocated string buffer instance. + * @brief Creates a new string buffer using the passed string. The passed + * string is used directly as the buffer, it's somehow the opposite function of + * @ref eina_binbuf_string_steal . The passed string must be malloced. * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_binbuf_free(). + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_binbuf_free(). * - * @see eina_binbuf_manage_new() * @since 1.2.0 - */ -EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; - -/** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_binbuf_string_steal . The passed string will not be touched. * - * @param str the string to start from - * @param length the length of the string. - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_binbuf_free(). It will - * not touch the internal buffer. Any changing operation will - * create a fresh new memory, copy old data there and starting modifying - * that one. + * @param[in] str The string to manage + * @param[in] length The length of the string + * @return A newly allocated string buffer instance * * @see eina_binbuf_manage_new() - * @since 1.9.0 */ -EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; +EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free a string buffer. + * @brief Frees a string buffer. + * + * @details This function frees the memory of @a buf. @a buf must have been + * created by eina_binbuf_new(). * - * @param buf The string buffer to free. + * @since_tizen 2.3 * - * This function frees the memory of @p buf. @p buf must have been - * created by eina_binbuf_new(). + * @param[in] buf The string buffer to free */ EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Reset a string buffer. + * @brief Resets a string buffer. + * + * @details This function resets @a buf, the buffer length is set to @c 0 and the + * string is set to '\\0'. No memory is freed. * - * @param buf The string buffer to reset. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to reset * - * This function reset @p buf: the buffer len is set to 0, and the - * string is set to '\\0'. No memory is free'd. */ EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Append a string of exact length to a buffer, reallocating as necessary. + * @brief Appends a string of exact length to a buffer, reallocating as necessary. + * + * @details This function appends @a str to @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_binbuf_append() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_strngshare. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @param length The exact length to use. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function appends @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_binbuf_append() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_strngshare. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @param[in] length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_binbuf_append() @@ -126,52 +111,38 @@ EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2); /** - * @brief Append an Eina_Binbuf to a buffer, reallocating as necessary. - * - * @param buf The string buffer to append to. - * @param data The string buffer to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @brief Appends a character to a string buffer, reallocating as + * necessary. * - * This function appends @p data to @p buf. @p data must be allocated and - * different from @c NULL. It is slightly faster than eina_binbuf_append() as - * it does not compute the size of @p str. If @p buf can't append it, - * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. + * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE + * is returned, otherwise @c EINA_TRUE is returned. * - * @see eina_binbuf_append() - * @see eina_binbuf_append_n() - * @see eina_binbuf_append_length() - * @since 1.9.0 - */ -EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2); - -/** - * @brief Append a character to a string buffer, reallocating as - * necessary. + * @since_tizen 2.3 * - * @param buf The string buffer to append to. - * @param c The char to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to append to + * @param[in] c The character to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1); /** - * @brief Insert a string of exact length to a buffer, reallocating as necessary. + * @brief Inserts a string of exact length into a buffer, reallocating as necessary. + * + * @details This function inserts @a str into @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_binbuf_insert() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_strngshare. If @a buf + * can't insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param length The exact length to use. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function inserts @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_binbuf_insert() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_strngshare. If @p buf - * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to insert to + * @param[in] str The string to insert + * @param[in] length The exact length to use + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_binbuf_insert() @@ -180,84 +151,99 @@ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_A EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a character to a string buffer, reallocating as - * necessary. + * @brief Inserts a character into a string buffer, reallocating as + * necessary. * - * @param buf The string buffer to insert to. - * @param c The char to insert. - * @param pos The position to insert the char. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a c into @a buf at position @a pos. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] c The character to insert + * @param[in] pos The position at which to insert the character + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf at position @p pos. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1); /** - * @brief Remove a slice of the given string buffer. - * - * @param buf The string buffer to remove a slice. - * @param start The initial (inclusive) slice position to start - * removing, in bytes. - * @param end The final (non-inclusive) slice position to finish - * removing, in bytes. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function removes a slice of @p buf, starting at @p start - * (inclusive) and ending at @p end (non-inclusive). Both values are - * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. + * @brief Removes a slice of the given string buffer. + * + * @details This function removes a slice of @a buf, starting from @a start + * (inclusive) and ending at @a end (non-inclusive). Both values are + * in bytes. It returns @c EINA_FALSE on failure, otherwise @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to remove a slice of + * @param[in] start The initial (inclusive) slice position to start + * removing from, in bytes + * @param[in] end The final (non-inclusive) slice position to finish + * removing at, in bytes + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure */ EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); /** - * @brief Retrieve a pointer to the contents of a string buffer + * @brief Gets a pointer to the contents of a string buffer. + * + * @details This function returns the string contained in @a buf. The returned + * value must not be modified and is no longer valid if @a buf is + * modified. In other words, any eina_binbuf_append() or similar + * makes that pointer invalid. * - * @param buf The string buffer. - * @return The current string in the string buffer. + * @since_tizen 2.3 * - * This function returns the string contained in @p buf. The returned - * value must not be modified and will no longer be valid if @p buf is - * modified. In other words, any eina_binbuf_append() or similar will - * make that pointer invalid. + * @param[in] buf The string buffer + * @return The current string in the string buffer * * @see eina_binbuf_string_steal() */ EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Steal the contents of a string buffer. + * @brief Steals the contents of a string buffer. * - * @param buf The string buffer to steal. - * @return The current string in the string buffer. + * @details This function returns the string contained in @a buf. @a buf is + * then initialized and does not own the returned string anymore. The + * caller must release the memory of the returned string by calling + * free(). * - * This function returns the string contained in @p buf. @p buf is - * then initialized and does not own the returned string anymore. The - * caller must release the memory of the returned string by calling - * free(). + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to steal from + * @return The current string in the string buffer * * @see eina_binbuf_string_get() */ EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Free the contents of a string buffer but not the buffer. + * @brief Frees the contents of a string buffer but not the buffer. + * + * @details This function frees the string contained in @a buf without freeing + * @a buf. + * + * @since_tizen 2.3 * - * @param buf The string buffer to free the string of. + * @param[in] buf The string buffer to free the string of * - * This function frees the string contained in @p buf without freeing - * @p buf. */ EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Retrieve the length of the string buffer content. + * @brief Gets the length of the string buffer's content. * - * @param buf The string buffer. - * @return The current length of the string, in bytes. + * @details This function returns the length of @a buf. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer + * @return The current length of the string, in bytes * - * This function returns the length of @p buf. */ EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -265,8 +251,4 @@ EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1 * @} */ -/** - * @} - */ - #endif /* EINA_STRBUF_H */ diff --git a/src/lib/eina/eina_convert.h b/src/lib/eina/eina_convert.h index be65cc404e..588a7e185c 100644 --- a/src/lib/eina/eina_convert.h +++ b/src/lib/eina/eina_convert.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric BAIL, Vincent Torri * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -26,22 +26,23 @@ /** - * @addtogroup Eina_Convert_Group Convert + * @defgroup Eina_Convert_Group Convert + * @ingroup Eina_Tools_Group * - * These functions allow you to convert integer or real numbers to - * string or conversely. + * @brief This group discusses the functions that allow you to convert an + * integer or real numbers to a string or conversely. * * To use these functions, you have to call eina_init() - * first, and eina_shutdown() when eina is not used anymore. + * first, and then eina_shutdown() when eina is not used anymore. * * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string * * To convert an integer to a string in the decimal base, * eina_convert_itoa() should be used. If the hexadecimal base is - * wanted, eina_convert_xtoa() should be used. They all need a buffer + * wanted, eina_convert_xtoa() should be used. They all need a buffer that is * sufficiently large to store all the cyphers. * - * Here is an example of use: + * Here is an example for use: * * @code * #include <stdlib.h> @@ -76,15 +77,14 @@ * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` * @endcode * - * @note - * The alphabetical cyphers are in lower case. + * @remarks The alphabetical cyphers are in lower case. * * @section Eina_Convert_Double Conversion double / string * * To convert a double to a string, eina_convert_dtoa() should be * used. Like with the integer functions, a buffer must be used. The * resulting string has the following format (which is the result - * obtained with snprintf() and the @%a modifier): + * obtained with snprintf() and the modifier): * * @code * [-]0xh.hhhhhp[+-]e @@ -92,18 +92,18 @@ * * To convert a string to a double, eina_convert_atod() should be * used. The format of the string must be as above. Then, the double - * has the following mantiss and exponent: + * has the following mantissa and exponent: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * with n being number of cypers after the point in the string - * format. To obtain the double number from the mantiss and exponent, + * with n being the number of cyphers after the point in the string + * format. To obtain the double number from the mantissa and exponent, * use ldexp(). * - * Here is an example of use: + * Here is an example for use: * * @code * #include <stdlib.h> @@ -144,97 +144,107 @@ * @code * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm * @endcode + * + * @{ */ /** - * @addtogroup Eina_Tools_Group Tools - * - * @{ + * @var EINA_ERROR_CONVERT_P_NOT_FOUND + * @brief Error identifier corresponding to string not containing 'p'. */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; + /** - * @defgroup Eina_Convert_Group Convert - * - * @{ + * @var EINA_ERROR_CONVERT_0X_NOT_FOUND + * @brief The error identifier corresponding to the string not containing '0x'. */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; -EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ -EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ -EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ +/** + * @var EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH + * @brief The error identifier corresponding to the length of the string being too small. + */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /** - * @brief Convert an integer number to a string in decimal base. + * @brief Converts an integer number to a string in decimal base. + * + * @details This function converts @a n to a null terminated string. The + * converted string is in decimal base. As no check is done, @a s must + * be a buffer that is sufficiently large to store the integer. * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. + * @since_tizen 2.3 * - * This function converts @p n to a nul terminated string. The - * converted string is in decimal base. As no check is done, @p s must - * be a buffer that is sufficiently large to store the integer. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] n The integer to convert + * @param[in] s The buffer to store the converted integer + * @return The length of the string, including the null terminated + * character * - * The returned value is the length of the string, including the nul - * terminated character. */ EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); /** - * @brief Convert an integer number to a string in hexadecimal base. + * @brief Converts an integer number to a string in hexadecimal base. + * + * @details This function converts @a n to a null terminated string. The + * converted string is in hexadecimal base and the alphabetical + * cyphers are in lower case. As no check is done, @a s must be a + * buffer that is sufficiently large to store the integer. * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. + * @since_tizen 2.3 * - * This function converts @p n to a nul terminated string. The - * converted string is in hexadecimal base and the alphabetical - * cyphers are in lower case. As no check is done, @p s must be a - * buffer that is sufficiently large to store the integer. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] n The integer to convert + * @param[in] s The buffer to store the converted integer + * @return The length of the string, including the null terminated + * character * - * The returned value is the length of the string, including the nul - * terminated character. */ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2); /** - * @brief Convert a double to a string. + * @brief Converts a double to a string. * - * @param d The double to convert. - * @param des The destination buffer to store the converted double. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function converts the double @a d to a string. The string is + * stored in the buffer pointed by @a des and must be sufficiently + * large to contain the converted double. The returned string is null + * terminated and has the following format: * - * This function converts the double @p d to a string. The string is - * stored in the buffer pointed by @p des and must be sufficiently - * large to contain the converted double. The returned string is nul - * terminated and has the following format: + * @since_tizen 2.3 * * @code * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the + * where h are the hexadecimal cyphers of the mantissa and e is the * exponent (a decimal number). * - * The returned value is the length of the string, including the nul - * character. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] d The double to convert + * @param[in] des The destination buffer to store the converted double + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); /** - * @brief Convert a string to a double. + * @brief Converts a string to a double. * - * @param src The string to convert. - * @param length The length of the string. - * @param m The mantisse. - * @param e The exponent. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function converts the string @a s of length @a length that + * represents a double in hexadecimal base to a double. It is used to + * replace the use of snprintf() with the modifier, which is + * missing on some platform (like Windows (tm) or OpenBSD). * - * This function converts the string @p s of length @p length that - * represent a double in hexadecimal base to a double. It is used to - * replace the use of snprintf() with the \%a modifier, which is - * missing on some platform (like Windows (tm) or OpenBSD). + * @since_tizen 2.3 * * The string must have the following format: * @@ -242,20 +252,33 @@ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: + * where h are the hexadecimal cyphers of the mantissa and e is the + * exponent (a decimal number). If n is the number of cyphers after the + * point, the returned mantissa and exponent are: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. + * The mantissa and exponent are stored in the buffers pointed + * by @a m and @a e respectively. + * + * If the string is invalid, the error is set to: * - * If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND - If no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct. + * + * In those cases, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is * returned. + * + * @param[in] src The string to convert + * @param[in] length The length of the string + * @param[out] m The mantissa + * @param[out] e The exponent + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_convert_atod(const char *src, int length, @@ -264,47 +287,45 @@ EAPI Eina_Bool eina_convert_atod(const char *src, /** - * @brief Convert a 32.32 fixed point number to a string. + * @brief Converts a 32.32 fixed point number to a string. * - * @param fp The fixed point number to convert. - * @param des The destination buffer to store the converted fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the 32.32 fixed point number @p fp to a - * string. The string is stored in the buffer pointed by @p des and - * must be sufficiently large to contain the converted fixed point - * number. The returned string is terminated and has the following - * format: + * @details This function converts the 32.32 fixed point number @a fp to a + * string. The string is stored in the buffer pointed by @a des and + * must be sufficiently large to contain the converted fixed point + * number. The returned string is terminated and has the following + * format: * * @code * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the + * where h are the hexadecimal cyphers of the mantissa and e is the * exponent (a decimal number). * - * The returned value is the length of the string, including the nul - * character. + * @since_tizen 2.3 + * + * @remarks The returned value is the length of the string, including the null + * terminating character. + * + * @remarks The code is the same as eina_convert_dtoa() except that it + * implements the frexp() function for fixed point numbers and does + * some optimisations. + * + * @param[in] fp The fixed point number to convert + * @param[in] des The destination buffer to store the converted fixed point number + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @note The code is the same than eina_convert_dtoa() except that it - * implements the frexp() function for fixed point numbers and does - * some optimisations. */ EAPI int eina_convert_fptoa(Eina_F32p32 fp, char *des) EINA_ARG_NONNULL(2); /** - * @brief Convert a string to a 32.32 fixed point number. + * @brief Converts a string to a 32.32 fixed point number. * - * @param src The string to convert. - * @param length The length of the string. - * @param fp The fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the string @p src of length @p length that - * represent a double in hexadecimal base to a 32.32 fixed point - * number stored in @p fp. The function always tries to convert the - * string with eina_convert_atod(). + * @details This function converts the string @a src of length @a length that + * represents a double in hexadecimal base to a 32.32 fixed point + * number stored in @a fp. The function always tries to convert the + * string with eina_convert_atod(). * * The string must have the following format: * @@ -312,23 +333,37 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp, * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: + * where h are the hexadecimal cyphers of the mantissa and e is the + * exponent (a decimal number). If n is the number of cyphers after the + * point, the returned mantissa and exponent are: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. + * The mantissa and exponent are stored in the buffers pointed + * by @a m and @a e respectively. + * + * @remarks If the string is invalid, the error is set to: * - * If the string is invalid, #EINA_FALSE is returned, - * otherwise @p fp is computed and #EINA_TRUE is returned. + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND If no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct. + * + * In those cases, or if @a fp is @c NULL, @c EINA_FALSE is returned, + * otherwise @a fp is computed and @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @remarks The code uses eina_convert_atod() and does the correct bit + * shift to compute the fixed point number. + * + * @param[in] src The string to convert + * @param[in] length The length of the string + * @param[out] fp The fixed point number + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @note The code uses eina_convert_atod() and do the correct bit - * shift to compute the fixed point number. */ EAPI Eina_Bool eina_convert_atofp(const char *src, int length, @@ -338,8 +373,4 @@ EAPI Eina_Bool eina_convert_atofp(const char *src, * @} */ -/** - * @} - */ - #endif /* EINA_CONVERT_H_ */ diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h index e871774aa2..19be53047d 100644 --- a/src/lib/eina/eina_cpu.h +++ b/src/lib/eina/eina_cpu.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. aSee the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -19,30 +19,8 @@ #ifndef EINA_CPU_H_ #define EINA_CPU_H_ -/** - * @addtogroup Eina_Cpu_Group Cpu - * - * @brief Cpu and architecture related helpers - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** - * @defgroup Eina_Cpu_Group Cpu - * - * @{ - */ - #include "eina_types.h" -/** - * @typedef Eina_Cpu_Features - * Enumerates different hardware architectures. - */ typedef enum _Eina_Cpu_Features { EINA_CPU_MMX = 0x00000001, @@ -53,83 +31,9 @@ typedef enum _Eina_Cpu_Features EINA_CPU_ALTIVEC = 0x00000010, EINA_CPU_VIS = 0x00000020, EINA_CPU_NEON = 0x00000040, - EINA_CPU_SSSE3 = 0x00000080, - EINA_CPU_SSE41 = 0x00000100, - EINA_CPU_SSE42 = 0x00000200 } Eina_Cpu_Features; -/** - * @brief Global hardware architecture handler - * - * @return the current cpu features - */ -EAPI extern Eina_Cpu_Features eina_cpu_features; - -/** - * @brief Cpu features accessor - * - * @return the current cpu features - */ EAPI Eina_Cpu_Features eina_cpu_features_get(void); - -/** - * @brief Get the current number of precessors - * - * @return the number of processors that are online, that - * is available when the function is called. - */ EAPI int eina_cpu_count(void); -/** - * @brief Get the current virtual page size - * - * @return the fixed length that represents the smallest unit of data for memory - * allocation performed by the operating system on behalf of the program, and - * for transfers between the main memory and any other auxiliary store. - */ -EAPI int eina_cpu_page_size(void); - -/** - * @brief Reverses the byte order of a 16-bit (destination) register. - * - * @param x The binary word to swap - * @return a byte order swapped 16-bit integer. - * - * On big endian systems, the number is converted to little endian byte order. - * On little endian systems, the number is converted to big endian byte order. - */ -static inline unsigned short eina_swap16(unsigned short x); - -/** - * @brief Reverses the byte order of a 32-bit (destination) register. - * - * @param x The binary word to swap - * @return a byte order swapped 32-bit integer. - * - * On big endian systems, the number is converted to little endian byte order. - * On little endian systems, the number is converted to big endian byte order. - */ -static inline unsigned int eina_swap32(unsigned int x); - -/** - * @brief Reverses the byte order of a 64-bit (destination) register. - * - * @param x The binary word to swap - * @return a byte order swapped 64-bit integer. - * - * On big endian systems, the number is converted to little endian byte order. - * On little endian systems, the number is converted to big endian byte order. - */ -static inline unsigned long long eina_swap64(unsigned long long x); - -#include "eina_inline_cpu.x" - -/** - * @} - */ - -/** - * @} - */ - #endif /* EINA_CPU_H_ */ diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h index 7a169a20f5..236bd1018d 100644 --- a/src/lib/eina/eina_fp.h +++ b/src/lib/eina/eina_fp.h @@ -2,14 +2,14 @@ * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * Copyright (C) 2009 Cedric BAIL * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -20,24 +20,6 @@ #ifndef EINA_FP_H_ # define EINA_FP_H_ -/** - * @addtogroup Eina_Fp_Group Fp - * - * @brief Floating point numbers data type management. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Fp_Group Fp - * - * @{ - */ - #include "eina_types.h" #ifdef _MSC_VER @@ -48,436 +30,77 @@ typedef signed int int32_t; # include <stdint.h> #endif -/** - * @def EINA_F32P32_PI - * @brief Yields the 32-bit PI constant - */ #define EINA_F32P32_PI 0x00000003243f6a89 -/** - * @typedef Eina_F32p32 - * Type for floating point number where the size of the integer part is 32-bit - * and the size of the decimal part is 32-bit - */ typedef int64_t Eina_F32p32; - -/** - * @typedef Eina_F16p16 - * Type for floating point number where the size of the integer part is 16-bit - * and the size of the decimal part is 16-bit - */ typedef int32_t Eina_F16p16; - -/** - * @typedef Eina_F8p24 - * Type for floating point number where the size of the integer part is 8-bit - * and the size of the decimal part is 24bits - */ typedef int32_t Eina_F8p24; -/** - * @brief Create a new Eina_F32p32 floating point number from standard 32-bit - * integer - * - * @param v 32-bit integer value to convert - * @return The value converted into Eina_F32p32 format - */ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v); - -/** - * @brief Create a new standard 32-bit integer from Eina_F32p32 floating point - * number - * - * @param v Eina_F32p32 value to convert - * @return The value converted into 32-bit integer - */ static inline int32_t eina_f32p32_int_to(Eina_F32p32 v); - -/** - * @brief Create a new Eina_F32p32 floating point number from standard double - * - * @param v double value to convert - * @return The value converted into Eina_F32p32 format - */ static inline Eina_F32p32 eina_f32p32_double_from(double v); - -/** - * @brief Create a new standard double from Eina_F32p32 floating point - * number - * - * @param v Eina_F32p32 value to convert - * @return The value converted into double - */ static inline double eina_f32p32_double_to(Eina_F32p32 v); -/** - * @brief Calculates the sum of two Eina_F32p32 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The sum result of the two numbers @p a + @p b - */ -static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 b); - -/** - * @brief Calculates the substraction of two Eina_F32p32 floating point numbers - * - * @param a The first number - * @param b The substracted number - * @return The substaction result of the two numbers @p a - @p b - */ -static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b); - -/** - * @brief Calculates the multiplication of two Eina_F32p32 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The mutliplication result of the two numbers @p a * @p b - * - * To prevent overflow during multiplication we need to reduce the precision of - * the fraction part Shift both values to only contain 16 bit of the fraction - * part (rounded). After multiplication we again have a value with a 32-bit - * fraction part. - */ -static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b); - -/** - * @brief Calculates the scale multiplication of one Eina_F32p32 floating point - * number with an integer - * - * @param a The Eina_F32p32 number - * @param b The integer value - * @return The mutliplication result of the two numbers @p a * @p b - */ -static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b); - -/** - * @brief Calculates the division of two Eina_F32p32 floating point numbers - * - * @param a The numerator number - * @param b The denominator number - * @return The division result of the two numbers @p a / @p b - */ -static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b); - -/** - * @brief Calculates the square root of an Eina_F32p32 floating point number - * - * @param a The number to calculate the square root from - * @return The square root result for the number @p a - */ +static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, + Eina_F32p32 b); +static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, + Eina_F32p32 b); +static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, + Eina_F32p32 b); +static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, + int b); +static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, + Eina_F32p32 b); static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a); - -/** - * @brief Get the absolute value of the integer part of and Eina_F32p32 floating - * point number - * - * @param a The floating point number - * @return The positive integer part of the number @p a - */ static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v); -/** - * @brief Get the absolute value of an Eina_F32p32 floating point number - * - * @param a The floating point number - * @return The absolute value for the number @p a - * @warning Has known issues on 64-bit architecture, prefer - * eina_f32p32_fracc_get() instead - */ +// dont use llabs - issues if not on 64bit #define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a)) -/** - * @brief Calculates the cosinus of a floating point number - * - * @param a The angle in radians to calculate the cosinus from. - * @return The cosinus value of the angle @p a - */ EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a); - -/** - * @brief Calculates the sinus of a floating point number - * - * @param a The angle in radians to calculate the sinus from. - * @return The cosinus value of the angle @p a - */ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a); - -/** - * @def EINA_F16P16_ONE - * - * Yields the maximum 16-bit unsigned integer size (= 65536) - */ -#define EINA_F16P16_ONE (1 << 16) - -/** - * @def EINA_F16P16_HALF - * - * Yields the maximum 16-bit signed integer size (= 32768) - */ -#define EINA_F16P16_HALF (1 << 15) - -/** - * @brief Create a new Eina_F16p316 floating point number from standard 32-bit - * integer - * - * @param v 32-bit integer value to convert - * @return The value converted into Eina_F16p16 format - */ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v); - -/** - * @brief Create a new standard 32-bit integer from Eina_F16p16 floating point - * number - * - * @param v Eina_F16p16 value to convert - * @return The value converted into 32-bit integer - */ static inline int32_t eina_f16p16_int_to(Eina_F16p16 v); - -/** - * @brief Create a new Eina_F16p16 floating point number from standard double - * - * @param v double value to convert - * @return The value converted into Eina_F16p16 format - */ -static inline Eina_F16p16 eina_f16p16_double_from(double v); - -/** - * @brief Create a new standard double from Eina_F16p16 floating point - * number - * - * @param v Eina_F16p16 value to convert - * @return The value converted into double - */ -static inline double eina_f16p16_double_to(Eina_F16p16 v); - -/** - * @brief Create a new Eina_F16p16 floating point number from standard float - * - * @param v float value to convert - * @return The value converted into Eina_F16p16 format - */ static inline Eina_F16p16 eina_f16p16_float_from(float v); - -/** - * @brief Create a new standard float from Eina_F16p16 floating point - * number - * - * @param v Eina_F16p16 value to convert - * @return The value converted into float - */ static inline float eina_f16p16_float_to(Eina_F16p16 v); -/** - * @brief Calculates the sum of two Eina_F16p16 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The sum result of the two numbers @p a + @p b - */ -static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 b); - -/** - * @brief Calculates the substraction of two Eina_F16p16 floating point numbers - * - * @param a The first number - * @param b The substracted number - * @return The substaction result of the two numbers @p a - @p b - */ -static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b); - -/** - * @brief Calculates the multiplication of two Eina_F16p16 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The mutliplication result of the two numbers @p a * @p b - */ -static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b); - -/** - * @brief Calculates the scale multiplication of one Eina_F16p16 floating point - * number with an integer - * - * @param a The Eina_F16p16 number - * @param b The integer value - * @return The mutliplication result of the two numbers @p a * @p b - */ -static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b); - -/** - * @brief Calculates the division of two Eina_F16p16 floating point numbers - * - * @param a The numerator number - * @param b The denominator number - * @return The division result of the two numbers @p a / @p b - */ -static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b); - -/** - * @brief Calculates the square root of an Eina_F16p16 floating point number - * - * @param a The number to calculate the square root from - * @return The square root result for the number @p a - */ +static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, + Eina_F16p16 b); +static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, + Eina_F16p16 b); +static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, + Eina_F16p16 b); +static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, + int b); +static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, + Eina_F16p16 b); static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a); - -/** - * @brief Get the absolute value of the integer part of and Eina_F16p16 floating - * point number - * - * @param a The floating point number - * @return The positive integer part of the number @p a - */ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v); - -/** - * @brief Create a new Eina_F16p316 floating point number from standard 32-bit - * integer - * - * @param v 32-bit integer value to convert - * @return The value converted into Eina_F8p24 format - */ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v); - -/** - * @brief Create a new standard 32-bit integer from Eina_F8p24 floating point - * number - * - * @param v Eina_F8p24 value to convert - * @return The value converted into 32-bit integer - */ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); - -/** - * @brief Create a new Eina_F8p24 floating point number from standard float - * - * @param v float value to convert - * @return The value converted into Eina_F8p24 format - */ static inline Eina_F8p24 eina_f8p24_float_from(float v); - -/** - * @brief Create a new standard float from Eina_F8p24 floating point number - * - * @param v Eina_F8p24 value to convert - * @return The value converted into float - */ static inline float eina_f8p24_float_to(Eina_F8p24 v); -/** - * @brief Calculates the sum of two Eina_F8p24 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The sum result of the two numbers @p a + @p b - */ -static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 b); - -/** - * @brief Calculates the substraction of two Eina_F8p24 floating point numbers - * - * @param a The first number - * @param b The substracted number - * @return The substaction result of the two numbers @p a - @p b - */ -static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b); - -/** - * @brief Calculates the multiplication of two Eina_F8p24 floating point numbers - * - * @param a The first number - * @param b The second number - * @return The mutliplication result of the two numbers @p a * @p b - */ -static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b); - -/** - * @brief Calculates the scale multiplication of one Eina_F8p24 floating point - * number with an integer - * - * @param a The Eina_F16p16 number - * @param b The integer value - * @return The mutliplication result of the two numbers @p a * @p b - */ -static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b); - -/** - * @brief Calculates the division of two Eina_F8p24 floating point numbers - * - * @param a The numerator number - * @param b The denominator number - * @return The division result of the two numbers @p a / @p b - */ -static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b); - -/** - * @brief Calculates the square root of an Eina_F8p24 floating point number - * - * @param a The number to calculate the square root from - * @return The square root result for the number @p a - */ +static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, + Eina_F8p24 b); +static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, + Eina_F8p24 b); +static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, + Eina_F8p24 b); +static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, + int b); +static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, + Eina_F8p24 b); static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a); - -/** - * @brief Get the absolute value of the integer part of and Eina_F8p24 floating - * point number - * - * @param a The floating point number - * @return The positive integer part of the number @p a - */ static inline unsigned int eina_f8p24_fracc_get(Eina_F8p24 v); -/** - * @brief Converts an Eina_F16p16 floating point number into Eina_F32p32 format - * - * @param a The Eina_F16p16 floating point number - * @return The converted Eina_F32p32 floating point number - */ static inline Eina_F32p32 eina_f16p16_to_f32p32(Eina_F16p16 a); - -/** - * @brief Converts an Eina_F8p24 floating point number into Eina_F32p32 format - * - * @param a The Eina_F8p24 floating point number - * @return The converted Eina_F32p32 floating point number - */ static inline Eina_F32p32 eina_f8p24_to_f32p32(Eina_F8p24 a); - -/** - * @brief Converts an Eina_F32p32 floating point number into Eina_F16p16 format - * - * @param a The Eina_F32p32 floating point number - * @return The converted Eina_F16p16 floating point number - */ static inline Eina_F16p16 eina_f32p32_to_f16p16(Eina_F32p32 a); - -/** - * @brief Converts an Eina_F8p24 floating point number into Eina_F16p16 format - * - * @param a The Eina_F8p24 floating point number - * @return The converted Eina_F16p16 floating point number - */ static inline Eina_F16p16 eina_f8p24_to_f16p16(Eina_F8p24 a); - -/** - * @brief Converts an Eina_F32p32 floating point number into Eina_F8p24 format - * - * @param a The Eina_F32p32 floating point number - * @return The converted Eina_F8p16 floating point number - */ static inline Eina_F8p24 eina_f32p32_to_f8p24(Eina_F32p32 a); - -/** - * @brief Converts an Eina_F16p16 floating point number into Eina_F8p16 format - * - * @param a The Eina_F16p16 floating point number - * @return The converted Eina_F8p16 floating point number - */ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f32p32.x" @@ -485,12 +108,4 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f8p24.x" #include "eina_inline_fp.x" -/** - * @} - */ - -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_hamster.h b/src/lib/eina/eina_hamster.h index bea759d57f..3bc58da3dd 100644 --- a/src/lib/eina/eina_hamster.h +++ b/src/lib/eina/eina_hamster.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -20,30 +20,24 @@ #define EINA_HAMSTER_H_ /** - * @addtogroup Eina_Hamster_Group Hamster + * @internal + * @defgroup Eina_Hamster_Group Hamster + * @ingroup Eina_Core_Group * - * @brief These functions provide hamster calls. + * @brief This group discusses the functions that provide hamster calls. * * @{ */ -/** - * @addtogroup Eina_Core_Group Core - * - * @{ - */ /** - * @defgroup Eina_Hamster_Group Hamster - */ - - -/** - * @brief Get the hamster count. + * @brief Gets the hamster count. * - * @return The number of available hamsters. + * @since_tizen 2.3 * - * This function returns how many hamsters you have. + * @details This function returns the number of hamsters that are available. + * + * @return The number of available hamsters */ EAPI int eina_hamster_count(void); @@ -51,8 +45,4 @@ EAPI int eina_hamster_count(void); * @} */ -/** - * @} - */ - #endif /* EINA_HAMSTER_H_ */ diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h index 4681a47164..3e256a5b64 100644 --- a/src/lib/eina/eina_hash.h +++ b/src/lib/eina/eina_hash.h @@ -2,14 +2,14 @@ * Copyright (C) 2002-2008 Carsten Haitzler, Gustavo Sverzut Barbieri, * Vincent Torri, Jorge Luis Zapata Muga, Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -24,152 +24,21 @@ #include "eina_iterator.h" /** - * @page hash_01_example_page Eina_Hash in action - * @dontinclude eina_hash_01.c - * - * We are going to store some tuples into our table, that will map each @a name - * to a @a number. The cost to access a given number from the name should be - * very small, even with many entries in our table. This is the initial data: - * @skip _Phone_Entry - * @until // _start_entries - * - * Before starting to play with the hash, let's write a callback that will be - * used to free the elements from it. Since we are just storing strduped - * strings, we just need to free them: - * - * @skip static - * @until } - * - * We also need a callback to iterate over the elements of the list later, so - * we are defining it now: - * - * @skip Eina_Bool - * @until } - * - * Now let's create our @ref Eina_Hash using @ref - * eina_hash_string_superfast_new : - * - * @skip eina_init - * @until phone_book - * - * Now we add the keys and data to the hash using @ref eina_hash_add . This - * means that the key is copied inside the table, together with the pointer to - * the data (phone numbers). - * - * @skip for - * @until } - * - * Some basic manipulations with the hash, like finding a value given a key, - * deleting an entry, modifying an entry are exemplified in the following lines. - * Notice that the @ref eina_hash_modify function returns the old value stored - * in that entry, and it needs to be freed, while the @ref eina_hash_del - * function already calls our free callback: - * - * @skip Look for - * @until free( - * - * The @ref eina_hash_set function can be used to set a key-value entry to the - * table if it doesn't exist, or to modify an existent entry. It returns the old - * entry if it was already set, and NULL otherwise. But since it will - * return NULL on error too, we need to check if an error has occurred: - * - * @skip Modify - * @until printf("\n"); - * - * There are different ways of iterate over the entries of a hash. Here we show - * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator . - * - * @skip List of phones - * @until eina_iterator_free(it); - * - * It's also possible to change the key for a specific entry, without having to - * remove the entry from the table and adding it again: - * - * @skipline eina_hash_move - * - * We can remove all the elements from the table without free the table itself: - * - * @skip Empty the phone book - * @until eina_hash_population - * - * Or free the the entire table with its content: - * - * @skipline eina_hash_free - * - * - * The full code for this example can be seen here: @ref eina_hash_01_c - */ - -/** - * @page eina_hash_01_c Hash table in action - * - * @include eina_hash_01.c - * @example eina_hash_01.c - */ - -/** - * @page hash_02_example_page Different types of tables - * - * This example shows two more types of hash tables that can be created using - * @ref Eina_Hash . For more types, consult the reference documentation of @ref - * eina_hash_new. - * @include eina_hash_02.c - * @example eina_hash_02.c - */ - -/** - * @example eina_hash_03.c - * Same example as @ref hash_01_example_page but using a "string small" hash - * table instead of "string superfast". - */ - -/** - * @example eina_hash_04.c - * Same example as @ref hash_01_example_page but using a "string djb2" hash - * table instead of "string superfast". - */ - -/** - * @example eina_hash_05.c - * Same example as @ref hash_01_example_page but using a "int32" hash - * table instead of "string superfast". - */ - -/** - * @example eina_hash_06.c - * Same example as @ref hash_01_example_page but using a "int64" hash - * table instead of "string superfast". - */ - -/** - * @example eina_hash_07.c - * Same example as @ref hash_01_example_page but using a "pointer" hash - * table instead of "string superfast". - */ - -/** - * @example eina_hash_08.c - * This example shows the the usage of eina_hash_add(), eina_hash_add_by_hash(), - * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_hash(), - * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash() and - * eina_hash_modify_by_hash(). - */ - -/** - * @addtogroup Eina_Hash_Group Hash Table + * @defgroup Eina_Hash_Group Hash Table + * @ingroup Eina_Containers_Group * - * @brief Hash table management. Useful for mapping keys to values. + * @brief Performs hash table management. It is useful for mapping keys to values. * - * The hash table is useful for when one wants to implement a table that maps + * The hash table is useful when one wants to implement a table that maps * keys (usually strings) to data, and have relatively fast access time. The * performance is proportional to the load factor of the table (number of * elements / number of buckets). See @ref hashtable_algo for implementation * details. * - * Different implementations exists depending on what kind of key will be used - * to access the data: strings, integers, pointers, stringshared or your own. + * Different implementations exist depending on what kind of key is used + * to access the data: strings, integers, pointers, stringshared, or your own key. * - * Eina hash tables can copy the keys when using eina_hash_add() or not when + * Eina hash tables can copy keys by using eina_hash_add() or not copy by * using eina_hash_direct_add(). * * @section hashtable_algo Algorithm @@ -178,46 +47,44 @@ * bucket is a pointer to a structure that is the head of a <a * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The * array can then be indexed by the [hash_of_element mod N]. The - * hash_of_element is calculated using the hashing function, passed as + * hash_of_element is calculated using the hashing function, passed as a * parameter to the @ref eina_hash_new function. N is the number of buckets * (array positions), and is calculated based on the buckets_power_size - * (argument of @ref eina_hash_new too). The following picture illustrates the + * (argument of @ref eina_hash_new too). The following picture ilustrates the * basic idea: * - * @htmlonly - * <img src="01_hash-table.png" width="500" /> - * @endhtmlonly + * @image html 01_hash-table.png * @image latex 01_hash-table.eps * - * Adding an element to the hash table is made of: - * @li calculating the hash for that key (using the specified hash function); - * @li calculate the array position [hash mod N]; - * @li add the element to the rbtree on that position. + * Adding an element to the hash table consists of: + * @li Calculating the hash for that key (using the specified hash function); + * @li Calculating the array position [hash mod N]; + * @li Adding the element to the rbtree at that position. * - * The two first steps have constant time, proportional to the hash function - * being used. Adding the key to the rbtree will be proportional on the number + * The first two steps have constant time, proportional to the hash function + * being used. Adding the key to the rbtree is proportional to the number * of keys on that bucket. * * The average cost of lookup depends on the number of keys per - * bucket (load factor) of the table, if the distribution of keys is + * bucket (load factor) of the table, if the distribution of the keys is * sufficiently uniform. * * @section hashtable_perf Performance * * As said before, the performance depends on the load factor. So trying to keep - * the load factor as small as possible will improve the hash table performance. But - * increasing the buckets_power_size will also increase the memory consumption. + * the load factor as small as possible improves the hash table performance. But + * increasing the buckets_power_size also increases the memory consumption. * The default hash table creation functions already have a good number of * buckets, enough for most cases. Particularly for strings, if just a few keys - * (less than 30) will be added to the hash table, @ref - * eina_hash_string_small_new should be used, since it will reduce the memory + * (less than 30) are added to the hash table, @ref + * eina_hash_string_small_new should be used, since it reduces the memory * consumption for the buckets, and you still won't have many collisions. * However, @ref eina_hash_string_small_new still uses the same hash calculation - * function that @ref eina_hash_string_superfast_new, which is more complex than + * function that @ref eina_hash_string_superfast_new uses, which is more complex than * @ref eina_hash_string_djb2_new. The latter has a faster hash computation - * function, but that will imply on a not so good distribution. But if just a - * few keys are being added, this is not a problem, it will still have not many - * collisions and be faster to calculate the hash than in a hash created with + * function, but that implies to a not so good distribution. But if just a + * few keys are being added, this is not a problem, it still does not have many + * collisions and is faster in calculating the hash than when a hash is created with * @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new. * * A simple comparison between them would be: @@ -226,64 +93,30 @@ * @li @c string_small - slower hash function but less collisions - 32 buckets * (lower memory consumption) * @li @c string_superfast - slower hash function but less collisions - 256 buckets - * (higher memory consumption) - not randomized, avoid it on public remote interface. + * (higher memory consumption) * * Basically for a very small number of keys (10 or less), @c djb2 should be * used, or @c string_small if you have a restriction on memory usage. And for a - * higher number of keys, @c string_superfast should be preferred if not used on a - * public remote interface. + * higher number of keys, @c string_superfast should always be preferred. * * If just stringshared keys are being added, use @ref - * eina_hash_stringshared_new. If a lot of keys will be added to the hash table + * eina_hash_stringshared_new. If a lot of keys are added to the hash table * (e.g. more than 1000), then it's better to increase the buckets_power_size. * See @ref eina_hash_new for more details. * * When adding a new key to a hash table, use @ref eina_hash_add or @ref - * eina_hash_direct_add (the latter if this key is already stored elsewhere). If + * eina_hash_direct_add (the latter is if this key is already stored elsewhere). If * the key may be already inside the hash table, instead of checking with * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref - * eina_hash_set (this will change the data pointed by this key if it was + * eina_hash_set (this changes the data pointed by this key if it is * already present in the table). * - * @section hashtable_tutorial Tutorial - * - * These examples show many Eina_Hash functions in action: - * <ul> - * <li> @ref hash_01_example_page - * <li> @ref hash_02_example_page - * <li> Different types of hash in use: - * <ul> - * <li> @ref eina_hash_03.c "string small" - * <li> @ref eina_hash_04.c "string djb2" - * <li> @ref eina_hash_05.c "int32" - * <li> @ref eina_hash_06.c "int64" - * <li> @ref eina_hash_07.c "pointer" - * </ul> - * <li> @ref eina_hash_08.c "Different add and delete functions" - * </ul> - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** - * @defgroup Eina_Hash_Group Hash Table - * * @{ */ /** * @typedef Eina_Hash - * Type for a generic hash table. + * @brief The structure type for a generic hash table. */ typedef struct _Eina_Hash Eina_Hash; @@ -309,10 +142,9 @@ struct _Eina_Hash_Tuple * Type for a function to determine the length of a hash key. */ typedef unsigned int (*Eina_Key_Length)(const void *key); - /** * @def EINA_KEY_LENGTH - * @param Function The function used to calculate length of hash key. + * @param Function The function used to calculate the length of the hash key */ #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) @@ -323,7 +155,7 @@ typedef unsigned int (*Eina_Key_Length)(const void *key); typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length); /** * @def EINA_KEY_CMP - * @param Function The function used to compare hash key. + * @param Function The function used to compare the hash key */ #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) @@ -334,7 +166,7 @@ typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const vo typedef int (*Eina_Key_Hash)(const void *key, int key_length); /** * @def EINA_KEY_HASH - * @param Function The function used to hash key. + * @param Function The function used to hash the key. */ #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) @@ -346,33 +178,36 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key /** - * @brief Create a new hash table. - * - * @param key_length_cb The function called when getting the size of the key. - * @param key_cmp_cb The function called when comparing the keys. - * @param key_hash_cb The function called when getting the values. - * @param data_free_cb The function called on each value when the hash table is - * freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @param buckets_power_size The size of the buckets. - * @return The new hash table. - * - * This function creates a new hash table using user-defined callbacks - * to manage the hash table. On failure, @c NULL is returned. - * If @p key_cmp_cb or @p key_hash_cb - * are @c NULL, @c NULL is returned. If @p buckets_power_size is - * smaller or equal than 2, or if it is greater or equal than 17, - * @c NULL is returned. - * - * The number of buckets created will be 2 ^ @p buckets_power_size. This means - * that if @p buckets_power_size is 5, there will be created 32 buckets. for a - * @p buckets_power_size of 8, there will be 256 buckets. - * - * Pre-defined functions are available to create a hash table. See - * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), - * eina_hash_string_small_new(), eina_hash_int32_new(), - * eina_hash_int64_new(), eina_hash_pointer_new() and - * eina_hash_stringshared_new(). + * @brief Creates a new hash table. + * + * @details This function creates a new hash table using user-defined callbacks + * to manage the hash table. On failure, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. If @a key_cmp_cb or @a key_hash_cb + * are @c NULL, @c NULL is returned. If @a buckets_power_size is + * smaller than or equal to 2, or if it is greater than or equal to 17, + * @c NULL is returned. + * + * @since_tizen 2.3 + * + * @remarks The number of buckets created are 2 ^ @a buckets_power_size. This means + * that if @a buckets_power_size is 5, it creates 32 buckets. For a + * @a buckets_power_size of 8, it creates 256 buckets. + * + * @remarks Pre-defined functions are available to create a hash table. See + * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), + * eina_hash_string_small_new(), eina_hash_int32_new(), + * eina_hash_int64_new(), eina_hash_pointer_new(), and + * eina_hash_stringshared_new(). + * + * @param[in] key_length_cb The function called when getting the size of the key + * @param[in] key_cmp_cb The function called when comparing the keys + * @param[in] key_hash_cb The function called when getting the values + * @param[in] data_free_cb The function called on each value when the hash table is + * freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @param[in] buckets_power_size The size of the buckets + * @return The new hash table + * */ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, Eina_Key_Cmp key_cmp_cb, @@ -381,124 +216,133 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); /** - * @brief Redefine the callback that clean the data of a hash + * @brief Redefines the callback that cleans the data of a hash. * - * @param hash The given hash table - * @param data_free_cb The function called on each value when the hash - * table is freed, or when an item is deleted from it. @c NULL can be passed as - * callback to remove an existing callback. + * @since 1.1 * - * The argument received by @p data_free_cb will be that data of the item being - * removed. + * @since_tizen 2.3 * - * @since 1.1 - * @see eina_hash_new. + * @remarks The argument received by @a data_free_cb is the data of the item being + * removed. + * + * @param[in] hash The given hash table + * @param[in] data_free_cb The function called on each value when the hash + * table is freed, or when an item is deleted from it \n + * @c NULL can be passed as + * callback to remove an existing callback. + * + * @see eina_hash_new */ EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1); /** - * @brief Create a new hash table using the djb2 algorithm. + * @brief Creates a new hash table using the djb2 algorithm. * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. + * @details This function creates a new hash table using the djb2 algorithm for + * table management and strcmp() to compare the keys. Values can then + * be looked up with pointers other than the original key pointer that + * is used to add values. On failure, this function returns @c NULL. * - * This function creates a new hash table using the djb2 algorithm for - * table management and strcmp() to compare the keys. Values can then - * be looked up with pointers other than the original key pointer that - * was used to add values. On failure, this function returns @c NULL. + * @since_tizen 2.3 + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * + * @return The new hash table */ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table for use with strings. + * @brief Creates a new hash table for use with strings. * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. + * @details This function creates a new hash table using the superfast algorithm + * for table management and strcmp() to compare the keys. Values can + * then be looked up with pointers other than the original key pointer + * that is used to add values. On failure, this function returns + * @c NULL. * - * This function creates a new hash table using the superfast algorithm - * for table management and strcmp() to compare the keys. Values can - * then be looked up with pointers other than the original key pointer - * that was used to add values. On failure, this function returns - * @c NULL. + * @since_tizen 2.3 * - * NOTE: don't use this kind of hash when their is a possibility to remotely - * request and push data in it. This hash is subject to denial of service. + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table */ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table for use with strings with small bucket size. - * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. - * - * This function creates a new hash table using the superfast algorithm - * for table management and strcmp() to compare the keys, but with a - * smaller bucket size (compared to eina_hash_string_superfast_new()) - * which will minimize the memory used by the returned hash - * table. Values can then be looked up with pointers other than the - * original key pointer that was used to add values. On failure, this - * function returns @c NULL. + * @brief Creates a new hash table for use with strings having a small bucket size. + * + * @details This function creates a new hash table using the superfast algorithm + * for table management and strcmp() to compare the keys, but with a + * smaller bucket size (compared to eina_hash_string_superfast_new()), + * which minimizes the memory used by the returned hash + * table. Values can then be looked up with pointers other than the + * original key pointer that is used to add values. On failure, this + * function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table */ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table for use with 32bit integers. - * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. - * - * This function creates a new hash table where keys are 32bit integers. - * When adding or looking up in the hash table, pointers to 32bit integers - * must be passed. They can be addresses on the stack if you let the - * eina_hash copy the key. Values can then - * be looked up with pointers other than the original key pointer that was - * used to add values. This method is not suitable to match string keys as - * it would only match the first character. - * On failure, this function returns @c NULL. + * @brief Creates a new hash table for use with 32 bit integers. + * + * @details This function creates a new hash table where keys are 32 bit integers. + * When adding or looking up in the hash table, pointers to 32 bit integers + * must be passed. They can be addresses on the stack if you let + * eina_hash copy the key. Values can then + * be looked up with pointers other than the original key pointer that is + * used to add values. This method is not suitable to match string keys as + * it would only match the first character. + * On failure, this function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table + * */ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table for use with 64bit integers. - * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. - * - * This function creates a new hash table where keys are 64bit integers. - * When adding or looking up in the hash table, pointers to 64bit integers - * must be passed. They can be addresses on the stack. Values can then - * be looked up with pointers other than the original key pointer that was - * used to add values. This method is not suitable to match string keys as - * it would only match the first character. - * On failure, this function returns @c NULL. + * @brief Creates a new hash table for use with 64 bit integers. + * + * @details This function creates a new hash table where keys are 64 bit integers. + * When adding or looking up in the hash table, pointers to 64 bit integers + * must be passed. They can be addresses on the stack. Values can then + * be looked up with pointers other than the original key pointer that is + * used to add values. This method is not suitable to match string keys as + * it would only match the first character. + * On failure, this function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table + * */ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table for use with pointers. - * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. + * @brief Creates a new hash table for use with pointers. * - * This function creates a new hash table using the int64/int32 algorithm for - * table management and dereferenced pointers to compare the - * keys. Values can then be looked up with pointers other than the - * original key pointer that was used to add values. This method may - * appear to be able to match string keys, actually it only matches - * the first character. On failure, this function returns @c NULL. + * @details This function creates a new hash table using the int64/int32 algorithm for + * table management and dereferenced pointers to compare the + * keys. Values can then be looked up with pointers other than the + * original key pointer that is used to add values. This method may + * appear to be able to match string keys, actually it only matches + * the first character. On failure, this function returns @c NULL. * * @code * // For a hash that will have only one pointer to each structure @@ -508,23 +352,28 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); * if (!eina_hash_find(hash, &data)) * eina_hash_add(hash, &data, data); * @endcode + * + * @since_tizen 2.3 + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table + * */ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); /** - * @brief Create a new hash table optimized for stringshared values. + * @brief Creates a new hash table optimized for stringshared values. * - * @param data_free_cb The function called on each value when the hash table - * is freed, or when an item is deleted from it. @c NULL can be passed as - * callback. - * @return The new hash table. + * @details This function creates a new hash table optimized for stringshared + * values. Values CANNOT be looked up with pointers not + * equal to the original key pointer that is used to add a value. On failure, + * this function returns @c NULL. * - * This function creates a new hash table optimized for stringshared - * values. Values CAN NOT be looked up with pointers not - * equal to the original key pointer that was used to add a value. On failure, - * this function returns @c NULL. + * @since_tizen 2.3 * - * Excerpt of code that will NOT work with this type of hash: + * An Excerpt of a code that does NOT work with this type of hash: * * @code * extern Eina_Hash *hash; @@ -532,173 +381,208 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); * const char *a = eina_stringshare_add("key"); * * eina_hash_add(hash, a, value); - * eina_hash_find(hash, "key"); + * eina_hash_find(hash, "key") * @endcode + * + * @param[in] data_free_cb The function called on each value when the hash table + * is freed, or when an item is deleted from it \n + * @c NULL can be passed as a callback. + * @return The new hash table + * */ EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); /** - * @brief Add an entry to the given hash table. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param data Data to associate with the string given by @p key. Cannot be @c - * NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function adds @p key to @p hash. @p key is - * expected to be unique within the hash table. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need to have unique pointers (which implies unique strings). - * All other string hash types require the strings - * themselves to be unique. Pointer, int32 and int64 hashes need to have these - * values as unique. Failure to use sufficient uniqueness will - * result in unexpected results when inserting data pointers accessed - * with eina_hash_find(), and removed with eina_hash_del(). Key - * strings are case sensitive. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. + * @brief Adds an entry to the given hash table. + * + * @details This function adds @a key to @a hash. @a key is + * expected to be unique within the hash table. The key's uniqueness varies + * depending on the type of @a hash: a stringshared @ref Eina_Hash + * needs to have unique pointers (which implies unique strings). + * All other string hash types require the strings + * themselves to be unique. Pointer, int32 and int64 hashes need to have these + * values as unique. Failure to use sufficient uniqueness + * results in unexpected results when inserting data pointers accessed + * by eina_hash_find() and removed by eina_hash_del(). + * + * @since_tizen 2.3 + * + * @remarks Key strings are case sensitive. If an error occurs, eina_error_get() + * should be used to determine if an allocation error occurred during + * this function. This function returns @c EINA_FALSE if an error + * occurs, otherwise it returns @c EINA_TRUE. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key A unique key \n + * It cannot be @c NULL. + * @param[in] data The data to associate with the string given by @a key \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Add an entry to the given hash table without duplicating the string - * key. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param data Data to associate with the string given by @p key. Cannot be @c - * NULL - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function adds @p key to @p hash. @p key is - * expected to be unique within the hash table. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need have unique pointers (which implies unique strings). - * All other string hash types require the strings - * themselves to be unique. Pointer, int32 and int64 hashes need to have these - * values as unique. Failure to use sufficient uniqueness will - * result in unexpected results when inserting data pointers accessed - * with eina_hash_find(), and removed with eina_hash_del(). This - * function does not make a copy of @p key, so it must be a string - * constant or stored elsewhere ( in the object being added). Key - * strings are case sensitive. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. + * @brief Adds an entry to the given hash table without duplicating the string + * key. + * + * @details This function adds @a key to @a hash. @a key is + * expected to be unique within the hash table. The key's uniqueness varies + * depending on the type of @a hash: a stringshared @ref Eina_Hash + * needs to have unique pointers (which implies unique strings). + * All other string hash types require the strings + * themselves to be unique. Pointer, int32 and int64 hashes need to have these + * values as unique. Failure to use sufficient uniqueness + * results in unexpected results when inserting data pointers accessed + * by eina_hash_find() and removed by eina_hash_del(). + * + * @since_tizen 2.3 + * + * @remarks This function does not make a copy of @a key, so it must be a string + * constant or should be stored elsewhere (in the object being added). Key + * strings are case sensitive. If an error occurs, eina_error_get() + * should be used to determine if an allocation error occurred during + * this function. This function returns @c EINA_FALSE if an error + * occurs, otherwise @c EINA_TRUE. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key A unique key \n + * It cannot be @c NULL. + * @param[in] data The data to associate with the string given by @a key \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, ptherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Remove the entry identified by a key or a data from the given - * hash table. - * - * @param hash The given hash table. - * @param key The key. - * @param data The data pointer to remove if the key is @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function removes the entry identified by @p key or @p data - * from @p hash. If a free function was given to the - * callback on creation, it will be called for the data being - * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE. - * If @p key is @c NULL, then @p data is used to find the a - * match to remove, otherwise @p key is used and @p data is not - * required and can be @c NULL. This function returns #EINA_FALSE if - * an error occurred, #EINA_TRUE otherwise. - * - * @note if you know you already have the key, use - * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you - * know you don't have the key, use eina_hash_del_by_data() - * directly. + * @brief Removes the entry identified by a key or data from the given + * hash table. + * + * @details This function removes the entry identified by @a key or @a data + * from @a hash. If a free function is given to the + * callback on creation, it is called for the data being + * deleted. If @a hash is @c NULL, the functions returns @c EINA_FALSE immediately. + * If @a key is @c NULL, then @a data is used to find the + * match to remove, otherwise @a key is used and @a data is not + * required and can be @c NULL. This function returns @c EINA_FALSE if + * an error occurs, otherwise it returns EINA_TRUE. + * + * @since_tizen 2.3 + * + * @remarks If you already have the key, use + * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you + * don't have the key, use eina_hash_del_by_data() directly. + * + * @param[in] hash The given hash table + * @param[in] key The key + * @param[in] data The data pointer to remove if the key is @c NULL + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1); /** - * @brief Retrieve a specific entry in the given hash table. + * @brief Finds a specific entry in the given hash table. * - * @param hash The given hash table. - * @param key The key of the entry to find. - * @return The data pointer for the stored entry on success, @c NULL - * otherwise. + * @details This function retrieves the entry associated to @a key in + * @a hash. If @a hash is @c NULL, this function returns + * @c NULL immediately. This function returns the data pointer on success, + * otherwise it returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @param[in] key The key of the entry to find + * @return The data pointer for the stored entry on success, otherwise @c NULL * - * This function retrieves the entry associated to @p key in - * @p hash. If @p hash is @c NULL, this function returns immediately - * @c NULL. This function returns the data pointer on success, @c NULL - * otherwise. */ EAPI void *eina_hash_find(const Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(2); /** - * @brief Modify the entry pointer at the specified key and return the old - * entry. - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param data The data to replace the old entry. - * @return The data pointer for the old stored entry on success, or - * @c NULL otherwise. - * - * This function modifies the data of @p key with @p data in @p - * hash. If no entry is found, nothing is added to @p hash. On success - * this function returns the old entry, otherwise it returns @c NULL. + * @brief Modifies the entry pointer at the specified key and returns the old + * entry. + * + * @details This function modifies the data of @a key with @a data in @a + * hash. If no entry is found, nothing is added to @a hash. On success + * this function returns the old entry, otherwise it returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @param[in] key The key of the entry to modify + * @param[in] data The data used to replace the old entry + * @return The data pointer for the old stored entry on success, + * otherwise @c NULL */ EAPI void *eina_hash_modify(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Modify the entry pointer at the specified key and return the - * old entry or add the entry if not found. - * - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param data The data to replace the old entry - * @return The data pointer for the old stored entry, or @c NULL - * otherwise. - * - * This function modifies the data of @p key with @p data in @p - * hash. If no entry is found, @p data is added to @p hash with the - * key @p key. On success this function returns the old entry, - * otherwise it returns @c NULL. + * @brief Modifies the entry pointer at the specified key and returns the + * old entry or adds the entry if not found. + * + * @details This function modifies the data of @a key with @a data in @a + * hash. If no entry is found, @a data is added to @a hash with the + * key @a key. On success, this function returns the old entry, + * otherwise it returns @c NULL. To check for errors, use + * eina_error_get(). + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @param[in] key The key of the entry to modify + * @param[in] data The data used to replace the old entry + * @return The data pointer for the old stored entry on success, + * otherwise @c NULL */ EAPI void *eina_hash_set(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2); /** - * @brief Change the key associated with a data without triggering the - * free callback. + * @brief Changes the key associated with the data without triggering the + * free callback. * - * @param hash The given hash table. - * @param old_key The current key associated with the data - * @param new_key The new key to associate data with - * @return #EINA_FALSE in any case but success, #EINA_TRUE on success. + * @details This function allows for the move of data from one key to another, + * but does not call the Eina_Free_Cb associated with the hash table + * when destroying the old key. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @param[in] old_key The current key associated with the data + * @param[in] new_key The new key to associate the data with + * @return @c EINA_FALSE in any case but success, otherwise @c EINA_TRUE on success * - * This function allows for the move of data from one key to another, - * but does not call the Eina_Free_Cb associated with the hash table - * when destroying the old key. */ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, const void *old_key, const void *new_key) EINA_ARG_NONNULL(1, 2, 3); /** - * Free the given hash table resources. + * @brief Frees the given hash table resources. * - * @param hash The hash table to be freed. + * @details This function frees up all the memory allocated to storing @a hash, + * and calls the free callback if it has been passed to the hash table + * at creation time. If no free callback has been passed, any entries + * in the table that the program has no more pointers for elsewhere + * may now be lost, so this should only be called if the program has + * already freed any allocated data in the hash table or has + * pointers for data in the table stored elsewhere as well. If @a hash + * is @c NULL, the function returns immediately. * - * This function frees up all the memory allocated to storing @p hash, - * and call the free callback if it has been passed to the hash table - * at creation time. If no free callback has been passed, any entries - * in the table that the program has no more pointers for elsewhere - * may now be lost, so this should only be called if the program has - * already freed any allocated data in the hash table or has the - * pointers for data in the table stored elsewhere as well. If @p hash - * is @c NULL, the function returns immediately. + * @since_tizen 2.3 * * Example: * @code @@ -707,55 +591,70 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, * eina_hash_free(hash); * hash = NULL; * @endcode + * + * @param[in] hash The hash table to be freed + * */ EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); /** - * Free the given hash table buckets resources. + * @brief Frees the given hash table buckets resources. + * + * @details This function frees up all the memory allocated to storing the + * buckets of @a hash, and calls the free callback on all hash table + * buckets if it has been passed to the hash table at creation time, + * it then frees the buckets. If no free callback has been passed, no + * buckets value are freed. If @a hash is @c NULL, the function + * returns immediately. + * + * @since_tizen 2.3 * - * @param hash The hash table whose buckets have to be freed. + * @param[in] hash The hash table whose buckets have to be freed * - * This function frees up all the memory allocated to storing the - * buckets of @p hash, and calls the free callback on all hash table - * buckets if it has been passed to the hash table at creation time, - * then frees the buckets. If no free callback has been passed, no - * buckets value will be freed. If @p hash is @c NULL, the function - * returns immediately. */ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); /** * @brief Returns the number of entries in the given hash table. * - * @param hash The given hash table. - * @return The number of entries in the hash table. + * @details This function returns the number of entries in @a hash, or @c 0 on + * error. If @a hash is @c NULL, @c 0 is returned. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @return The number of entries in the hash table * - * This function returns the number of entries in @p hash, or 0 on - * error. If @p hash is @c NULL, @c 0 is returned. */ EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); /** - * @brief Add an entry to the given hash table. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param key_length The length of the key. - * @param key_hash The hash that will always match key. - * @param data The data to associate with the string given by the key. Cannot be - * @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function adds @p key to @p hash. @p hash, @p key and @p data - * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is - * expected to be a unique within the hash table. Otherwise, - * one cannot be sure which inserted data pointer will be accessed - * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do - * not forget to count '\\0' for string when setting the value of - * @p key_length. @p key_hash is expected to always match - * @p key. Otherwise, one cannot be sure to find it again with @ref - * eina_hash_find_by_hash. Key strings are case sensitive. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * @brief Adds an entry to the given hash table. + * + * @details This function adds @a key to @a hash. @a hash, @a key, and @a data + * cannot be @c NULL, in that case @c EINA_FALSE is returned. @a key is + * expected to be unique within the hash table. Otherwise, + * one cannot be sure which inserted data pointer is accessed + * by @ref eina_hash_find, and removed by @ref eina_hash_del. Do + * not forget to count '\\0' for string when setting the value of + * @a key_length. @a key_hash is expected to always match + * @a key. Otherwise, one cannot be sure to find it again with @ref + * eina_hash_find_by_hash. Key strings are case sensitive. If an error + * occurs, eina_error_get() should be used to determine if an + * allocation error occurred during this function. This function + * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key A unique key \n + * It cannot be @c NULL. + * @param[in] key_length The length of the key + * @param[in] key_hash The hash that always matches the key + * @param[in] data The data to associate with the string given by the key \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE * * @see eina_hash_add() */ @@ -766,30 +665,36 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); /** - * @brief Add an entry to the given hash table and do not duplicate the string - * key. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param key_length Should be the length of @p key (don't forget to count - * '\\0' for string). - * @param key_hash The hash that will always match key. - * @param data Data to associate with the string given by @p key. Cannot be @c - * NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function adds @p key to @p hash. @p hash, @p key and @p data - * can be @c NULL, in that case #EINA_FALSE is returned. @p key is - * expected to be unique within the hash table. Otherwise, - * one cannot be sure which inserted data pointer will be accessed - * with @ref eina_hash_find, and removed with @ref eina_hash_del. This - * function does not make a copy of @p key so it must be a string - * constant or stored elsewhere (in the object being added). Do - * not forget to count '\\0' for string when setting the value of - * @p key_length. @p key_hash is expected to always match - * @p key. Otherwise, one cannot be sure to find it again with @ref - * eina_hash_find_by_hash. Key strings are case sensitive. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * @brief Adds an entry to the given hash table and does not duplicate the string + * key. + * + * @details This function adds @a key to @a hash. @a hash, @a key, and @a data + * can be @c NULL, in that case @c EINA_FALSE is returned. @a key is + * expected to be unique within the hash table. Otherwise, + * one cannot be sure which inserted data pointer is going to be accessed + * by @ref eina_hash_find, and removed by @ref eina_hash_del. This + * function does not make a copy of @a key so it must be a string + * constant or should be stored elsewhere (in the object being added). Do + * not forget to count '\\0' for string when setting the value of + * @a key_length. @a key_hash is expected to always match + * @a key. Otherwise, one cannot be sure to find it again with @ref + * eina_hash_find_by_hash. Key strings are case sensitive. If an error + * occurs, eina_error_get() should be used to determine if an + * allocation error occurred during this function. This function + * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key A unique key \n + * It cannot be @c NULL. + * @param[in] key_length The length of @a key (don't forget to count + * '\\0' for string). + * @param[in] key_hash The hash that always matches the key. + * @param[in] data The data to associate with the string given by @a key \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE * * @see eina_hash_direct_add() */ @@ -800,25 +705,29 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); /** - * @brief Remove the entry identified by a key and a key hash from the given - * hash table. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key. Cannot be @c NULL. - * @param key_length The length of the key. - * @param key_hash The hash that always match the key. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function removes the entry identified by @p key and - * @p key_hash from @p hash. If a free function was given to the - * callback on creation, it will be called for the data being - * deleted. Do not forget to count '\\0' for string when setting the - * value of @p key_length. If @p hash or @p key are @c NULL, the - * functions returns immediately #EINA_FALSE. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * @note if you don't have the key_hash, use eina_hash_del_by_key() instead. - * @note if you don't have the key, use eina_hash_del_by_data() instead. + * @brief Removes the entry identified by a key and a key hash from the given + * hash table. + * + * @details This function removes the entry identified by @a key and + * @a key_hash from @a hash. If a free function is given to the + * callback on creation, it is called for the data being + * deleted. Do not forget to count '\\0' for string when setting the + * value of @a key_length. If @a hash or @a key is @c NULL, the + * functions return @c EINA_FALSE immediately. This function + * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @remarks If you don't have the key_hash, use eina_hash_del_by_key() instead. + * @remarks If you don't have the key, use eina_hash_del_by_data() instead. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key The key \n + * It cannot be @c NULL. + * @param[in] key_length The length of the key + * @param[in] key_hash The hash that always matches the key + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE */ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, const void *key, @@ -826,81 +735,92 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, int key_hash) EINA_ARG_NONNULL(1, 2); /** - * @brief Remove the entry identified by a key from the given hash table. - * - * This version will calculate key length and hash by using functions - * provided to hash creation function. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key. Cannot be @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function removes the entry identified by @p key from @p - * hash. The key length and hash will be calculated automatically by - * using functiond provided to has creation function. If a free - * function was given to the callback on creation, it will be called - * for the data being deleted. If @p hash or @p key are @c NULL, the - * functions returns immediately #EINA_FALSE. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * @note if you already have the key_hash, use eina_hash_del_by_key_hash() - * instead. - * @note if you don't have the key, use eina_hash_del_by_data() instead. + * @brief Removes the entry identified by a key from the given hash table. + * + * @details This function removes the entry identified by @a key from @a + * hash. The key length and hash is calculated automatically by + * using functions provided to the hash creation function. If a free + * function is given to the callback on creation, it is called + * for the data being deleted. If @a hash or @a key is @c NULL, the + * functions return @c EINA_FALSE immediately. This function + * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @remarks If you already have the key_hash, use eina_hash_del_by_key_hash() + * instead. + * @remarks If you don't have the key, use eina_hash_del_by_data() instead. + * + * @remarks This version calculates the key length and hash by using functions + * provided to the hash creation function. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key The key \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(1, 2); /** - * @brief Remove the entry identified by a data from the given hash table. + * @brief Removes the entry identified by data from the given hash table. * - * This version is slow since there is no quick access to nodes based on data. + * @details This function removes the entry identified by @a data from @a + * hash. If a free function is given to the callback on creation, it + * is called for the data being deleted. If @a hash or @a data + * is @c NULL, the functions return @c EINA_FALSE immediately. This + * function returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. * - * @param hash The given hash table. Cannot be @c NULL. - * @param data The data value to search and remove. Cannot be @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * thing goes fine. + * @since_tizen 2.3 * - * This function removes the entry identified by @p data from @p - * hash. If a free function was given to the callback on creation, it - * will be called for the data being deleted. If @p hash or @p data - * are @c NULL, the functions returns immediately #EINA_FALSE. This - * function returns #EINA_FALSE if an error occurred, #EINA_TRUE - * otherwise. + * @remarks If you already have the key, use eina_hash_del_by_key() or + * eina_hash_del_by_key_hash() instead. * - * @note if you already have the key, use eina_hash_del_by_key() or - * eina_hash_del_by_key_hash() instead. + * @remarks This version is slow since there is no quick access to nodes based on the data. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] data The data value to search and remove \n + * It cannot be @c NULL. + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE on success */ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2); /** - * @brief Remove the entry identified by a key and a key hash or a - * data from the given hash table. - * - * If @p key is @c NULL, then @p data is used to find a match to - * remove. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key. - * @param key_length The length of the key. - * @param key_hash The hash that always match the key. - * @param data The data pointer to remove if the key is @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * This function removes the entry identified by @p key and - * @p key_hash, or @p data, from @p hash. If a free function was given to - * the callback on creation, it will be called for the data being - * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE. - * If @p key is @c NULL, then @p key_length and @p key_hash - * are ignored and @p data is used to find a match to remove, - * otherwise @p key and @p key_hash are used and @p data is not - * required and can be @c NULL. Do not forget to count '\\0' for - * string when setting the value of @p key_length. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * @note if you know you already have the key, use eina_hash_del_by_key_hash(), - * if you know you don't have the key, use eina_hash_del_by_data() - * directly. + * @brief Removes the entry identified by a key and a key hash or the + * data from the given hash table. + * + * @details This function removes the entry identified by @a key and + * @a key_hash, or @a data, from @a hash. If a free function is given to + * the callback on creation, it is called for the data being + * deleted. If @a hash is @c NULL, the functions return @c EINA_FALSE immediately. + * If @a key is @c NULL, then @a key_length and @a key_hash + * are ignored and @a data is used to find a match to remove, + * otherwise @a key and @a key_hash are used and @a data is not + * required and can be @c NULL. Do not forget to count '\\0' for + * string when setting the value of @a key_length. This function + * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @remarks If you already have the key, use eina_hash_del_by_key_hash(). + * If you don't have the key, use eina_hash_del_by_data() + * directly. + * + * @remarks If @a key is @c NULL, then @a data is used to find a match to + * remove. + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key The key + * @param[in] key_length The length of the key + * @param[in] key_hash The hash that always matches the key + * @param[in] data The data pointer to remove if the key is @c NULL + * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE + * */ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *key, @@ -909,21 +829,24 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1); /** - * @brief Retrieve a specific entry in the given hash table. - * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key of the entry to find. - * @param key_length The length of the key. - * @param key_hash The hash that always match the key - * @return The data pointer for the stored entry on success, @c NULL - * otherwise. - * - * This function retrieves the entry associated to @p key of length - * @p key_length in @p hash. @p key_hash is the hash that always match - * @p key. It is ignored if @p key is @c NULL. Do not forget to count - * '\\0' for string when setting the value of @p key_length. If - * @p hash is @c NULL, this function returns immediately @c NULL. This - * function returns the data pointer on success, @c NULL otherwise. + * @brief Retrieves a specific entry in the given hash table. + * + * @details This function retrieves the entry associated to @a key of length + * @a key_length in @a hash. @a key_hash is the hash that always matches + * @a key. It is ignored if @a key is @c NULL. Do not forget to count + * '\\0' for string when setting the value of @a key_length. If + * @a hash is @c NULL, this function returns @c NULL immediately. This + * function returns the data pointer on success, otherwise it returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table \n + * It cannot be @c NULL. + * @param[in] key The key of the entry to find + * @param[in] key_length The length of the key + * @param[in] key_hash The hash that always matches the key + * @return The data pointer for the stored entry on success, + * otherwise @c NULL */ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, const void *key, @@ -931,19 +854,22 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, int key_hash) EINA_ARG_NONNULL(1, 2); /** - * @brief Modify the entry pointer at the specified key and returns - * the old entry. - * - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param key_length Should be the length of @p key (don't forget to count - * '\\0' for string). - * @param key_hash The hash that always match the key. Ignored if @p key is - * @c NULL. - * @param data The data to replace the old entry, if it exists. - * @return The data pointer for the old stored entry, or @c NULL if not - * found. If an existing entry is not found, nothing is added to the - * hash. + * @brief Modifies the entry pointer at the specified key and returns + * the old entry. + * + * @since_tizen 2.3 + * + * @param[in] hash The given hash table + * @param[in] key The key of the entry to modify + * @param[in] key_length The length of @a key (don't forget to count + * '\\0' for string) + * @param[in] key_hash The hash that always matches the key \n + * It is ignored if @a key is @c NULL. + * @param[in] data The data to replace the old entry, if it exists + * @return The data pointer for the old stored entry, otherwise @c NULL if not + * found \n + * If an existing entry is not found, nothing is added to the + * hash. */ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, const void *key, @@ -952,80 +878,90 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); /** - * @brief Returned a new iterator associated to hash keys. + * @brief Returns a new iterator associated to hash keys. + * + * @details This function returns a newly allocated iterator associated to @a + * hash. If @a hash is not populated, this function still returns a + * valid iterator that always returns @c false on a call to + * eina_iterator_next(), thus keeping the API sane. * - * @param hash The hash. - * @return A new iterator. + * @since_tizen 2.3 * - * This function returns a newly allocated iterator associated to @p - * hash. If @p hash is not populated, this function still returns a - * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * If the memory can not be allocated, NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the hash structure changes, the iterator becomes + * invalid. That is, if you add or remove items this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] hash The hash + * @return A new iterator * - * @warning if the hash structure changes then the iterator becomes - * invalid! That is, if you add or remove items this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new iterator associated to hash data. + * @brief Returns a new iterator associated to hash data. + * + * @details This function returns a newly allocated iterator associated to + * @a hash. If @a hash is not populated, this function still returns a + * valid iterator that always returns @c false on a call to + * eina_iterator_next(), thus keeping the API sane. * - * @param hash The hash. - * @return A new iterator. + * @since_tizen 2.3 * - * This function returns a newly allocated iterator associated to - * @p hash. If @p hash is not populated, this function still returns a - * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the hash structure changes then the iterator becomes + * invalid. That is, if you add or remove items this iterator's behavior + * is undefined and your program may crash. + * + * @param[in] hash The hash + * @return A new iterator * - * @warning if the hash structure changes then the iterator becomes - * invalid. That is, if you add or remove items this iterator behavior - * is undefined and your program may crash. */ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new iterator associated to hash keys and data. + * @brief Returns a new iterator associated to hash keys and data. + * + * @details This function returns a newly allocated iterator associated to @a + * hash. If @a hash is not populated, this function still returns a + * valid iterator that always returns @c false on a call to + * eina_iterator_next(), thus keeping the API sane. + * + * @since_tizen 2.3 * - * @param hash The hash. - * @return A new iterator. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * This function returns a newly allocated iterator associated to @p - * hash. If @p hash is not populated, this function still returns a - * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. + * @remarks The iterator data provides values as Eina_Hash_Tuple that should not + * be modified. * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the hash structure changes then the iterator becomes + * invalid. That is, if you add or remove items this iterator's + * behavior is undefined and your program may crash. * - * @note iterator data will provide values as Eina_Hash_Tuple that should not - * be modified! + * @param[in] hash The hash + * @return A new iterator * - * @warning if the hash structure changes then the iterator becomes - * invalid! That is, if you add or remove items this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Call a function on every member stored in the hash table + * @brief Calls a function on every member stored in the hash table. * - * @param hash The hash table whose members will be walked - * @param func The function to call on each parameter - * @param fdata The data pointer to pass to the function being called + * @details This function goes through every entry in the hash table @a hash and calls + * the function @a func on each member. The function should @b not modify the + * hash table contents if it returns @c 1. @b If the hash table contents are + * modified by this function or the function wishes to stop processing it, it must + * return @c 0, otherwise it must return @c 1 to keep processing. * - * This function goes through every entry in the hash table @p hash and calls - * the function @p func on each member. The function should @b not modify the - * hash table contents if it returns @c 1. @b If the hash table contents are - * modified by this function or the function wishes to stop processing it must - * return @c 0, otherwise return @c 1 to keep processing. + * @since_tizen 2.3 * * Example: * @code @@ -1048,125 +984,107 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL * free(hash_fn_data); * } * @endcode + * + * @param[in] hash The hash table whose members are walked + * @param[in] func The function to call on each parameter + * @param[in] fdata The data pointer to pass to the function being called */ EAPI void eina_hash_foreach(const Eina_Hash *hash, Eina_Hash_Foreach func, const void *fdata) EINA_ARG_NONNULL(1, 2); - - /** - * @brief Append data to an #Eina_List inside a hash - * - * This function is identical to the sequence of calling - * eina_hash_find(), eina_list_append(), eina_hash_set(), - * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to append to the list - * @since 1.10 - */ -EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); -/** - * @brief Append data to an #Eina_List inside a hash - * - * This function is identical to the sequence of calling - * eina_hash_find(), eina_list_append(), eina_hash_set(), - * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to append to the list - * @since 1.10 - */ -EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); -/** - * @brief Append data to an #Eina_List inside a hash - * - * This function is identical to the sequence of calling - * eina_hash_find(), eina_list_append(), eina_hash_set(), - * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to append to the list - * @since 1.10 - */ -EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); - -/** - * @brief - * Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) - * - * @param key The key to hash - * @param len The length of the key + * @brief Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash + * function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) + * + * @since_tizen 2.3 + * + * @param[in] key The key to hash + * @param[in] len The length of the key * @return The hash value */ EAPI int eina_hash_superfast(const char *key, int len) EINA_ARG_NONNULL(1); -/** - * @brief - * Hash function first reported by Dan Bernstein many years ago in comp.lang.c - * - * @param key The key to hash - * @param len The length of the key +/** + * @details The djb2 hash function + * + * @since_tizen 2.3 + * + * @remarks djb2 hash algorithm was first reported by dan bernstein, and was + * the old default hash function for evas. + * + * @remarks This hash function first reported by dan bernstein many years ago + * in comp.lang.c + * + * @param[in] key The key to hash + * @param[in] len The length of the key * @return The hash value */ static inline int eina_hash_djb2(const char *key, int len) EINA_ARG_NONNULL(1); -/** - * @brief - * Hash function first reported by Dan Bernstein many years ago in comp.lang.c - * - * @param key The key to hash - * @param plen The length of the key + +/** + * @details The djb2 hash function withoug length + * + * @since_tizen 2.3 + * + * @remarks djb2 hash algorithm was first reported by dan bernstein, and was + * the old default hash function for evas. + * + * @remarks This hash function first reported by dan bernstein many years ago + * in comp.lang.c + * + * @param[in] key The key to hash + * @param[out] plen The length of the key to be returned * @return The hash value */ static inline int eina_hash_djb2_len(const char *key, int *plen) EINA_ARG_NONNULL(1, 2); -/** - * @brief - * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm - * - * @param pkey The key to hash - * @param len The length of the key +/** + * @details The 32 bit integer hash function + * + * @since_tizen 2.3 + * + * @remarks Hash function from + * http://www.concentric.net/~Ttwang/tech/inthash.htm + * + * @param[in] pkey The key to hash + * @param[in] len The length of the key * @return The hash value */ static inline int eina_hash_int32(const unsigned int *pkey, int len) EINA_ARG_NONNULL(1); -/** - * @brief - * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm - * - * @param pkey The key to hash - * @param len The length of the key + +/** + * @details The 64 bit integer hash function + * + * @since_tizen 2.3 + * + * @param[in] pkey The key to hash + * @param[in] len The length of the key * @return The hash value */ -static inline int eina_hash_int64(const unsigned long long int *pkey, +static inline int eina_hash_int64(const unsigned long int *pkey, int len) EINA_ARG_NONNULL(1); -/** - * @brief - * Hash function from http://sites.google.com/site/murmurhash/ - * - * @param key The key to hash - * @param len The length of the key +/** + * @details The murmur3 hash function + * + * @since_tizen 2.3 + * + * @remarks http://sites.google.com/site/murmurhash/ + * + * @param[in] key The key to hash + * @param[in] len The length of the key * @return The hash value */ static inline int eina_hash_murmur3(const char *key, int len) EINA_ARG_NONNULL(1); - #include "eina_inline_hash.x" /** * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif /*EINA_HASH_H_*/ diff --git a/src/lib/eina/eina_inarray.h b/src/lib/eina/eina_inarray.h index 34e7380841..a75f354c4a 100644 --- a/src/lib/eina/eina_inarray.h +++ b/src/lib/eina/eina_inarray.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2012 ProFUSION embedded systems * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -24,138 +24,13 @@ #include "eina_accessor.h" /** - * @page eina_inarray_example_01 Eina inline array usage - * @dontinclude eina_inarray_01.c - * - * This example creates an inline array of chars, adds some elements, prints - * them, re-purposes the array to store ints, adds some elements and print that. - * - * We are going to start with a function to compare ints. We need this because the '>' - * operator is not a function and can't be used where Eina_Compare_Cb is needed. - * @skip int - * @until } - * - * And then move on to the code we actually care about, starting with variable - * declarations and eina initialization: - * @until eina_init - * - * Creating an inline array is very simple, we just need to know what type we - * want to store: - * @until inarray_new - * @note The second parameter(the step) is left at zero which means that eina - * chooses an appropriate value, this should @b only be changed if it's - * known, beforehand, that how many elements the array has. - * - * Once we have an array we can start adding elements to it. Because the - * insertion function expects a memory address we have to put the value we want - * to store in a variable(this should be no problem since in the real world usage - * that's usually where the value is anyways): - * @until push - * @note Because the inline array copies the value given to it we can later - * change @c ch, which we do, without affecting the contents of the array. - * - * So let's add some more elements: - * @until push - * @until push - * @until push - * - * We then iterate over our array and print every position of it. The thing - * to note here is not so much the values, which are the expected 'a', 'b', - * 'c', and 'd', but rather the memory address of these values, they are - * sequential: - * @until printf - * @until printf - * - * We are now going to use our array to store ints, so we need to first erase every member - * currently on the array: - * @until _flush - * - * And then to be able to store a different type on the same array, we use the - * eina_inarray_step_set() function, which is just like the eina_inarray_new() - * function except it receives an already allocated memory. This time we're going - * to ask eina to use a step of size 4 because that's how many elements we are going to - * put in the array: - * @until _step_set - * @note Strictly speaking the reason to call eina_inarray_step_set() is not - * because we're storing a different type, but because our types have - * different sizes. Eina inline arrays don't actually know anything about types, - * they only deal with blocks of memory of a given size. - * @note Since eina_inarray_step_set() receives already allocated memory, you can(and - * it is in fact a good practice) use inline arrays that are not declared as pointers: - * @code - * Eina_Inarray arr; - * eina_inarray_step_set(&arr, sizeof(arr), sizeof(int), 4); - * @endcode - * - * And now to add our integer values to the array: - * @until push - * @until push - * @until push - * - * Just to change things up a bit we've left out the 99 value, but we still - * add it in such a way that it keeps the array ordered. There are many ways to do - * this, we could use eina_inarray_insert_at(), or we could change the value - * of the last member using eina_inarray_replace_at() and then append the values - * in the right order, but for no particular reason we're going to use - * eina_inarray_insert_sorted() instead: - * @until insert_sorted - * - * We then print the size of our array, and the array itself, much like last - * time the values are not surprising, and neither should it be that the memory - * addresses are contiguous: - * @until printf - * @until printf - * - * Once done we free our array and shutdown eina: - * @until } - * - * The source for this example: @ref eina_inarray_01_c - */ - -/** - * @page eina_inarray_01_c eina_inarray_01.c - * @include eina_inarray_01.c - * @example eina_inarray_01.c - */ - -/** - * @page eina_inarray_example_02 Eina inline array of strings - * @dontinclude eina_inarray_02.c - * - * This example creates an inline array of strings, adds some elements, and - * then prints them. This example is based on @ref eina_array_01_example_page and - * @ref eina_inarray_example_01. - * - * We start with some variable declarations and eina initialization: - * @skip int - * @until eina_init - * - * We then create the array much like we did on @ref eina_inarray_example_01 : - * @until inarray_new - * - * The point is this example significantly differs from the first eina inline - * array example. We are not going to add the strings themselves to the array since - * their size varies, we are going to store a pointer to the strings instead. We therefore - * use @c char** to populate our inline array: - * @until } - * - * The source for this example: @ref eina_inarray_02_c - */ - -/** - * @page eina_inarray_02_c eina_inarray_02.c - * @include eina_inarray_02.c - * @example eina_inarray_02.c - */ - -/** * @defgroup Eina_Inline_Array_Group Inline Array * @ingroup Eina_Containers_Group * @since 1.2 * - * @brief Inline array is a container that stores the data itself, not the pointers to the data. + * @brief Inline array is a container that stores the data itself, not the pointers to the data, * - * This means there is no memory fragmentation, also for small data types(such + * this means there is no memory fragmentation, also for small data types(such * as char, short, int, and so on) it's more memory efficient. * * Usage of the inline array is very similar to that of other @@ -163,29 +38,23 @@ * of the array is a lot more costly than appending, so those operations should * be minimized. * - * Examples: - * @li @ref eina_inarray_example_01 - * @li @ref eina_inarray_example_02 - * * @{ */ /** * @typedef Eina_Inarray - * @brief Type for the inlined array. + * @brief The structure type for the inlined array type. * * @since 1.2 */ typedef struct _Eina_Inarray Eina_Inarray; /** - * @brief Inline array structure. - * - * @note Use #Eina_Inarray instead. + * @brief Inline array structure, use #Eina_Inarray typedef instead. * - * @note Do not modify these fields directly, use eina_inarray_step_set() or - * eina_inarray_new() instead. + * @details Do not modify these fields directly, use eina_inarray_step_set() or + * eina_inarray_new() instead. * * @since 1.2 */ @@ -205,21 +74,24 @@ struct _Eina_Inarray /** * @brief Creates a new inline array. * - * @param[in] member_size The size of each member in the array - * @param[in] step The step size by which to resize the array, do this using the following - * extra amount - * @return The new inline array table, otherwise @c NULL on failure - * * @details This creates a new array where members are inlined in a sequence. Each * member has @a member_size bytes. * - * @note If the @a step is @c 0, then a safe default is chosen. + * @since 1.2 * - * @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned. + * @since_tizen 2.3 * - * @see eina_inarray_free() + * @remarks If the @a step is @c 0, then a safe default is chosen. * - * @since 1.2 + * @remarks On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. If @a member_size is zero, then @c NULL is returned. + * + * @param[in] member_size The size of each member in the array + * @param[in] step The step size by which to resize the array, do this using the following + * extra amount + * @return The new inline array table, otherwise @c NULL on failure + * + * @see eina_inarray_free() */ EAPI Eina_Inarray *eina_inarray_new(unsigned int member_size, unsigned int step) EINA_MALLOC EINA_WARN_UNUSED_RESULT; @@ -227,32 +99,37 @@ EAPI Eina_Inarray *eina_inarray_new(unsigned int member_size, /** * @brief Frees an array and its members. * + * @since 1.2 + * + * @since_tizen 2.3 + * * @param[in] array The array object * * @see eina_inarray_flush() * - * @since 1.2 */ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1); /** * @brief Initializes an inline array. * + * @details This initializes an array. If the @a step is @c 0, then a safe default is + * chosen. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks This is useful for arrays inlined into other structures or + * allocated to a stack. + * * @param[in] array The array object to initialize * @param[in] sizeof_eina_inarray The size of array object * @param[in] member_size The size of each member in the array * @param[in] step The step size by which to resize the array, do this using the following - * extra amount - * - * @details This initializes an array. If the @p step is @c 0, then a safe default is - * chosen. - * - * @note This is useful for arrays inlined into other structures or - * allocated to a stack. + * extra amount * * @see eina_inarray_flush() - * - * @since 1.2 */ EAPI void eina_inarray_step_set(Eina_Inarray *array, unsigned int sizeof_eina_inarray, @@ -262,65 +139,59 @@ EAPI void eina_inarray_step_set(Eina_Inarray *array, /** * @brief Removes every member from the array. * + * @since 1.2 + * + * @since_tizen 2.3 * * @param[in] array The array object * - * @since 1.2 */ EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1); /** * @brief Copies the data as the last member of the array. * - * @param[in] array The array object - * @param[in] data The data to be copied at the end - * @return The index of the new member, otherwise @c -1 on errors - * * @details This copies the given pointer contents at the end of the array. The * pointer is not referenced, instead its contents are copied to the * members array using the previously defined @c member_size. * - * @see eina_inarray_insert_at() - * * @since 1.2 - */ -EAPI int eina_inarray_push(Eina_Inarray *array, - const void *data) EINA_ARG_NONNULL(1, 2); - -/** - * @brief Allocate new item at the end of the array. + * + * @since_tizen 2.3 * * @param[in] array The array object - * @param[in] size The number of new item to allocate + * @param[in] data The data to be copied at the end + * @return The index of the new member, otherwise @c -1 on errors * - * @note The returned pointer is only valid until you use any other eina_inarray - * function. + * @see eina_inarray_insert_at() * - * @since 1.8 */ -EAPI void *eina_inarray_grow(Eina_Inarray *array, unsigned int size); +EAPI int eina_inarray_push(Eina_Inarray *array, + const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Copies the data to the array at a position found by the comparison function. * - * @param[in] array The array object - * @param[in] data The data to be copied - * @param[in] compare The compare function - * @return The index of the new member, otherwise @c -1 on errors - * * @details This copies the given pointer contents at the array position defined by the * given @a compare function. The pointer is not referenced, instead * its contents are copied to the members array using the previously * defined @c member_size. * - * @note The data given to the @p compare function is a pointer to the member - * memory itself, do no change it. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The data given to the @a compare function is a pointer to the member + * memory itself, do no change it. + * + * @param[in] array The array object + * @param[in] data The data to be copied + * @param[in] compare The compare function + * @return The index of the new member, otherwise @c -1 on errors * * @see eina_inarray_insert_sorted() * @see eina_inarray_insert_at() * @see eina_inarray_push() - * - * @since 1.2 */ EAPI int eina_inarray_insert(Eina_Inarray *array, const void *data, @@ -329,25 +200,27 @@ EAPI int eina_inarray_insert(Eina_Inarray *array, /** * @brief Copies the data to the array at a position found by the comparison function. * - * @param[in] array The array object - * @param[in] data The data to be copied - * @param[in] compare The compare function - * @return The index of the new member, otherwise @c -1 on errors - * * @details This copies the given pointer contents at the array position defined by the - * given @p compare function. The pointer is not referenced, instead + * given @a compare function. The pointer is not referenced, instead * its contents are copied to the members array using the previously - * defined @p member_size. + * defined @c member_size. * - * @note The data given to the @p compare function is a pointer to the member - * memory itself, do no change it. + * @since 1.2 * - * @note This variation optimizes the insertion position assuming that the array - * is already sorted by doing a binary search. + * @since_tizen 2.3 * - * @see eina_inarray_sort() + * @remarks The data given to the @a compare function is a pointer to the member + * memory itself, do no change it. * - * @since 1.2 + * @remarks This variation optimizes the insertion position assuming that the array + * is already sorted by doing a binary search. + * + * @param[in] array The array object + * @param[in] data The data to be copied + * @param[in] compare The compare function + * @return The index of the new member, otherwise @c -1 on errors + * + * @see eina_inarray_sort() */ EAPI int eina_inarray_insert_sorted(Eina_Inarray *array, const void *data, @@ -356,18 +229,20 @@ EAPI int eina_inarray_insert_sorted(Eina_Inarray *array, /** * @brief Finds data and removes the matching member. * - * @param[in] array The array object - * @param[in] data The data to be found and removed - * @return The index of the removed member, otherwise @c -1 on errors - * * @details This finds data in the array and removes it. Data may be an existing * member of the array (then optimized) or the contents are matched * using memcmp(). * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] array The array object + * @param[in] data The data to be found and removed + * @return The index of the removed member, otherwise @c -1 on errors + * * @see eina_inarray_pop() * @see eina_inarray_remove_at() - * - * @since 1.2 */ EAPI int eina_inarray_remove(Eina_Inarray *array, const void *data) EINA_ARG_NONNULL(1, 2); @@ -375,31 +250,36 @@ EAPI int eina_inarray_remove(Eina_Inarray *array, /** * @brief Removes the last member of the array. * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The data could be considered valid only until any other operation touched the Inarray. + * * @param[in] array The array object * @return The data poped out of the array * - * @note The data could be considered valid only until any other operation touched the Inarray. - * - * @since 1.2 */ EAPI void *eina_inarray_pop(Eina_Inarray *array) EINA_ARG_NONNULL(1); /** * @brief Gets the member at the given position. * - * @param[in] array The array object - * @param[in] position The member position - * @return A pointer to current the member memory - * * @details This gets the member given that its position in the array is provided. It is a pointer to * its current memory, then it can be invalidated with functions that * change the array such as eina_inarray_push(), * eina_inarray_insert_at(), or eina_inarray_remove_at(), or variants. * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] array The array object + * @param[in] position The member position + * @return A pointer to current the member memory + * * @see eina_inarray_lookup() * @see eina_inarray_lookup_sorted() - * - * @since 1.2 */ EAPI void *eina_inarray_nth(const Eina_Inarray *array, unsigned int position) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -407,25 +287,28 @@ EAPI void *eina_inarray_nth(const Eina_Inarray *array, /** * @brief Copies the data at the given position in the array. * - * @param[in] array The array object - * @param[in] position The position to insert the member at - * @param[in] data The data to be copied at the position - * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure - * - * @details This copies the given pointer contents at the given @p position in the + * @details This copies the given pointer contents at the given @a position in the * array. The pointer is not referenced, instead its contents are * copied to the members array using the previously defined - * @p member_size. + * @c member_size. * - * @note All the members from @a position to the end of the array are - * shifted to the end. + * All the members from @a position to the end of the array are + * shifted to the end. * - * @note If @a position is equal to the end of the array (equal to - * eina_inarray_count()), then the member is appended. + * If @a position is equal to the end of the array (equal to + * eina_inarray_count()), then the member is appended. * - * @note If @a position is bigger than the array length, it fails. + * If @a position is bigger than the array length, it fails. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] array The array object + * @param[in] position The position to insert the member at + * @param[in] data The data to be copied at the position + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_inarray_insert_at(Eina_Inarray *array, unsigned int position, @@ -434,28 +317,31 @@ EAPI Eina_Bool eina_inarray_insert_at(Eina_Inarray *array, /** * @brief Opens a space at the given position, returning its pointer. * - * @param[in] array The array object - * @param[in] position The position to insert first member at (open/allocate space) - * @param[in] member_count The number of times @c member_size bytes are allocated - * @return A pointer to the first member memory allocated, otherwise @c NULL on errors + * @since 1.2 * - * @note This is similar to eina_inarray_insert_at(), but useful if the - * members contents are still unknown or unallocated. It makes - * room for the required number of items and returns the pointer to the - * first item, similar to malloc(member_count * member_size), with the - * guarantee that all the memory is within the members array. + * @since_tizen 2.3 * - * @note The new member memory is undefined, it's not automatically zeroed. + * @remarks This is similar to eina_inarray_insert_at(), but useful if the + * members contents are still unknown or unallocated. It makes + * room for the required number of items and returns the pointer to the + * first item, similar to malloc(member_count * member_size), with the + * guarantee that all the memory is within the members array. * - * @note All the members from @a position to the end of the array are - * shifted to the end. + * The new member memory is undefined, it's not automatically zeroed. * - * @note If @a position is equal to the end of the array (equal to - * eina_inarray_count()), then the member is appended. + * @remarks All the members from @a position to the end of the array are + * shifted to the end. * - * @note If @a position is bigger than the array length, it fails. + * If @a position is equal to the end of the array (equal to + * eina_inarray_count()), then the member is appended. + * + * If @a position is bigger than the array length, it fails. + * + * @param[in] array The array object + * @param[in] position The position to insert first member at (open/allocate space) + * @param[in] member_count The number of times @c member_size bytes are allocated + * @return A pointer to the first member memory allocated, otherwise @c NULL on errors * - * @since 1.2 */ EAPI void *eina_inarray_alloc_at(Eina_Inarray *array, unsigned int position, @@ -464,19 +350,22 @@ EAPI void *eina_inarray_alloc_at(Eina_Inarray *array, /** * @brief Copies the data to the given position. * - * @param[in] array The array object - * @param[in] position The position to copy the member at - * @param[in] data The data to be copied at the position - * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure - * - * @details This copies the given pointer contents at the given @p position in the + * @details This copies the given pointer contents at the given @a position in the * array. The pointer is not referenced, instead its contents are * copied to the members array using the previously defined - * @p member_size. + * @c member_size. * - * @note If @p position does not exist, it fails. + * If @a position does not exist, it fails. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] array The array object + * @param[in] position The position to copy the member at + * @param[in] data The data to be copied at the position + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_inarray_replace_at(Eina_Inarray *array, unsigned int position, @@ -485,17 +374,20 @@ EAPI Eina_Bool eina_inarray_replace_at(Eina_Inarray *array, /** * @brief Removes a member from the given position. * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The member is removed from an array and members after it are moved + * towards the array head. + * * @param[in] array The array object * @param[in] position The position from which to remove a member - * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure - * - * @note The member is removed from an array and members after it are moved - * towards the array head. + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_inarray_pop() * @see eina_inarray_remove() * - * @since 1.2 */ EAPI Eina_Bool eina_inarray_remove_at(Eina_Inarray *array, unsigned int position) EINA_ARG_NONNULL(1); @@ -503,31 +395,35 @@ EAPI Eina_Bool eina_inarray_remove_at(Eina_Inarray *array, /** * @brief Reverses members in the array. * - * @param[in] array The array object + * @since 1.2 * - * @note If you do not want to change the array, just walk through its elements - * backwards, then use the EINA_INARRAY_REVERSE_FOREACH() macro. + * @since_tizen 2.3 * - * @see EINA_INARRAY_REVERSE_FOREACH() + * @remarks If you do not want to change the array, just walk through its elements + * backwards, then use the EINA_INARRAY_REVERSE_FOREACH() macro. * - * @since 1.2 + * @param[in] array The array object + * + * @see EINA_INARRAY_REVERSE_FOREACH() */ EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1); /** * @brief Applies a quick sort to the array. * - * @param[in] array The array object - * @param[in] compare The compare function - * * @details This applies a quick sort to the @a array. * - * @note The data given to the @a compare function is a pointer to the member - * memory itself, do no change it. + * @since 1.2 + * + * @since_tizen 2.3 * - * @see eina_inarray_insert_sorted() + * @remarks The data given to the @a compare function is a pointer to the member + * memory itself, do no change it. * - * @since 1.2 + * @param[in] array The array object + * @param[in] compare The compare function + * + * @see eina_inarray_insert_sorted() */ EAPI void eina_inarray_sort(Eina_Inarray *array, Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2); @@ -535,20 +431,26 @@ EAPI void eina_inarray_sort(Eina_Inarray *array, /** * @brief Searches for a member (linear walk). * + * @details This walks through an array by linearly looking for the given data compared by + * the @a compare function. + * + * The data given to the @a compare function is a pointer to the member + * memory itself, do no change it. + * + * @since 1.2 + * + * @since_tizen 2.3 + * * @param[in] array The array object - * @param[in] data The member to search using the @p compare function + * @param[in] data The member to search using the @a compare function * @param[in] compare The compare function * @return The member index, otherwise @c -1 if not found * - * @details This walks through an array by linearly looking for the given data compared by - * the @p compare function. - * - * @note The data given to the @p compare function is a pointer to the member - * memory itself, do no change it. - * * @see eina_inarray_lookup_sorted() * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI int eina_inarray_search(const Eina_Inarray *array, const void *data, @@ -557,41 +459,47 @@ EAPI int eina_inarray_search(const Eina_Inarray *array, /** * @brief Searches for member (binary search walk). * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks Uses a binary search for the given data as compared by the @a compare function. + * + * The data given to the @a compare function is a pointer to the member + * memory itself, do no change it. + * * @param[in] array The array object - * @param[in] data The member to search using the @p compare function + * @param[in] data The member to search using the @a compare function * @param[in] compare The compare function * @return The member index, otherwise @c -1 if not found * - * @note Uses a binary search for the given data as compared by the @p compare function. - * - * @note The data given to the @p compare function is a pointer to the member - * memory itself, do no change it. - * - * @since 1.2 */ EAPI int eina_inarray_search_sorted(const Eina_Inarray *array, const void *data, Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Calls @p function for each array member. + * @brief Calls @a function for each array member. * - * @param[in] array The array object - * @param[in] function The callback function - * @param[in] user_data The user data given to a callback @a function - * @return #EINA_TRUE if it successfully iterates all the items of the array + * @details This calls @a function for every given data in @a array. * - * @details This calls @p function for every given data in @p array. + * @since 1.2 * - * @note This is a safe way to iterate over an array. @p function should return #EINA_TRUE - * as long as you want the function to continue iterating, by - * returning #EINA_FALSE it stops and returns #EINA_FALSE as the result. + * @since_tizen 2.3 * - * @note The data given to @p function is a pointer to the member memory itself. + * @remarks This is a safe way to iterate over an array. @a function should return @c EINA_TRUE + * as long as you want the function to continue iterating, by + * returning @c EINA_FALSE it stops and returns @c EINA_FALSE as the result. * - * @see EINA_INARRAY_FOREACH() + * The data given to @a function is a pointer to the member memory + * itself. * - * @since 1.2 + * @param[in] array The array object + * @param[in] function The callback function + * @param[in] user_data The user data given to a callback @a function + * @return @c EINA_TRUE if it successfully iterates all the items of the array + * + * @see EINA_INARRAY_FOREACH() */ EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array, Eina_Each_Cb function, @@ -600,96 +508,104 @@ EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array, /** * @brief Removes all the members that match. * + * @details This removes all the entries in @a array, where the @a match function + * returns @c EINA_TRUE. + * + * @since 1.2 + * + * @since_tizen 2.3 + * * @param[in] array The array object * @param[in] match The match function - * @param[in] user_data The user data given to callback @p match + * @param[in] user_data The user data given to callback @a match * @return The number of removed entries, otherwise @c -1 on error * - * @details This removes all the entries in @p array, where the @p match function - * returns #EINA_TRUE. - * - * @since 1.2 */ EAPI int eina_inarray_foreach_remove(Eina_Inarray *array, Eina_Each_Cb match, const void *user_data) EINA_ARG_NONNULL(1, 2); /** - * @brief Resizes array to new size + * @brief Counts the number of members in an array. * - * @param[in] array The array object - * @param[in] new_size New size for resize - * @return #EINA_TRUE if it resized the array successfully. + * @since 1.2 * - * @since 1.10 - */ -EAPI Eina_Bool eina_inarray_resize(Eina_Inarray *array, unsigned int new_size); - -/** - * @brief Counts the number of members in an array. + * @since_tizen 2.3 * * @param[in] array The array object * @return The number of members in the array * - * @since 1.2 */ EAPI unsigned int eina_inarray_count(const Eina_Inarray *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Returns a new iterator associated to an array. * - * @param[in] array The array object - * @return A new iterator - * * @details This function returns a newly allocated iterator associated to - * @p array. + * @a array. + * + * If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. + * + * @since 1.2 * - * @note If the memory cannot be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @since_tizen 2.3 * - * @warning If the array structure changes then the iterator becomes + * @remarks If the array structure changes then the iterator becomes * invalid. That is, if you add or remove members this * iterator's behavior is undefined and your program may crash. * - * @since 1.2 + * @param[in] array The array object + * @return A new iterator + * */ EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** * @brief Returns a new reversed iterator associated to an array. * - * @param[in] array The array object - * @return A new iterator - * * @details This function returns a newly allocated iterator associated to - * @p array. + * @a array. * - * @note Unlike eina_inarray_iterator_new(), this walks through the array backwards. + * If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * @note If the memory cannot be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @since 1.2 * - * @warning If the array structure changes then the iterator becomes + * @since_tizen 2.3 + * + * @remarks Unlike eina_inarray_iterator_new(), this walks through the array backwards. + * + * + * @remarks If the array structure changes then the iterator becomes * invalid. That is, if you add or remove nodes this iterator's * behavior is undefined and your program may crash. * - * @since 1.2 + * @param[in] array The array object + * @return A new iterator + * */ EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** * @brief Returns a new accessor associated to an array. * - * @param[in] array The array object - * @return A new accessor - * * @details This function returns a newly allocated accessor associated to - * @p array. + * @a array. * - * @note If the memory cannot be allocated, @c NULL is returned - * Otherwise, a valid accessor is returned. + * If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is + * returned. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] array The array object + * @return A new accessor + * */ EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); @@ -697,46 +613,52 @@ EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MA * @def EINA_INARRAY_FOREACH * @brief Walks through an array linearly from head to tail. * - * @param[in] array The array object - * @param[in] itr An iterator pointer + * @since 1.2 * - * @note @p itr must be a pointer with sizeof(itr*) == array->member_size. + * @since_tizen 2.3 * - * @note This is fast as it does direct pointer access, but it does - * not check for @c NULL pointers or invalid array objects. - * Use eina_inarray_foreach() to do that. + * @remarks @a itr must be a pointer with sizeof(itr*) == array->member_size. * - * @note Do not modify an array as you walk through it. If that is desired, - * then use eina_inarray_foreach_remove(). + * @remarks This is fast as it does direct pointer access, but it does + * not check for @c NULL pointers or invalid array objects. + * Use eina_inarray_foreach() to do that. + * + * @remarks Do not modify an array as you walk through it. If that is desired, + * then use eina_inarray_foreach_remove(). + * + * @param array The array object + * @param itr An iterator pointer * - * @since 1.2 */ #define EINA_INARRAY_FOREACH(array, itr) \ for ((itr) = (array)->members; \ - (itr) < (((__typeof__(*itr)*)(array)->members) + (array)->len); \ + (itr) < (((typeof(*itr)*)(array)->members) + (array)->len); \ (itr)++) /** * @def EINA_INARRAY_REVERSE_FOREACH * @brief Walks through an array linearly from tail to head. * - * @param[in] array The array object - * @param[in] itr An iterator pointer + * @since 1.2 * - * @note @p itr must be a pointer with sizeof(itr*) == array->member_size. + * @since_tizen 2.3 * - * @note This is fast as it does direct pointer access, but it does - * not check for @c NULL pointers or invalid array objects. + * @remarks @a itr must be a pointer with sizeof(itr*) == array->member_size. * - * @note Do not modify an array as you walk through it. If that is desired, - * then use eina_inarray_foreach_remove(). + * @remarks This is fast as it does direct pointer access, but it does + * not check for @c NULL pointers or invalid array objects. + * + * @remarks Do not modify an array as you walk through it. If that is desired, + * then use eina_inarray_foreach_remove(). + * + * @param array The array object + * @param itr An iterator pointer * - * @since 1.2 */ #define EINA_INARRAY_REVERSE_FOREACH(array, itr) \ - for ((itr) = ((((__typeof__(*(itr))*)(array)->members) + (array)->len) - 1); \ - (((itr) >= (__typeof__(*(itr))*)(array)->members) \ - && ((array)->members != NULL)); \ + for ((itr) = ((((typeof(*(itr))*)(array)->members) + (array)->len) - 1); \ + (((itr) >= (typeof(*(itr))*)(array)->members) \ + && ((array)->members != NULL)); \ (itr)--) /** diff --git a/src/lib/eina/eina_inlist.h b/src/lib/eina/eina_inlist.h index 6c1b1cc951..3753ae1fc8 100644 --- a/src/lib/eina/eina_inlist.h +++ b/src/lib/eina/eina_inlist.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -25,298 +25,32 @@ #include <stddef.h> /** - * @page eina_inlist_01_example_page Eina_Inlist basic usage - * @dontinclude eina_inlist_01.c - * - * To see the full source for this example, click here: @ref - * eina_inlist_01_c - * - * As explained before, inline lists mean its nodes pointers are part of same - * memory block/blob. This is done by using the macro @ref EINA_INLIST inside the - * data structure that will be used: - * - * @skip struct - * @until }; - * - * The resulting node representing this struct can be exemplified by the - * following picture: - * - * @image html eina_inlist-node_eg1-my-struct.png - * @image rtf eina_inlist-node_eg1-my-struct.png - * @image latex eina_inlist-node_eg1-my-struct.eps - * - * Let's define a comparison function that will be used later during the - * sorting of the list: - * - * @skip int - * @until } - * - * The @ref Eina_Inlist can be used exactly the same way as @ref Eina_List when - * appending, prepending and removing items. But since we already have the node - * pointers inside the structure, they need to be retrieved with the macro @ref - * EINA_INLIST_GET : - * - * @skip malloc - * @until append - * - * Notice that @ref eina_inlist_append always receives the head of the list as - * first argument, and its return value should be used as the list pointer - * (head): - * - * @skip malloc - * @until append - * - * After appending 3 items, the list now should look similar to this: - * - * @image html eina_inlist-node_eg1-inlist.png - * @image rtf eina_inlist-node_eg1-inlist.png - * @image latex eina_inlist-node_eg1-inlist.eps "" width=\textwidth - * - * The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list: - * - * @skip printf - * @until cur->a - * - * @ref eina_inlist_promote(), @ref eina_inlist_demote(), @ref - * eina_inlist_append_relative() and similar functions all work in the same way - * as the @ref Eina_List : - * - * @skip eina_inlist_promote - * @until eina_inlist_demote - * - * Now let's use the @c sort_cb function declared above to sort our list: - * - * @skipline eina_inlist_sort - * - * Removing an element from the inlist is also similar to @ref Eina_List : - * - * @skip inlist_remove - * @until free - * - * Another way of walking through the inlist. - * - * @skip for - * @until } - * - * Notice that in the previous piece of code, since we only have the pointers to - * the inlist nodes, we have to use the @ref EINA_INLIST_CONTAINER_GET macro - * that will return the pointer to the entire structure. Of course, in this case - * it is the same as the list pointer, since the @ref EINA_INLIST macro was used - * in the beginning of the structure. - * - * Now to finish this example, lets delete this list: - * - * @skip while - * @until } - */ - -/** - * @page eina_inlist_02_example_page Eina_Inlist advanced usage - lists and inlists - * @dontinclude eina_inlist_02.c - * - * This example describes the usage of @ref Eina_Inlist mixed with @ref - * Eina_List . We create and add elements to an inlist, and the even members - * are also added to a normal list. Later we remove the elements divisible by 3 - * from this normal list. - * - * The struct that is going to be used is the same used in @ref - * eina_inlist_01_example_page , since we still need the @ref EINA_INLIST macro to - * declare the inlist node info: - * - * @skip struct - * @until }; - * - * The resulting node representing this struct can be exemplified by the - * following picture: - * - * @image html eina_inlist-node_eg2-my-struct.png - * @image rtf eina_inlist-node_eg2-my-struct.png - * @image latex eina_inlist-node_eg2-my-struct.eps - * - * Now we need some pointers and auxiliar variables that will help us iterate on - * the lists: - * - * @skip struct - * @until l_next; - * - * Allocating 100 elements and putting them into an inlist, and the even - * elements also go to the normal list: - * - * @skip for - * @until } - * - * After this point, what we have are two distinct lists that share some - * elements. The first list (inlist) is defined by the pointers inside the - * elements data structure, while the second list (normal list) has its own node - * data structure that is kept outside of the elements. - * - * The two lists, sharing some elements, can be represented by the following - * picture: - * - * @htmlonly - * <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;"/> - * @endhtmlonly - * @image rtf eina_inlist-node_eg2-list-inlist.png - * @image latex eina_inlist-node_eg2-list-inlist.eps "" width=\textwidth - * - * Accessing both lists is done normally, as if they didn't have any elements in - * common: - * - * @skip printf - * @until eina_list_count - * - * We can remove elements from the normal list, but we just don't free them - * because they are still stored in the inlist: - * - * @skip EINA_LIST_FOREACH_SAFE - * @until eina_list_count - * - * To finish this example, we want to free both lists, we can't just free all - * elements on the second list (normal list) because they are still being used - * in the inlist. So we first discard the normal list without freeing its - * elements, then we free all elements in the inlist (that contains all elements - * allocated until now): - * - * @skip eina_list_free - * @until } - * - * Here is the full source code for this example: @ref eina_inlist_02_c - */ - -/** - * @page eina_inlist_03_example_page Eina_Inlist advanced usage - multi-inlists - * @dontinclude eina_inlist_03.c - * - * This example describes the usage of multiple inlists storing the same data. - * It means that some data may appear in more than one inlist at the same time. - * We will demonstrate this by creating an inlist with 100 numbers, and adding - * the odd numbers to the second inlist, then remove the numbers divisible by 3 - * from the second list. - * - * To accomplish this, it is necessary to have two inlist pointers in the struct - * that is going to be stored. We are using the default inlist member @ref - * EINA_INLIST, and adding another member @c even that is of type @ref - * Eina_Inlist too: - * - * @skip struct - * @until }; - * - * The representation for this struct is: - * - * @image html eina_inlist-node_eg3-my-struct.png - * @image rtf eina_inlist-node_eg3-my-struct.png - * @image latex eina_inlist-node_eg3-my-struct.eps - * - * And we will define some convenience macros that are equivalent to @ref - * EINA_INLIST_GET and @ref EINA_INLIST_CONTAINER_GET : - * - * @skip define - * @until offsetof - * - * We need two pointers, one for each list, and a pointer that will be used as - * an iterator: - * - * @skipline Eina_Inlist - * - * Now we allocate and add to the first list every number from 0 to 99. These - * nodes data also have the @ref Eina_Inlist node info for the second list (@c - * even). We will use them to add just the even numbers to the second list, the - * @c list_even. Also notice that we are using our macro @c EVEN_INLIST_GET to - * get the pointer to the even list node info: - * - * @skip for - * @until } - * - * And the resulting lists will be as follow: - * - * @htmlonly - * <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;"/> - * @endhtmlonly - * @image rtf eina_inlist-node_eg3-two-inlists.png - * @image latex eina_inlist-node_eg3-two-inlists.eps "" width=\textwidth - * - * For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate - * over its elements: - * - * @skip FOREACH - * @until printf - * - * But for the second list, we have to do it manually. Of course we could create - * a similar macro to @ref EINA_INLIST_FOREACH, but since this macro is more - * complex than the other two and we are using it only once, it's better to just - * do it manually: - * - * @skip for - * @until } - * - * Let's just check that the two lists have the expected number of elements: - * - * @skip list count - * @until list_even count - * - * And removing the numbers divisible by 3 only from the second list: - * - * @skip itr - * @until list_even count - * - * Now that we don't need the two lists anymore, we can just free all the items. - * Since all of the allocated data was put into the first list, and both lists - * are made of pointers to inside the data structures, we can free only the - * first list (that contains all the elements) and the second list will be gone - * with it: - * - * @skip while - * @until free - * - * To see the full source code for this example, click here: @ref - * eina_inlist_03_c - * - */ - -/** - * @page eina_inlist_01_c eina_inlist_01.c Eina_Inlist basic usage source - * @include eina_inlist_01.c - */ - -/** - * @page eina_inlist_02_c eina_inlist_02.c Eina_Inlist advanced usage - lists and inlists source - * @include eina_inlist_02.c - */ - -/** - * @page eina_inlist_03_c eina_inlist_03.c Eina_Inlist advanced usage - multi-inlists source - * @include eina_inlist_03.c - */ - -/** - * @addtogroup Eina_Inline_List_Group Inline List + * @defgroup Eina_Inline_List_Group Inline List + * @ingroup Eina_Containers_Group * * @brief These functions provide inline list management. * - * Inline lists mean its nodes pointers are part of same memory as - * data. This has the benefit of fragmenting memory less and avoiding + * Inline lists mean its nodes pointers are part of the same memory as + * the data. This has the benefit of fragmenting less memory and avoiding * @c node->data indirection, but has the drawback of higher cost for some * common operations like count and sort. * * It is possible to have inlist nodes to be part of regular lists, created with * @ref eina_list_append() or @ref eina_list_prepend(). It's also possible to - * have a structure with two inlist pointers, thus be part of two different - * inlists at the same time, but the current convenience macros provided won't + * have a structure with two inlist pointers, thus being part of two different + * inlists at the same time, but the current convenience macros that are provided won't * work for both of them. Consult @ref inlist_advanced for more info. * * Inline lists have their purposes, but if you don't know what those purposes are, go with * regular lists instead. * * Tip: When using inlists in more than one place (that is, passing them around - * functions or keeping a pointer to them in a structure) it's more correct + * functions or keeping a pointer to them in a structure) it's is better * to keep a pointer to the first container, and not a pointer to the first * inlist item (mostly they are the same, but that's not always correct). - * This lets the compiler to do type checking and let the programmer know + * This lets the compiler do type checking and lets the programmer know * exactly what type this list is. * - * A simple example demonstrating the basic usage of an inlist can be found - * here: @ref eina_inlist_01_example_page - * * @section inlist_algo Algorithm * * The basic structure can be represented by the following picture: @@ -325,304 +59,274 @@ * @image rtf eina_inlist-node.png * @image latex eina_inlist-node.eps * - * One data structure will also have the node information, with three pointers: - * @a prev, @a next and @a last. The @a last pointer is just valid for the first - * element (the list head), otherwise each insertion in the list would have to - * be done updating every node with the correct pointer. This means that it's - * always very important to keep a pointer to the first element of the list, + * One data structure also has node information with three pointers: + * @a prev, @a next, and @a last. The @a last pointer is just valid for the first + * element (the list head), otherwise each insertion in the list has to + * be done by updating every node with the correct pointer. This means that it's + * very important to keep a pointer to the first element of the list, * since it is the only one that has the correct information to allow a proper * O(1) append to the list. * * @section inlist_perf Performance * * Due to the nature of the inlist, there's no accounting information, and no - * easy access to the last element from each list node. This means that @ref + * easy access to the last element of each list node. This means that @ref * eina_inlist_count() is order-N, while @ref eina_list_count() is order-1 (constant * time). * * @section inlist_advanced Advanced Usage * - * The basic usage considers a struct that will have the user data, and also - * have an inlist node information (prev, next and last pointers) created with - * @ref EINA_INLIST during the struct declaration. This allows one to use the + * The basic usage considers a struct that has the user data, and also + * has the inlist node information (prev, next, and last pointers) created with + * @ref EINA_INLIST during struct declaration. This allows one to use the * convenience macros @ref EINA_INLIST_GET(), @ref EINA_INLIST_CONTAINER_GET(), - * @ref EINA_INLIST_FOREACH() and so. This happens because the @ref EINA_INLIST + * @ref EINA_INLIST_FOREACH(), and so on. This happens because the @ref EINA_INLIST * macro declares a struct member with the name @a __inlist, and all the other * macros assume that this struct member has this name. * * It may be the case that someone needs to have some inlist nodes added to a * @ref Eina_List too. If this happens, the inlist nodes can be added to the - * @ref Eina_List without any problems. This example demonstrates this case: - * @ref eina_inlist_02_example_page - * - * It's also possible to have some data that is part of two different inlists. - * If this is the case, then it won't be possible to use the convenience macros - * to both of the lists. It will be necessary to create a new set of macros that - * will allow access to the second list node info. An example for this usage can - * be found here: - * @ref eina_inlist_03_example_page - * - * List of examples: - * @li @ref eina_inlist_01_example_page - * @li @ref eina_inlist_02_example_page - * @li @ref eina_inlist_03_example_page - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers + * @ref Eina_List without any problem. * - * @{ - */ - -/** - * @defgroup Eina_Inline_List_Group Inline List + * It's also possible to have data that is part of two different inlists. + * If this is the case, then it won't be possible to use convenience macros + * for both of the lists. It is necessary to create a new set of macros that + * allow access to the second list node info. * * @{ */ /** * @typedef Eina_Inlist - * Inlined list type. + * @brief The structure type for an inlined list type. */ typedef struct _Eina_Inlist Eina_Inlist; /** * @typedef Eina_Inlist_Sorted_State + * @brief The structure type for the state of a sorted Eina_Inlist. * @since 1.1.0 - * State of sorted Eina_Inlist */ typedef struct _Eina_Inlist_Sorted_State Eina_Inlist_Sorted_State; /** * @struct _Eina_Inlist - * Inlined list type. + * @brief The structure type for an Inlined list type. */ struct _Eina_Inlist { - Eina_Inlist *next; /**< next node */ - Eina_Inlist *prev; /**< previous node */ - Eina_Inlist *last; /**< last node */ + Eina_Inlist *next; /**< Next node */ + Eina_Inlist *prev; /**< Previous node */ + Eina_Inlist *last; /**< Last node */ }; -/** Used for declaring an inlist member in a struct */ +/** Definition used for declaring an inlist member in a struct */ #define EINA_INLIST Eina_Inlist __in_list -/** Utility macro to get the inlist object of a struct */ +/** Definition of the utility macro to get the inlist object of a struct */ #define EINA_INLIST_GET(Inlist) (& ((Inlist)->__in_list)) -/** Utility macro to get the container object of an inlist */ +/** Definition of the utility macro to get the container object of an inlist */ #define EINA_INLIST_CONTAINER_GET(ptr, \ type) ((type *)((char *)ptr - \ offsetof(type, __in_list))) /** - * Add a new node to end of a list. + * @brief Adds a new node to the end of a list. + * + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a in_list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a in_list. + * @since_tizen 2.3 * - * @note @a in_item is considered to be in no list. If it was in another - * list before, eina_inlist_remove() it before adding. No - * check of @a new_l prev and next pointers is done, so it's safe - * to have them uninitialized. + * @remarks @a in_item is considered to be in no list. If it has been in another + * list before, eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it's safe + * to have them uninitialized. * - * @param in_list existing list head or @c NULL to create a new list. - * @param in_item new list node, must not be @c NULL. + * @param[in] in_list The existing list head, otherwise @c NULL to create a new list + * @param[in] in_item new The list node, must not be @c NULL * - * @return the new list head. Use it and not @a in_list anymore. + * @return The new list head \n + * Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * Add a new node to beginning of list. + * @brief Adds a new node to the beginning of the list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a in_list. + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a in_list. * - * @note @a new_l is considered to be in no list. If it was in another - * list before, eina_inlist_remove() it before adding. No - * check of @a new_l prev and next pointers is done, so it's safe - * to have them uninitialized. + * @since_tizen 2.3 * - * @param in_list existing list head or @c NULL to create a new list. - * @param in_item new list node, must not be @c NULL. + * @remarks @a new_l is considered to be in no list. If it has been in another + * list before, eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it's safe + * to have them uninitialized. * - * @return the new list head. Use it and not @a in_list anymore. + * @param[in] in_list The existing list head, otherwise @c NULL to create a new list + * @param[in] in_item The new list node, must not be @c NULL + * + * @return The new list head \n + * Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * Add a new node after the given relative item in list. + * @brief Adds a new node after the given relative item in the list. + * + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a in_list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a in_list. + * @since_tizen 2.3 * - * @note @a in_item_l is considered to be in no list. If it was in another - * list before, eina_inlist_remove() it before adding. No - * check of @a in_item prev and next pointers is done, so it's safe - * to have them uninitialized. + * @remarks @a in_item_l is considered to be in no list. If it has been in another + * list before, eina_inlist_remove() it before adding. No + * check of @a in_item prev and next pointers is done, so it's safe + * to have them uninitialized. * - * @note @a in_relative is considered to be inside @a in_list, no checks are - * done to confirm that and giving nodes from different lists - * will lead to problems. Giving NULL @a in_relative is the same as - * eina_list_append(). + * @remarks @a in_relative is considered to be inside @a in_list, no checks are + * done to confirm that and giving nodes from different lists + * leads to problems. Setting @a in_relative to @c NULL is the same as + * eina_list_append(). * - * @param in_list existing list head or @c NULL to create a new list. - * @param in_item new list node, must not be @c NULL. - * @param in_relative reference node, @a in_item will be added after it. + * @param[in] in_list The existing list head, otherwise @c NULL to create a new list + * @param[in] in_item new The list node, must not be @c NULL + * @param[in] in_relative The reference node, @a in_item is added after it * - * @return the new list head. Use it and not @a list anymore. + * @return The new list head \n + * Use it and not @a list anymore. */ EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, Eina_Inlist *in_item, Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * Add a new node before the given relative item in list. + * @brief Adds a new node before the given relative item in the list. + * + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a in_list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a in_list. + * @since_tizen 2.3 * - * @note @a in_item is considered to be in no list. If it was in another - * list before, eina_inlist_remove() it before adding. No - * check of @a in_item prev and next pointers is done, so it's safe - * to have them uninitialized. + * @remarks @a in_item is considered to be in no list. If it has been in another + * list before, eina_inlist_remove() it before adding. No + * check of @a in_item prev and next pointers is done, so it's safe + * to have them uninitialized. * - * @note @a in_relative is considered to be inside @a in_list, no checks are - * done to confirm that and giving nodes from different lists - * will lead to problems. Giving NULL @a in_relative is the same as - * eina_list_prepend(). + * @remarks @a in_relative is considered to be inside @a in_list, no checks are + * done to confirm that and giving nodes from different lists + * leads to problems. Setting @a in_relative to @c NULL is the same as + * eina_list_prepend(). * - * @param in_list existing list head or @c NULL to create a new list. - * @param in_item new list node, must not be @c NULL. - * @param in_relative reference node, @a in_item will be added before it. + * @param[in] in_list The existing list head, otherwise @c NULL to create a new list + * @param[in] in_item new The list node, must not be @c NULL + * @param[in] in_relative The reference node, @a in_item is added before it * - * @return the new list head. Use it and not @a in_list anymore. + * @return The new list head \n + * Use it and not @a in_list anymore. */ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, Eina_Inlist *in_item, Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * Remove node from list. + * @brief Removes a node from the list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a list. * - * @note @a in_item is considered to be inside @a in_list, no checks are - * done to confirm that and giving nodes from different lists - * will lead to problems, especially if @a in_item is the head since - * it will be different from @a list and the wrong new head will - * be returned. + * @since_tizen 2.3 * - * @param in_list existing list head, must not be @c NULL. - * @param in_item existing list node, must not be @c NULL. + * @remarks @a in_item is considered to be inside @a in_list, no checks are + * done to confirm that and giving nodes from different lists + * lead to problems, especially if @a in_item is the head since + * it is different from @a list and the wrong new head is + * returned. * - * @return the new list head. Use it and not @a list anymore. + * @param[in] in_list The existing list head, must not be @c NULL + * @param[in] in_item The existing list node, must not be @c NULL + * + * @return The new list head \n + * Use it and not @a list anymore. */ EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * Find given node in list, returns itself if found, NULL if not. + * @brief Finds a given node in the list, returns itself if found, @c NULL if not. + * + * @details This is an expensive call and has O(n) cost, possibly + * walking the whole list. * - * @warning this is an expensive call and has O(n) cost, possibly - * walking the whole list. + * @since_tizen 2.3 * - * @param in_list existing list to search @a in_item in, must not be @c NULL. - * @param in_item what to search for, must not be @c NULL. + * @param[in] in_list The existing list to search @a in_item in, must not be @c NULL + * @param[in] in_item The item to search for, must not be @c NULL * - * @return @a in_item if found, @c NULL if not. + * @return @a in_item if found, @c NULL if not */ EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list, Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * Move existing node to beginning of list. + * @brief Moves an existing node to the beginning of the list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a list. * - * @note @a item is considered to be inside @a list. No checks are - * done to confirm this, and giving nodes from different lists - * will lead to problems. + * @since_tizen 2.3 * - * @param list existing list head or @c NULL to create a new list. - * @param item list node to move to beginning (head), must not be @c NULL. + * @remarks @a item is considered to be inside @a list. No checks are + * done to confirm this, and giving nodes from different lists + * leads to problems. * - * @return the new list head. Use it and not @a list anymore. + * @param[in] list The existing list head, otherwise @c NULL to create a new list + * @param[in] item The list node to move to the beginning (head), must not be @c NULL + * + * @return The new list head \n + * Use it and not @a list anymore. */ EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * Move existing node to end of list. + * @brief Moves an existing node to the end of the list. + * + * @details This code is meant to be fast: appends are O(1) and do not + * walk through @a list. * - * @note this code is meant to be fast: appends are O(1) and do not - * walk @a list. + * @since_tizen 2.3 * - * @note @a item is considered to be inside @a list. No checks are - * done to confirm this, and giving nodes from different lists - * will lead to problems. + * @remarks @a item is considered to be inside @a list. No checks are + * done to confirm this, and giving nodes from different lists + * leads to problems. * - * @param list existing list head or @c NULL to create a new list. - * @param item list node to move to end (tail), must not be @c NULL. + * @param[in] list The existing list head, otherwise @c NULL to create a new list + * @param[in] item The list node to move to the end (tail), must not be @c NULL * - * @return the new list head. Use it and not @a list anymore. + * @return The new list head \n + * Use it and not @a list anymore. */ EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief Get the first list node in the list. - * - * @param list The list to get the first list node from. - * @return The first list node in the list. - * - * This function returns the first list node in the list @p list. If - * @p list is @c NULL, @c NULL is returned. - * - * This is a O(N) operation (it takes time proportional - * to the length of the list). - * - * @since 1.8 - */ -static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT; - -/** - * @brief Get the last list node in the list. - * - * @param list The list to get the last list node from. - * @return The last list node in the list. - * - * This function returns the last list node in the list @p list. If - * @p list is @c NULL, @c NULL is returned. + * @brief Gets the count of the number of items in a list. * - * This is a O(N) operation (it takes time proportional - * to the length of the list). + * @details This function returns the number of members that @a list contains. If the + * @a list is @c NULL, @c 0 is returned. * - * @since 1.8 - */ -static inline Eina_Inlist *eina_inlist_last(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT; - -/** - * @brief Get the count of the number of items in a list. + * @since_tizen 2.3 * - * @param list The list whose count to return. - * @return The number of members in the list. + * @remarks This is an order-N operation and so the time depends + * on the number of elements in the list, so it might become + * slow for big lists. * - * This function returns how many members @p list contains. If the - * list is @c NULL, @c 0 is returned. + * @param[in] list The list whose count to return + * @return The number of members in the list * - * @warning This is an order-N operation and so the time will depend - * on the number of elements on the list, so, it might become - * slow for big lists! */ EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_RESULT; @@ -630,152 +334,178 @@ EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_ /** * @brief Returns a new iterator associated to @a list. * - * @param in_list The list. - * @return A new iterator. + * @details This function returns a newly allocated iterator associated to @a + * in_list. If @a in_list is @c NULL or the count member of @a in_list is less than + * or equal to @c 0, this function still returns a valid iterator that + * always returns @c false on a call to eina_iterator_next(), thus keeping the API + * sane. * - * This function returns a newly allocated iterator associated to @p - * in_list. If @p in_list is @c NULL or the count member of @p in_list is less - * or equal than 0, this function still returns a valid iterator that - * will always return false on eina_iterator_next(), thus keeping API - * sane. + * @since_tizen 2.3 * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator + * is returned. + * + * @remarks If the list structure changes then the iterator becomes + * invalid, and if you add or remove nodes the iterator's + * behavior is undefined, and your program may crash. + * + * @param[in] in_list The list + * @return A new iterator * - * @warning if the list structure changes then the iterator becomes - * invalid, and if you add or remove nodes iterator - * behavior is undefined, and your program may crash! */ EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Returns a new accessor associated to a list. + * @brief Returns a new accessor associated to the list. + * + * @details This function returns a newly allocated accessor associated to + * @a in_list. If @a in_list is @c NULL or the count member of @a in_list is + * less than or equal to @c 0, this function returns @c NULL. If the memory cannot + * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, a valid accessor is returned. * - * @param in_list The list. - * @return A new accessor. + * @since_tizen 2.3 + * + * @param[in] in_list The list + * @return A new accessor * - * This function returns a newly allocated accessor associated to - * @p in_list. If @p in_list is @c NULL or the count member of @p in_list is - * less or equal than @c 0, this function returns @c NULL. If the memory can - * not be allocated, @c NULL is returned and Otherwise, a valid accessor is - * returned. */ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Insert a new node into a sorted list. + * @brief Inserts a new node into a sorted list. + * + * @details This function inserts items into a linked list assuming it is + * sorted and the result is sorted. If @a list is @c NULLL, @a item + * is returned. On success, a new list pointer that should be + * used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. * - * @param list The given linked list, @b must be sorted. - * @param item list node to insert, must not be @c NULL. - * @param func The function called for the sort. - * @return A list pointer. * @since 1.1.0 * - * This function inserts item into a linked list assuming it was - * sorted and the result will be sorted. If @p list is @c NULLL, item - * is returned. On success, a new list pointer that should be - * used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. - * - * @note O(log2(n)) comparisons (calls to @p func) average/worst case - * performance. As said in eina_list_search_sorted_near_list(), - * lists do not have O(1) access time, so walking to the correct node - * can be costly, consider worst case to be almost O(n) pointer - * dereference (list walk). + * @since_tizen 2.3 + * + * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func). + * As said in eina_list_search_sorted_near_list(), + * lists do not have O(1) access time, so walking to the correct node + * can be costly, consider worst case to be almost O(n) pointer + * dereference (list walk). + * + * @param[in] list The given linked list, @b must be sorted + * @param[in] item The list node to insert, must not be @c NULL + * @param[in] func The function called for the sort + * @return A list pointer + * + * @see eina_error_get() */ EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item, Eina_Compare_Cb func) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; /** - * @brief Create state with valid data in it. + * @brief Creates a state with the valid data in it. * - * @return A valid Eina_Inlist_Sorted_State. * @since 1.1.0 * - * See eina_inlist_sorted_state_insert() for more information. + * @since_tizen 2.3 + * + * @return A valid Eina_Inlist_Sorted_State + * + * @see eina_inlist_sorted_state_insert() */ EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void); /** - * @brief Force an Eina_Inlist_Sorted_State to match the content of a list. + * @brief Forces an Eina_Inlist_Sorted_State to match the content of a list. + * + * @details This function is useful if you didn't use eina_inlist_sorted_state_insert() at any point, + * but still think you have a sorted list. + * It only works correctly on a sorted list. * - * @param state The state to update - * @param list The list to match - * @return The number of item in the actually in the list * @since 1.1.0 * - * See eina_inlist_sorted_state_insert() for more information. This function is - * usefull if you didn't use eina_inlist_sorted_state_insert() at some point, but - * still think you have a sorted list. It will only correctly work on a sorted list. + * @since_tizen 2.3 + * + * @param[in] state The state to update + * @param[in] list The list to match + * @return The number of items that are actually in the list + * + * @see eina_inlist_sorted_state_insert() */ EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inlist *list); /** - * @brief Free an Eina_Inlist_Sorted_State. + * @brief Frees an Eina_Inlist_Sorted_State. * - * @param state The state to destroy * @since 1.1.0 * - * See eina_inlist_sorted_state_insert() for more information. + * @since_tizen 2.3 + * + * @param[in] state The state to destroy + * + * @see eina_inlist_sorted_state_insert() */ EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state); /** - * @brief Insert a new node into a sorted list. + * @brief Inserts a new node into a sorted list. + * + * @details This function inserts an item into a linked list assuming @a state matches + * the exact content order of the list. It uses @a state to do a fast + * first step dichotomic search before starting to walk through the inlist itself. + * This makes this code much faster than eina_inlist_sorted_insert() as it + * doesn't need to walk through the list at all. The result is of course a sorted + * list with an updated state.. If @a list is @c NULLL, @a item + * is returned. On success, a new list pointer that should be + * used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. * - * @param list The given linked list, @b must be sorted. - * @param item list node to insert, must not be @c NULL. - * @param func The function called for the sort. - * @param state The current array for initial dichotomic search - * @return A list pointer. * @since 1.1.0 * - * This function inserts item into a linked list assuming @p state match - * the exact content order of the list. It use @p state to do a fast - * first step dichotomic search before starting to walk the inlist itself. - * This make this code much faster than eina_inlist_sorted_insert() as it - * doesn't need to walk the list at all. The result is of course a sorted - * list with an updated state.. If @p list is @c NULLL, item - * is returned. On success, a new list pointer that should be - * used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. - * - * @note O(log2(n)) comparisons (calls to @p func) average/worst case - * performance. As said in eina_list_search_sorted_near_list(), - * lists do not have O(1) access time, so walking to the correct node - * can be costly, but this version try to minimize that by making it a - * O(log2(n)) for number small number. After n == 256, it start to add a - * linear cost again. Consider worst case to be almost O(n) pointer - * dereference (list walk). + * @since_tizen 2.3 + * + * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func) + * As said in eina_list_search_sorted_near_list(), + * lists do not have O(1) access time, so walking to the correct node + * can be costly, but this version tries to minimize that by making it + * O(log2(n)) for a small number. After n == 256, it starts to add + * linear cost again. Consider worst case to be almost O(n) pointer + * dereference (list walk). + * + * @param[in] list The given linked list, @b must be sorted + * @param[in] item The list node to insert, must not be @c NULL + * @param[in] func The function called for the sort + * @param[in] state The current array for an initial dichotomic search + * @return A list pointer + * + * + * @see eina_error_get() */ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list, Eina_Inlist *item, Eina_Compare_Cb func, Eina_Inlist_Sorted_State *state); /** - * @brief Sort a list according to the ordering func will return. + * @brief Sorts a list according to the ordering that @a func returns. * - * @param head The list handle to sort. - * @param func A function pointer that can handle comparing the list data - * nodes. - * @return the new head of list. + * @details This function sorts all the elements of @a head. @a func is used to + * compare two elements of @a head. If @a head or @a func is @c NULL, + * this function returns @c NULL. * - * This function sorts all the elements of @p head. @p func is used to - * compare two elements of @p head. If @p head or @p func are @c NULL, - * this function returns @c NULL. + * @since_tizen 2.3 * - * @note @b in-place: this will change the given list, so you should - * now point to the new list head that is returned by this function. + * @remarks @b in-place: This changes the given list, so you should + * now point to the new list head that is returned by this function. * - * @note Worst case is O(n * log2(n)) comparisons (calls to func()). - * That means that for 1,000,000 list elements, sort will do 20,000,000 - * comparisons. + * @remarks Worst case is O(n * log2(n)) comparisons (calls to func()). + * That means, for 1,000,000 list elements, sort does 20,000,000 + * comparisons. * * Example: * @code * typedef struct _Sort_Ex Sort_Ex; * struct _Sort_Ex * { - * EINA_INLIST; + * INLIST; * const char *text; * }; * @@ -794,21 +524,33 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list, * * list = eina_inlist_sort(list, sort_cb); * @endcode + * + * @param[in] head The list handle to sort + * @param[in] func A function pointer that can handle comparing the list data nodes + * + * @return The new head of the list + * */ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); -/* This two macros are helpers for the _FOREACH ones, don't use them */ +/* These two macros are helpers for the _FOREACH ones, don't use them */ /** * @def _EINA_INLIST_OFFSET - * @param ref The reference to be used. + * + * @since_tizen 2.3 + * + * @param ref The reference to be used */ #define _EINA_INLIST_OFFSET(ref) ((char *)&(ref)->__in_list - (char *)(ref)) #if !defined(__cplusplus) /** * @def _EINA_INLIST_CONTAINER - * @param ref The reference to be used. - * @param ptr The pointer to be used. + * + * @since_tizen 2.3 + * + * @param ref The reference to be used + * @param ptr The pointer to be used */ #define _EINA_INLIST_CONTAINER(ref, ptr) (void *)((char *)(ptr) - \ _EINA_INLIST_OFFSET(ref)) @@ -817,15 +559,18 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); * In C++ we can't assign a "type*" pointer to void* so we rely on GCC's typeof * operator. */ -# define _EINA_INLIST_CONTAINER(ref, ptr) (__typeof__(ref))((char *)(ptr) - \ - _EINA_INLIST_OFFSET(ref)) +#define _EINA_INLIST_CONTAINER(ref, ptr) (typeof(ref))((char *)(ptr) - \ + _EINA_INLIST_OFFSET(ref)) #endif /** * @def EINA_INLIST_FOREACH - * @param list The list to iterate on. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * + * @since_tizen 2.3 + * + * @param list The list to iterate on + * @param it A pointer to the list item, i.e. a pointer to each item + * that is a part of the list. */ #define EINA_INLIST_FOREACH(list, it) \ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); it; \ @@ -833,69 +578,37 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); /** * @def EINA_INLIST_FOREACH_SAFE - * @param list The list to iterate on. - * @param list2 Auxiliar Eina_Inlist variable so we can save the pointer to the - * next element, allowing us to free/remove the current one. Note that this - * macro is only safe if the next element is not removed. Only the current one - * is allowed to be removed. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * + * @since_tizen 2.3 + * + * @param list The list to iterate on + * @param list2 The auxiliar Eina_Inlist variable so we can save the pointer to the + * next element, allowing us to free/remove the current one \n + * Note that this macro is safe only if the next element is not removed \n + * Only the current one is allowed to be removed. + * + * @param it A pointer to the list item, i.e. a pointer to each item + * that is a part of the list */ #define EINA_INLIST_FOREACH_SAFE(list, list2, it) \ - for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? EINA_INLIST_GET(it)->next : NULL; \ + for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? ((EINA_INLIST_GET(it) ? EINA_INLIST_GET(it)->next : NULL)) : NULL; \ it; \ it = NULL, it = list2 ? _EINA_INLIST_CONTAINER(it, list2) : NULL, list2 = list2 ? list2->next : NULL) /** * @def EINA_INLIST_REVERSE_FOREACH - * @param list The list to traversed in reverse order. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. + * + * @since_tizen 2.3 + * + * @param list The list to traverse in the reverse order + * @param it A pointer to the list item, i.e. a pointer to each item + * that is a part of the list */ #define EINA_INLIST_REVERSE_FOREACH(list, it) \ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list->last) : NULL); \ it; it = (EINA_INLIST_GET(it)->prev ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->prev) : NULL)) /** - * @def EINA_INLIST_REVERSE_FOREACH_FROM - * @param list The last list to traversed in reverse order. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. - * @see EINA_INLIST_REVERSE_FOREACH() - * @since 1.8 - * - * EINA_INLIST_REVERSE_FOREACH() starts from last list of the given list. - * This starts from given list, not the last one. - */ -#define EINA_INLIST_REVERSE_FOREACH_FROM(list, it) \ - for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); \ - it; it = (EINA_INLIST_GET(it)->prev ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->prev) : NULL)) - -/** - * @def EINA_INLIST_FREE - * @param list The list to free. - * @param it The pointer to the list item, i.e. a pointer to each item - * that is part of the list. - * - * NOTE: it is the duty of the body loop to properly remove the item from the - * inlist and free it. This function will turn into a infinite loop if you - * don't remove all items from the list. - * @since 1.8 - */ -#define EINA_INLIST_FREE(list, it) \ - for (it = (__typeof__(it)) list; list; it = (__typeof__(it)) list) - -#include "eina_inline_inlist.x" - -/** - * @} - */ - -/** - * @} - */ - -/** * @} */ diff --git a/src/lib/eina/eina_iterator.h b/src/lib/eina/eina_iterator.h index 291b98d66f..0ed573d9d3 100644 --- a/src/lib/eina/eina_iterator.h +++ b/src/lib/eina/eina_iterator.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -25,147 +25,80 @@ #include "eina_magic.h" /** - * @page eina_iterator_example_page Eina_Iterator usage - * @dontinclude eina_iterator_01.c - * - * As always when using eina we need to include it: - * @skip #include - * @until Eina.h - * - * Here we a declare an unimpressive @ref Eina_Each_Cb "function" that prints - * some data: - * @until } - * @note Returning EINA_TRUE is important so we don't stop iterating over the - * container. - * - * And here a more interesting function, it uses an iterator to print the - * contents of a container. What's interesting about it is that it doesn't care - * the type of container, it works for anything that can provide an iterator: - * @until } - * - * And on to our main function were we declare some variables and initialize - * eina, nothing too special: - * @until eina_init - * - * Next we populate both an array and a list with our strings, for more details - * see @ref eina_list_01_example_page and @ref eina_array_01_example_page : - * @until } - * - * And now we create an array and because the first element of the container - * doesn't interest us we skip it: - * @until iterator_next - * - * Having our iterator now pointing to interesting data we go ahead and print: - * @until print_eina_container - * - * As always once data with a structure we free it, but just because we can we - * do it by asking the iterator for it's container, and then of course free the - * iterator itself: - * @until eina_iterator_free - * - * But so far you're not impressed in @ref eina_array_01_example_page an array is - * also printed, so now we go to the cool stuff and use an iterator to do same - * stuff to a list: - * @until eina_iterator_free - * @note The only significant diference to the block above is in the - * function used to create the iterator. - * - * And now we free the list and shut eina down: - * @until } - */ - -/** - * @page eina_iterator_01_c Eina_Iterator usage - * @page eina_iterator_01_c Eina_Iterator usage - * - * @include eina_iterator_01.c - * @example eina_iterator_01.c - */ - -/** - * @addtogroup Eina_Iterator_Group Iterator Functions + * @defgroup Eina_Iterator_Group Iterator Functions + * @ingroup Eina_Content_Access_Group Content * - * @brief These functions manage iterators on containers. + * @brief This group of functions manages iterators on containers. * * These functions allow to access elements of a container in a * generic way, without knowing which container is used (a bit like - * iterators in the C++ STL). Iterators only allows sequential access - * (that is, from an element to the next one). For random access, see + * iterators in the C++ STL). Iterators only allow sequential access + * (that is, from one element to the next one). For random access, see * @ref Eina_Accessor_Group. * * Getting an iterator to access elements of a given container is done through * the functions of that particular container. There is no function to create * a generic iterator as iterators absolutely depend on the container. This - * means you won't find iterator creation function here, those can be found on + * means you won't find a iterator creation function here, those can be found on * the documentation of the container type you're using. Though created with * container specific functions iterators are always deleted with the same * function: eina_iterator_free(). * - * To get the data and iterate, use eina_iterator_next(). To call a function on + * To get data and iterate it, use eina_iterator_next(). To call a function on * all the elements of a container, use eina_iterator_foreach(). - * - * Here an @ref eina_iterator_example_page "example" - */ - -/** - * @addtogroup Eina_Content_Access_Group Content Access - * - * @{ - */ - -/** - * @defgroup Eina_Iterator_Group Iterator Functions * * @{ */ /** * @typedef Eina_Iterator - * Abstract type for iterators. + * @brief The structure type containing the abstract type for iterators. */ typedef struct _Eina_Iterator Eina_Iterator; /** * @typedef Eina_Iterator_Next_Callback - * Type for a callback that returns the next element in a container. + * @brief The boolean type for a callback that returns the next element in a container. */ typedef Eina_Bool (*Eina_Iterator_Next_Callback)(Eina_Iterator *it, void **data); /** * @typedef Eina_Iterator_Get_Container_Callback - * Type for a callback that returns the container. + * @brief Called to return the container. */ typedef void *(*Eina_Iterator_Get_Container_Callback)(Eina_Iterator *it); /** * @typedef Eina_Iterator_Free_Callback - * Type for a callback that frees the container. + * @brief Called to free the container. */ typedef void (*Eina_Iterator_Free_Callback)(Eina_Iterator *it); /** * @typedef Eina_Iterator_Lock_Callback - * Type for a callback that lock the container. + * @brief Called to lock the container. */ typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it); /** * @struct _Eina_Iterator - * structure of an iterator + * @brief The structure type of an iterator. * - * If creating an iterator remember to set the type using @ref EINA_MAGIC_SET. + * @internal + * @remarks When creating an iterator remember to set the type using #EINA_MAGIC_SET. + * @endinternal */ struct _Eina_Iterator { #define EINA_ITERATOR_VERSION 1 - int version; /**< Version of the Iterator API. */ + int version; /**< Version of the Iterator API */ - Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when a next element is requested. */ - Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */ - Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */ + Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when the next element is requested */ + Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested */ + Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed */ - Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ - Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */ + Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked */ + Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked */ #define EINA_MAGIC_ITERATOR 0x98761233 EINA_MAGIC @@ -173,79 +106,91 @@ struct _Eina_Iterator /** * @def FUNC_ITERATOR_NEXT(Function) - * Helper macro to cast @p Function to a Eina_Iterator_Next_Callback. + * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Next_Callback. */ #define FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function) /** * @def FUNC_ITERATOR_GET_CONTAINER(Function) - * Helper macro to cast @p Function to a Eina_Iterator_Get_Container_Callback. + * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Get_Container_Callback. */ #define FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function) /** * @def FUNC_ITERATOR_FREE(Function) - * Helper macro to cast @p Function to a Eina_Iterator_Free_Callback. + * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Free_Callback. */ #define FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function) /** * @def FUNC_ITERATOR_LOCK(Function) - * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. + * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Lock_Callback. */ #define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function) /** - * @brief Free an iterator. + * @brief Frees an iterator. + * + * @details This function frees @a iterator if it is not @c NULL. + * + * @since_tizen 2.3 * - * @param iterator The iterator to free. + * @param[in] iterator The iterator to free * - * This function frees @p iterator if it is not @c NULL; */ EAPI void eina_iterator_free(Eina_Iterator *iterator); /** - * @brief Return the container of an iterator. + * @brief Gets the container of an iterator. * - * @param iterator The iterator. - * @return The container which created the iterator. + * @details This function returns the container that created @a iterator. If + * @a iterator is @c NULL, this function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] iterator The iterator + * @return The container that created the iterator * - * This function returns the container which created @p iterator. If - * @p iterator is @c NULL, this function returns @c NULL. */ EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE; /** - * @brief Return the value of the current element and go to the next one. + * @brief Returns the value of the current element and goes to the next one. + * + * @details This function returns the value of the current element pointed by + * @a iterator in @a data and then goes to the next element. If @a + * iterator is @c NULL or if a problem occurs, @c EINA_FALSE is + * returned, otherwise @c EINA_TRUE is returned. * - * @param iterator The iterator. - * @param data The data of the element. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @since_tizen 2.3 + * + * @param[in] iterator The iterator + * @param[in] data The data of the element + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * This function returns the value of the current element pointed by - * @p iterator in @p data, then goes to the next element. If @p - * iterator is @c NULL or if a problem occurred, #EINA_FALSE is - * returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator, void **data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Iterate over the container and execute a callback on each element. - * - * @param iterator The iterator. - * @param callback The callback called on each iteration. - * @param fdata The data passed to the callback. - * - * This function iterates over the elements pointed by @p iterator, - * beginning from the current element. For Each element, the callback - * @p cb is called with the data @p fdata. If @p iterator is @c NULL, - * the function returns immediately. Also, if @p cb returns #EINA_FALSE, - * the iteration stops at that point, if @p cb returns #EINA_TRUE - * the iteration continues. + * @brief Iterates over the container and executes a callback on each element. + * + * @details This function iterates over the elements pointed by @a iterator, + * beginning from the current element. For each element, the callback + * @a cb is called with the data @a fdata. If @a iterator is @c NULL, + * the function returns immediately. Also, if @a cb returns @c EINA_FALSE, + * the iteration stops at that point. If @a cb returns @c EINA_TRUE + * the iteration continues. + * + * @since_tizen 2.3 + * + * @param[in] iterator The iterator + * @param[in] callback The callback called on each iteration + * @param[in] fdata The data passed to the callback + * */ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, Eina_Each_Cb callback, @@ -253,52 +198,55 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator, /** - * @brief Lock the container of the iterator. + * @brief Locks the container of the iterator. + * + * @since_tizen 2.3 * - * @param iterator The iterator. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @remarks If the container of the @a iterator permits it, it is locked. When a + * container is locked by calling eina_iterator_foreach() on it, it returns + * immediately. If @a iterator is @c NULL or if a problem occurs, @c EINA_FALSE + * is returned, otherwise @c EINA_TRUE is returned. If the container isn't + * lockable, it returns @c EINA_TRUE. * - * If the container of the @p iterator permits it, it will be locked. When a - * container is locked calling eina_iterator_foreach() on it will return - * immediately. If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. If the container isn't - * lockable, it will return #EINA_TRUE. + * @remarks None of the existing eina data structures are lockable. + * + * @param[in] iterator The iterator + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @warning None of the existing eina data structures are lockable. */ EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); /** - * @brief Unlock the container of the iterator. + * @brief Unlocks the container of the iterator. + * + * @since_tizen 2.3 + * + * @remarks If the container of the @a iterator permits it and is previously + * locked, it is unlocked. If @a iterator is @c NULL or if a + * problem occurs, @c EINA_FALSE is returned, otherwise @c EINA_TRUE + * is returned. If the container is not lockable, it + * returns @c EINA_TRUE. * - * @param iterator The iterator. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @remarks None of the existing eina data structures are lockable. * - * If the container of the @p iterator permits it and was previously - * locked, it will be unlocked. If @p iterator is @c NULL or if a - * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE - * is returned. If the container is not lockable, it will - * return #EINA_TRUE. + * @param[in] iterator The iterator + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @warning None of the existing eina data structures are lockable. */ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); /** * @def EINA_ITERATOR_FOREACH - * @brief Macro to iterate over all elements easily. + * @brief Definition of the macro to iterate over all the elements easily. * - * @param itr The iterator to use. - * @param data Where to store * data, must be a pointer support getting - * its address since * eina_iterator_next() requires a pointer - * to pointer! + * @since_tizen 2.3 * - * This macro is a convenient way to use iterators, very similar to - * EINA_LIST_FOREACH(). + * @details This macro is a convenient way to use iterators, very similar to + * EINA_LIST_FOREACH(). * - * This macro can be used for freeing the data of a list, like in the - * following example. It has the same goal as the one documented in - * EINA_LIST_FOREACH(), but using iterators: + * @remarks This macro can be used for freeing the data of a list, like in the + * following example. It has the same goal as the one documented in + * EINA_LIST_FOREACH(), but using iterators: * * @code * Eina_List *list; @@ -315,19 +263,25 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) * eina_list_free(list); * @endcode * - * @note this example is not optimal algorithm to release a list since - * it will walk the list twice, but it serves as an example. For - * optimized version use EINA_LIST_FREE() + * @remarks This example is not an optimal algorithm to release a list as + * it walks through the list twice, but it serves as an example. For an + * optimized version use EINA_LIST_FREE(). + * + * @remarks The order in which the elements are traversed depends on the + * underlying container and @b shouldn't be relied upon. + * + * @remarks Unless explicitly stated in the function's returning iterators, + * do not modify the iterated object while you walk through it. In this + * example using lists, do not remove the list nodes or the program might + * crash. This is not a limitation of the iterators themselves, + * but a limitation in the iterators implementations to keep them as simple + * and fast as possible. * - * @warning The order in which the elements will be traversed depends on the - * underlying container and @b shouldn't be relied upon. + * @param itr The iterator to use + * @param data A pointer to store the data \n + * It must be a pointer to support getting + * its address since eina_iterator_next() requires a pointer. * - * @warning unless explicitly stated in functions returning iterators, - * do not modify the iterated object while you walk it, in this - * example using lists, do not remove list nodes or you might - * crash! This is not a limitiation of iterators themselves, - * rather in the iterators implementations to keep them as simple - * and fast as possible. */ #define EINA_ITERATOR_FOREACH(itr, \ data) while (eina_iterator_next((itr), \ @@ -337,8 +291,4 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) * @} */ -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_lalloc.h b/src/lib/eina/eina_lalloc.h index 573562e601..f015d83dc6 100644 --- a/src/lib/eina/eina_lalloc.h +++ b/src/lib/eina/eina_lalloc.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -22,38 +22,38 @@ #include "eina_types.h" /** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** * @defgroup Eina_Lalloc_Group Lazy allocator + * @ingroup Eina_Tools_Group + * + * @brief This group provides lazy allocator functions. * * @{ */ -/** +/** * @typedef Eina_Lalloc_Alloc * Type definition for the callback used to allocate new items in a lazy allocator. - * */ typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num); + /** * @def EINA_LALLOC_ALLOC - * @param function The function to allocate. + * + * @since_tizen 2.3 + * + * @param function The function to allocate */ #define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function) -/** +/** * @typedef Eina_Lalloc_Free - * Type definition for the callback used to allocate new items in a lazy allocator. - * + * + * @brief Type definition for the callback used to allocate new items in a lazy allocator. */ typedef void (*Eina_Lalloc_Free)(void *user_data); /** * @def EINA_LALLOC_FREE - * @param function The function to free. + * @param function The function to free */ #define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function) @@ -67,11 +67,12 @@ typedef struct _Eina_Lalloc Eina_Lalloc; /** * @brief Create a new lazy allocator. * - * @param data The data for which memory will be allocated. - * @param alloc_cb The callback to allocate memory for @p data items. - * @param free_cb The callback to free memory for @p data items. - * @param num_init The number of @p data items to initally allocate space for. - * + * @since_tizen 2.3 + * + * @param[in] data The data for which memory will be allocated. + * @param[in] alloc_cb The callback to allocate memory for @p data items. + * @param[in] free_cb The callback to free memory for @p data items. + * @param[in] num_init The number of @p data items to initally allocate space for. * @return A new lazy allocator. * */ @@ -79,34 +80,36 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init) EINA_ARG_NONNULL(2, 3); - + /** * @brief Free the resources for a lazy allocator. * - * @param a The lazy allocator to free. + * @since_tizen 2.3 * + * @param[in] a The lazy allocator to free. */ EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1); /** * @brief Add several elements to a lazy allocator. * - * @param a The lazy allocater to add items to. - * @param num The number of elements to add. - * - * @return EINA_TRUE on success, else EINA_FALSE. + * @since_tizen 2.3 * + * @param[in] a The lazy allocater to add items to. + * @param[in] num The number of elements to add. + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num) EINA_ARG_NONNULL(1); - + /** * @brief Allocate one more of whatever the lazy allocator is allocating. * - * @param a The lazy allocator to add an item to. - * - * @return EINA_TRUE on success, else EINA_FALSE. + * @since_tizen 2.3 * + * @param[in] a The lazy allocator to add an item to. + * + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1); @@ -114,8 +117,4 @@ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1); * @} */ -/** - * @} - */ - #endif /* EINA_LALLOC_H_ */ diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h index 91de6ea08c..bad591ed21 100644 --- a/src/lib/eina/eina_list.h +++ b/src/lib/eina/eina_list.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -29,297 +29,69 @@ #include "eina_magic.h" /** - * @page eina_list_01_example_page Adding elements to Eina_List - * @dontinclude eina_list_01.c - * - * Creating an @ref Eina_List and adding elements to it is very easy and can be - * understood from an example: - * First thing is always to include Eina.h, for this example we also - * include stdio.h so we can use printf. - * @skip #include - * @until Eina.h - * - * Just some boilerplate code, declaring some variable and initializing eina. - * @until eina_init - * Here we add a sequence of elements to our list. By using append we add - * elements to the end of the list, so the list will look like this:@n - * @htmlonly - * <img src="eina_list_example_01_a.png" style="max-width: 100%;" /> - * <a href="eina_list_example_01_a.png">Full-size</a> - * @endhtmlonly - * @image rtf eina_list_example_01_a.png - * @image latex eina_list_example_01_a.eps "" width=\textwidth - * @until roslin - * There are a couple of interesting things happening here, first is that we are - * passing a NULL pointer to the first @ref eina_list_append() call, when this - * is done a list is created. The other @b very important detail to notice is - * that the return value is attributed to the @a list variable, this needs to - * be done every time we use a a function that alters the contents of the list. - * - * Now that we have a list with some elements in it we can look at its contents. - * @until printf - * - * There are many ways of accessing elements in the list, including by its - * index: - * @until nth - * @note It should be noted that the index starts at 0. - * - * @ref eina_list_append() is not the only way to add elements to a a list. A - * common requirement is to add an element in a specific position this can be - * accomplished using @ref eina_list_append_relative() and - * @ref eina_list_append_relative_list(): - * @until zarek - * First @a "cain" is added after the second element(remember that indexes are - * 0 based) and then we add @a "zarek" after @a "cain". - * - * @ref Eina_List also has prepend analogs to append functions we have used so - * far: - * @until lampkin - * With this additions our list now looks like this:@n - * @htmlonly - * <img src="eina_list_example_01_b.png" style="max-width: 100%;" /> - * <a href="eina_list_example_01_b.png">Full-size</a> - * @endhtmlonly - * @image rtf eina_list_example_01_b.png - * @image latex eina_list_example_01_b.eps "" width=\textwidth - * - * Once done using the list it needs to be freed, and since we are done with - * eina that also need to be shutdown: - * @until } - * - * The full source code can be found on the examples folder - * on the @ref eina_list_01_c "eina_list_01.c" file. - */ - -/** - * @page eina_list_01_c Adding elements to Eina_List example - * - * @include eina_list_01.c - * @example eina_list_01.c - */ - -/** - * @page eina_list_02_example_page Sorting Eina_List elements - * @dontinclude eina_list_02.c - * - * If you don't know how to create lists see - * @ref eina_list_01_example_page. - * - * @skip #include - * @until boomer - * This is the code we have already seen to create a list. Now if we need to - * search the list we can do it like this: - * @until return - * - * However if searching the list multiple times it probably is better to sort - * the list since the sorted_search functions are much faster: - * @until return - * - * Once the list is sorted it's not a good idea to use append/prepend functions - * since that would add the element in the wrong place, instead elements should - * be added with @ref eina_list_sorted_insert(): - * @until sorted_insert - * - * A noteworthy use case is adding an element to a list only if it doesn't exist - * already, this can accomplished by searching for the element that is closest - * to what is being added, and if that doesn't match add: - * @until append - * @note @ref eina_list_search_sorted_near_list() will tell you not only the - * nearest node to what was searched for but how it compares to your term, this - * way it is easy to know if you have to add before or after that node. - * - * It is sometimes useful to get a portion of the list as another list, here we - * take every element that comes after "boomer" and split it into "other_list": - * @until split_list - * - * It is also possible to add entire lists of elements using - * @ref eina_list_sorted_merge(): - * @until sorted_merge - * - * And as always release memory and shutdown eina before ending: - * @until } - * - * The full source code can be found on the examples folder - * on the @ref eina_list_02_c "eina_list_02.c" file. - */ - -/** - * @page eina_list_02_c Sorting Eina_List elements example + * @defgroup Eina_List_Group List + * @ingroup Eina_Containers_Group * - * @include eina_list_02.c - * @example eina_list_02.c - */ - -/** - * @page eina_list_03_example_page Reordering Eina_List elements - * @dontinclude eina_list_03.c - * - * If you don't know how to create lists see - * @ref eina_list_01_example_page. - * - * We start out with code that should be familiar by now: - * @skip #include - * @until gemenon - * - * You can move elements around in a list using @ref eina_list_move() or using - * @ref eina_list_promote_list() and @ref eina_list_demote_list() which move a - * list node to the head and end of the list respectevely: - * @until demote - * - * Removing elements from a list can be done with ease: - * @until sagitarius - * - * To replace an element in the list it is not necessary to remove it and then - * add with the new value, it is possible to just change the value of a node: - * @until aquarius - * - * We will now take a peek to see if the list still has the right number of - * elements: - * @until printf - * - * Now that the list is in alphabetical order let's create a copy of it in - * reverse order and print every element to see if worked as expected: - * @until iterator_free - * @note Always remember to free your iterators when done using them. - * - * And as always release memory and shutdown eina before ending: - * @until } - * - * The full source code can be found on the examples folder - * on the @ref eina_list_03_c "eina_list_03.c" file. - */ - -/** - * @page eina_list_03_c Reordering Eina_List elements example + * @brief This group discusses the functions that provide double linked list management. * - * @include eina_list_03.c - * @example eina_list_03.c - */ - -/** - * @page eina_list_04_example_page Eina_List and memory allocation - * @dontinclude eina_list_04.c - * - * If you don't know how to create lists see - * @ref eina_list_01_example_page. In this example we also use - * @ref Eina_Stringshare_Group, however it should be possible to understand the code - * regardless of previous knowledge about it. - * - * Here we have the usual list creation code with a twist, now we are using as - * data for the list memory that has to be freed later on. - * @skip #include - * @until Sharon - * - * This time we are going to iterate over our list in a different way: - * @until printf - * - * And now we are going to iterate over the list backwards: - * @until printf - * - * And now we need to free up the memory allocated during creation of the list: - * @until stringshare_del - * @note We don't need to use eina_list_free() since @ref EINA_LIST_FREE takes - * care of that. - * - * And shut everything down: - * @until } - * - * The full source code can be found on the examples folder - * on the @ref eina_list_04_c "eina_list_04.c" file. - */ - -/** - * @page eina_list_04_c Eina_List and memory allocation example + * @remarks Eina_List is a doubly linked list. It can store data of any type in the + * form of void pointers. It has convenience functions to do all the common + * operations, which means it should rarely, if ever, be necessary to directly + * access the struct's fields. Nevertheless it can be useful to understand the + * inner workings of the data structure being used. * - * @include eina_list_04.c - * @example eina_list_04.c - */ - -/** - * @addtogroup Eina_List_Group List - * - * @brief These functions provide double linked list management. - * - * Eina_List is a doubly linked list. It can store data of any type in the - * form of void pointers. It has convenience functions to do all the common - * operations which means it should rarely if ever be necessary to directly - * access the struct's fields. Nevertheless it can be useful to understand the - * inner workings of the data structure being used. - * - * @ref Eina_List nodes keep references to the previous node, the next node, its - * data and to an accounting structure. + * @remarks @ref Eina_List nodes keep references to the previous node, the next node, its + * data, and to an accounting structure. * + * @image html eina_list.png * @htmlonly - * <img src="eina_list.png" style="max-width: 100%;" /> * <a href="eina_list.png">Full-size</a> * @endhtmlonly * @image rtf eina_list.png * @image latex eina_list.eps width=5cm * - * @ref Eina_List_Accounting is used to improve the performance of some - * functions. It is private and <b>should not</b> be modified. It contains a - * reference to the end of the list and the number of elements in the list. - * - * @note Every function that modifies the contents of the list returns a pointer - * to the head of the list and it is essential that this be pointer be used in - * any future references to the list. - * - * Most functions have two versions that have the same effect but operate on - * different arguments, the @a plain functions operate over data(eg.: - * @ref eina_list_append_relative, @ref eina_list_remove, - * @ref eina_list_data_find), the @a list versions of these functions operate - * on @ref Eina_List nodes. - * - * @warning You must @b always use the pointer to the first element of the list - * as the list! - * @warning You must @b never use a pointer to an element in the middle of the - * list as the list! - * - * Here are some examples of @ref Eina_List usage: - * @li @ref eina_list_01_example_page - * @li @ref eina_list_02_example_page - * @li @ref eina_list_03_example_page - * @li @ref eina_list_04_example_page - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types + * @remarks @ref Eina_List_Accounting is used to improve the performance of some + * functions. It is private and <b>should not</b> be modified. It contains a + * reference to the end of the list and the number of elements in the list. * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers + * @remarks Every function that modifies the contents of the list returns a pointer + * to the head of the list and it is essential that this pointer be used in + * any future references to the list. * - * @{ - */ - -/** - * @defgroup Eina_List_Group List + * @remarks Most functions have two versions that have the same effect but operate on + * different arguments, the @a plain functions operate over data(eg.: + * @ref eina_list_append_relative, @ref eina_list_remove, + * @ref eina_list_data_find), the @a list versions of these functions operate + * on @ref Eina_List nodes. + * + * @remarks You must @b always use the pointer to the first element of the list, + * as the list. + * @remarks You must @b never use a pointer to an element in the middle of the + * list, as the list. * * @{ */ /** * @typedef Eina_List - * Type for a generic double linked list. + * @brief The structure type for a generic double linked list. */ typedef struct _Eina_List Eina_List; /** * @typedef Eina_List_Accounting - * Cache used to store the last element of a list and the number of - * elements, for fast access. + * @brief The structure type of the cache used to store the last element of a list and the number of + * elements, for fast access. */ typedef struct _Eina_List_Accounting Eina_List_Accounting; /** * @struct _Eina_List - * Type for a generic double linked list. + * @brief The structure type for a generic double linked list. */ struct _Eina_List { - void *data; /**< Pointer to list element payload */ + void *data; /**< Pointer to the list element payload */ Eina_List *next; /**< Next member in the list */ Eina_List *prev; /**< Previous member in the list */ Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */ @@ -329,41 +101,49 @@ struct _Eina_List /** * @struct _Eina_List_Accounting - * Cache used to store the last element of a list and the number of - * elements, for fast access. It is for private used and must not be - * touched. + * @brief The structure type for the cache used to store the last element of a list and the number of + * elements, for fast access. It is for private use and must not be + * touched. */ struct _Eina_List_Accounting { Eina_List *last; /**< Pointer to the last element of the list - don't touch */ - unsigned int count; /**< Number of elements of the list - don't touch */ + unsigned int count; /**< Number of elements in the list - don't touch */ EINA_MAGIC }; /** - * @brief Append the given data to the given linked list. + * @brief Appends the given data to the given linked list. * - * @param list The given list. - * @param data The data to append. - * @return A list pointer. + * @details This function appends @a data to @a list. If @a list is @c NULL, a + * new list is returned. On success, a new list pointer that should be + * used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. * - * This function appends @p data to @p list. If @p list is @c NULL, a - * new list is returned. On success, a new list pointer that should be - * used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. + * @since_tizen 2.3 * - * The following example code demonstrates how to ensure that the - * given data has been successfully appended. + * @remarks The following example code demonstrates how to ensure that the + * given data has been successfully appended. * * @code * Eina_List *list = NULL; * extern void *my_data; * * list = eina_list_append(list, my_data); + * if (eina_error_get()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list(or NULL). + * @remarks @a list must be a pointer to the first element of the list(or NULL). + * + * @param[in] list The given list + * @param[in] data The data to append + * @return A list pointer + * */ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; @@ -371,17 +151,15 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E /** * @brief Prepends the given data to the given linked list. * - * @param list The given list. - * @param data The data to prepend. - * @return A list pointer. + * @details This function prepends @a data to @a list. If @a list is @c NULL, a + * new list is returned. On success, a new list pointer that should be + * used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. * - * This function prepends @p data to @p list. If @p list is @c NULL, a - * new list is returned. On success, a new list pointer that should be - * used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. + * @since_tizen 2.3 * - * The following example code demonstrates how to ensure that the - * given data has been successfully prepended. + * @remarks The following example code demonstrates how to ensure that the + * given data has been successfully prepended. * * Example: * @code @@ -389,31 +167,38 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E * extern void *my_data; * * list = eina_list_prepend(list, my_data); + * if (eina_error_get()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given list + * @param[in] data The data to prepend. + * @return A list pointer + * */ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Insert the given data into the given linked list after the specified data. + * @brief Inserts the given data into the given linked list after the specified data. * - * @param list The given linked list. - * @param data The data to insert. - * @param relative The data to insert after. - * @return A list pointer. + * @details This function inserts @a data to @a list after @a relative. If + * @a relative is not in the list, @a data is appended to the end of + * the list. If @a list is @c NULL, a new list is returned. If there + * are multiple instances of @a relative in the list, @a data is + * inserted after the first instance.On success, a new list pointer + * that should be used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. * - * This function inserts @p data to @p list after @p relative. If - * @p relative is not in the list, @p data is appended to the end of - * the list. If @p list is @c NULL, a new list is returned. If there - * are multiple instances of @p relative in the list, @p data is - * inserted after the first instance.On success, a new list pointer - * that should be used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. + * @since_tizen 2.3 * - * The following example code demonstrates how to ensure that the - * given data has been successfully inserted. + * @remarks The following example code demonstrates how to ensure that the + * given data has been successfully inserted. * * @code * Eina_List *list = NULL; @@ -421,54 +206,70 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) * extern void *relative_member; * * list = eina_list_append(list, relative_member); + * if (eina_error_get()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * list = eina_list_append_relative(list, my_data, relative_member); + * if (eina_error_get()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list + * @param[in] data The data to insert + * @param[in] relative The data to insert after + * @return A list pointer + * */ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Append a list node to a linked list after the specified member - * - * @param list The given linked list. - * @param data The data to insert. - * @param relative The list node to insert after. - * @return A list pointer. - * - * This function inserts @p data to @p list after the list node - * @p relative. If @p list or @p relative are @c NULL, @p data is just - * appended to @p list using eina_list_append(). If @p list is - * @c NULL, a new list is returned. If there are multiple instances - * of @p relative in the list, @p data is inserted after the first - * instance. On success, a new list pointer that should be used in - * place of the one given to this function is returned. Otherwise, the - * old pointer is returned. - * - * @warning @p list must be a pointer to the first element of the list. + * @brief Appends a list node to a linked list after the specified member. + * + * @details This function inserts @a data to @a list after the list node + * @a relative. If @a list or @a relative is @c NULL, @a data is just + * appended to @a list using eina_list_append(). If @a list is + * @c NULL, a new list is returned. If there are multiple instances + * of @a relative in the list, @a data is inserted after the first + * instance. On success, a new list pointer that should be used in + * place of the one given to this function is returned. Otherwise, the + * old pointer is returned. + * + * @since_tizen 2.3 + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list + * @param[in] data The data to insert + * @param[in] relative The list node to insert after + * @return A list pointer + * */ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Prepend a data pointer to a linked list before the specified member + * @brief Prepends a data pointer to a linked list before the specified member. * - * @param list The given linked list. - * @param data The data to insert. - * @param relative The data to insert before. - * @return A list pointer. + * @details This function inserts @a data to @a list before @a relative. If + * @a relative is not in the list, @a data is prepended to the list + * with eina_list_prepend(). If @a list is @c NULL, a new list is + * returned. If there are multiple instances of @a relative in the + * list, @a data is inserted before the first instance. On success, a + * new list pointer that should be used in place of the one given to + * this function is returned. Otherwise, the old pointer is returned. * - * This function inserts @p data to @p list before @p relative. If - * @p relative is not in the list, @p data is prepended to the list - * with eina_list_prepend(). If @p list is @c NULL, a new list is - * returned. If there are multiple instances of @p relative in the - * list, @p data is inserted before the first instance. On success, a - * new list pointer that should be used in place of the one given to - * this function is returned. Otherwise, the old pointer is returned. + * @since_tizen 2.3 * - * The following code example demonstrates how to ensure that the - * given data has been successfully inserted. + * @remarks The following code example demonstrates how to ensure that the + * given data has been successfully inserted. * * @code * Eina_List *list = NULL; @@ -476,97 +277,121 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const * extern void *relative_member; * * list = eina_list_append(list, relative_member); + * if (eina_error_get_error()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * list = eina_list_prepend_relative(list, my_data, relative_member); + * if (eina_error_get()) + * { + * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); + * exit(-1); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list + * @param[in] data The data to insert + * @param[in] relative The data to insert before + * @return A list pointer + * */ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Prepend a list node to a linked list before the specified member - * - * @param list The given linked list. - * @param data The data to insert. - * @param relative The list node to insert before. - * @return A list pointer. - * - * This function inserts @p data to @p list before the list node - * @p relative. If @p list or @p relative are @c NULL, @p data is just - * prepended to @p list using eina_list_prepend(). If @p list is - * @c NULL, a new list is returned. If there are multiple instances - * of @p relative in the list, @p data is inserted before the first - * instance. On success, a new list pointer that should be used in - * place of the one given to this function is returned. Otherwise, the - * old pointer is returned. - * - * @warning @p list must be a pointer to the first element of the list. + * @brief Prepends a list node to a linked list before the specified member. + * + * @details This function inserts @a data to @a list before the list node + * @a relative. If @a list or @a relative is @c NULL, @a data is just + * prepended to @a list using eina_list_prepend(). If @a list is + * @c NULL, a new list is returned. If there are multiple instances + * of @a relative in the list, @a data is inserted before the first + * instance. On success, a new list pointer that should be used in + * place of the one given to this function is returned. Otherwise, the + * old pointer is returned. + * + * @since_tizen 2.3 + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list + * @param[in] data The data to insert + * @param[in] relative The list node to insert before + * @return A list pointer + * */ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Insert a new node into a sorted list. - * - * @param list The given linked list, @b must be sorted. - * @param func The function called for the sort. - * @param data The data to insert sorted. - * @return A list pointer. - * - * This function inserts values into a linked list assuming it was - * sorted and the result will be sorted. If @p list is @c NULLL, a new - * list is returned. On success, a new list pointer that should be - * used in place of the one given to this function is - * returned. Otherwise, the old pointer is returned. - * - * @note O(log2(n)) comparisons (calls to @p func) average/worst case - * performance as it uses eina_list_search_sorted_near_list() and thus - * is bounded to that. As said in eina_list_search_sorted_near_list(), - * lists do not have O(1) access time, so walking to the correct node - * can be costly, consider worst case to be almost O(n) pointer - * dereference (list walk). - * - * @warning @p list must be a pointer to the first element of the list. + * @brief Inserts a new node into a sorted list. + * + * @details This function inserts values into a linked list assuming it is + * sorted and the result is sorted. If @a list is @c NULLL, a new + * list is returned. On success, a new list pointer that should be + * used in place of the one given to this function is + * returned. Otherwise, the old pointer is returned. + * + * @since_tizen 2.3 + * + * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func) + * as it uses eina_list_search_sorted_near_list() and thus + * is bounded to that. As said in eina_list_search_sorted_near_list(), + * lists do not have O(1) access time, so walking to the correct node + * can be costly, consider worst case to be almost O(n) pointer + * dereference (list walk). + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list, @b must be sorted + * @param[in] func The function called for the sort + * @param[in] data The data to insert in the sorted list + * @return A list pointer + * + * @see eina_error_get() */ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; /** - * @brief Remove the first instance of the specified data from the given list. + * @brief Removes the first instance of the specified data from the given list. + * + * @details This function removes the first instance of @a data from + * @a list. If the specified data is not in the given list (this + * includes the case where @a data is @c NULL), nothing is done and the + * specified @a list is returned. If @a list is @c NULL, @c NULL is returned, + * otherwise a new list pointer that should be used in place of the one + * passed to this function is returned. + * + * @since_tizen 2.3 * - * @param list The given list. - * @param data The specified data. - * @return A list pointer. + * @remarks @a list must be a pointer to the first element of the list. * - * This function removes the first instance of @p data from - * @p list. If the specified data is not in the given list (this - * includes the case where @p data is @c NULL), nothing is done and the - * specified @p list returned. If @p list is @c NULL, @c NULL is returned, - * otherwise a new list pointer that should be used in place of the one - * passed to this function. + * @param[in] list The given list + * @param[in] data The specified data + * @return A list pointer * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Remove the specified list node. + * @brief Removes the specified list node. * - * @param list The given linked list. - * @param remove_list The list node which is to be removed. - * @return A list pointer. + * @details This function removes the list node @a remove_list from @a list and + * frees the list node structure @a remove_list. If @a list is + * @c NULL, this function returns @c NULL. If @a remove_list is + * @c NULL, it returns @a list, otherwise, a new list pointer that + * should be used in place of the one passed to this function is returned. * - * This function removes the list node @p remove_list from @p list and - * frees the list node structure @p remove_list. If @p list is - * @c NULL, this function returns @c NULL. If @p remove_list is - * @c NULL, it returns @p list, otherwise, a new list pointer that - * should be used in place of the one passed to this function. + * @since_tizen 2.3 * - * The following code gives an example (notice we use EINA_LIST_FOREACH - * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after - * removing the current node). + * @remarks The following code gives an example (notice we use EINA_LIST_FOREACH + * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after + * removing the current node). * * @code * extern Eina_List *list; @@ -576,30 +401,33 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E * * EINA_LIST_FOREACH(list, l, data) * { - * if (data == my_data) - * { - * list = eina_list_remove_list(list, l); - * break; - * } + * if (data == my_data) + * { + * list = eina_list_remove_list(list, l); + * break; + * } * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The given linked list + * @param[in] remove_list The list node to be removed + * @return A list pointer + * */ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Move the specified data to the head of the list. + * @brief Moves the specified data to the head of the list. * - * @param list The list handle to move the data. - * @param move_list The list node to move. - * @return A new list handle to replace the old one + * @details This function moves @a move_list to the front of @a list. If the list is + * @c NULL, @c NULL is returned. If @a move_list is @c NULL, + * @a list is returned. Otherwise, a new list pointer that should be + * used in place of the one passed to this function is returned. * - * This function move @p move_list to the front of @p list. If list is - * @c NULL, @c NULL is returned. If @p move_list is @c NULL, - * @p list is returned. Otherwise, a new list pointer that should be - * used in place of the one passed to this function. + * @since_tizen 2.3 * * Example: * @code @@ -610,30 +438,33 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem * * EINA_LIST_FOREACH(list, l, data) * { - * if (data == my_data) - * { - * list = eina_list_promote_list(list, l); - * break; - * } + * if (data == my_data) + * { + * list = eina_list_promote_list(list, l); + * break; + * } * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list handle to move the data + * @param[in] move_list The list node to move + * @return A new list handle to replace the old one + * */ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Move the specified data to the tail of the list. + * @brief Moves the specified data to the tail of the list. * - * @param list The list handle to move the data. - * @param move_list The list node to move. - * @return A new list handle to replace the old one + * @details This function moves @a move_list to the back of @a list. If the list is + * @c NULL, @c NULL is returned. If @a move_list is @c NULL, + * @a list is returned. Otherwise, a new list pointer that should be + * used in place of the one passed to this function is returned. * - * This function move @p move_list to the back of @p list. If list is - * @c NULL, @c NULL is returned. If @p move_list is @c NULL, - * @p list is returned. Otherwise, a new list pointer that should be - * used in place of the one passed to this function. + * @since_tizen 2.3 * * Example: * @code @@ -644,29 +475,32 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo * * EINA_LIST_FOREACH(list, l, data) * { - * if (data == my_data) - * { - * list = eina_list_demote_list(list, l); - * break; - * } + * if (data == my_data) + * { + * list = eina_list_demote_list(list, l); + * break; + * } * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list handle to move the data + * @param[in] move_list The list node to move + * @return A new list handle to replace the old one + * */ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list); /** - * @brief Find a member of a list and return the member. + * @brief Finds a member of a list and returns the member. * - * @param list The list to search for a data. - * @param data The data pointer to find in the list. - * @return The found member data pointer if found, @c NULL otherwise. + * @details This function searches in @a list from beginning to end for the + * first member whose data pointer is @a data. If it is found, @a data + * is returned, otherwise @c NULL is returned. * - * This function searches in @p list from beginning to end for the - * first member whose data pointer is @p data. If it is found, @p data - * will be returned, otherwise @c NULL will be returned. + * @since_tizen 2.3 * * Example: * @code @@ -679,126 +513,151 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to search for data + * @param[in] data The data pointer to find in the list + * @return The found member data pointer, otherwise @c NULL + * */ EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Find a member of a list and return the list node containing that member. + * @brief Finds a member of a list and returns the list node containing that member. + * + * @details This function searches in @a list from beginning to end for the + * first member whose data pointer is @a data. If it is found, the + * list node containing the specified member is returned, otherwise + * @c NULL is returned. + * + * @since_tizen 2.3 * - * @param list The list to search for data. - * @param data The data pointer to find in the list. - * @return The found members list node on success, @c NULL otherwise. + * @remarks @a list must be a pointer to the first element of the list. * - * This function searches in @p list from beginning to end for the - * first member whose data pointer is @p data. If it is found, the - * list node containing the specified member is returned, otherwise - * @c NULL is returned. + * @param[in] list The list to search for data + * @param[in] data The data pointer to find in the list + * @return The found members list node on success, otherwise @c NULL * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; /** - * @brief Move a data pointer from one list to another + * @brief Moves a data pointer from one list to another. * - * @param to The list to move the data to - * @param from The list to move from - * @param data The data to move - * @return #EINA_TRUE on success, else #EINA_FALSE + * @details This function is a shortcut for doing the following: + * to = eina_list_append(to, data); + * from = eina_list_remove(from, data); * - * This function is a shortcut for doing the following: - * to = eina_list_append(to, data); - * from = eina_list_remove(from, data); + * @since_tizen 2.3 + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[out] to The list to move the data to + * @param[out] from The list to move from + * @param[in] data The data to move + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data); /** - * @brief Move a list node from one list to another + * @brief Moves a list node from one list to another. + * + * @details This function is a shortcut for doing the following: + * to = eina_list_append(to, data->data); + * from = eina_list_remove_list(from, data); * - * @param to The list to move the data to - * @param from The list to move from - * @param data The list node containing the data to move - * @return #EINA_TRUE on success, else #EINA_FALSE + * @since_tizen 2.3 * - * This function is a shortcut for doing the following: - * to = eina_list_append(to, data->data); - * from = eina_list_remove_list(from, data); + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[out] to The list to move the data to + * @param[out] from The list to move from + * @param[in] data The list node containing the data to move + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data); /** - * @brief Free an entire list and all the nodes, ignoring the data contained. - - * @param list The list to free + * @brief Frees an entire list and all the nodes, ignoring the data contained. + * + * @details This function frees all the nodes of @a list. It does not free the + * data of the nodes. To free them, use #EINA_LIST_FREE. + * + * @since_tizen 2.3 + * + * @param[in] list The list to free * @return A @c NULL pointer * - * This function frees all the nodes of @p list. It does not free the - * data of the nodes. To free them, use #EINA_LIST_FREE. */ EAPI Eina_List *eina_list_free(Eina_List *list); /** - * @brief Get the nth member's data pointer in a list. + * @brief Gets the nth member's data pointer in a list. + * + * @details This function returns the data pointer of element number @a n, in + * the @a list. The first element in the array is element number 0. If + * the element number @a n does not exist, @c NULL is + * returned. Otherwise, the data of the found element is returned. * - * @param list The list to get the specified member number from. - * @param n The number of the element (0 being the first). - * @return The data pointer stored in the specified element. + * @since_tizen 2.3 * - * This function returns the data pointer of element number @p n, in - * the @p list. The first element in the array is element number 0. If - * the element number @p n does not exist, @c NULL is - * returned. Otherwise, the data of the found element is returned. + * @remarks Worst case is O(n). * - * @note Worst case is O(n). + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to get the specified member number from + * @param[in] n The number of the element (0 being the first) + * @return The data pointer stored in the specified element * - * @warning @p list must be a pointer to the first element of the list. */ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Get the nth member's list node in a list. + * @brief Gets the nth member's list node in a list. + * + * @details This function returns the list node of element number @a n, in + * @a list. The first element in the array is element number 0. If the + * element number @a n does not exist or @a list is @c NULL, or @a n is + * greater than the count of the elements in @a list minus 1, @c NULL is + * returned. Otherwise the list node stored in the numbered element is + * returned. + * + * @since_tizen 2.3 * - * @param list The list to get the specfied member number from. - * @param n The number of the element (0 being the first). - * @return The list node stored in the numbered element. + * @remarks Worst case is O(n). * - * This function returns the list node of element number @p n, in - * @p list. The first element in the array is element number 0. If the - * element number @p n does not exist or @p list is @c NULL or @p n is - * greater than the count of elements in @p list minus 1, @c NULL is - * returned. Otherwise the list node stored in the numbered element is - * returned. + * @remarks @a list must be a pointer to the first element of the list. * - * @note Worst case is O(n). + * @param[in] list The list to get the specfied member number from + * @param[in] n The number of the element (0 being the first) + * @return The list node stored in the numbered element * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Reverse all the elements in the list. + * @brief Reverses all the elements in the list. * - * @param list The list to reverse. - * @return The list head after it has been reversed. + * @details This function reverses the order of all the elements in @a list, so the + * last member is now first, and so on. If @a list is @c NULL, this + * function returns @c NULL. * - * This function reverses the order of all elements in @p list, so the - * last member is now first, and so on. If @p list is @c NULL, this - * functon returns @c NULL. + * @since_tizen 2.3 * - * @note @b in-place: this will change the given list, so you should - * now point to the new list head that is returned by this function. + * @remarks @b in-place: This changes the given list, so you should + * now point to the new list head that is returned by this function. * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to reverse + * @return The list head after it has been reversed * * @see eina_list_reverse_clone() * @see eina_list_iterator_reversed_new() @@ -807,19 +666,21 @@ EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_R /** - * @brief Clone (copy) all the elements in the list in reverse order. + * @brief Clones (copies) all the elements in the list in the reverse order. + * + * @details This function reverses the order of all the elements in @a list, so the + * last member is now first, and so on. If @a list is @c NULL, this + * function returns @c NULL. This returns a copy of the given list. * - * @param list The list to reverse. - * @return The new list that has been reversed. + * @since_tizen 2.3 * - * This function reverses the order of all elements in @p list, so the - * last member is now first, and so on. If @p list is @c NULL, this - * functon returns @c NULL. This returns a copy of the given list. + * @remarks @b copy: This copies the list and you should then use + * eina_list_free() when it is not required anymore. * - * @note @b copy: this will copy the list and you should then - * eina_list_free() when it is not required anymore. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning @p list must be a pointer to the first element of the list. + * @param[in] list The list to reverse + * @return The new list that has been reversed * * @see eina_list_reverse() * @see eina_list_clone() @@ -828,19 +689,21 @@ EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_W /** - * @brief Clone (copy) all the elements in the list in exactly same order. + * @brief Clones (copies) all the elements in the list in the exactly same order. + * + * @details This function clones in an order which is same as the order of all the elements in @a list. + * If @a list is @c NULL, this functon returns @c NULL. This returns a copy of + * the given list. * - * @param list The list to clone. - * @return The new list that has been cloned. + * @since_tizen 2.3 * - * This function clone in order of all elements in @p list. If @p list - * is @c NULL, this functon returns @c NULL. This returns a copy of - * the given list. + * @remarks @b copy: This copies the list and you should then use + * eina_list_free() when it is not required anymore. * - * @note @b copy: this will copy the list and you should then - * eina_list_free() when it is not required anymore. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning @p list must be a pointer to the first element of the list. + * @param[in] list The list to clone + * @return The new list that has been cloned * * @see eina_list_reverse_clone() */ @@ -848,24 +711,21 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS /** - * @brief Sort a list according to the ordering func will return. + * @brief Sorts a list according to the ordering that @a func returns. * - * @param list The list handle to sort. - * @param limit The maximum number of list elements to sort. - * @param func A function pointer that can handle comparing the list data - * nodes. - * @return the new head of list. + * @details This function sorts @a list. + * If @a limit is @c 0 or greater than the number of + * elements in @a list, all the elements are sorted. @a func is used to + * compare two elements of @a list. If @a func is @c NULL, this function returns + * @a list. * - * This function sorts @p list. If @p limit is 0 or greater than the number of - * elements in @p list, all the elements are sorted. @p func is used to - * compare two elements of @p list. If @p func is @c NULL, this function returns - * @p list. + * @since_tizen 2.3 * - * @note @b in-place: this will change the given list, so you should - * now point to the new list head that is returned by this function. + * @remarks @b in-place: This changes the given list, so you should + * now point to the new list head that is returned by this function. * - * @note Worst case is O(n * log2(n)) comparisons (calls to func()). - * That means that for 1,000,000 list sort will do 20,000,000 comparisons. + * @remarks Worst case is O(n * log2(n)) comparisons (calls to func()). + * That means, for 1,000,000 list sort we do 20,000,000 comparisons. * * Example: * @code @@ -885,67 +745,51 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS * list = eina_list_sort(list, eina_list_count(list), sort_cb); * @endcode * - * @warning @p list must be a pointer to the first element of the list. - */ -EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; - - -/** - * @brief Shuffle list. - * - * @param list The list handle to shuffle. - * @param func A function pointer that can return an int between 2 inclusives values - * @return the new head of list. - * - * This function shuffles @p list. - * @p func is used to generate random list indexes within the range of - * unshuffled list items. If @p func is @c NULL, rand is used. - * - * @note @b in-place: this will change the given list, so you should - * now point to the new list head that is returned by this function. + * @remarks @a list must be a pointer to the first element of the list. * - * @since 1.8 + * @param[in] list The list handle to sort + * @param[in] limit The maximum number of list elements to sort + * @param[in] func A function pointer that can handle comparing the list data + * nodes + * @return The new head of the list * - * @warning @p list must be a pointer to the first element of the list. */ -EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb func) EINA_WARN_UNUSED_RESULT; +EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; /** - * @brief Merge two list. + * @brief Merges two lists. + * + * @details This function puts @a right at the end of @a left and returns the head. + * Both @a left and @a right do not exist anymore after the merge. * - * @param left Head list to merge. - * @param right Tail list to merge. - * @return A new merged list. + * @since_tizen 2.3 * - * This function puts right at the end of left and returns the head. + * @remarks Merge cost is O(n), @b n being the size of the smallest + * list. This is due to the need to fix accounting of that segment, + * making count and last access O(1). * - * Both left and right do not exist anymore after the merge. + * @remarks @a list must be a pointer to the first element of the list. * - * @note merge cost is O(n), being @b n the size of the smallest - * list. This is due the need to fix accounting of that segment, - * making count and last access O(1). + * @param[in] left The head list to merge + * @param[in] right The tail list to merge + * @return A new merged list * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT; /** - * @brief Merge two sorted list according to the ordering func will return. + * @brief Merges two sorted lists according to the ordering that @a func returns. * - * @param left First list to merge. - * @param right Second list to merge. - * @param func A function pointer that can handle comparing the list data - * nodes. - * @return A new sorted list. + * @details This function compares the head of @a left and @a right, and chooses the + * smallest one to be the head of the returned list. It continues this process + * for all the entries of both the lists. * - * This function compares the head of @p left and @p right, and choose the - * smallest one to be head of the returned list. It will continue this process - * for all entry of both list. + * Both the left and the right lists are not vaild anymore after the merge and should + * not be used. If @a func is @c NULL, it returns @c NULL. * - * Both left and right lists are not vailid anymore after the merge and should - * not be used. If @p func is @c NULL, it will return @c NULL. + * @since_tizen 2.3 * * Example: * @code @@ -966,61 +810,63 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb); * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] left The first list to merge + * @param[in] right The second list to merge + * @param[in] func A function pointer that can handle comparing the list data + * nodes + * @return A new sorted list + * */ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; /** - * @brief Split a list into 2 lists. + * @brief Splits a list into 2 lists. * - * @param list List to split. - * @param relative The list will be split after @p relative. - * @param right The head of the new right list. - * @return The new left list + * @details This function splits @a list into two lists ( left and right ) after the node @a relative. @a relative + * becomes the last node of the left list. If @a list or @a right is @c NULL, @a list is returned. + * If @a relative is @c NULL, @a right is set to @a list and @c NULL is returned. + * If @a relative is the last node of @a list, @a list is returned and @a right is set to @c NULL. + * + * List does not exist anymore after the split. * - * This function splits @p list into two lists ( left and right ) after the node @p relative. @p Relative - * will become the last node of the left list. If @p list or @p right are @c NULL list is returns. - * If @p relative is NULL right is set to @p list and @c NULL is returns. - * If @p relative is the last node of @p list list is returns and @p right is set to @c NULL. + * @since_tizen 2.3 * - * list does not exist anymore after the split. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to split + * @param[in] relative The list is split after @a relative + * @param[out] right The head of the new right list + * @return The new left list * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT; /** - * @brief Returns node nearest to data is in the sorted list. - * - * @param list The list to search for data, @b must be sorted. - * @param func A function pointer that can handle comparing the list data nodes. - * @param data reference value to search. - * @param result_cmp if provided returns the result of - * func(node->data, data) node being the last (returned) node. If node - * was found (exact match), then it is 0. If returned node is smaller - * than requested data, it is less than 0 and if it's bigger it's - * greater than 0. It is the last value returned by func(). - * @return the nearest node, @c NULL if not found. - * - * This function searches for a node containing @p data as its data in @p list, - * if such a node exists it will be returned and @p result_cmp will be @p 0. If - * the data of no node in @p list is equal to @p data, the node with the nearest - * value to that will be returned and @p result_cmp will be the return value of - * @p func with @p data and the returned node's data as arguments. - * - * This function is useful for inserting an element in the list only in case it - * isn't already present in the list, the naive way of doing this would be: + * @brief Returns the node nearest to data in the sorted list. + * + * @details This function searches for a node containing @a data as its data in @a list, + * if such a node exists it is returned and @a result_cmp is @c 0. If + * the data of no node in @a list is equal to @a data, the node with the nearest + * value to that is returned and @a result_cmp is the return value of + * @a func with @a data and the returned node's data as arguments. + * + * @since_tizen 2.3 + * + * @remarks This function is useful for inserting an element in the list only in case it + * isn't already present in the list, the naive way of doing this would be: * @code * void *ptr = eina_list_data_find(list, "my data"); * if (!ptr) * eina_list_sorted_insert(list, "my data"); * @endcode - * - * However this has the downside of walking through the list twice, once to - * check if the data is already present and another to insert the element in the - * corret position. This can be done more eficiently: + * + * @remarks However, this has the downside of walking through the list twice, once to + * check if the data is already present and another to insert the element in the + * correct position. This can be done more efficiently by: * @code * int cmp_result; * l = eina_list_search_sorted_near_list(list, cmp_func, "my data", @@ -1030,21 +876,32 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela * else if (cmp_result < 0) * list = eina_list_append_relative_list(list, "my data", l); * @endcode - * - * If @a cmp_result is 0 the element is already in the list and we need not - * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to - * come after @a l(the nearest node present), if less than zero before. - * - * @note O(log2(n)) average/worst case performance, for 1,000,000 - * elements it will do a maximum of 20 comparisons. This is much - * faster than the 1,000,000 comparisons made naively walking the list - * from head to tail, so depending on the number of searches and - * insertions, it may be worth to eina_list_sort() the list and do the - * searches later. As lists do not have O(1) access time, walking to - * the correct node can be costly, consider worst case to be almost - * O(n) pointer dereference (list walk). - * - * @warning @p list must be a pointer to the first element of the list. + * + * If @a cmp_result is 0 the element is already in the list and we need not + * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to + * come after @a l(the nearest node present), if less than zero it needs to come before. + * + * @remarks Average/worst case performance is O(log2(n)), for 1,000,000 + * elements it does a maximum of 20 comparisons. This is much + * faster than the 1,000,000 comparisons made naively by walking the list + * from head to tail, so depending on the number of searches and + * insertions, it may be better to eina_list_sort() the list and do the + * searches later. As lists do not have O(1) access time, walking to + * the correct node can be costly, consider worst case to be almost + * O(n) pointer dereference (list walk). + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to search for data, @b must be sorted + * @param[in] func A function pointer that can handle comparing the list data nodes + * @param[in] data The reference value to search + * @param[in] result_cmp If provided it returns the result of + * the func(node->data, data) node being the last (returned) node. If node + * is found (exact match), then it is @c 0. If the returned node is smaller + * than the requested data, it is less than @c 0 and if it's bigger it's + * greater than @c 0. It is the last value returned by func(). + * @return The nearest node, otherwise @c NULL if not found + * * * @see eina_list_search_sorted_list() * @see eina_list_sort() @@ -1054,31 +911,33 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li /** - * @brief Returns node if data is in the sorted list. + * @brief Returns the node if data is in the sorted list. + * + * @since_tizen 2.3 * - * @param list The list to search for data, @b must be sorted. - * @param func A function pointer that can handle comparing the list data nodes. - * @param data reference value to search. - * @return the node if func(node->data, data) == 0, @c NULL if not found. + * @remarks This can be used to check if some value is inside the list and get + * the container node in this case. It should be used when the list is + * known to be sorted as it does a binary search for results. * - * This can be used to check if some value is inside the list and get - * the container node in this case. It should be used when list is - * known to be sorted as it will do binary search for results. + * Example: Imagine a user gives a string, you check if it's in the list + * before duplicating its contents. * - * Example: imagine user gives a string, you check if it's in the list - * before duplicating its contents. + * @remarks Average/worst case performance is O(log2(n)), for 1,000,000 + * elements it does a maximum of 20 comparisons. This is much + * faster than the 1,000,000 comparisons made by + * eina_list_search_unsorted_list(), so depending on the number of + * searches and insertions, it may be better to eina_list_sort() the + * list and do the searches later. As said in + * eina_list_search_sorted_near_list(), lists do not have O(1) access + * time, so walking to the correct node can be costly, consider worst + * case to be almost O(n) pointer dereference (list walk). * - * @note O(log2(n)) average/worst case performance, for 1,000,000 - * elements it will do a maximum of 20 comparisons. This is much - * faster than the 1,000,000 comparisons made by - * eina_list_search_unsorted_list(), so depending on the number of - * searches and insertions, it may be worth to eina_list_sort() the - * list and do the searches later. As said in - * eina_list_search_sorted_near_list(), lists do not have O(1) access - * time, so walking to the correct node can be costly, consider worst - * case to be almost O(n) pointer dereference (list walk). + * @remarks @a list must be a pointer to the first element of the list. * - * @warning @p list must be a pointer to the first element of the list. + * @param[in] list The list to search for data, @b must be sorted + * @param[in] func A function pointer that can handle comparing the list data nodes + * @param[in] data The reference value to search + * @return The node if func(node->data, data) == 0, otherwise @c NULL if not found * * @see eina_list_search_sorted() * @see eina_list_sort() @@ -1090,32 +949,34 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E /** - * @brief Returns node data if it is in the sorted list. + * @brief Returns the node data if it is in the sorted list. * - * @param list The list to search for data, @b must be sorted. - * @param func A function pointer that can handle comparing the list data nodes. - * @param data reference value to search. - * @return the node value (@c node->data) if func(node->data, data) == 0, - * NULL if not found. + * @since_tizen 2.3 * - * This can be used to check if some value is inside the list and get - * the existing instance in this case. It should be used when list is - * known to be sorted as it will do binary search for results. + * @remarks This can be used to check if some value is inside the list and get + * the existing instance in this case. It should be used when a list is + * known to be sorted as it does a binary search for results. * - * Example: imagine user gives a string, you check if it's in the list - * before duplicating its contents. + * Example: Imagine a user gives a string, you check if it's in the list + * before duplicating its contents. * - * @note O(log2(n)) average/worst case performance, for 1,000,000 - * elements it will do a maximum of 20 comparisons. This is much - * faster than the 1,000,000 comparisons made by - * eina_list_search_unsorted(), so depending on the number of - * searches and insertions, it may be worth to eina_list_sort() the - * list and do the searches later. As said in - * eina_list_search_sorted_near_list(), lists do not have O(1) access - * time, so walking to the correct node can be costly, consider worst - * case to be almost O(n) pointer dereference (list walk). + * @remarks Average/worst case performance is O(log2(n)), for 1,000,000 + * elements it does a maximum of 20 comparisons. This is much + * faster than the 1,000,000 comparisons made by + * eina_list_search_unsorted(), so depending on the number of + * searches and insertions, it may be better to eina_list_sort() the + * list and do the searches later. As said in + * eina_list_search_sorted_near_list(), lists do not have O(1) access + * time, so walking to the correct node can be costly, consider worst + * case to be almost O(n) pointer dereference (list walk). * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to search for data, @b must be sorted + * @param[in] func A function pointer that can handle comparing the list data nodes. + * @param[in] data The reference value to search + * @return The node value (@c node->data) if func(node->data, data) == 0, + * otherwise @c NULL if not found * * @see eina_list_search_sorted_list() * @see eina_list_sort() @@ -1126,24 +987,26 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C /** - * @brief Returns node if data is in the unsorted list. + * @brief Returns the node if data is in the unsorted list. + * + * @since_tizen 2.3 * - * @param list The list to search for data, may be unsorted. - * @param func A function pointer that can handle comparing the list data nodes. - * @param data reference value to search. - * @return the node if func(node->data, data) == 0, @c NULL if not found. + * @remarks This can be used to check if some value is inside the list and get + * the container node in this case. * - * This can be used to check if some value is inside the list and get - * the container node in this case. + * Example: Imagine a user gives a string, you check if it's in the list + * before duplicating its contents. * - * Example: imagine user gives a string, you check if it's in the list - * before duplicating its contents. + * @remarks This is expensive and may walk the whole list, it's order-N, + * that is for 1,000,000 elements list it may walk and compare + * 1,000,000 nodes. * - * @note this is expensive and may walk the whole list, it's order-N, - * that is for 1,000,000 elements list it may walk and compare - * 1,000,000 nodes. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning @p list must be a pointer to the first element of the list. + * @param[in] list The list to search for data, may be unsorted + * @param[in] func A function pointer that can handle comparing the list data nodes + * @param[in] data The reference value to search + * @return The node if func(node->data, data) == 0, otherwise @c NULL if not found * * @see eina_list_search_sorted_list() * @see eina_list_search_unsorted() @@ -1152,25 +1015,27 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, /** - * @brief Returns node data if it is in the unsorted list. + * @brief Returns the node data if it is in the unsorted list. * - * @param list The list to search for data, may be unsorted. - * @param func A function pointer that can handle comparing the list data nodes. - * @param data reference value to search. - * @return the node value (@c node->data) if func(node->data, data) == 0, - * @c NULL if not found. + * @since_tizen 2.3 * - * This can be used to check if some value is inside the list and get - * the existing instance in this case. + * @remarks This can be used to check if some value is inside the list and get + * the existing instance in this case. * - * Example: imagine user gives a string, you check if it's in the list - * before duplicating its contents. + * Example: Imagine a user gives a string, you check if it's in the list + * before duplicating its contents. * - * @note this is expensive and may walk the whole list, it's order-N, - * that is for 1,000,000 elements list it may walk and compare - * 1,000,000 nodes. + * @remarks This is expensive and may walk the whole list, it's order-N, + * that is for 1,000,000 elements list it may walk and compare + * 1,000,000 nodes. * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list to search for data, may be unsorted + * @param[in] func A function pointer that can handle comparing the list data nodes + * @param[in] data The reference value to search. + * @return The node value (@c node->data) if func(node->data, data) == 0, + * otherwise @c NULL if not found * * @see eina_list_search_sorted() * @see eina_list_search_unsorted_list() @@ -1178,191 +1043,211 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data); /** - * @brief Get the last list node in the list. + * @brief Gets the last list node in the list. + * + * @details This function returns the last list node in the list @a list. If + * @a list is @c NULL or empty, @c NULL is returned. + * + * @since_tizen 2.3 * - * @param list The list to get the last list node from. - * @return The last list node in the list. + * @remarks This is an order-1 operation (it takes the same short time + * regardless of the length of the list). * - * This function returns the last list node in the list @p list. If - * @p list is @c NULL or empty, @c NULL is returned. + * @remarks @a list must be a pointer to the first element of the list. * - * This is a order-1 operation (it takes the same short time - * regardless of the length of the list). + * @param[in] list The list to get the last list node from + * @return The last list node in the list * - * @warning @p list must be a pointer to the first element of the list. */ static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Get the next list node after the specified list node. + * @brief Gets the next list node after the specified list node. * - * @param list The list node to get the next list node from - * @return The next list node on success, @c NULL otherwise. + * @details This function returns the next list node after the current one in + * @a list. It is equivalent to list->next. If @a list is @c NULL or + * if no next list node exists, it returns @c NULL. * - * This function returns the next list node after the current one in - * @p list. It is equivalent to list->next. If @p list is @c NULL or - * if no next list node exists, it returns @c NULL. + * @since_tizen 2.3 + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list node to get the next list node from + * @return The next list node on success, otherwise @c NULL * - * @warning @p list must be a pointer to the first element of the list. */ static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Get the previous list node before the specified list node. + * @brief Gets the previous list node before the specified list node. + * + * @details This function returns the previous list node before the current one + * in @a list. It is equivalent to list->prev. If @a list is @c NULL or + * if no previous list node exists, it returns @c NULL. * - * @param list The list node to get the previous list node from. - * @return The previous list node o success, @c NULL otherwise. - * if no previous list node exists + * @since_tizen 2.3 * - * This function returns the previous list node before the current one - * in @p list. It is equivalent to list->prev. If @p list is @c NULL or - * if no previous list node exists, it returns @c NULL. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list node to get the previous list node from + * @return The previous list node on success, otherwise @c NULL + * if no previous list node exists * - * @warning @p list must be a pointer to the first element of the list. */ static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Get the list node data member. + * @brief Gets the list node data member. + * + * @details This function returns the data member of the specified list node + * @a list. It is equivalent to list->data. If @p list is @c NULL, this + * function returns @c NULL. + * + * @since_tizen 2.3 * - * @param list The list node to get the data member of. - * @return The data member from the list node. + * @remarks @a list must be a pointer to the first element of the list. * - * This function returns the data member of the specified list node @p - * list. It is equivalent to list->data. If @p list is @c NULL, this - * function returns @c NULL. + * @param[in] list The list node to get the data member of + * @return The data member from the list node * - * @warning @p list must be a pointer to the first element of the list. */ static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Set the list node data member. + * @brief Sets the list node data member. * - * @param list The list node to get the data member of. - * @param data The data member to the list node. - * @return The previous data value. + * @details This function sets the data member @a data of the specified list node + * @a list. It returns the previous data of the node. If @a list is + * @c NULL, this function returns @c NULL. * - * This function set the data member @p data of the specified list node - * @p list. It returns the previous data of the node. If @p list is - * @c NULL, this function returns @c NULL. + * @since_tizen 2.3 + * + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list node to get the data member of + * @param[in] data The data member for the list node + * @return The previous data value * - * @warning @p list must be a pointer to the first element of the list. */ static inline void *eina_list_data_set(Eina_List *list, const void *data); /** - * @brief Get the count of the number of items in a list. + * @brief Gets the count of the number of items in a list. + * + * @details This function returns the number of members that @a list contains. If the + * @a list is @c NULL, @c 0 is returned. * - * @param list The list whose count to return. - * @return The number of members in the list. + * @since_tizen 2.3 * - * This function returns how many members @p list contains. If the - * list is @c NULL, @c 0 is returned. + * @remarks This is an order-1 operation and takes the same time regardless + * of the length of the list. * - * NB: This is an order-1 operation and takes the same time regardless - * of the length of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list whose count to return + * @return The number of members in the list * - * @warning @p list must be a pointer to the first element of the list. */ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; + /** - * @brief Returns the last list node's data + * @brief Returns a new iterator associated to a list. * - * @param list The list - * @return The node's data, or @c NULL on being passed a @c NULL pointer + * @details This function returns a newly allocated iterator associated to @a + * list. If @a list is @c NULL or the count member of @a list is less than + * or equal to @c 0, this function still returns a valid iterator that + * always returns @c false on eina_iterator_next(), thus keeping the API + * sane. * - * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) - * @since 1.8 - */ -static inline void *eina_list_last_data_get(const Eina_List *list); - -/** - * @brief Returned a new iterator associated to a list. + * @since_tizen 2.3 * - * @param list The list. - * @return A new iterator. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator + * is returned. * - * This function returns a newly allocated iterator associated to @p - * list. If @p list is @c NULL or the count member of @p list is less - * or equal than 0, this function still returns a valid iterator that - * will always return false on eina_iterator_next(), thus keeping API - * sane. + * @remarks @a list must be a pointer to the first element of the list. * - * If the memory can not be allocated, NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the list structure changes then the iterator becomes + * invalid. That is, if you add or remove nodes this iterator's + * behavior is undefined and your program may crash. * - * @warning @p list must be a pointer to the first element of the list. + * @param[in] list The list + * @return A new iterator * - * @warning if the list structure changes then the iterator becomes - * invalid! That is, if you add or remove nodes this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new reversed iterator associated to a list. + * @brief Returns a new reversed iterator associated to a list. + * + * @details This function returns a newly allocated iterator associated to + * @a list. If @a list is @c NULL or the count member of @a list is less than + * or equal to 0, this function still returns a valid iterator that + * always returns @c false on eina_iterator_next(), thus keeping the API + * sane. * - * @param list The list. - * @return A new iterator. + * @since_tizen 2.3 * - * This function returns a newly allocated iterator associated to @p - * list. If @p list is @c NULL or the count member of @p list is less - * or equal than 0, this function still returns a valid iterator that - * will always return false on eina_iterator_next(), thus keeping API - * sane. + * @remarks Unlike eina_list_iterator_new(), this walks the list backwards. * - * Unlike eina_list_iterator_new(), this will walk the list backwards. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator + * is returned. * - * If the memory can not be allocated, NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning @p list must be a pointer to the first element of the list. + * @remarks If the list structure changes then the iterator becomes + * invalid. That is, if you add or remove nodes this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] list The list + * @return A new iterator * - * @warning if the list structure changes then the iterator becomes - * invalid! That is, if you add or remove nodes this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new accessor associated to a list. + * @brief Returns a new accessor associated to a list. + * + * @details This function returns a newly allocated accessor associated to + * @a list. If @a list is @c NULL or the count member of @a list is + * less than or equal to 0, this function returns @c NULL. + * + * @since_tizen 2.3 * - * @param list The list. - * @return A new accessor. + * @remarks If the memory cannot be allocated, + * @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, a valid accessor is returned. * - * This function returns a newly allocated accessor associated to - * @p list. If @p list is @c NULL or the count member of @p list is - * less or equal than 0, this function returns @c NULL. If the memory can - * not be allocated, @c NULL is returned Otherwise, a valid accessor is - * returned. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param[in] list The list + * @return A new accessor * - * @warning @p list must be a pointer to the first element of the list. */ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** * @def EINA_LIST_FOREACH - * @brief Macro to iterate over a list. + * @brief Definition of the macro to iterate over a list. + * + * @details This macro iterates over @a list from the first element to + * the last. @a data is the data related to the current element. + * @a l is an #Eina_List used as the list iterator. * - * @param list The list to iterate over. - * @param l A list that is used as an iterator and points to the current node. - * @param data Current item's data. + * @since_tizen 2.3 * - * This macro iterates over @p list from the first element to - * the last. @p data is the data related to the current element. - * @p l is an #Eina_List used as the list iterator. + * @remarks The following diagram ilustrates this macro iterating over a list of four + * elements("one", "two", "three" and "four"): * - * The following diagram illustrates this macro iterating over a list of four - * elements("one", "two", "three" and "four"): + * @image html eina-list-foreach.png * @htmlonly - * <img src="eina-list-foreach.png" style="max-width: 100%;" /> * <a href="eina-list-foreach.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-foreach.eps "" width=\textwidth + * @image latex eina-list-foreach.eps "eina list foreach" width=\textwidth * * It can be used to free list data, as in the following example: * @@ -1380,19 +1265,24 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * eina_list_free(list); * @endcode * - * @note This is not the optimal way to release memory allocated to - * a list, since it iterates over the list twice. - * For an optimized algorithm, use EINA_LIST_FREE(). + * @remarks This is not the optimal way to release memory allocated to + * a list, since it iterates over the list twice. + * For an optimized algorithm, use EINA_LIST_FREE(). * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning Be careful when deleting list nodes. + * @remarks Be careful when deleting list nodes. * If you remove the current node and continue iterating, - * the code will fail because the macro will not be able + * the code fails because the macro is not able * to get the next node. Notice that it's OK to remove any * node if you stop the loop after that. * For destructive operations such as this, consider * using EINA_LIST_FOREACH_SAFE(). + * + * @param list The list to iterate over + * @param l A list that is used as an iterator and points to the current node + * @param data The current item's data + * */ #define EINA_LIST_FOREACH(list, l, data) \ for (l = list, \ @@ -1403,24 +1293,23 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA /** * @def EINA_LIST_REVERSE_FOREACH - * @brief Macro to iterate over a list in the reverse order. + * @brief Definition of the macro to iterate over a list in the reverse order. + * + * @details This macro works like EINA_LIST_FOREACH, but iterates from the + * last element of a list to the first. + * @a data is the data related to the current element, while @a l + * is an #Eina_List that is used as the list iterator. * - * @param list The list to iterate over. - * @param l A list that is used as an iterator and points to the current node. - * @param data Current item's data. + * @since_tizen 2.3 * - * This macro works like EINA_LIST_FOREACH, but iterates from the - * last element of a list to the first. - * @p data is the data related to the current element, while @p l - * is an #Eina_List that is used as the list iterator. + * @remarks The following diagram ilustrates this macro iterating over a list of four + * elements("one", "two", "three" and "four"): * - * The following diagram illustrates this macro iterating over a list of four - * elements("one", "two", "three" and "four"): + * @image html eina-list-reverse-foreach.png * @htmlonly - * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" /> * <a href="eina-list-reverse-foreach.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-reverse-foreach.eps "" width=\textwidth + * @image latex eina-list-reverse-foreach.eps "eina list reverse foreach" width=\textwidth * * It can be used to free list data, as in the following example: * @@ -1438,19 +1327,24 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * eina_list_free(list); * @endcode * - * @note This is not the optimal way to release memory allocated to - * a list, since it iterates over the list twice. - * For an optimized algorithm, use EINA_LIST_FREE(). + * @remarks This is not the optimal way to release memory allocated to + * a list, since it iterates over the list twice. + * For an optimized algorithm, use EINA_LIST_FREE(). * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. * - * @warning Be careful when deleting list nodes. + * @remarks Be careful when deleting list nodes. * If you remove the current node and continue iterating, - * the code will fail because the macro will not be able + * the code fails because the macro is not able * to get the next node. Notice that it's OK to remove any * node if you stop the loop after that. * For destructive operations such as this, consider * using EINA_LIST_REVERSE_FOREACH_SAFE(). + * + * @param list The list to iterate over + * @param l A list that is used as an iterator and points to the current node + * @param data The current item's data + * */ #define EINA_LIST_REVERSE_FOREACH(list, l, data) \ for (l = eina_list_last(list), \ @@ -1461,27 +1355,25 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA /** * @def EINA_LIST_FOREACH_SAFE - * @brief Macro to iterate over a list with support for node deletion. + * @brief Definition of the macro to iterate over a list with support for node deletion. + * + * @details This macro iterates over @a list from the first element to + * the last. @a data is the data related to the current element. + * @a l is an #Eina_List used as the list iterator. * - * @param list The list to iterate over. - * @param l A list that is used as an iterator and points to the current node. - * @param l_next A list that is used as an iterator and points to the next node. - * @param data Current item's data. + * @since_tizen 2.3 * - * This macro iterates over @p list from the first element to - * the last. @p data is the data related to the current element. - * @p l is an #Eina_List used as the list iterator. + * @remarks Since this macro stores a pointer to the next list node in @a l_next, + * deleting the current node and continuing looping is safe. * - * Since this macro stores a pointer to the next list node in @p l_next, - * deleting the current node and continuing looping is safe. + * @remarks The following diagram ilustrates this macro iterating over a list of four + * elements("one", "two", "three" and "four"): * - * The following diagram illustrates this macro iterating over a list of four - * elements("one", "two", "three" and "four"): + * @image html eina-list-foreach-safe.png * @htmlonly - * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" /> * <a href="eina-list-foreach-safe.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-foreach-safe.eps "" width=\textwidth + * @image latex eina-list-foreach-safe.eps "eina list foreach safe" width=\textwidth * * This macro can be used to free list nodes, as in the following example: * @@ -1496,14 +1388,19 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key". * * EINA_LIST_FOREACH_SAFE(list, l, l_next, data) - * if (strcmp(data, "key") == 0) - * { - * free(data); - * list = eina_list_remove_list(list, l); - * } + * if (strcmp(data, "key") == 0) { + * free(data); + * list = eina_list_remove_list(list, l); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param list The list to iterate over + * @param l A list that is used as an iterator and points to the current node + * @param l_next A list that is used as an iterator and points to the next node + * @param data The current item's data + * */ #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \ for (l = list, \ @@ -1516,29 +1413,27 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA /** * @def EINA_LIST_REVERSE_FOREACH_SAFE - * @brief Macro to iterate over a list in the reverse order with support + * @brief Definition of the macro to iterate over a list in the reverse order with support * for deletion. * - * @param list The list to iterate over. - * @param l A list that is used as an iterator and points to the current node. - * @param l_prev A list that is used as an iterator and points to the previous node. - * @param data Current item's data. + * @details This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the + * last element of a list to the first. + * @a data is the data related to the current element, while @a l + * is an #Eina_List that is used as the list iterator. * - * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the - * last element of a list to the first. - * @p data is the data related to the current element, while @p l - * is an #Eina_List that is used as the list iterator. + * @since_tizen 2.3 * - * Since this macro stores a pointer to the previous list node in @p l_prev, - * deleting the current node and continuing looping is safe. + * @remarks Since this macro stores a pointer to the previous list node in @a l_prev, + * deleting the current node and continuing looping is safe. * - * The following diagram illustrates this macro iterating over a list of four - * elements("one", "two", "three" and "four"): + * @remarks The following diagram ilustrates this macro iterating over a list of four + * elements("one", "two", "three" and "four"): + * + * @image html eina-list-reverse-foreach-safe.png * @htmlonly - * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" /> * <a href="eina-list-reverse-foreach-safe.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-reverse-foreach-safe.eps "" width=\textwidth + * @image latex eina-list-reverse-foreach-safe.eps "eina list reverse foreach safe" width=\textwidth * * This macro can be used to free list nodes, as in the following example: * @@ -1553,14 +1448,19 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key". * * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) - * if (strcmp(data, "key") == 0) - * { - * free(data); - * list = eina_list_remove_list(list, l); - * } + * if (strcmp(data, "key") == 0) { + * free(data); + * list = eina_list_remove_list(list, l); + * } * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param list The list to iterate over + * @param l A list that is used as an iterator and points to the current node + * @param l_prev A list that is used as an iterator and points to the previous node + * @param data The current item's data + * */ #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \ for (l = eina_list_last(list), \ @@ -1573,21 +1473,21 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA /** * @def EINA_LIST_FREE - * @brief Macro to remove each list node while having access to each node's data. + * @brief Definition of the macro to remove each list node while having access to each node's data. + * + * @details This macro calls #eina_list_remove_list for each list node and stores + * the data contained in the current node in @a data. * - * @param list The list that will be cleared. - * @param data Current node's data. + * @since_tizen 2.3 * - * This macro will call #eina_list_remove_list for each list node, and store - * the data contained in the current node in @p data. + * @remarks The following diagram ilustrates this macro iterating over a list of four + * elements("one", "two", "three" and "four"): * - * The following diagram illustrates this macro iterating over a list of four - * elements("one", "two", "three" and "four"): + * @image html eina-list-free.png * @htmlonly - * <img src="eina-list-free.png" style="max-width: 100%;" /> * <a href="eina-list-free.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-free.eps "" width=\textwidth + * @image latex eina-list-free.eps "eina list free" width=\textwidth * * If you do not need to release node data, it is easier to call #eina_list_free(). * @@ -1602,7 +1502,10 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * free(data); * @endcode * - * @warning @p list must be a pointer to the first element of the list. + * @remarks @a list must be a pointer to the first element of the list. + * + * @param list The list that is cleared + * @param data The current node's data * * @see eina_list_free() */ @@ -1618,12 +1521,4 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif /* EINA_LIST_H_ */ diff --git a/src/lib/eina/eina_log.h b/src/lib/eina/eina_log.h index 84e7f23655..ee609a0efd 100644 --- a/src/lib/eina/eina_log.h +++ b/src/lib/eina/eina_log.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -39,189 +39,51 @@ #define EINA_COLOR_RESET "\033[0m" #define EINA_COLOR_HIGH "\033[1m" - -/** - * @page tutorial_log_page Log Tutorial - * - * @section tutorial_log_introduction Introduction - * - * The Eina Log module provides logging facilities for libraries and - * applications. It provides colored logging, basic logging levels (error, - * warning, debug, info, critical) and loggers - called logging domains - - * which will be covered on next sections. - * - * @section tutorial_log_basic_usage Basic Usage - * - * Log messages can be displayed using the following macros: - * - * @li EINA_LOG_ERR(), - * @li EINA_LOG_INFO(), - * @li EINA_LOG_WARN(), - * @li EINA_LOG_DBG(). - * - * Here is an example: - * - * @include eina_log_02.c - * - * If you compiled Eina without debug mode, execution will yield only one log - * message, which is "argument is negative". - * - * Here we introduce the concept of logging domains (or loggers), which might - * already be familiar to readers. It is basically a way to separate a set of - * log messages into a context (e.g. a module) and provide a way of controlling - * this set as a whole. - * - * For example, suppose you have 3 different modules on your application and you - * want to get logging only from one of them (e.g. create some sort of filter). - * For achieving that, all you need to do is create a logging domain for each - * module so that all logging inside a module can be considered as a whole. - * - * Logging domains are specified by a name, color applied to the name and the - * level. The first two (name and color) are set through code, that is, inside - * your application/module/library. - * - * The level is used for controlling which messages should appear. It - * specifies the lowest level that should be displayed (e.g. a message - * with level 11 being logged on a domain with level set to 10 would be - * displayed, while a message with level 9 wouldn't). - * - * The domain level is set during runtime (in contrast with the name and - * color) through the environment variable EINA_LOG_LEVELS. This variable - * expects a list in the form domain_name1:level1,domain_name2:level2,... . For - * example: - * - * @verbatim EINA_LOG_LEVELS=mymodule1:5,mymodule2:2,mymodule3:0 ./myapp@endverbatim - * - * This line would set mymodule1 level to 5, mymodule2 level to 2 and mymodule3 - * level to 0. - * - * There's also a global logger to which EINA_LOG_(ERR, DBG, INFO, CRIT, WARN) - * macros do log on. It is a logger that is created internally by Eina Log with - * an empty name and can be used for general logging (where logging domains do - * not apply). - * - * Since this global logger doesn't have a name, you can't set its level through - * EINA_LOG_LEVELS variable. Here we introduce a second environment variable - * that is a bit more special: EINA_LOG_LEVEL. - * - * This variable specifies the level of the global logging domain and the level - * of domains that haven't been set through EINA_LOG_LEVELS. Here's an example: - * - * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS=module1:10,module3:2 ./myapp@endverbatim - * - * Supposing you have modules named "module1", "module2" and "module3", this - * line would result in module1 with level 10, module2 with level 3 and module3 - * with level 2. Note that module2's level wasn't specified, so it's level is - * set to the global level. This way we can easily apply filters to multiple - * domains with only one parameter (EINA_LOG_LEVEL=num). - * - * The global level (EINA_LOG_LEVEL) can also be set through code, using - * eina_log_level_set() function. - * - * While developing your libraries or applications, you may notice that - * EINA_LOG_DOM_(ERR, DBG, INFO, CRIT, WARN) macros also print out - * messages from eina itself. Here we introduce another environment variable - * that is a bit more special: EINA_LOG_LEVELS_GLOB. - * - * This variable allows you to disable the logging of any/all code in eina itself. - * This is useful when developing your libraries or applications so that you can - * see your own domain's messages easier without having to sift through a lot of - * internal eina debug messages. Here's an example: - * - * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS_GLOB=eina_*:0 ./myapp@endverbatim - * - * This will disable eina_log output from all internal eina code thus allowing - * you to see your own domain messages easier. - * - * @section tutorial_log_advanced_display Advanced usage of print callbacks - * - * The log module allows the user to change the way - * eina_log_print() displays the messages. It suffices to pass to - * eina_log_print_cb_set() the function used to display the - * message. That function must be of type #Eina_Log_Print_Cb. As a - * custom data can be passed to that callback, powerful display - * messages can be displayed. - * - * It is suggested to not use __FILE__, __FUNCTION__ or __LINE__ when - * writing that callback, but when defining macros (like - * EINA_LOG_ERR() and other macros). - * - * Here is an example of custom callback, whose behavior can be - * changed at runtime: - * - * @include eina_log_03.c - * @example eina_log_02.c - * @example eina_log_03.c - */ - /** - * @addtogroup Eina_Log_Group Log - * * @brief Full-featured logging system. * * Eina provides eina_log_print(), a standard function to manage all - * logging messages. This function may be called directly or using the - * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR() or those that - * take a specific domain as argument EINA_LOG_DOM_DBG(), - * EINA_LOG_DOM_ERR(). Internally, eina_log_print() will call the + * logging messages. This function may be called directly or by using the + * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR(), or those that + * take a specific domain as an argument such as EINA_LOG_DOM_DBG(), + * EINA_LOG_DOM_ERR(). Internally, eina_log_print() calls the * function defined with eina_log_print_cb_set(), that defaults to * eina_log_print_cb_stderr(), but may be changed to do whatever you * need, such as networking or syslog logging. * * The logging system is thread safe once initialized with * eina_log_threads_enable(). The thread that calls this function - * first is considered "main thread" and other threads will have their - * thread id (pthread_self()) printed in the log message so it is easy + * first is considered "main thread" and other threads have their + * thread ID (pthread_self()) printed in the log message so it is easy * to detect from where it is coming. * - * Log domains is the Eina way to differentiate messages. There might + * Log domains is the Eina way to differentiate between messages. There might * be different domains to represent different modules, different - * feature-set, different categories and so on. Filtering can be + * feature-sets, different categories, and so on. Filtering can be * applied to domain names by means of @c EINA_LOG_LEVELS environment * variable or eina_log_domain_level_set(). * * The different logging levels serve to customize the amount of - * debugging one want to take and may be used to automatically call + * debugging one might want to take and may be used to automatically call * abort() once some given level message is printed. This is - * controlled by environment variable @c EINA_LOG_ABORT and the level - * to be considered critical with @c EINA_LOG_ABORT_LEVEL. These can - * be changed with eina_log_abort_on_critical_set() and + * controlled by an environment variable @c EINA_LOG_ABORT and the level + * to be considered critical, which is @c EINA_LOG_ABORT_LEVEL. These can + * be changed by eina_log_abort_on_critical_set() and * eina_log_abort_on_critical_level_set(). * * The default maximum level to print is defined by environment * variable @c EINA_LOG_LEVEL, but may be set per-domain with @c - * EINA_LOG_LEVELS. It will default to #EINA_LOG_ERR. This can be - * changed with eina_log_level_set(). + * EINA_LOG_LEVELS. It defaults to #EINA_LOG_ERR. This can be + * changed by eina_log_level_set(). * * To use the log system Eina must be initialized with eina_init() and - * later shut down with eina_shutdown(). Here is a straightforward - * example: - * - * @include eina_log_01.c - * - * Compile this code with the following command: - * - * @verbatim gcc -Wall -o eina_log_01 eina_log_01.c `pkg-config --cflags --libs eina`@endverbatim - * - * Now execute the program with: - * - * @verbatim EINA_LOG_LEVEL=2 ./eina_log_01@endverbatim - * - * You should see a message displayed in the terminal. - * - * For more information, you can look at the @ref tutorial_log_page. - * - * @example eina_log_01.c - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ + * later shut down with eina_shutdown(). */ /** + * @internal * @defgroup Eina_Log_Group Log + * @ingroup Eina_Tools_Group * * @{ */ @@ -236,15 +98,15 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; /** * @def EINA_LOG_DOMAIN_DEFAULT - * This macro defines the domain to use with the macros EINA_LOG_DOM_DBG(), - * EINA_LOG_DOM_INFO(), EINA_LOG_DOM_WARN(), EINA_LOG_DOM_ERR() and - * EINA_LOG_DOM_CRIT(). + * @brief Definition of the macro that defines the domain to use with the macros EINA_LOG_DOM_DBG(), + * EINA_LOG_DOM_INFO(), EINA_LOG_DOM_WARN(), EINA_LOG_DOM_ERR(), and + * EINA_LOG_DOM_CRIT(). * - * If not defined prior to the inclusion of this header, then it - * defaults to #EINA_LOG_DOMAIN_GLOBAL. + * @remarks If not defined prior to the inclusion of this header, then it + * defaults to #EINA_LOG_DOMAIN_GLOBAL. * - * @note One may like to redefine this in its code to avoid typing too - * much. In this case the recommended way is: + * @remarks One may like to redefine this in its code to avoid typing too + * much. In this case, the recommended way is: * * @code * #include <Eina.h> @@ -261,10 +123,10 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; * } * @endcode * - * @warning If one defines the domain prior to inclusion of this + * @remarks If one defines the domain prior to inclusion of this * header, the defined log domain symbol must be defined * prior as well, otherwise the inlined functions defined by - * Eina will fail to find the symbol, causing build failure. + * Eina fail to find the symbol, causing a build failure. * * @code * #define EINA_LOG_DOMAIN_DEFAULT _log_dom @@ -287,17 +149,17 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; /** * @def EINA_LOG(DOM, LEVEL, fmt, ...) - * Logs a message on the specified domain, level and format. - * - * @note if @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger - * than this value will be ignored regardless of current domain - * level, the eina_log_print() is not even called! Most - * compilers will just detect the two integers make the branch - * impossible and remove the branch and function call all - * together. Take this as optimization tip and possible remove - * debug messages from binaries to be deployed, saving on hot - * paths. Never define @c EINA_LOG_LEVEL_MAXIMUM on public - * header files. + * @brief Definition that logs a message on the specified domain, level, and format. + * + * @remarks If @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger + * than this value are ignored regardless of the current domain + * level, eina_log_print() is not even called. Most + * compilers just detect the two integers that make the branch + * impossible and remove the branch and function call all + * together. Take this as an optimization tip and possibly remove + * debug messages from binaries to be deployed, saving on hot + * paths. Never define @c EINA_LOG_LEVEL_MAXIMUM on public + * header files. */ #ifdef EINA_ENABLE_LOG # ifdef EINA_LOG_LEVEL_MAXIMUM @@ -324,43 +186,43 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; /** * @def EINA_LOG_DOM_CRIT(DOM, fmt, ...) - * Logs a message with level CRITICAL on the specified domain and format. + * @brief Definition that logs a message with level as CRITICAL on the specified domain and format. */ #define EINA_LOG_DOM_CRIT(DOM, fmt, ...) \ EINA_LOG(DOM, EINA_LOG_LEVEL_CRITICAL, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_DOM_ERR(DOM, fmt, ...) - * Logs a message with level ERROR on the specified domain and format. + * @brief Definition that logs a message with level as ERROR on the specified domain and format. */ #define EINA_LOG_DOM_ERR(DOM, fmt, ...) \ EINA_LOG(DOM, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_DOM_INFO(DOM, fmt, ...) - * Logs a message with level INFO on the specified domain and format. + * @brief Definition that logs a message with level as INFO on the specified domain and format. */ #define EINA_LOG_DOM_INFO(DOM, fmt, ...) \ EINA_LOG(DOM, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_DOM_DBG(DOM, fmt, ...) - * Logs a message with level DEBUG on the specified domain and format. + * @brief Definition that logs a message with level as DEBUG on the specified domain and format. */ #define EINA_LOG_DOM_DBG(DOM, fmt, ...) \ EINA_LOG(DOM, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_DOM_WARN(DOM, fmt, ...) - * Logs a message with level WARN on the specified domain and format. + * @brief Definition that logs a message with level as WARN on the specified domain and format. */ #define EINA_LOG_DOM_WARN(DOM, fmt, ...) \ EINA_LOG(DOM, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_CRIT(fmt, ...) - * Logs a message with level CRITICAL on the default domain with the specified - * format. + * @brief Definition that logs a message with level as CRITICAL on the default domain with the specified + * format. */ #define EINA_LOG_CRIT(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, \ @@ -370,87 +232,79 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL; /** * @def EINA_LOG_ERR(fmt, ...) - * Logs a message with level ERROR on the default domain with the specified - * format. + * @brief Definition that logs a message with level as ERROR on the default domain with the specified + * format. */ #define EINA_LOG_ERR(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_INFO(fmt, ...) - * Logs a message with level INFO on the default domain with the specified - * format. + * @brief Definition that logs a message with level as INFO on the default domain with the specified + * format. */ #define EINA_LOG_INFO(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_WARN(fmt, ...) - * Logs a message with level WARN on the default domain with the specified - * format. + * @brief Definition that logs a message with level as WARN on the default domain with the specified + * format. */ #define EINA_LOG_WARN(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__) /** * @def EINA_LOG_DBG(fmt, ...) - * Logs a message with level DEBUG on the default domain with the specified - * format. + * @brief Definition that logs a message with level as DEBUG on the default domain with the specified + * format. */ #define EINA_LOG_DBG(fmt, ...) \ EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__) /** * @typedef Eina_Log_Domain - * The domain used for logging. + * @brief The structure type containing the domain used for logging. */ typedef struct _Eina_Log_Domain Eina_Log_Domain; /** * @struct _Eina_Log_Domain - * The domain used for logging. + * @brief The structure type containing the domain used for logging. */ struct _Eina_Log_Domain { - int level; /**< Max level to log */ + int level; /**< Maximum level to log */ const char *domain_str; /**< Formatted string with color to print */ const char *name; /**< Domain name */ size_t namelen; /**< strlen(name) */ /* Private */ Eina_Bool deleted : 1; /**< Flags deletion of domain, a free slot */ - - /* Add new members here. */ - const char *color; /**< Color to use when printing in this domain */ }; /** - * Enable logging module to handle threads. + * @brief Enables logging module to handle threads. * - * There is no disable option on purpose, if it is enabled, there is - * no way back until you call the last eina_shutdown(). + * @remarks There is no disable option on purpose, if it is enabled, there is + * no way back until you call the last eina_shutdown(). * - * There is no function to retrieve if threads are enabled as one is - * not supposed to know this from outside. + * @remarks There is no function to retrieve if threads are enabled as one is + * not supposed to know this from outside. * - * After this call is executed at least once, if Eina was compiled - * with threads support then logging will lock around debug messages - * and threads that are not the main thread will have its identifier - * printed. + * @remarks After this call is executed at least once, if Eina is compiled + * with threads support then logging locks around debug messages + * and threads that are not the main thread is going to have its identifier + * printed. * - * The main thread is considered the thread where the first - * eina_init() was called. + * The main thread is considered the thread where the first + * eina_init() was called. */ EAPI void eina_log_threads_enable(void); - -/** - * @typedef Eina_Log_Level - * List of available logging levels. - */ /** * @enum _Eina_Log_Level - * List of available logging levels. + * @brief Enumeration for the list of available logging levels. */ typedef enum _Eina_Log_Level { @@ -465,165 +319,162 @@ typedef enum _Eina_Log_Level /** * @typedef Eina_Log_Print_Cb - * Type for print callbacks. + * Called to print callbacks. */ typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d, Eina_Log_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args); -/** - * @typedef Eina_Log_State - * List of available log states. - */ -/** - * @enum _Eina_Log_State - * List of available log states. - */ -typedef enum _Eina_Log_State -{ - EINA_LOG_STATE_START, - EINA_LOG_STATE_STOP -} Eina_Log_State; - /* * Customization */ /** - * Sets logging method to use. + * @brief Sets the logging function to use. * - * @param cb The callback to call when printing a log. - * @param data The data to pass to the callback. + * @since_tizen 2.3 * - * By default, eina_log_print_cb_stderr() is used. + * @remarks By default, eina_log_print_cb_stderr() is used. + * @remarks It is safe to call from any thread. + * @remarks The given function @a cb is called protected by mutex. + * This means you're safe from other calls but you should never + * call eina_log_print(), directly or indirectly. * - * @note MT: safe to call from any thread. + * @param[in] cb The callback to call when printing a log + * @param[in] data The data to pass to the callback * - * @note MT: given function @a cb will be called protected by mutex. - * This means you're safe from other calls but you should never - * call eina_log_print(), directly or indirectly. */ EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNULL(1); /** - * @brief Set the default log level. + * @brief Sets the default log level. * - * @param level The log level. + * @details This function sets the log level @a level. It is used in + * eina_log_print(). * - * This function sets the log level @p level. It is used in - * eina_log_print(). + * @since_tizen 2.3 * - * @note this is initially set to envvar EINA_LOG_LEVEL by eina_init(). + * @remarks This is initially set to envvar EINA_LOG_LEVEL by eina_init(). + * + * @param[in] level The log level * * @see eina_log_level_get() */ EAPI void eina_log_level_set(int level); /** - * @brief Get the default log level. + * @brief Gets the default log level. + * + * @since_tizen 2.3 * - * @return the log level that limits eina_log_print(). + * @return The log level that limits eina_log_print() * * @see eina_log_level_set() */ EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT; -/** - * @brief Determine if a given @p level should be logged. - * - * @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE. - * - * @see eina_log_level_set() - */ static inline Eina_Bool eina_log_level_check(int level); /** - * @brief Checks if current thread is the main thread. + * @brief Checks whether the current thread is the main thread. + * + * @since_tizen 2.3 * - * If there is no thread support (compiled with --disable-pthreads) or - * threads were not enabled, then #EINA_TRUE is returned. The only case where - * #EINA_FALSE is returned is when threads were successfully enabled but the - * current thread is not the one that called eina_log_threads_init() (the - * manin thread). - * - * @return #EINA_TRUE if the current thread is the one that called - * eina_log_threads_init(), otherwise #EINA_FALSE. + * @return @c EINA_TRUE if threads are enabled and the current thread + * is the one that called eina_log_threads_init() \n + * If there is no thread support (compiled with --disable-pthreads) or + * they are not enabled, then @c EINA_TRUE is also + * returned \n + * The only case where @c EINA_FALSE is returned is + * when threads are successfully enabled but the current + * thread is not the main (one that called + * eina_log_threads_init()). */ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT; /** - * @brief Enable or disable colored text in the logs. + * @brief Sets whether color logging should be disabled. * - * @param disabled If #EINA_TRUE, color logging should be disabled. + * @since_tizen 2.3 * - * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init(). + * @remarks This is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init(). + * + * @param[in] disabled If @c EINA_TRUE color logging should be disabled * * @see eina_log_color_disable_get() */ EAPI void eina_log_color_disable_set(Eina_Bool disabled); /** - * @brief Determine if color logging is enabled or disabled. + * @brief Gets whether color logging should be disabled. + * + * @since_tizen 2.3 * - * @return If #EINA_TRUE, color logging is disabled. + * @return @c EINA_TRUE if color logging should be disabled * * @see eina_log_color_disable_set() */ EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT; /** - * @brief Set if originating file name logging should be disabled. + * @brief Sets whether originating file name logging should be disabled. * - * @param disabled if #EINA_TRUE, file name logging should be disabled. + * @since_tizen 2.3 * - * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init(). + * @remarks This is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init(). + * + * @param[in] disabled If @c EINA_TRUE file name logging should be disabled * * @see eina_log_file_disable_get() */ EAPI void eina_log_file_disable_set(Eina_Bool disabled); /** - * @brief Get if originating file name logging should be disabled. + * @brief Gets whether originating file name logging should be disabled. + * + * @since_tizen 2.3 * - * @return if #EINA_TRUE, file name logging should be disabled. + * @return @c EINA_TRUE if file name logging should be disabled * * @see eina_log_file_disable_set() */ EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT; /** - * @brief Set if originating function name logging should be disabled. + * @brief Sets whether originating function name logging should be disabled. * - * @param disabled if #EINA_TRUE, function name logging should be disabled. + * @since_tizen 2.3 * - * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by - * eina_init(). + * @remarks This is initially set to envvar EINA_LOG_FUNCTION_DISABLE by + * eina_init(). + * + * @param[in] disabled If @c EINA_TRUE function name logging should be disabled * * @see eina_log_function_disable_get() */ EAPI void eina_log_function_disable_set(Eina_Bool disabled); /** - * @brief Get if originating function name logging should be disabled. + * @brief Gets whether originating function name logging should be disabled. * - * @return if #EINA_TRUE, function name logging should be disabled. + * @return @c EINA_TRUE if function name logging should be disabled * * @see eina_log_function_disable_set() */ EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT; /** - * @brief Set if critical messages should abort the program. + * @brief Sets whether critical messages should abort the program. * - * @param abort_on_critical if #EINA_TRUE, messages with level equal - * or smaller than eina_log_abort_on_critical_level_get() will - * abort the program. + * @remarks This is initially set to envvar EINA_LOG_ABORT by + * eina_init(). * - * @note this is initially set to envvar EINA_LOG_ABORT by - * eina_init(). + * @param[in] abort_on_critical If @c EINA_TRUE, messages with level equal to + * or smaller than eina_log_abort_on_critical_level_get() + * abort the program. * * @see eina_log_abort_on_critical_get() * @see eina_log_abort_on_critical_level_set() @@ -631,11 +482,13 @@ EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RES EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critical); /** - * @brief Get if critical messages should abort the program. + * @brief Gets whether critical messages should abort the program. + * + * @since_tizen 2.3 * - * @return if #EINA_TRUE, any messages with level equal or smaller - * than eina_log_abort_on_critical_level_get() will abort the - * program. + * @return @c EINA_TRUE if messages with level equal to or smaller + * than eina_log_abort_on_critical_level_get() abort the + * program * * @see eina_log_abort_on_critical_set() * @see eina_log_abort_on_critical_level_set() @@ -643,14 +496,15 @@ EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critic EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RESULT; /** - * @brief Set level that triggers abort if abort-on-critical is set. + * @brief Sets the level that triggers abort if abort-on-critical is set. * - * @param critical_level levels equal or smaller than the given value - * will trigger program abortion if - * eina_log_abort_on_critical_get() returns #EINA_TRUE. + * @since_tizen 2.3 * - * @note this is initially set to envvar EINA_LOG_ABORT_LEVEL by - * eina_init(). + * @remarks This is initially set to envvar EINA_LOG_ABORT_LEVEL by + * eina_init(). + * + * @param[in] critical_level If @c EINA_TRUE, levels equal to or smaller than + * eina_log_abort_on_critical_get() triggers program abortion * * @see eina_log_abort_on_critical_level_get() * @see eina_log_abort_on_critical_get() @@ -658,11 +512,12 @@ EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RE EAPI void eina_log_abort_on_critical_level_set(int critical_level); /** - * @brief Get level that triggers abort if abort-on-critical is set. + * @brief Gets the level that triggers abort if abort-on-critical is set. + * + * @since_tizen 2.3 * - * @return critical level equal or smaller than value will trigger - * program abortion if eina_log_abort_on_critical_get() - * returns #EINA_TRUE. + * @return @c EINA_TRUE if the critical level equal to or smaller than + * eina_log_abort_on_critical_get() triggers program abortion * * @see eina_log_abort_on_critical_level_set() * @see eina_log_abort_on_critical_get() @@ -671,32 +526,39 @@ EAPI int eina_log_abort_on_critical_level_get(void) EINA_WARN_UNU /** - * Set the domain level given its name. + * @brief Sets the domain level given that its name is provided. * - * This call has the same effect as setting - * EINA_LOG_LEVELS=<@p domain_name>:<@p level> + * @since_tizen 2.3 * - * @param domain_name domain name to change the level. It may be of a - * still not registered domain. If the domain is not registered - * yet, it will be saved as a pending set and applied upon - * registration. - * @param level level to use to limit eina_log_print() for given domain. + * @remarks This call has the same effect as setting + * EINA_LOG_LEVELS=<@a domain_name>:<@a level> + * + * @param[in] domain_name The domain name to change the level \n + * It may be of a still not registered domain \n + * If the domain is not registered + * yet, it is saved as a pending set and applied upon + * registration. + * @param[in] level The level to use to limit eina_log_print() for the given domain */ EAPI void eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1); /** - * Get the domain level given its name. + * @brief Gets the domain level given that its name is provided. + * + * @since_tizen 2.3 * - * @param domain_name domain name to retrieve the level. It may be of - * a still not registered domain. If the domain is not - * registered yet, but there is a pending value, either from - * eina_log_domain_level_set(),EINA_LOG_LEVELS environment - * variable or from EINA_LOG_LEVELS_GLOB, these are - * returned. If nothing else was found, then the global/default - * level (eina_log_level_get()) is returned. + * @param[in] domain_name The domain name to retrieve the level \n + * It may be of a still not registered domain \n + * If the domain is not registered yet, but there is a pending value either from + * eina_log_domain_level_set(), EINA_LOG_LEVELS environment + * variable, or EINA_LOG_LEVELS_GLOB, these are + * returned \n + * If nothing else is found, then the global/default + * level (eina_log_level_get()) is returned. * - * @return level to use to limit eina_log_print() for given - * domain. On error (@p domain_name == NULL), + * @return The level to use to limit eina_log_print() for the given + * domain \n + * On error (@a domain_name == NULL), * EINA_LOG_LEVEL_UNKNOWN is returned. * * @see eina_log_domain_level_set() @@ -705,29 +567,19 @@ EAPI void eina_log_domain_level_set(const char *domain_name, int l EAPI int eina_log_domain_level_get(const char *domain_name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * Get the domain level given its identifier. + * @brief Gets the domain level given that its identifier is provided. * - * @param domain identifier, so it must be previously registered with - * eina_log_domain_register(). It's a much faster version of - * eina_log_domain_level_get(), but relies on domain being - * present. + * @since_tizen 2.3 * - * @return #EINA_TRUE if level should be printed, #EINA_FALSE if not. - * (domain's level is greater or equal @a level). - */ -EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT; - -/** - * Set the domain level given its identifier. + * @param[in] domain The domain identifier, so it must be previously registered with + * eina_log_domain_register() \n + * It's a much faster version of eina_log_domain_level_get(), + * but relies on the domain being present. * - * @param domain identifier, so it must be previously registered with - * eina_log_domain_register(). It's a much faster version of - * eina_log_domain_level_get(), but relies on domain being - * present. - * @param level level to use to limit eina_log_print() for given domain. - * @since 1.10 + * @return @c EINA_TRUE if the level should be printed, otherwise @c EINA_FALSE if not + * (domain's level is greater than or equal to @a level) */ -EAPI void eina_log_domain_registered_level_set(int domain, int level); +EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT; static inline Eina_Bool eina_log_domain_level_check(int domain, int level); @@ -736,23 +588,30 @@ static inline Eina_Bool eina_log_domain_level_check(int domain, int level); */ /** - * @param name Domain name - * @param color Color of the domain name + * @brief Logs domains + * + * @since_tizen 2.3 * - * @return Domain index that will be used as the DOMAIN parameter on log - * macros. A negative return value means an log occurred. + * @remarks It is safe to call from any thread. * - * @note MT: safe to call from any thread. + * @param[in] name The domain name + * @param[in] color The color of the domain name + * + * @return The domain index that is used as the DOMAIN parameter on log + * macros \n + * A negative return value means a log occurred. */ EAPI int eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1); /** - * Forget about a logging domain registered by eina_log_domain_register() + * @brief Forgets about a logging domain registered by eina_log_domain_register(). + * + * @since_tizen 2.3 * - * @param domain domain identifier as reported by eina_log_domain_register(), - * must be >= 0. + * @remarks It is safe to call from any thread. * - * @note MT: safe to call from any thread. + * @param[in] domain The domain identifier as reported by eina_log_domain_register(), + * must be >= 0 */ EAPI void eina_log_domain_unregister(int domain); @@ -761,27 +620,29 @@ EAPI void eina_log_domain_unregister(int domain); */ /** - * Print out log message using given domain and level. + * @brief Prints out log messages using the given domain and level. * - * @note Usually you'll not use this function directly but the helper - * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and - * so on. See eina_log.h + * @details This function may be called from different threads if + * eina_log_threads_enable() is called before. * - * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if - * you registered none. It is recommended that modules and - * applications have their own logging domain. - * @param level message level, those with level greater than user - * specified value (eina_log_level_set() or environment - * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. - * @param file filename that originated the call, must @b not be @c NULL. - * @param function function that originated the call, must @b not be @c NULL. - * @param line originating line in @a file. - * @param fmt printf-like format to use. Should not provide trailing - * '\n' as it is automatically included. - * @param ... variadic args. + * @since_tizen 2.3 * - * @note MT: this function may be called from different threads if - * eina_log_threads_enable() was called before. + * @remarks Usually you do not use this function directly but the helper + * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT(), and + * so on. See eina_log.h + * + * @param[in] domain The logging domain to use, otherwise @c EINA_LOG_DOMAIN_GLOBAL if + * you registered none \n + * It is recommended that modules and + * applications have their own logging domain. + * @param[in] level The message level, those with levels greater than the user + * specified value (eina_log_level_set() or environment + * variables like EINA_LOG_LEVEL, EINA_LOG_LEVELS) are ignored + * @param[in] file The filename that originated the call, must @b not be @c NULL + * @param[in] function The function that originated the call, must @b not be @c NULL + * @param[in] line The originating line in @a file + * @param[in] fmt The printf-like format to use, should not provide trailing + * '\n' as it is automatically included */ EAPI void eina_log_print(int domain, Eina_Log_Level level, @@ -792,27 +653,30 @@ EAPI void eina_log_print(int domain, ...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT; /** - * Print out log message using given domain and level. + * @brief Prints out log messages using the given domain and level. + * + * @details This function may be called from different threads if + * eina_log_threads_enable() is called before. * - * @note Usually you'll not use this function directly but the helper - * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and - * so on. See eina_log.h + * @since_tizen 2.3 * - * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if - * you registered none. It is recommended that modules and - * applications have their own logging domain. - * @param level message level, those with level greater than user - * specified value (eina_log_level_set() or environment - * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. - * @param file filename that originated the call, must @b not be @c NULL. - * @param fnc function that originated the call, must @b not be @c NULL. - * @param line originating line in @a file. - * @param fmt printf-like format to use. Should not provide trailing - * '\n' as it is automatically included. - * @param args the arguments needed by the format. + * @remarks Usually you do not use this function directly, but the helper + * macros like EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT(), and + * so on. See eina_log.h * - * @note MT: this function may be called from different threads if - * eina_log_threads_enable() was called before. + * @param[in] domain The logging domain to use, otherwise @c EINA_LOG_DOMAIN_GLOBAL if + * you registered none \n + * It is recommended that modules and + * applications have their own logging domain. + * @param[in] level The message level, those with levels greater than the user + * specified value (eina_log_level_set() or environment + * variables like EINA_LOG_LEVEL, EINA_LOG_LEVELS) are ignored + * @param[in] file The filename that originated the call, must @b not be @c NULL + * @param[in] fnc The function that originated the call, must @b not be @c NULL + * @param[in] line The originating line in @a file. + * @param[in] fmt The printf-like format to use, should not provide trailing + * '\n' as it is automatically included + * @param[in] args The arguments needed by the format. * * @see eina_log_print() */ @@ -829,30 +693,33 @@ EAPI void eina_log_vprint(int domain, */ /** - * @brief Alternative logging method, this will output to standard output stream. + * @brief Alternative logging function, this outputs to the standard output stream. + * + * @details This function colorizes the output based on the domain provided color and + * the message logging level. To disable color, set the environment variable + * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line + * information, set EINA_LOG_FILE_DISABLE=1 or + * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in the output. It is + * not acceptable to have both EINA_LOG_FILE_DISABLE and + * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just + * EINA_LOG_FUNCTION_DISABLE is considered and file information + * is printed anyways. + * + * @since_tizen 2.3 * - * @param d The domain. - * @param level The level. - * @param file The file which is logged. - * @param fnc The function which is logged. - * @param line The line which is logged. - * @param fmt The ouptut format to use. - * @param data Not used. - * @param args The arguments needed by the format. + * @remarks If threads are enabled, this function is called within locks. + * @remarks Threads different from the main thread have a thread ID + * appended to the domain name. * - * This method will colorize output based on domain provided color and - * message logging level. To disable color, set environment variable - * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line - * information, set EINA_LOG_FILE_DISABLE=1 or - * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is - * not acceptable to have both EINA_LOG_FILE_DISABLE and - * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just - * EINA_LOG_FUNCTION_DISABLE will be considered and file information - * will be printed anyways. + * @param[in] d The domain + * @param[in] level The level + * @param[in] file The file that is logged + * @param[in] fnc The function that is logged + * @param[in] line The line that is logged + * @param[in] fmt The ouptut format to use + * @param[in] data Not used + * @param[in] args The arguments needed by the format * - * @note MT: if threads are enabled, this function is called within locks. - * @note MT: Threads different from main thread will have thread id - * appended to domain name. */ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d, Eina_Log_Level level, @@ -864,38 +731,41 @@ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d, va_list args); /** - * @brief Default logging method, this will output to standard error stream. + * @brief Default logging function, this outputs to the standard error stream. * - * @param d The domain. - * @param level The level. - * @param file The file which is logged. - * @param fnc The function which is logged. - * @param line The line which is logged. - * @param fmt The ouptut format to use. - * @param data Not used. - * @param args The arguments needed by the format. + * @details This function colorizes the output based on the domain provided color and + * the message logging level. * - * This method will colorize output based on domain provided color and - * message logging level. + * To disable color, set the environment variable + * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a + * file or when using a non-supported color terminal, use + * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or + * -1), then Eina disables color if terminal ($TERM) is + * unsupported or redirecting to a file. * - * To disable color, set environment variable - * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a - * file or when using a non-supported color terminal, use - * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or - * -1), then Eina will disable color if terminal ($TERM) is - * unsupported or if redirecting to a file. - - . Similarly, to disable file and line - * information, set EINA_LOG_FILE_DISABLE=1 or - * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is - * not acceptable to have both EINA_LOG_FILE_DISABLE and - * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just - * EINA_LOG_FUNCTION_DISABLE will be considered and file information - * will be printed anyways. + * Similarly, to disable file and line + * information, set EINA_LOG_FILE_DISABLE=1 or + * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in the output. It is + * not acceptable to have both EINA_LOG_FILE_DISABLE and + * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just + * EINA_LOG_FUNCTION_DISABLE is considered and file information + * is printed anyways. + * + * @since_tizen 2.3 + * + * @remarks If threads are enabled, this function is called within locks. + * @remarks Threads different from the main thread have a thread ID + * appended to the domain name. + * + * @param[in] d The domain + * @param[in] level The level + * @param[in] file The file that is logged + * @param[in] fnc The function that is logged + * @param[in] line The line that is logged + * @param[in] fmt The ouptut format to use + * @param[in] data Not used + * @param[in] args The arguments needed by the format * - * @note MT: if threads are enabled, this function is called within locks. - * @note MT: Threads different from main thread will have thread id - * appended to domain name. */ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d, Eina_Log_Level level, @@ -907,22 +777,25 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d, va_list args); /** - * Alternative logging method, this will output to given file stream. + * @brief Alternative logging function, this outputs to the given file stream. * - * @param d The domain. - * @param level Not used. - * @param file The file which is logged. - * @param fnc The function which is logged. - * @param line The line which is logged. - * @param fmt The ouptut format to use. - * @param data The file which will store the output (as a FILE *). - * @param args The arguments needed by the format. + * @details This function never gives color as the output. * - * This method will never output color. + * @since_tizen 2.3 + * + * @remarks If threads are enabled, this function is called within locks. + * @remarks Threads different from the main thread have a thread ID + * appended to the domain name. + * + * @param[in] d The domain + * @param[in] level Not used + * @param[in] file The file that is logged + * @param[in] fnc The function that is logged + * @param[in] line The line that is logged + * @param[in] fmt The ouptut format to use + * @param[in] data The file that stores the output (as a FILE *) + * @param[in] args The arguments needed by the format * - * @note MT: if threads are enabled, this function is called within locks. - * @note MT: Threads different from main thread will have thread id - * appended to domain name. */ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d, Eina_Log_Level level, @@ -933,79 +806,77 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d, void *data, va_list args); - +/*--- TIZEN_ONLY : begin ---*/ /** - * Alternative logging method, this will output to systemd journal. - * - * @param d The domain. - * @param level Not used. - * @param file The file which is logged. - * @param fnc The function which is logged. - * @param line The line which is logged. - * @param fmt The ouptut format to use. - * @param data The file which will store the output (as a FILE *). - * @param args The arguments needed by the format. + * @brief Alternative logging function, this outputs to the system log. * - * This method will never output color. + * @details This function never gives color as the output. * - * @note if systemd journal is not there it will display error on stderr. - * @note if the process has been started by systemd this will be the default logging method. + * @param[in] d The domain + * @param[in] level Not used + * @param[in] file The file that is logged + * @param[in] fnc The function that is logged + * @param[in] line The line that is logged + * @param[in] fmt The ouptut format to use + * @param[in] data Not Used + * @param[in] args The arguments needed by the format * - * @since 1.8 */ -EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d, - Eina_Log_Level level, - const char *file, - const char *fnc, - int line, - const char *fmt, - void *data, - va_list args); +EAPI void eina_log_print_cb_syslog(const Eina_Log_Domain *d, + Eina_Log_Level level, + const char *file, + const char *fnc, + int line, + const char *fmt, + void *data, + va_list args); +#ifdef HAVE_DLOG /** - * Configure console color of given file. + * @brief Alternative logging function, this outputs to the dlog. * - * @param fp file to configure console color (usually stderr or stdout). - * @param color a VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET. + * @since_tizen 2.3 * - * @note if color is disabled, nothing is done. See - * eina_log_color_disable_get() - * @note on windows, both @a fp and @a color is converted automatically. + * @param[in] d The domain + * @param[in] level Not used + * @param[in] file The file that is logged + * @param[in] fnc The function that is logged + * @param[in] line The line that is logged + * @param[in] fmt The ouptut format to use + * @param[in] data Not Used + * @param[in] args The arguments needed by the format * - * @since 1.7 */ -EAPI void eina_log_console_color_set(FILE *fp, - const char *color) EINA_ARG_NONNULL(1, 2); +EAPI void eina_log_print_cb_dlog(const Eina_Log_Domain *d, + Eina_Log_Level level, + const char *file, + const char *fnc, + int line, + const char *fmt, + void *data, + va_list args); +#endif -/** String that indicates the log system is initializing */ -extern EAPI const char *_eina_log_state_init; -/** String that indicates the log system is shutting down */ -extern EAPI const char *_eina_log_state_shutdown; -/** @def EINA_LOG_STATE_INIT - *String that indicates the log system is initializing - */ -#define EINA_LOG_STATE_INIT _eina_log_state_init -/** @def EINA_LOG_STATE_SHUTDOWN - *String that indicates the log system is shutting down - */ -#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown +/*--- TIZEN_ONLY : end ---*/ /** - * @brief Start or stop the timing of a phase. + * @brief Configures the console color of the given file. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @remarks If color is disabled, nothing is done. + * @remarks In windows, both @a fp and @a color are converted automatically. * - * @param domain The domain. - * @param state State indicating if we are starting or stopping a phase. - * @param phase The name of the phase to be used in the log. + * @param[in] fp The file to configure the console color of(usually stderr or stdout) + * @param[in] color A VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET * - * @note One domain can be in only one phase at a time. - * @note If you change the name of the phase, it is assumed that - * the previous phase has stopped. - * @note The phase name should be available for all the life of the timing. - * @since 1.8 + * + * @see eina_log_color_disable_get() */ -EAPI void eina_log_timing(int domain, - Eina_Log_State state, - const char *phase) EINA_ARG_NONNULL(1, 3); +EAPI void eina_log_console_color_set(FILE *fp, + const char *color) EINA_ARG_NONNULL(1, 2); #include "eina_inline_log.x" @@ -1013,8 +884,4 @@ EAPI void eina_log_timing(int domain, * @} */ -/** - * @} - */ - #endif /* EINA_LOG_H_ */ diff --git a/src/lib/eina/eina_main.h b/src/lib/eina/eina_main.h index d7a7f0b01f..f0efe7ed5a 100644 --- a/src/lib/eina/eina_main.h +++ b/src/lib/eina/eina_main.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -19,44 +19,34 @@ #ifndef EINA_MAIN_H_ #define EINA_MAIN_H_ -#include <Efl_Config.h> - #include "eina_types.h" /** - * @addtogroup Eina_Main_Group Main - * - * @brief These functions provide general initialisation and shut down - * functions. - */ - -/** - * @addtogroup Eina_Core_Group Core - * - * @{ - */ - -/** + * @internal * @defgroup Eina_Main_Group Main + * @ingroup Eina_Core_Group + * + * @brief This group discusses the functions that provide general initialisation and shut down + * functions. * * @{ */ /** * @def EINA_VERSION_MAJOR - * @brief Major version of Eina + * @brief Definition of the major version of Eina. */ -#define EINA_VERSION_MAJOR EFL_VERSION_MAJOR +#define EINA_VERSION_MAJOR 1 /** * @def EINA_VERSION_MINOR - * @brief Minor version of Eina + * @brief Definition of the minor version of Eina. */ -#define EINA_VERSION_MINOR EFL_VERSION_MINOR +#define EINA_VERSION_MINOR 8 /** * @typedef Eina_Version - * The version of Eina. + * @brief The structure type containing the version of Eina. */ typedef struct _Eina_Version { @@ -69,90 +59,104 @@ typedef struct _Eina_Version EAPI extern Eina_Version *eina_version; /** - * @brief Initialize the Eina library. + * @brief Initializes the Eina library. + * + * @details This function sets up all the eina modules. It returns @c 0 on + * failure (that is, when one of the module fails to initialize), + * otherwise it returns the number of times it has already been + * called. * - * @return 1 or greater on success, 0 on error. + * @since_tizen 2.3 * - * This function sets up all the eina modules. It returns 0 on - * failure (that is, when one of the module fails to initialize), - * otherwise it returns the number of times it has already been - * called. + * @remarks When Eina is not used anymore, call eina_shutdown() to shut down + * the Eina library. + * + * @return @c 1 or greater on success, otherwise @c 0 on error * - * When Eina is not used anymore, call eina_shutdown() to shut down - * the Eina library. */ EAPI int eina_init(void); /** - * @brief Shut down the Eina library. + * @brief Shuts down the Eina library. + * + * @details This function shuts down the Eina library. It returns @c 0 when it has + * been called the same number of times as eina_init(). In that case, + * it shuts down all the Eina modules. + * + * Once this function succeeds (that is, @c 0 is returned), you must + * not call any of the Eina functions anymore. You must call + * eina_init() again to use the Eina functions again. * - * @return 0 when all the modules are completely shut down, 1 or - * greater otherwise. + * @since_tizen 2.3 * - * This function shuts down the Eina library. It returns 0 when it has - * been called the same number of times than eina_init(). In that case - * it shut down all the Eina modules. + * @return @c 0 when all the modules are completely shut down, otherwise @c 1 or greater * - * Once this function succeeds (that is, @c 0 is returned), you must - * not call any of the Eina function anymore. You must call - * eina_init() again to use the Eina functions again. */ EAPI int eina_shutdown(void); /** - * @brief Initialize the mutexes of the Eina library. + * @brief Initializes the mutexes of the Eina library. * - * @return 1 or greater on success, 0 on error. + * @details This function sets up all the mutexes in all the eina modules. It returns @c 0 on + * failure (that is, when one of the module fails to initialize), + * otherwise it returns the number of times it has already been + * called. * - * This function sets up all the mutexes in all eina modules. It returns 0 on - * failure (that is, when one of the module fails to initialize), - * otherwise it returns the number of times it has already been - * called. + * @since_tizen 2.3 * - * When the mutexes are not used anymore, call eina_threads_shutdown() to shut down - * the mutexes. + * @remarks When the mutexes are not used anymore, call eina_threads_shutdown() to shut down + * the mutexes. + * + * @remarks This function should never be called outside the main loop. + * + * @return @c 1 or greater on success, otherwise @c 0 on error * - * This function should never be called outside of the main loop. */ EAPI int eina_threads_init(void); /** - * @brief Shut down mutexes in the Eina library. + * @brief Shuts down mutexes in the Eina library. + * + * @details This function shuts down the mutexes in the Eina library. It returns @c 0 when it has + * been called the same number of times as eina_threads_init(). In that case + * it shuts down all the mutexes. + * + * Once this function succeeds (that is, @c 0 is returned), you must + * not call any of the Eina functions in a thread anymore. You must call + * eina_threads_init() again to use the Eina functions in a thread again. * - * @return 0 when all mutexes are completely shut down, 1 or - * greater otherwise. + * @since_tizen 2.3 * - * This function shuts down the mutexes in the Eina library. It returns 0 when it has - * been called the same number of times than eina_threads_init(). In that case - * it shut down all the mutexes. + * @remarks This function should never be called outside the main loop. * - * Once this function succeeds (that is, @c 0 is returned), you must - * not call any of the Eina function in a thread anymore. You must call - * eina_threads_init() again to use the Eina functions in a thread again. + * @return @c 0 when all the mutexes are completely shut down, otherwise @c 1 or greater * - * This function should never be called outside of the main loop. */ EAPI int eina_threads_shutdown(void); /** - * @brief Check if you are calling this function from the same thread Eina was initialized or not - * - * @return #EINA_TRUE is the calling function is the same thread, #EINA_FALSE otherwise. + * @brief Check whether you are calling this function from the same thread in which Eina is initialized. * * @since 1.1.0 * - * Most EFL function are not thread safe and all the call need to happen in - * the main loop. With this call you could know if you can call an EFL - * function or not. + * @since_tizen 2.3 + * + * @remarks Most EFL functions are not thread safe and all the calls need to happen in + * the main loop. With this call you could know if you can call an EFL + * function. + * + * @return @c EINA_TRUE if the calling function is in the same thread, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_main_loop_is(void); /** - * @brief You should never use that function excpet if you really really know what your are doing. - * @since 1.1.0 + * @brief You should never use this function unless you really know what you are doing. * - * If you are reading this documentation, that certainly means you don't know what is the purpose of - * this call and you should just not use it. + * @since_tizen 2.3 + * + * @remarks If you are reading this documentation, that certainly means you don't know the purpose of + * this call, so you should not use it. */ EAPI void eina_main_loop_define(void); @@ -160,8 +164,4 @@ EAPI void eina_main_loop_define(void); * @} */ -/** - * @} - */ - #endif /* EINA_MAIN_H_ */ diff --git a/src/lib/eina/eina_matrixsparse.h b/src/lib/eina/eina_matrixsparse.h index 5523c0fb31..fc29481846 100644 --- a/src/lib/eina/eina_matrixsparse.h +++ b/src/lib/eina/eina_matrixsparse.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2009 Gustavo Sverzut Barbieri * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -28,66 +28,54 @@ #include "eina_accessor.h" /** - * @addtogroup Eina_Matrixsparse_Group Sparse Matrix - * - * @brief These functions provide matrix sparse management. - * - * For more information, you can look at the @ref tutorial_matrixsparse_page. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** * @defgroup Eina_Matrixsparse_Group Sparse Matrix + * @ingroup Eina_Containers_Group + * + * @brief This group discusses the functions to provide matrix sparse management. * * @{ */ /** * @typedef Eina_Matrixsparse - * Type for a generic sparse matrix. + * @brief The structure type for a generic sparse matrix. */ typedef struct _Eina_Matrixsparse Eina_Matrixsparse; /** * @typedef Eina_Matrixsparse_Row - * Type for a generic sparse matrix row, opaque for users. + * @brief The structure type for a generic sparse matrix row, opaque for users. */ typedef struct _Eina_Matrixsparse_Row Eina_Matrixsparse_Row; /** * @typedef Eina_Matrixsparse_Cell - * Type for a generic sparse matrix cell, opaque for users. + * @brief The structure type for a generic sparse matrix cell, opaque for users. */ typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell; -/* constructors and destructors */ +/* Constructors and destructors */ /** - * @brief Create a new Sparse Matrix. - * - * @param rows number of rows in matrix. Operations with rows greater than this - * value will fail. - * @param cols number of columns in matrix. Operations with columns greater - * than this value will fail. - * @param free_func used to delete cell data contents, used by - * eina_matrixsparse_free(), eina_matrixsparse_size_set(), - * eina_matrixsparse_row_idx_clear(), - * eina_matrixsparse_column_idx_clear(), - * eina_matrixsparse_cell_idx_clear() and possible others. - * @param user_data given to @a free_func as first parameter. - * - * @return Newly allocated matrix or @c NULL if allocation failed. + * @brief Creates a new Sparse Matrix. + * + * @since_tizen 2.3 + * + * @param[in] rows The number of rows in the matrix \n + * Operations with rows greater than this + * value fail. + * @param[in] cols The number of columns in the matrix \n + * Operations with columns greater + * than this value fail. + * @param[in] free_func The function used to delete cell data contents, used by + * eina_matrixsparse_free(), eina_matrixsparse_size_set(), + * eina_matrixsparse_row_idx_clear(), + * eina_matrixsparse_column_idx_clear(), + * eina_matrixsparse_cell_idx_clear(), and other possible functions. + * @param[in] user_data The data given to @a free_func as the first parameter + * + * @return The newly allocated matrix, otherwise @c NULL if allocation fails and eina_error + * is set */ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows, unsigned long cols, @@ -96,61 +84,71 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows, const void *user_data); /** - * @brief Free resources allocated to Sparse Matrix. + * @brief Frees resources allocated to the Sparse Matrix. + * + * @since_tizen 2.3 * - * @param m The Sparse Matrix instance to free, must @b not be @c NULL. + * @param[in] m The Sparse Matrix instance to free, must @b not be @c NULL */ EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m); -/* size manipulation */ +/* Size manipulation */ /** - * @brief Get the current size of Sparse Matrix. + * @brief Gets the current size of the Sparse Matrix. + * + * @since_tizen 2.3 * - * The given parameters are guaranteed to be set if they're not @c NULL, - * even if this function fails (ie: @a m is not a valid matrix instance). + * @remarks The given parameters are guaranteed to be set if they're not @c NULL, + * even if this function fails (ie: @a m is not a valid matrix instance). * - * @param m the sparse matrix to operate on. - * @param rows returns the number of rows, may be @c NULL. If @a m is invalid, - * returned value is zero, otherwise it's a positive integer. - * @param cols returns the number of columns, may be @c NULL. If @a m is - * invalid, returned value is zero, otherwise it's a positive integer. + * @param[in] m The sparse matrix to operate on + * @param[out] rows The number of rows, may be @c NULL \n + * If @a m is invalid the returned value is zero, otherwise it's a positive integer. + * @param[out] cols The number of columns, may be @c NULL \n + * If @a m is invalid the returned value is zero, otherwise it's a positive integer. */ EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m, unsigned long *rows, unsigned long *cols); /** - * @brief Resize the Sparse Matrix. + * @brief Resizes the Sparse Matrix. * - * This will resize the sparse matrix, possibly freeing cells on rows - * and columns that will cease to exist. + * @details This resizes the sparse matrix, possibly freeing cells of rows + * and columns that cease to exist. * - * @param m the sparse matrix to operate on. - * @param rows the new number of rows, must be greater than zero. - * @param cols the new number of columns, must be greater than zero. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @remarks The cells, rows, or columns are not reference counted and thus + * after this call any reference might be invalid if the instance is + * freed. + * + * @param[in] m The sparse matrix to operate on + * @param[in] rows The new number of rows, must be greater than zero + * @param[in] cols The new number of columns, must be greater than zero + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * @warning cells, rows or columns are not reference counted and thus - * after this call any reference might be invalid if instance were - * freed. */ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m, unsigned long rows, unsigned long cols); -/* data getting */ +/* Obtaining data */ /** - * Get the cell reference inside Sparse Matrix. + * @brief Gets the cell reference inside the Sparse Matrix. + * + * @since_tizen 2.3 * - * @param m the sparse matrix to operate on. - * @param row the new number of row to clear. - * @param col the new number of column to clear. - * @param cell pointer to return cell reference, if any exists. + * @param[in] m The sparse matrix to operate on + * @param[in] row The new row number to clear + * @param[in] col The new column number to clear + * @param[out] cell A pointer to return the cell reference, if it exists * - * @return @c 1 on success, @c 0 on failure. It is considered success if did not - * exist but index is inside matrix size, in this case @c *cell == NULL + * @return @c 1 on success, otherwise @c 0 on failure \n + * It is considered successful if it does not + * exist but its index is inside the matrix size, in this case @c *cell == NULL * * @see eina_matrixsparse_cell_data_get() * @see eina_matrixsparse_data_idx_get() @@ -158,11 +156,11 @@ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m, EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell); /** - * Get data associated with given cell reference. + * @brief Gets the data associated to the given cell reference. * - * @param cell given cell reference, must @b not be @c NULL. + * @param[in] cell The given cell reference, must @b not be @c NULL * - * @return data associated with given cell. + * @return The data associated to the given cell * * @see eina_matrixsparse_cell_idx_get() * @see eina_matrixsparse_data_idx_get() @@ -170,13 +168,15 @@ EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsign EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cell); /** - * Get data associated with given cell given its indexes. + * @brief Gets the data associated to the given cell given that its indexes are provided. * - * @param m the sparse matrix to operate on. - * @param row the new number of row to clear. - * @param col the new number of column to clear. + * @since_tizen 2.3 * - * @return Data associated with given cell or @c NULL if nothing is associated. + * @param[in] m The sparse matrix to operate on + * @param[in] row The new row number to clear + * @param[in] col The new column number to clear + * + * @return The data associated to the given cell, otherwise @c NULL if nothing is associated * * @see eina_matrixsparse_cell_idx_get() * @see eina_matrixsparse_cell_data_get() @@ -184,26 +184,30 @@ EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col); /** - * Get position (indexes) of the given cell. + * @brief Gets the position (indexes) of the given cell. + * + * @since_tizen 2.3 * - * @param cell the cell reference, must @b not be @c NULL. - * @param row where to store cell row number, may be @c NULL. - * @param col where to store cell column number, may be @c NULL. + * @param[in] cell The cell reference, must @b not be @c NULL + * @param[out] row The location to store the cell row number, may be @c NULL + * @param[out] col The location to store the column number, may be @c NULL * - * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL). + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@c cell is @c NULL) */ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col); -/* data setting */ +/* Setting data */ /** - * Change cell reference value without freeing the possibly existing old value. + * @brief Changes the cell reference value without freeing a possible existing old value. + * + * @since_tizen 2.3 * - * @param cell the cell reference, must @b not be @c NULL. - * @param data new data to set. - * @param p_old returns the old value intact (not freed). + * @param[in] cell The cell reference, must @b not be @c NULL + * @param[in] data The new data to set + * @param[out] p_old The old value that is intact (not freed) * - * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL). + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a cell is @c NULL) * * @see eina_matrixsparse_cell_data_set() * @see eina_matrixsparse_data_idx_replace() @@ -211,15 +215,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old); /** - * Change cell value freeing the possibly existing old value. + * @brief Changes the cell value by freeing a possible existing old value. * - * In contrast to eina_matrixsparse_cell_data_replace(), this function will - * call @c free_func() on existing value. + * @since_tizen 2.3 * - * @param cell the cell reference, must @b not be @c NULL. - * @param data new data to set. + * @remarks In contrast to eina_matrixsparse_cell_data_replace(), this function + * calls @c free_func() on the existing value. * - * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL). + * @param[in] cell The cell reference, must @b not be @c NULL + * @param[in] data The new data to set + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a cell is @c NULL). * * @see eina_matrixsparse_cell_data_replace() * @see eina_matrixsparse_data_idx_set() @@ -227,16 +233,18 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data); /** - * Change cell value without freeing the possibly existing old value, using - * indexes. + * @brief Changes the cell value without freeing a possible existing old value, using + * indexes. + * + * @since_tizen 2.3 * - * @param m the sparse matrix, must @b not be @c NULL. - * @param row the row number to set the value. - * @param col the column number to set the value. - * @param data new data to set. - * @param p_old returns the old value intact (not freed). + * @param[in] m The sparse matrix, must @b not be @c NULL + * @param[in] row The row number to set the value of + * @param[in] col The column number to set the value of + * @param[in] data The new data to set + * @param[out] p_old The old value that is intact (not freed) * - * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid). + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a m is @c NULL, indexes are not valid) * * @see eina_matrixsparse_cell_data_replace() * @see eina_matrixsparse_data_idx_set() @@ -244,146 +252,166 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, con EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old); /** - * Change cell value freeing the possibly existing old value, using - * indexes. + * @brief Changes the cell value by freeing a possible existing old value, using + * indexes. + * + * @since_tizen 2.3 * - * In contrast to eina_matrixsparse_data_idx_replace(), this function will - * call @c free_func() on existing value. + * @remarks In contrast to eina_matrixsparse_data_idx_replace(), this function + * calls @c free_func() on the existing value. * - * @param m the sparse matrix, must @b not be @c NULL. - * @param row the row number to set the value. - * @param col the column number to set the value. - * @param data new data to set. + * @param[in] m The sparse matrix, must @b not be @c NULL + * @param[in] row The row number to set the value of + * @param[in] col The column number to set the value of + * @param[in] data The new data to set * - * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid). + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a m is @c NULL, indexes are not valid) * * @see eina_matrixsparse_cell_data_replace() */ EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data); -/* data deleting */ +/* Deleting data */ /** - * Clear (erase all cells) of row given its index. + * @brief Clears (erases) all the cells of the row given that its index is provided. * - * Existing cells will be cleared with @c free_func() given to - * eina_matrixsparse_new(). + * @since_tizen 2.3 * - * @param m the sparse matrix to operate on. - * @param row the new number of row to clear. + * @remarks Existing cells are cleared with @c free_func() given to + * eina_matrixsparse_new(). * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if row - * had no cells filled. Failure is asking for clear row outside - * matrix size. + * @remarks The cells, rows, or columns are not reference counted and thus + * after this call any reference might be invalid if an instance is + * freed. + * + * @param[in] m The sparse matrix to operate on + * @param[in] row The new row number to clear + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n + * It is considered successful if the row has no filled cells \n + * Failure is asking for a clear row outside the matrix size. * - * @warning cells, rows or columns are not reference counted and thus - * after this call any reference might be invalid if instance were - * freed. */ EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row); /** - * Clear (erase all cells) of column given its index. + * @brief Clears (erases) all the cells of the column given that its index is provided. + * + * @since_tizen 2.3 * - * Existing cells will be cleared with @c free_func() given to - * eina_matrixsparse_new(). + * @remarks Existing cells are cleared with @c free_func() given to + * eina_matrixsparse_new(). * - * @param m the sparse matrix to operate on. - * @param col the new number of column to clear. + * @remarks The cells, rows, or columns are not reference counted and thus + * after this call any reference might be invalid if an instance is + * freed. * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if column - * had no cells filled. Failure is asking for clear column outside - * matrix size. + * @param[in] m The sparse matrix to operate on + * @param[in] col The new column number to clear + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n + * It is considered successful if the column has no filled cells \n + * Failure is asking for a clear column outside the matrix size. * - * @warning cells, rows or columns are not reference counted and thus - * after this call any reference might be invalid if instance were - * freed. */ EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col); /** - * Clear (erase) cell given its indexes. + * @brief Clears (erases) a cell given that its indexes are provided. + * + * @since_tizen 2.3 + * + * @remarks Existing cells are cleared with @c free_func() given to + * eina_matrixsparse_new(). * - * Existing cell will be cleared with @c free_func() given to - * eina_matrixsparse_new(). + * @remarks The cells, rows, or columns are not reference counted and thus + * after this call any reference might be invalid if an instance is + * freed. * - * @param m the sparse matrix to operate on. - * @param row the new number of row to clear. - * @param col the new number of column to clear. + * @remarks This call might delete a container column and row if this cell is the + * last remainder. * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not - * exist but index is inside matrix size. + * @param[in] m The sparse matrix to operate on + * @param[in] row The new row number to clear + * @param[in] col The new column number to clear * - * @warning cells, rows or columns are not reference counted and thus - * after this call any reference might be invalid if instance were - * freed. + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n + * It is considered successful if it does not exist but its index is inside the matrix size. * - * @note This call might delete container column and row if this cell was the - * last remainder. */ EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col); /** - * Clear (erase) cell given its reference. + * @brief Clears (erases) a cell given that its referenceis provided. * - * @param cell the cell reference, must @b not be @c NULL. + * @since_tizen 2.3 * - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @remarks The cells, rows, or columns are not reference counted and thus + * after this call any reference might be invalid if an instance is + * freed. * - * @warning cells, rows or columns are not reference counted and thus - * after this call any reference might be invalid if instance were - * freed. + * @remarks This call might delete a container column and row if this cell is the + * last remainder. + * + * @param[in] cell The cell reference, must @b not be @c NULL + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * @note This call might delete container column and row if this cell was the - * last remainder. */ EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell); -/* iterators */ +/* Iterators */ /** - * Creates a new iterator over existing matrix cells. + * @brief Creates a new iterator over existing matrix cells. + * + * @since_tizen 2.3 * - * This is a cheap walk, it will just report existing cells and holes - * in the sparse matrix will be ignored. That means the reported - * indexes will not be sequential. + * @remarks This is a cheap walk, it just reports existing cells and holes + * in the sparse matrix are ignored. That means the reported + * indexes are not sequential. * - * The iterator data will be the cell reference, one may query current - * position with eina_matrixsparse_cell_position_get() and cell value - * with eina_matrixsparse_cell_data_get(). + * @remarks The iterator data is the cell reference, one may query the current + * position with eina_matrixsparse_cell_position_get() and cell value + * with eina_matrixsparse_cell_data_get(). * - * @param m The Sparse Matrix reference, must @b not be @c NULL. - * @return A new iterator. + * @remarks If the matrix structure changes then the iterator becomes + * invalid. That is, if you add or remove cells this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] m The Sparse Matrix reference, must @b not be @c NULL + * @return A new iterator * - * @warning if the matrix structure changes then the iterator becomes - * invalid! That is, if you add or remove cells this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m); /** - * Creates a new iterator over all matrix cells. + * @brief Creates a new iterator over all the matrix cells. + * + * @since_tizen 2.3 + * + * @remarks Unlike eina_matrixsparse_iterator_new(), this one reports all + * the matrix cells, even those that are still empty (holes). These are + * reported as dummy cells that contain no data. * - * Unlike eina_matrixsparse_iterator_new() this one will report all - * matrix cells, even those that are still empty (holes). These will - * be reported as dummy cells that contains no data. + * @remarks Be aware that iterating a big matrix (1000x1000) calls your + * function that number of times (1000000 times in that case) even if + * your matrix have no elements at all. * - * Be aware that iterating a big matrix (1000x1000) will call your - * function that number of times (1000000 times in that case) even if - * your matrix have no elements at all! + * @remarks The iterator data is the cell reference, one may query the current + * position with eina_matrixsparse_cell_position_get() and cell value + * with eina_matrixsparse_cell_data_get(). If the cell is empty then the + * reference is a dummy/placeholder, thus setting a value with + * eina_matrixsparse_cell_data_set() leaves the pointer unreferenced. * - * The iterator data will be the cell reference, one may query current - * position with eina_matrixsparse_cell_position_get() and cell value - * with eina_matrixsparse_cell_data_get(). If cell is empty then the - * reference will be a dummy/placeholder, thus setting value with - * eina_matrixsparse_cell_data_set() will leave pointer unreferenced. + * @remarks If the matrix structure changes then the iterator becomes + * invalid. That is, if you add or remove cells this iterator's + * behavior is undefined and your program may crash. * - * @param m The Sparse Matrix reference, must @b not be @c NULL. - * @return A new iterator. + * @param[in] m The Sparse Matrix reference, must @b not be @c NULL + * @return A new iterator * - * @warning if the matrix structure changes then the iterator becomes - * invalid! That is, if you add or remove cells this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixsparse *m); @@ -391,12 +419,4 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixspa * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif /* EINA_MATRIXSPARSE_H_ */ diff --git a/src/lib/eina/eina_mmap.h b/src/lib/eina/eina_mmap.h index 1d1d58c976..16f3044ffe 100644 --- a/src/lib/eina/eina_mmap.h +++ b/src/lib/eina/eina_mmap.h @@ -2,10 +2,11 @@ #define EINA_MMAP_H_ /** - * @addtogroup Eina_Mmap_Group Mmap Group - * @ingroup Eina + * @internal + * @defgroup Eina_Mmap_Group Mmap Group + * @ingroup Eina_Core_Group * - * @brief These functions provide helpers for safe mmap handling + * @brief This group discusses the functions that provide helpers for safe mmap handling. * * @{ * @@ -13,44 +14,50 @@ */ /** - * @brief Enable or disable safe mmaped IO handling - * - * @param enabled The enabled state (to enable, pass #EINA_TRUE) - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This enables (if possible on your platform) a signal handler for - * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero) - * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate - * or from files on devices with IO errors. Normally these cases will result - * in a SIGBUS being delivered (and termination of your process), but - * when "mmap safety" is enabled, this will not occur. Instead a page of - * bytes of the value 0 will replace the "bad page", allowing the process - * to continue and allow its own parsing error detection to safely abort - * the operation without the process falling apart. - * - * If you disable mmap safety, the SIGBUS handler will be restored to its - * default handler. Note that eina_file_map_all() and eina_file_map_new() - * will automatically enable mmap safety as they provide an mmaped file IO - * layer, and rely on mmap to not fail for any part of the file. - * - * If you set up your own SIGBUS handler, then this will effectively disable - * the safe mmap handling and make you liable to crashes on IO to or from - * such "damaged files" that would take down your process. + * @brief Enables or disables safe mmaped IO handling. + * + * @details This enables (if possible on your platform) a signal handler for + * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero) + * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate + * or from files on devices with IO errors. Normally these cases result + * in a SIGBUS being delivered (and termination of your process), but + * when "mmap safety" is enabled, this does not occur. Instead a page of + * bytes of the value 0 replaces the "bad page", allowing the process + * to continue and allow its own parsing error detection to safely abort + * the operation without the process falling apart. * * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @remarks If you disable mmap safety, the SIGBUS handler is restored to its + * default handler. Note that eina_file_map_all() and eina_file_map_new() + * automatically enable mmap safety as they provide an mmaped file IO + * layer, and rely on mmap to not fail for any part of the file. + * + * @remarks If you set up your own SIGBUS handler, then this effectively disables + * the safe mmap handling and makes you liable to crashes on IO to or from + * such "damaged files" that would take down your process. + * + * @param[in] enabled The enabled state (to enable, pass @c EINA_TRUE) + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_mmap_safety_enabled_set(Eina_Bool enabled); /** - * @brief Get the enabled state of mmap safety. - * - * @return The safety state (#EINA_TRUE if enabled) + * @brief Gets the enabled state of mmap safety. * - * This returns the mmap safety state set by eina_mmap_safety_enabled_set(). - * See eina_mmap_safety_enabled_set() for more information. + * @details This returns the mmap safety state set by eina_mmap_safety_enabled_set(). * * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @return The safety state (@c EINA_TRUE if enabled) + * + * @see eina_mmap_safety_enabled_set() */ EAPI Eina_Bool eina_mmap_safety_enabled_get(void); diff --git a/src/lib/eina/eina_model.h b/src/lib/eina/eina_model.h index b6229c1ce5..8e323390c5 100644 --- a/src/lib/eina/eina_model.h +++ b/src/lib/eina/eina_model.h @@ -46,228 +46,9 @@ */ /** - * @page eina_model_02_example_page Creating a simple model - * @dontinclude eina_model_02.c - * - * This example shows the creation of a model with five properties, named: - * 'a', 'b', 'c', 'd' and 'e' with values 0, 1, 2, 3 and 4 - * respectively. In addition to the 5 properties our model also add 5 children, - * and to each child we give a property named 'x' with a value of 1, 2, 3, 4 and - * 5. - * - * In other words this piece of code shows how to use eina_model to store a list - * of elements, given that the list itself has some properties. - * - * Now let's walk through the code and examine the interesting bits. - * - * This is some pretty standard initialization code. - * @until eina_init - * - * We now create our eina_model, the important detail here is the type of the - * model being created, for this example we use the generic type provided by - * eina: - * @until model_new - * - * Once our model has been created we can add callbacks to be notified of events - * that happen to our model, for this example we are just going to add a - * callback for the "delete" event. To get a list of events a given eina model - * can emit see @ref eina_model_event_names_list_get(). - * @until callback_add - * - * Once we have a model, we need to populate it with information. There are two - * types of information we can store on an eina model: properties and eina - * models. We are going to start by looking at properties. - * - * Properties are, simply put, named values. They have a char* identifier and an - * Eina_Value value. This means you can store in a property almost any type of - * data. For this example we are going to add some very simple numeric - * properties which will have single letter identifiers. - * @until } - * @until } - * - * Despite being able to store almost any value properties the least flexible - * information unit we can put in an eina model. We can add eina models to our - * eina model, this allows us to represt complex information hierarchies. This - * example adds 5 models(with no children of their own) to our parent model @c - * m. - * @until } - * The code here should be pretty easy to understand, we create a model, much - * like we did before, and we then add a property to our model, again a task we - * have already done. - * - * The important issue to note here is that we could have given each of our @c c - * child models as complex an structure as we needed, they could each be a list - * or a tree on their own right. - * - * Now that we have a populated model we print a string representation of - * it(without forgetting to free the string): - * @until free - * - * And since we are done using our model we release our reference to it(and - * since no else holds references to it, it will be freed): - * @until } - * - * Note that we don't need to iterate over the children of @c m unrefing it, - * this is because we don't hold references to it, we freed our references right - * after we added them to their parent model, so when the parent model dies(and - * releases the references to it's children) they will be freed. - * - * The only thing we are going to look at is the callback we registered for - * whenever a model is deleted, since our models don't do anything fancy we are - * just going to print the memory address of the model being freed. - * @until } - * - * Note that this means the memory address is still valid, our callback is - * called just before the memory is freed so we could still access its - * information here. - * - * The full code can be seen in @ref eina_model_02_c - */ - -/** - * @page eina_model_02_c eina_model_02.c - * @include eina_model_02.c - * @example eina_model_02.c - */ - -/** - * @page eina_model_03_example_page Using Eina_Model and inheritance - * @dontinclude eina_model_03.c - * - * This example will use two custom defined eina model types: @c PERSON_TYPE to - * represent a person and @c ADDRESS_BOOK_TYPE to represent the an address book. - * Both our types inherit from EINA_MODEL_TYPE_STRUCT, and, therefore, - * store it's data on a struct. Our address book will be very simple it will - * only contain one property, the name of the file where we store our address - * book. The person type will contain two fields a name and en email. Let's look - * at the code. - * - * We'll start with declaring the variables and functions we'll need to define - * our custom type. This will all be explained when the variables get used. - * @until address_book_init - * - * We then jump into our @c main function, declare a couple of variables and - * initialize eina: - * @until eina_init - * - * After eina is initialized we'll @c address_book_init() which will initialize - * both our @c PERSON_TYPE and our @c ADDRESS_BOOK_TYPE. Details of this will be - * shown latter on: - * @until address_book_init - * - * Now that everything is correctly initialized we can create the model that - * will represent our address book's - * @until eina_model_new - * - * Before we can load data into our model we need to tell it where to load from, - * we do this by setting it's filename property: - * @until value_flush - * - * We then load data into our model and display it as a string: - * @until free - * - * While @c eina_model_to_string allows you to see the contents of the model, - * it's display format is not user friendly, it's best used for debugging. So - * let's now print our model in a user friendly way. - * - * First we see how many people are in our address book and print that: - * @until printf - * - * And now we iterate over every child of our address book model, which - * represents a person: - * @until person - * - * But again simply calling @c eina_model_to_string would result in not very - * user friendly output, so we'll need to get the properties of the person(name - * and email) and print them with some formatting: - * @until printf - * - * We then free the resources we allocated to print this person: - * @until } - * - * And that's it for our main function, now just freeing our resources: - * @until } - * - * This however obviously doesn't conclude our example we need to examine how - * the the loading of data works to really understand what is happening in the - * @c main function. - * - * Let's start with the constructors(and the variables they use). Both our - * constructors do two very important tasks: - * @li Calls our parent's constructor, and - * @li Sets the description of the struct on our model - * - * For these constructors that's all we need to do since most of our - * functionality is provided by @c EINA_MODEL_TYPE_STRUCT. - * @until } - * @until } - * - * And now we have our load function, it opens the file from which we'll - * read the address book: - * @until EINA_SAFETY_ON_NULL_RETURN_VAL - * - * Once the file has been opened we read from it line by line and for each - * non-blank line we get a name and an email: - * @until email - * @until email - * - * Once we have the name and email we create our person model, set it's - * properties and make our person a child of the address book: - * @until } - * - * And now that we're done reading the file we close it: - * @until } - * - * This next function is perphaps the most interesting one of our example, it's - * the one that creates the definition of our derived types. - * - * First thing we'll do is the description of the members of our person type. - * @until person_members[1].type - * Now the description of the struct itself(which uses the members): - * @until } - * And finally we define the person type itself: - * @until person_type.constructor - * - * With the person now described we'll do the same process for our address book - * type: - * @until address_book_type.load - * - * So far everything we created has been in the scope of our function to make - * this available outside(such as in the @c main function where we use @c - * ADDRESS_BOOK_TYPE and on @c _address_book_load function where we use @c - * PERSON_TYPE) we need to assign our descriptions and type to global variables: - * @until } - * - * This concludes this example. A good exercise for the reader is to extend this - * example to have the model save the addres book, for example once it's - * unloaded, this can be done by overriding the .unload property of @c - * ADDRESS_BOOK_TYPE. - * - * For the full code see: @ref eina_model_03_c - */ - -/** - * @page eina_model_03_c eina_model_03.c - * @include eina_model_03.c - * @example eina_model_03.c - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @since 1.2 - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** + * @internal * @defgroup Eina_Model_Group Data Model API + * @ingroup Eina_Containers_Group * * Abstracts data access to hierarchical data in an efficient way, * extensible to different backing stores such as database or remote @@ -288,21 +69,19 @@ * fixed set of names and they have fixed type, as defined by * the #Eina_Value_Struct_Desc description used internally. * - * Examples: - * @li @ref eina_model_01_c inheritance example, uses #EINA_MODEL_TYPE_GENERIC - * @li @ref eina_model_02_example_page contains an easy to follow - * example that demonstrates several of the important features of - * eina_model, uses #EINA_MODEL_TYPE_GENERIC. - * @li @ref eina_model_03_example_page walk-through example on how to - * inherit types, a suggestion of eina_model_load() usage and - * uses #EINA_MODEL_TYPE_STRUCT. - * @li @ref eina_model_04_c Advanced inheritance, interfaces and interface - * function overloading example. - * * @{ */ +/** + * @var EINA_ERROR_MODEL_FAILED + * Defined when model-specific errors happens. + */ EAPI extern Eina_Error EINA_ERROR_MODEL_FAILED; + +/** + * @var EINA_ERROR_MODEL_METHOD_MISSING + * Defined when model-specific errors happens. + */ EAPI extern Eina_Error EINA_ERROR_MODEL_METHOD_MISSING; /** @@ -508,8 +287,9 @@ EAPI void eina_model_xunref(Eina_Model *model, /** + * @internal * @defgroup Eina_Model_Event_Group Data Model Events - * Events and their usage with models. + * @brief Events and their usage with models. * * Events are specified by each type and interface level * using #Eina_Model_Event_Description. One can know all events supported @@ -748,8 +528,9 @@ EAPI Eina_Bool eina_model_unload(Eina_Model *model) EINA_ARG_NONNULL(1); /** + * @internal * @defgroup Eina_Model_Properties_Group Data Model Properties - * Properties and their usage with models. + * @brief Properties and their usage with models. * * Properties are attributes of model. They have a name and contain a * data value (@ref Eina_Value_Group). @@ -835,8 +616,9 @@ EAPI void eina_model_properties_names_list_free(Eina_List *list); */ /** + * @internal * @defgroup Eina_Model_Children_Group Data Model Children - * Children and their usage with models. + * @brief Children and their usage with models. * * Children are other model instances that are kept sequentially in * the model. They are accessed by their integer index within the @@ -1005,8 +787,9 @@ EAPI Eina_Bool eina_model_child_sort(Eina_Model *model, */ /** + * @internal * @defgroup Eina_Model_Iterators_Group Data Model Iterators - * Iterators and their usage with models. + * @brief Iterators and their usage with models. * * One of the most common tasks of models is to iterate over their * children, either forwards or backwards, filtering by some criteria @@ -1273,10 +1056,11 @@ EAPI Eina_Iterator *eina_model_child_slice_filtered_iterator_get(Eina_Model *mod EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC; /** + * @internal * @defgroup Eina_Model_Type_Group Data Model Type management * - * Functions and structures related to implementing new types or - * extending existing ones. + * @brief Functions and structures related to implementing new types or + * extending existing ones. * * All eina_model_type functions takes an Eina_Model_Type or * Eina_Model_Interface as parameter and may be used to validate or @@ -1288,14 +1072,6 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN * compare() method of the given type (or its parent) instead of the * most specific type of provided Eina_Model. * - * Examples: - * @li @ref eina_model_02_example_page contains an easy to follow - * example that demonstrates several of the important features of - * eina_model, uses #EINA_MODEL_TYPE_GENERIC. - * @li @ref eina_model_03_example_page walk-through example on how to - * inherit types, a suggestion of eina_model_load() usage and uses - * #EINA_MODEL_TYPE_STRUCT. - * * @{ */ @@ -2218,7 +1994,7 @@ EAPI Eina_Bool eina_model_interface_constructor(const Eina_Model_Interface *ifac * @param model The model instance. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * @warning If @a model doesn't implement @a iface does nothing and + * @warning If @a model doesn't implement @a iface does nothing and * returns #EINA_FALSE. * * @see eina_model_del() @@ -2819,9 +2595,10 @@ EAPI void eina_model_interface_children_sort(const Eina_Model_Interface *iface, */ /** + * @internal * @defgroup Eina_Model_Utils_Group Data Model Utilities * - * Miscellaneous utilities to help usage or debug of @ref Eina_Model_Group. + * @brief Miscellaneous utilities to help usage or debug of @ref Eina_Model_Group. * * @{ */ @@ -3135,12 +2912,4 @@ EAPI extern const char *EINA_MODEL_INTERFACE_NAME_CHILDREN; /** * @} */ - -/** - * @} - */ - -/** - * @} - */ #endif diff --git a/src/lib/eina/eina_module.h b/src/lib/eina/eina_module.h index 834dfa8d83..6d50284ecc 100644 --- a/src/lib/eina/eina_module.h +++ b/src/lib/eina/eina_module.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -24,318 +24,336 @@ #include "eina_error.h" /** - * @addtogroup Eina_Module_Group Module - * - * @brief These functions provide module management. - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** * @defgroup Eina_Module_Group Module + * @ingroup Eina_Tools_Group + * + * @brief This group of functions provide module management. * * Eina module provides some helpers over POSIX dlopen(). It is not - * meant to replace, abstract or make a "portable" version of the + * meant to replace, abstract, or make a "portable" version of the * POSIX, but enhance its usage by defining some good practices. * * Modules are created with eina_module_new() and later loaded with * eina_module_load(). Loads are reference counted and there must be * the same number of eina_module_unload() in order to have it to call - * dlclose(). This makes simple to have different users for the same + * dlclose(). This makes it simple to have different users for the same * module. * - * The loaded shared objects may have two visible functions that will - * be called and might provide initialization and shutdown + * The loaded shared objects may have two visible functions that are + * called and might provide initialization and shutdown * procedures. The symbols are @c __eina_module_init and - * @c __eina_module_shutdown and will be defined by the macros + * @c __eina_module_shutdown and are defined by the macros * EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN(). * * There are some helpers to automatically create modules based on * directory listing. See eina_module_arch_list_get(), - * eina_module_list_get() and eina_module_find(). + * eina_module_list_get(), and eina_module_find(). * * @{ */ /** * @typedef Eina_Module - * Dynamic module loader handle. + * @brief The structure type for the dynamic module loader handle. */ typedef struct _Eina_Module Eina_Module; /** * @typedef Eina_Module_Cb - * Dynamic module loader callback. + * @brief The dynamic module loader callback. */ typedef Eina_Bool (*Eina_Module_Cb)(Eina_Module *m, void *data); /** * @typedef Eina_Module_Init - * If a function with such signature is exported by module as - * __eina_module_init, it will be called on the first load after - * dlopen() and if #EINA_FALSE is returned, load will fail, #EINA_TRUE - * means the module was successfully initialized. + * @brief If a function with such a signature is exported by the module as + * __eina_module_init, it is called on the first load after + * dlopen() and if @c EINA_FALSE is returned, the load fails, @c EINA_TRUE + * means the module is successfully initialized. * @see Eina_Module_Shutdown */ typedef Eina_Bool (*Eina_Module_Init)(void); /** * @typedef Eina_Module_Shutdown - * If a function with such signature is exported by module as - * __eina_module_shutdown, it will be called before calling dlclose() + * @brief If a function with such a signature is exported by the module as + * __eina_module_shutdown, it is called before calling dlclose() * @see Eina_Module_Init */ typedef void (*Eina_Module_Shutdown)(void); /** * @def EINA_MODULE_INIT - * declares the given function as the module initializer (__eina_module_init). - * It must be of signature #Eina_Module_Init + * @brief Definition that declares the given function as the module initializer (__eina_module_init). + * It must be of signature #Eina_Module_Init */ #define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f /** * @def EINA_MODULE_SHUTDOWN - * declares the given function as the module shutdownializer - * (__eina_module_shutdown). It must be of signature #Eina_Module_Shutdown + * @brief Defintion that declares the given function as the module shutdown initializer (__eina_module_shutdown). + * It must be of signature #Eina_Module_Shutdown */ #define EINA_MODULE_SHUTDOWN(f) EAPI Eina_Module_Shutdown __eina_module_shutdown = &f +/** + * @var EINA_ERROR_WRONG_MODULE + * @brief The error identifier corresponding to a wrong module. + */ extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE; + +/** + * @var EINA_ERROR_MODULE_INIT_FAILED + * @brief The error identifier corresponding to a failure during the initialisation of a module. + */ extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED; /** - * @brief Return a new module. + * @brief Returns a new module. * - * @param file The name of the file module to load. - * @return A new module. If @p file is @c NULL, or if it does not exist, - * the function returns @c NULL, otherwise, it allocates an Eina_Module, - * stores a duplicate string of @p file, sets its reference to @c 0 and - * its handle to @c NULL. + * @since_tizen 2.3 * - * When the new module is not needed anymore, use eina_module_free() - * to free the allocated memory. + * @remarks When the new module is not needed anymore, use eina_module_free() + * to free the allocated memory. + * + * @param[in] file The name of the file module to load + * @return A new module \n + * If @a file is @c NULL, the function returns @c NULL, + * otherwise it allocates an Eina_Module, stores + * a duplicate string of @a file, sets its reference to @c 0 and + * its handle to @c NULL. * * @see eina_module_load */ -EAPI Eina_Module * - eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +EAPI Eina_Module *eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Delete a module. + * @brief Deletes a module. * - * @param module The module to delete. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function calls eina_module_unload() if @a module has been previously + * loaded and frees the allocated memory. On success this function + * returns @c EINA_TRUE, otherwise it returns @c EINA_FALSE. If @a module is @c NULL, the + * function returns immediately. + * + * @since_tizen 2.3 + * + * @param[in] module The module to delete + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * This function calls eina_module_unload() if @p module has been previously - * loaded and frees the allocated memory. On success this function - * returns #EINA_TRUE and #EINA_FALSE otherwise. If @p module is @c NULL, the - * function returns immediately. - */ -EAPI Eina_Bool - eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1); - -/** - * @brief Load a module. - * - * @param module The module to load. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function load the shared file object passed in - * eina_module_new(). If it is a internal Eina module (like the - * mempools), it also initialize it. If the shared file object can not - * be loaded, #EINA_FALSE is returned. If it is an internal Eina module and the - * module can not be initialized, #EINA_FALSE is returned. If the module has - * already been loaded, it's reference counter is increased by one and - * #EINA_TRUE is returned. If @p module is @c NULL, the function returns - * immediately #EINA_FALSE. - * - * When the symbols of the shared file objects are not needed - * anymore, call eina_module_unload() to unload the module. */ -EAPI Eina_Bool - eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1); +EAPI Eina_Bool eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1); /** - * @brief Unload a module. - * - * @param module The module to load. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function unload the module @p module that has been previously - * loaded by eina_module_load(). If the reference counter of @p module is - * strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the - * shared object file is closed and if it is a internal Eina module, it - * is shutted down just before. In that case, #EINA_TRUE is - * returned. In all case, the reference counter is decreased. If @p module - * is @c NULL, the function returns immediately #EINA_FALSE. + * @brief Loads a module. + * + * @details This function loads the shared file object passed in + * eina_module_new(). If it is an internal Eina module (like the + * mempools), it also initializes it. If the shared file object cannot + * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and + * and @c EINA_FALSE is returned. If it is an internal Eina module and the + * module cannot be initialized, the error #EINA_ERROR_MODULE_INIT_FAILED + * is set and @c EINA_FALSE is returned. If the module has already been loaded, + * its reference counter is increased by one and @c EINA_TRUE is returned. + * If @a module is @c NULL, the function returns @c EINA_FALSE immediately. + * + * @since_tizen 2.3 + * + * @remarks When the symbols of the shared file objects are not needed + * anymore, call eina_module_unload() to unload the module. + * + * @param[in] module The module to load + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ -EAPI Eina_Bool - eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1); +EAPI Eina_Bool eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1); /** - * @brief Retrieve the data associated to a symbol. + * @brief Unloads a module. * - * @param module The module. - * @param symbol The symbol. - * @return The data associated to the symbol, or @c NULL on failure. + * @details This function unloads the module @a module that has been previously + * loaded by eina_module_load(). If the reference counter of @a module is + * strictly greater than @c 1, @c EINA_FALSE is returned. Otherwise, the + * shared object file is closed and if it is an internal Eina module, it + * is shut down just before. In that case, @c EINA_TRUE is + * returned. In all cases, the reference counter is decreased. If @a module + * is @c NULL, the function returns @c EINA_FALSE immediately. + * + * @since_tizen 2.3 + * + * @param[in] module The module to unload + * @return @c EINA_TRUE on success, otherwise EINA_FALSE * - * This function returns the data associated to @p symbol of @p module. @p - * module must have been loaded before with eina_module_load(). If @p module - * is @c NULL, or if it has not been correctly loaded before, the - * function returns immediately @c NULL. */ -EAPI void * - eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; +EAPI Eina_Bool eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1); /** - * @brief Return the file name associated to the module. + * @brief Gets the data associated to a symbol. + * + * @details This function returns the data associated to @a symbol of @a module. @a + * module must have been loaded earlier with eina_module_load(). If @a module + * is @c NULL, or if it has not been correctly loaded before, the + * function returns @c NULL immediately. * - * @param module The module. - * @return The file name. + * @since_tizen 2.3 + * + * @param[in] module The module + * @param[in] symbol The symbol + * @return The data associated to the symbol, otherwise @c NULL on failure * - * This function returns the file name passed in eina_module_new(). If - * @p module is @c NULL, the function returns immediately @c NULL. The - * returned value must no be freed. */ -EAPI const char * - eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +EAPI void *eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief Define if on module load we should expose all symbol + * @brief Gets the file name associated to the module. + * + * @details This function returns the file name passed in eina_module_new(). If + * @a module is @c NULL, the function returns @c NULL immediately. The + * returned value must no be freed. + * + * @since_tizen 2.3 + * + * @param[in] module The module + * @return The file name * - * @param module The module to turn off/on symbol to be exposed - * @since 1.11 */ -EAPI void eina_module_symbol_global_set(Eina_Module *module, Eina_Bool global) EINA_ARG_NONNULL(1); +EAPI const char *eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + /** - * @brief Return the path built from the location of a library and a - * given sub directory. - * - * @param symbol The symbol to search for. - * @param sub_dir The subdirectory to append. - * @return The built path on success, @c NULL otherwise. - * - * This function returns the path built by concatenating the path of - * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir - * can be @c NULL. The returned path must be freed when not used - * anymore. If the symbol is not found, or dl_addr() is not supported, - * or allocation fails, this function returns @c NULL. + * @brief Gets the path built from the location of a library and a + * given sub directory. + * + * @details This function returns the path built by concatenating the path of + * the library containing the symbol @a symbol and @a sub_dir. @a sub_dir + * can be @c NULL. The returned path must be freed when not used + * anymore. If the symbol is not found, or dl_addr() is not supported, + * or allocation fails, this function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] symbol The symbol to search for + * @param[in] sub_dir The subdirectory to append + * @return The built path on success, otherwise @c NULL + * */ -EAPI char * - eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); +EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); /** - * @brief Return the path built from the value of an environment variable and a - * given sub directory. - * - * @param env The environment variable to expand. - * @param sub_dir The subdirectory to append. - * @return The built path on success, @c NULL otherwise. - * - * This function returns the path built by concatenating the value of - * the environment variable named @p env and @p sub_dir. @p sub_dir - * can be @c NULL. The returned path must be freed when not used - * anymore. If the symbol is not found, or @p env does not exist, or - * allocation fails, this function returns @c NULL. + * @brief Gets the path built from the value of an environment variable and a + * given sub directory. + * + * @details This function returns the path built by concatenating the value of + * the environment variable named @a env and @a sub_dir. @a sub_dir + * can be @c NULL. The returned path must be freed when not used + * anymore. If the symbol is not found, or @a env does not exist, or + * allocation fails, this function returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] env The environment variable to expand + * @param[in] sub_dir The subdirectory to append + * @return The built path on success, otherwise @c NULL + * */ -EAPI char * - eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); +EAPI char *eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); /** - * @brief Get an array of modules found on the directory path matching an arch type. + * @brief Gets an array of modules found on the directory path matching an arch type. + * + * @details This function adds to @a array the module names found in @a path + * which match the CPU architecture @a arch. If @a path or @a arch is + * @c NULL, the function returns @a array immediately. @a array can be + * @c NULL. In that case, it is created with 4 elements. * - * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules. - * @param arch The architecture string. - * @return The array of modules found in @p path matching @p arch. + * @since_tizen 2.3 + * + * @param[in] array The array that stores the list of the modules + * @param[in] path The directory path to search for modules + * @param[in] arch The architecture string + * @return The array of modules found in @a path matching @a arch * - * This function adds to @p array the module names found in @p path - * which match the cpu architecture @p arch. If @p path or @p arch is - * @c NULL, the function returns immediately @p array. @p array can be - * @c NULL. In that case, it is created with 4 elements. */ -EAPI Eina_Array * - eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch); +EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch); /** - * @brief Get a list of modules found on the directory path. - * - * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules. - * @param recursive Iterate recursively on the path. - * @param cb Callback function to call on each module. - * @param data Data passed to the callback function. - * @return The array of modules found in @p path. - * - * This function adds to @p array the list of modules found in - * @p path. If @p recursive is #EINA_TRUE, then recursive search is - * done. The callback @p cb is called on each module found, and @p data - * is passed to @p cb. If @p path is @c NULL, the function returns - * immediately @p array. If the returned value of @p cb is @c 0, the - * module will not be added to the list, otherwise it will be added. - * @p array can be @c NULL. In that case, it is created with 4 - * elements. @p cb can be @c NULL. + * @brief Gets a list of modules found on the directory path. + * + * @details This function adds to @a array the list of modules found in + * @a path. If @a recursive is @c EINA_TRUE, then recursive search is + * done. The callback @a cb is called on each module found, and @a data + * is passed to @a cb. If @a path is @c NULL, the function returns + * @a array immediately. If the returned value of @a cb is @c 0, the + * module is not added to the list, otherwise it is added. + * @a array can be @c NULL. In that case, it is created with 4 + * elements. @a cb can be @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] array The array that stores the list of the modules + * @param[in] path The directory path to search for modules + * @param[in] recursive The boolean value to iterate recursively on the path + * @param[in] cb The callback function to call on each module + * @param[in] data The data passed to the callback function + * @return The array of modules found in @a path + * */ -EAPI Eina_Array * - eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT; +EAPI Eina_Array *eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Load every module on the list of modules. + * @brief Loads every module on the list of modules. * - * @param array The array of modules to load. + * @details This function calls eina_module_load() on each element found in + * @a array. If @a array is @c NULL, this function does nothing. * - * This function calls eina_module_load() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. - */ -EAPI void - eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1); - -/** - * @brief Unload every module on the list of modules. + * @since_tizen 2.3 * - * @param array The array of modules to unload. + * @param[in] array The array of modules to load * - * This function calls eina_module_unload() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. */ -EAPI void - eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1); +EAPI void eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @p Free every module on the list of modules. + * @brief Unloads every module on the list of modules. + * + * @details This function calls eina_module_unload() on each element found in + * @a array. If @a array is @c NULL, this function does nothing. + * + * @since_tizen 2.3 * - * @param array The array of modules to free. + * @param[in] array The array of modules to unload * - * This function calls eina_module_free() on each element found in - * @p array. If @p array is @c NULL, this function does nothing. */ -EAPI void - eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1); +EAPI void eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @brief Find an module in array. + * @brief Frees every module on the list of modules. * - * @param array The array to find the module. - * @param module The name of module to be searched. - * @return The module to find on success, @c NULL otherwise. + * @details This function calls eina_module_free() on each element found in + * @a array. If @a array is @c NULL, this function does nothing. + * + * @since_tizen 2.3 + * + * @param[in] array The array of modules to free * - * This function finds an @p module in @p array. - * If the element is found the function returns the module, else - * @c NULL is returned. */ -EAPI Eina_Module * - eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2); +EAPI void eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1); /** - * @} + * @brief Finds a module in an array. + * + * @details This function finds a @a module in @a array. + * If the element is found the function returns the module, otherwise + * @c NULL is returned. + * + * @since_tizen 2.3 + * + * @param[in] array The array to find the module in + * @param[in] module The name of the module to be searched + * @return The module to find on success, otherwise @c NULL + * */ +EAPI Eina_Module *eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2); /** * @} diff --git a/src/lib/eina/eina_quadtree.h b/src/lib/eina/eina_quadtree.h index 2638d8ba59..28817404bc 100644 --- a/src/lib/eina/eina_quadtree.h +++ b/src/lib/eina/eina_quadtree.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2010 Cedric BAIL * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public diff --git a/src/lib/eina/eina_rbtree.h b/src/lib/eina/eina_rbtree.h index 6a4d764299..e37d1f06b5 100644 --- a/src/lib/eina/eina_rbtree.h +++ b/src/lib/eina/eina_rbtree.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -26,38 +26,23 @@ #include "eina_iterator.h" /** - * @addtogroup Eina_Rbtree_Group Red-Black tree + * @defgroup Eina_Rbtree_Group Red-Black tree + * @ingroup Eina_Containers_Group * - * @brief These functions provide Red-Black trees management. + * @brief This group discusses the functions that provide Red-Black trees management. * * For a brief description look at http://en.wikipedia.org/wiki/Red-black_tree . * This code is largely inspired from a tutorial written by Julienne Walker at : * http://eternallyconfuzzled.com/tuts/datastructures/jsw_tut_rbtree.aspx . The - * main difference is that this set of function never allocate any data, making + * main difference is that this set of functions never allocate any data, making * them particularly useful for memory management. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** - * @defgroup Eina_Rbtree_Group Red-Black tree * * @{ */ /** * @typedef Eina_Rbtree_Color - * node color. + * @brief Enumeration of the node color. */ typedef enum { EINA_RBTREE_RED, @@ -66,7 +51,7 @@ typedef enum { /** * @typedef Eina_Rbtree_Direction - * walk direction. + * @brief Enumeration of the walk direction. */ typedef enum { EINA_RBTREE_LEFT = 0, @@ -75,19 +60,19 @@ typedef enum { /** * @typedef Eina_Rbtree - * Type for a Red-Black tree node. It should be inlined into user's type. + * @brief The structure type for a Red-Black tree node. It should be inlined into the user type. */ typedef struct _Eina_Rbtree Eina_Rbtree; struct _Eina_Rbtree { Eina_Rbtree *son[2]; - unsigned int color : 1; + Eina_Rbtree_Color color : 1; }; /** * @def EINA_RBTREE - * recommended way to declare the inlined Eina_Rbtree in your type. + * @brief Definition of the recommended way to declare the inlined Eina_Rbtree for your type. * * @code * struct my_type { @@ -103,87 +88,101 @@ struct _Eina_Rbtree /** * @def EINA_RBTREE_GET - * access the inlined node if it was created with #EINA_RBTREE. + * + * @since_tizen 2.3 + * + * @brief Definition to access the inlined node if it is created with #EINA_RBTREE. */ #define EINA_RBTREE_GET(Rbtree) (&((Rbtree)->__rbtree)) /** * @def EINA_RBTREE_CONTAINER_GET - * find back the container of an red black tree. + * + * @since_tizen 2.3 + * + * @brief Definition to find back the container of a red black tree. */ #define EINA_RBTREE_CONTAINER_GET(Ptr, Type) ((Type *)((char *)Ptr - offsetof(Type, __rbtree))) /** * @typedef Eina_Rbtree_Cmp_Node_Cb - * Function used compare two nodes and see which direction to navigate. + * @brief Compares two nodes and decides which direction to navigate. */ typedef Eina_Rbtree_Direction (*Eina_Rbtree_Cmp_Node_Cb)(const Eina_Rbtree *left, const Eina_Rbtree *right, void *data); /** * @def EINA_RBTREE_CMP_NODE_CB - * Cast using #Eina_Rbtree_Cmp_Node_Cb + * @brief Definition of the cast using #Eina_Rbtree_Cmp_Node_Cb. */ #define EINA_RBTREE_CMP_NODE_CB(Function) ((Eina_Rbtree_Cmp_Node_Cb)Function) /** * @typedef Eina_Rbtree_Cmp_Key_Cb - * Function used compare node with a given key of specified length. + * @brief Compares a node with the given key of the specified length. */ typedef int (*Eina_Rbtree_Cmp_Key_Cb)(const Eina_Rbtree *node, const void *key, int length, void *data); /** * @def EINA_RBTREE_CMP_KEY_CB - * Cast using #Eina_Rbtree_Cmp_Key_Cb + * @brief Definition of the cast using #Eina_Rbtree_Cmp_Key_Cb. */ #define EINA_RBTREE_CMP_KEY_CB(Function) ((Eina_Rbtree_Cmp_Key_Cb)Function) /** * @typedef Eina_Rbtree_Free_Cb - * Function used free a node. + * @brief Called to free a node. */ typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data); /** * @def EINA_RBTREE_FREE_CB - * Cast using #Eina_Rbtree_Free_Cb + * @brief Definition of the cast using #Eina_Rbtree_Free_Cb. */ #define EINA_RBTREE_FREE_CB(Function) ((Eina_Rbtree_Free_Cb)Function) /** - * @brief Insert a new node inside an existing red black tree. + * @brief Inserts a new node inside an existing red black tree. * - * @param root The root of an exisiting valid red black tree. - * @param node The new node to insert. - * @param cmp The callback that is able to compare two nodes. - * @param data Private data to help the compare function. - * @return The new root of the red black tree. + * @details This function inserts a new node into a valid red black tree. @c NULL is + * an empty valid red black tree. The resulting new tree is a valid red + * black tree. This function doesn't allocate any data. + * + * @since_tizen 2.3 + * + * @param[in] root The root of an existing valid red black tree + * @param[in] node The new node to insert + * @param[in] cmp The callback that is able to compare two nodes + * @param[in] data The private data to help the compare function + * @return The new root of the red black tree * - * This function insert a new node in a valid red black tree. @c NULL is - * an empty valid red black tree. The resulting new tree is a valid red - * black tree. This function doesn't allocate any data. */ EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; /** - * @brief Remove a node from an existing red black tree. + * @brief Removes a node from an existing red black tree. + * + * @details This function removes a new node from a valid red black tree that should + * contain the node that you are removing. This function returns @c NULL + * when the red black tree becomes empty. This function doesn't free any data. * - * @param root The root of a valid red black tree. - * @param node The node to remove from the tree. - * @param cmp The callback that is able to compare two nodes. - * @param data Private data to help the compare function. - * @return The new root of the red black tree. + * @since_tizen 2.3 + * + * @param[in] root The root of a valid red black tree + * @param[in] node The node to remove from the tree + * @param[in] cmp The callback that is able to compare two nodes + * @param[in] data The private data to help the compare function + * @return The new root of the red black tree * - * This function remove a new node in a valid red black tree that should - * contain the node that you are removing. This function will return @c NULL - * when the red black tree got empty. This function doesn't free any data. */ EAPI Eina_Rbtree *eina_rbtree_inline_remove(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; /** - * @brief Delete all nodes from a valid red black tree. + * @brief Deletes all the nodes from a valid red black tree. + * + * @since_tizen 2.3 * - * @param root The root of a valid red black tree. - * @param func The callback that will free each node. - * @param data Private data to help the compare function. + * @param[in] root The root of a valid red black tree + * @param[in] func The callback that frees each node + * @param[in] data The private data to help the compare function * */ EAPI void eina_rbtree_delete(Eina_Rbtree *root, Eina_Rbtree_Free_Cb func, void *data) EINA_ARG_NONNULL(2); @@ -192,62 +191,74 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co /** - * @brief Returned a new prefix iterator associated to a rbtree. + * @brief Returns a new prefix iterator associated to an rbtree. * - * @param root The root of rbtree. - * @return A new iterator. + * @details This function returns a newly allocated iterator associated to + * @a root. It iterates the tree using prefix walk. If @a root is + * @c NULL, this function still returns a valid iterator that always + * returns @c false on eina_iterator_next(), thus keeping the API sane. * - * This function returns a newly allocated iterator associated to @p - * root. It will iterate the tree using prefix walk. If @p root is @c - * NULL, this function still returns a valid iterator that will always - * return false on eina_iterator_next(), thus keeping API sane. + * @since_tizen 2.3 * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. + * + * @remarks If the rbtree structure changes then the iterator becomes + * invalid. That is, if you add or remove nodes this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] root The root of the rbtree + * @return A new iterator * - * @warning if the rbtree structure changes then the iterator becomes - * invalid! That is, if you add or remove nodes this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new prefix iterator associated to a rbtree. + * @brief Returns a new prefix iterator associated to an rbtree. + * + * @details This function returns a newly allocated iterator associated to + * @a root. It iterates the tree using infix walk. If @a root is + * @c NULL, this function still returns a valid iterator that always + * returns @c false on eina_iterator_next(), thus keeping the API sane. * - * @param root The root of rbtree. - * @return A new iterator. + * @since_tizen 2.3 * - * This function returns a newly allocated iterator associated to @p - * root. It will iterate the tree using infix walk. If @p root is @c - * NULL, this function still returns a valid iterator that will always - * return false on eina_iterator_next(), thus keeping API sane. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the rbtree structure changes then the iterator becomes + * invalid. That is, if you add or remove nodes this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] root The root of the rbtree + * @return A new iterator * - * @warning if the rbtree structure changes then the iterator becomes - * invalid! That is, if you add or remove nodes this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new prefix iterator associated to a rbtree. + * @brief Returns a new prefix iterator associated to an rbtree. + * + * @details This function returns a newly allocated iterator associated to + * @a root. It iterates the tree using postfix walk. If @a root is + * @c NULL, this function still returns a valid iterator that always + * returns @c false on eina_iterator_next(), thus keeping the API sane. * - * @param root The root of rbtree. - * @return A new iterator. + * @since_tizen 2.3 * - * This function returns a newly allocated iterator associated to @p - * root. It will iterate the tree using postfix walk. If @p root is @c - * NULL, this function still returns a valid iterator that will always - * return false on eina_iterator_next(), thus keeping API sane. + * @remarks If the memory cannot be allocated, @c NULL is returned + * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * @remarks If the rbtree structure changes then the iterator becomes + * invalid. That is, if you add or remove nodes this iterator's + * behavior is undefined and your program may crash. + * + * @param[in] root The root of the rbtree + * @return A new iterator * - * @warning if the rbtree structure changes then the iterator becomes - * invalid! That is, if you add or remove nodes this iterator - * behavior is undefined and your program may crash! */ EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT; @@ -257,12 +268,4 @@ EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root) * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_rectangle.h b/src/lib/eina/eina_rectangle.h index 55d370ff25..e7675128df 100644 --- a/src/lib/eina/eina_rectangle.h +++ b/src/lib/eina/eina_rectangle.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -22,490 +22,417 @@ #include "eina_types.h" /** - * @addtogroup Eina_Rectangle_Group Rectangle - * - * @brief These functions provide rectangle management. - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** * @defgroup Eina_Rectangle_Group Rectangle + * @ingroup Eina_Tools_Group + * + * @brief This group discusses the functions that provide rectangle management. * * @{ */ -#define EINA_RECTANGLE_INIT { 0, 0, 0, 0} -#define EINA_RECTANGLE_FORMAT "dx%d - %dx%d" -#define EINA_RECTANGLE_ARGS(r) (r)->x, (r)->y, (r)->w, (r)->h - /** * @typedef Eina_Rectangle - * Simple rectangle structure. + * @brief The structure type for the simple rectangle structure. */ typedef struct _Eina_Rectangle { - int x; /**< top-left x co-ordinate of rectangle */ - int y; /**< top-left y co-ordinate of rectangle */ - int w; /**< width of rectangle */ - int h; /**< height of rectangle */ + int x; /**< The top-left x co-ordinate of the rectangle */ + int y; /**< The top-left y co-ordinate of the rectangle */ + int w; /**< The width of the rectangle */ + int h; /**< The height of the rectangle */ } Eina_Rectangle; /** * @typedef Eina_Rectangle_Pool - * Type for an opaque pool of rectangle. + * @brief The structure type for an opaque rectangle pool. */ typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool; /** - * @typedef Eina_Rectangle_Pool_Type - * Type for an Eina Pool based on packing algorithm. - * @since 1.11 + * @typedef Eina_Rectangle_Packing + * @brief Enumeration of the type for an Eina Pool based on the packing algorithm. + * @since 1.10 */ typedef enum { Eina_Packing_Descending, /**< Current */ - Eina_Packing_Ascending, /**< sorting in assending order */ - Eina_Packing_Bottom_Left, /**< sorting in bottemleft fasion */ - Eina_Packing_Bottom_Left_Skyline, /**< bottemleft skyline */ - Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */ + Eina_Packing_Ascending, /**< Sorting in ascending order */ + Eina_Packing_Bottom_Left, /**< Sorting in bottom left fashion */ + Eina_Packing_Bottom_Left_Skyline, /**< Bottom left skyline */ + Eina_Packing_Bottom_Left_Skyline_improved /**< Optimized bottom left skyline */ } Eina_Rectangle_Packing; /** * @brief Check if the given spans intersect. * - * @param c1 The column of the first span. - * @param l1 The length of the first span. - * @param c2 The column of the second span. - * @param l2 The length of the second span. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if the given spans intersect, + * #EINA_FALSE otherwise. * - * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE - * otherwise. + * @since_tizen 2.3 + * + * @param[in] c1 The column of the first span. + * @param[in] l1 The length of the first span. + * @param[in] c2 The column of the second span. + * @param[in] l2 The length of the second span. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT; /** * @brief Check if the given rectangle is empty. * - * @param r The rectangle to check. - * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE + * otherwise. No check is done on @p r, so it must be a valid + * rectangle. + * + * @since_tizen 2.3 * - * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE - * otherwise. No check is done on @p r, so it must be a valid - * rectangle. + * @param[in] r The rectangle to check. + * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Set the coordinates and size of the given rectangle. * - * @param r The rectangle. - * @param x The top-left x coordinate of the rectangle. - * @param y The top-left y coordinate of the rectangle. - * @param w The width of the rectangle. - * @param h The height of the rectangle. + * @details This function sets its top-left x coordinate to @p x, its top-left + * y coordinate to @p y, its width to @p w and its height to @p h. No + * check is done on @p r, so it must be a valid rectangle. + * + * @since_tizen 2.3 * - * This function sets its top-left x coordinate to @p x, its top-left - * y coordinate to @p y, its width to @p w and its height to @p h. No - * check is done on @p r, so it must be a valid rectangle. + * @param[in] r The rectangle. + * @param[in] x The top-left x coordinate of the rectangle. + * @param[in] y The top-left y coordinate of the rectangle. + * @param[in] w The width of the rectangle. + * @param[in] h The height of the rectangle. */ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1); /** * @brief Check if the given rectangles intersect. * - * @param r1 The first rectangle. - * @param r2 The second rectangle. - * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE + * otherwise. No check is done on @p r1 and @p r2, so they must be valid + * rectangles. * - * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE - * otherwise. No check is done on @p r1 and @p r2, so they must be valid - * rectangles. + * @since_tizen 2.3 + * + * @param[in] r1 The first rectangle. + * @param[in] r2 The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** * @brief Check if the given x-coordinate is in the rectangle . * - * @param r The rectangle. - * @param x The x coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if @p x is in @p r with respect to + * the horizontal direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. * - * This function returns #EINA_TRUE if @p x is in @p r with respect to - * the horizontal direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. + * @since_tizen 2.3 + * + * @param[in] r The rectangle. + * @param[in] x The x coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Check if the given y-coordinate is in the rectangle . * - * @param r The rectangle. - * @param y The y coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if @p y is in @p r with respect to + * the vertical direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. * - * This function returns #EINA_TRUE if @p y is in @p r with respect to - * the vertical direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. + * @since_tizen 2.3 + * + * @param[in] r The rectangle. + * @param[in] y The y coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Check if the given point is in the rectangle . * - * @param r The rectangle. - * @param x The x coordinate of the point. - * @param y The y coordinate of the point. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function returns #EINA_TRUE if the point of coordinate (@p x, + * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, + * so it must be a valid rectangle. + * + * @since_tizen 2.3 * - * This function returns #EINA_TRUE if the point of coordinate (@p x, - * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, - * so it must be a valid rectangle. + * @param[in] r The rectangle. + * @param[in] x The x coordinate of the point. + * @param[in] y The y coordinate of the point. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. */ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Get the union of two rectangles. * - * @param dst The first rectangle. - * @param src The second rectangle. + * @details This function get the union of the rectangles @p dst and @p src. The + * result is stored in @p dst. No check is done on @p dst or @p src, + * so they must be valid rectangles. + * + * @since_tizen 2.3 * - * This function get the union of the rectangles @p dst and @p src. The - * result is stored in @p dst. No check is done on @p dst or @p src, - * so they must be valid rectangles. + * @param[in] dst The first rectangle. + * @param[in] src The second rectangle. */ static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2); /** * @brief Get the intersection of two rectangles. * - * @param dst The first rectangle. - * @param src The second rectangle. + * @details This function get the intersection of the rectangles @p dst and + * @p src. The result is stored in @p dst. No check is done on @p dst + * or @p src, so they must be valid rectangles. + * + * @since_tizen 2.3 + * + * @param[in] dst The first rectangle. + * @param[in] src The second rectangle. * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE * otherwise. - * - * This function get the intersection of the rectangles @p dst and - * @p src. The result is stored in @p dst. No check is done on @p dst - * or @p src, so they must be valid rectangles. */ static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief FIXME I am useless and used by no one + * @brief Rescale a rectangle inner position. + * + * @details This function rescales a rectangle by using @p out and @p in. * - * @param in The inner rectangle. - * @param out The outer rectangle. - * @param res The resulting rectangle. + * @since_tizen 2.3 * + * @param[in] out The outter rectangle. + * @param[in] in The inner rectangle. + * @param[in] res The rectangle to be rescaled */ static inline void eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief FIXME I am useless and used by no one + * @brief Rescale a rectangle outter position. * - * @param in The inner rectangle. - * @param out The outer rectangle. - * @param res The resulting rectangle. + * @details This function rescales a rectangle by using @p out and @p in. * + * @since_tizen 2.3 + * + * @param[in] out The outter rectangle. + * @param[in] in The inner rectangle. + * @param[in] res The rectangle to be rescaled */ static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); -/** - * - * @brief Tells whether a rectangle is valid or not. - * - * @param r The rectangle - * @return #EINA_TRUE if the rectangle is valid, #EINA_FALSE otherwise. - * - * This function checks if both width and height attributes of the rectangle are - * positive integers. If so, the rectangle is considered valid, else the - * rectangle is invalid. - */ -static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1); /** + * @brief Adds a rectangle in a new pool. * - * @brief Gives the rectangle maximum x coordinate. - * - * @param thiz The rectangle - * @return the maximum x coordinate - * - * This function calculates the maximum x coordinate of the rectangle by summing - * the @p width with the current @p x coodinate of the rectangle. - */ -static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); - -/** + * @details This function adds the rectangle of size (@a width, @a height) to a + * new pool. If the pool cannot be created, @c NULL is + * returned. Otherwise the newly allocated pool is returned. * - * @brief Gives the rectangle maximum y coordinate. + * @since_tizen 2.3 * - * @param thiz The rectangle - * @return the maximum y coordinate + * @param[in] w The width of the rectangle + * @param[in] h The height of the rectangle + * @return A newly allocated pool on success, otherwise @c NULL * - * This function calculates the maximum y coordinate of the rectangle by summing - * the @p height with the current @p y coodinate of the rectangle. */ -static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); +EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** + * @brief Gets the pool of the given rectangle. * - * @brief Slices a rectangle vertically into two subrectangles starting from left edge + * @details This function returns the pool in which @a rect is present. If @a rect is + * @c NULL, @c NULL is returned. * - * @param thiz The rectangle to slice - * @param slice The sliced part of the rectangle - * @param remainder The left over part of the original rectangle after slice - * @param amount The x inner coordinate of the rectangle where to perform the - * slicing. - * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * @since_tizen 2.3 * - * Use this function if we must cut a rectangle vertically. The @p amount - * parameter defines the x inner coordinate where to do the cut, starting from - * the left edge of the rectangle. If the @p amount value is greater than the - * rectangle width, there will be not cut possible and #EINA_FALSE will be - * returned. - */ -static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); - -/** + * @param[in] rect The rectangle + * @return The pool of the given rectangle * - * @brief Slices a rectangle horizontally into two subrectangles starting from bottom edge - * - * @param thiz The rectangle to slice - * @param slice The sliced part of the rectangle - * @param remainder The left over part of the original rectangle after slice - * @param amount The y inner coordinate of the rectangle where to perform the - * slicing. - * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise - * - * Use this function if we must cut a rectangle horizontally. The @p amount - * parameter defines the y inner coordinate where to do the cut, starting from - * the bottom edge of the rectangle. If the @p amount value is greater than the - * rectangle width, there will be not cut possible and #EINA_FALSE will be - * returned. */ -static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); +EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** + * @brief Gets the width and height of the given pool. + * + * @details This function returns the width and height of @a pool and stores + * them in @a w and @a h respectively if they are not @c NULL. If + * @a pool is @c NULL, @c EINA_FALSE is returned. Otherwise @c EINA_TRUE is + * returned. * - * @brief Slices a rectangle vertically starting from right edge + * @since_tizen 2.3 * - * @param thiz The rectangle to slice - * @param slice The sliced part of the rectangle - * @param remainder The left over part of the original rectangle after slice - * @param amount The amount to cut off the rectangle starting from the right - * edge - * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * @param[in] pool The pool + * @param[out] w The returned width + * @param[out] h The returned height + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * Use this function if we must cut a rectangle vertically. The @p amount - * parameter defines the inner x coordinate where to do the cut, starting from - * the right edge of the rectangle. If the @p amount value is greater than the - * rectangle width, there will be not cut possible and #EINA_FALSE will be - * returned. */ -static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); +EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** + * @brief Gets the data from the given pool. + * + * @details This function gets the data from @a pool set by + * eina_rectangle_pool_data_set(). If @a pool is @c NULL, this + * function returns @c NULL. * - * @brief Slices a rectangle horizontally starting from top edge + * @since_tizen 2.3 * - * @param thiz The rectangle to slice - * @param slice The sliced part of the rectangle - * @param remainder The left over part of the original rectangle after slice - * @param amount The amount to cut off the rectangle starting from the top edge - * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * @param[in] pool The pool + * @return The returned data * - * Use this function if we must cut a rectangle horizontally. The @p amount - * parameter defines the inner y coordinate where to do the cut, starting from - * the top edge of the rectangle. If the @p amount value is greater than the - * rectangle width, there will be not cut possible and #EINA_FALSE will be - * returned. */ -static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); +EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Subtract two rectangles. + * @brief Sets the data to the given pool. * - * @param thiz The minuend rectangle - * @param other The subtrahend rectangle + * @details This function sets @a data to @a pool. If @a pool is @c NULL, this + * function does nothing. * - * This function subtract two rectangles. The difference is stored on @p out - * There will be at most four differences, use eina_rectangle_is_valid to - * confirm the number of differences. - */ -static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); - -/** - * @brief Add a rectangle in a new pool. + * @since_tizen 2.3 * - * @param w The width of the rectangle. - * @param h The height of the rectangle. - * @return A newly allocated pool on success, @c NULL otherwise. + * @param[in] pool The pool + * @param[in] data The data to set * - * This function adds the rectangle of size (@p width, @p height) to a - * new pool. If the pool can not be created, @c NULL is - * returned. Otherwise the newly allocated pool is returned. */ -EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT; +EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1); /** - * @brief Return the pool of the given rectangle. + * @brief Frees the given pool. * - * @param rect The rectangle. - * @return The pool of the given rectangle. + * @details This function frees the allocated data of @a pool. If @a pool is + * @c NULL, this function returns immediately. * - * This function returns the pool in which @p rect is. If @p rect is - * @c NULL, @c NULL is returned. - */ -EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - -/** - * @brief Return the width and height of the given pool. + * @since_tizen 2.3 * - * @param pool The pool. - * @param w The returned width. - * @param h The returned height. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @param[in] pool The pool to free * - * This function returns the width and height of @p pool and store - * them in respectively @p w and @p h if they are not @c NULL. If - * @p pool is @c NULL, #EINA_FALSE is returned. Otherwise #EINA_TRUE is - * returned. */ -EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; +EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1); /** - * @brief Get the data from the given pool. + * @brief Returns the number of rectangles in the given pool. * - * @param pool The pool. - * @return The returned data. + * @details This function returns the number of rectangles in @a pool. * - * This function gets the data from @p pool set by - * eina_rectangle_pool_data_set(). If @p pool is @c NULL, this - * function returns @c NULL. - */ -EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); - -/** - * @brief Set the data to the given pool. + * @since_tizen 2.3 * - * @param pool The pool. - * @param data The data to set. + * @param[in] pool The pool + * @return The number of rectangles in the pool * - * This function sets @p data to @p pool. If @p pool is @c NULL, this - * function does nothing. */ -EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1); +EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Free the given pool. + * @brief Requests for a rectangle of the given size in the given pool. * - * @param pool The pool to free. + * @details This function retrieves from @a pool the rectangle of width @a w and + * height @a h. If @a pool is @c NULL, or @a w or @a h are non-positive, + * the function returns @c NULL. If @a w or @a h are greater than the + * pool size, the function returns @c NULL. On success, the function + * returns the rectangle that matches the size (@a w, @a h). + * Otherwise it returns @c NULL. * - * This function frees the allocated data of @p pool. If @p pool is - * @c NULL, this function returned immediately. - */ -EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1); - -/** - * @brief Return the number of rectangles in the given pool. + * @since_tizen 2.3 * - * @param pool The pool. - * @return The number of rectangles in the pool. + * @param[in] pool The pool + * @param[in] w The width of the rectangle to request for + * @param[in] h The height of the rectangle to request for + * @return The requested rectangle on success, otherwise @c NULL * - * This function returns the number of rectangles in @p pool. - */ -EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; - -/** - * @brief Request a rectangle of given size in the given pool. - * - * @param pool The pool. - * @param w The width of the rectangle to request. - * @param h The height of the rectangle to request. - * @return The requested rectangle on success, @c NULL otherwise. - * - * This function retrieve from @p pool the rectangle of width @p w and - * height @p h. If @p pool is @c NULL, or @p w or @p h are non-positive, - * the function returns @c NULL. If @p w or @p h are greater than the - * pool size, the function returns @c NULL. On success, the function - * returns the rectangle which matches the size (@p w, @p h). - * Otherwise it returns @c NULL. */ EAPI Eina_Rectangle *eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Remove the given rectangle from the pool. + * @brief Removes the given rectangle from the pool. + * + * @details This function removes @a rect from the pool. If @a rect is + * @c NULL, the function returns immediately. Otherwise it removes + * @a rect from the pool. + * + * @since_tizen 2.3 * - * @param rect The rectangle to remove from the pool. + * @param[in] rect The rectangle to remove from the pool * - * This function removes @p rect from the pool. If @p rect is - * @c NULL, the function returns immediately. Otherwise it removes @p - * rect from the pool. */ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA_ARG_NONNULL(1); /** * @def EINA_RECTANGLE_SET - * @brief Macro to set the values of a #Eina_Rectangle. + * @brief Provides a macro to set the values of a #Eina_Rectangle. * - * @param Rectangle The rectangle to set the values. - * @param X The X coordinate of the top left corner of the rectangle. - * @param Y The Y coordinate of the top left corner of the rectangle. - * @param W The width of the rectangle. - * @param H The height of the rectangle. + * @details This macro sets the values of @a Rectangle. (@a X, @a Y) are the + * coordinates of the top left corner of @a Rectangle, @a W is its + * width and @a H is its height. + * + * @since_tizen 2.3 + * + * @param Rectangle The rectangle to set the values of + * @param X The X coordinate of the top left corner of the rectangle + * @param Y The Y coordinate of the top left corner of the rectangle + * @param W The width of the rectangle + * @param H The height of the rectangle * - * This macro set the values of @p Rectangle. (@p X, @p Y) is the - * coordinates of the top left corner of @p Rectangle, @p W is its - * width and @p H is its height. */ #define EINA_RECTANGLE_SET(Rectangle, X, Y, W, H) \ - { \ - (Rectangle)->x = X; \ - (Rectangle)->y = Y; \ - (Rectangle)->w = W; \ - (Rectangle)->h = H; \ - } + (Rectangle)->x = X; \ + (Rectangle)->y = Y; \ + (Rectangle)->w = W; \ + (Rectangle)->h = H; /** - * @brief Create a new rectangle. - * - * @param x The X coordinate of the top left corner of the rectangle. - * @param y The Y coordinate of the top left corner of the rectangle. - * @param w The width of the rectangle. - * @param h The height of the rectangle. - * @return The new rectangle on success, @ NULL otherwise. - * - * This function creates a rectangle which top left corner has the - * coordinates (@p x, @p y), with height @p w and height @p h and adds - * it to the rectangles pool. No check is done on @p w and @p h. This - * function returns a new rectangle on success, @c NULL otherwhise. + * @brief Creates a new rectangle. + * + * @details This function creates a rectangle whose top left corner has the + * coordinates (@a x, @a y), with width @a w and height @a h and adds + * it to the rectangle's pool. No check is done on @a w and @a h. This + * function returns a new rectangle on success, otherwise it returns @c NULL. + * + * @since_tizen 2.3 + * + * @param[in] x The X coordinate of the top left corner of the rectangle + * @param[in] y The Y coordinate of the top left corner of the rectangle + * @param[in] w The width of the rectangle + * @param[in] h The height of the rectangle + * @return The new rectangle on success, otherwise @c NULL + * */ EAPI Eina_Rectangle *eina_rectangle_new(int x, int y, int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free the given rectangle. + * @brief Frees the given rectangle. * - * @param rect The rectangle to free. + * @details This function removes @a rect from the rectangles pool. + * + * @since_tizen 2.3 + * + * @param[in] rect The rectangle to free * - * This function removes @p rect from the rectangles pool. */ EAPI void eina_rectangle_free(Eina_Rectangle *rect) EINA_ARG_NONNULL(1); /** - * @brief Sets the type of given rectangle pool. + * @brief Sets the type of the given rectangle pool. + * + * @details This function sets @a type of @a pool. * - * @param pool The rectangle pool for which type is to be set. + * @since 1.10 + * + * @since_tizen 2.3 + * + * @param[in] pool The rectangle pool type to set + * @param[in] type The packing type to set * - * This function sets @p type of @p pool. * @see Eina_Rectangle_Packing - * @since 1.11 */ -EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool,Eina_Rectangle_Packing type) EINA_ARG_NONNULL(1); +EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool, Eina_Rectangle_Packing type) EINA_ARG_NONNULL(1); #include "eina_inline_rectangle.x" @@ -513,8 +440,4 @@ EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool,E * @} */ -/** - * @} - */ - #endif /*_EINA_RECTANGLE_H_*/ diff --git a/src/lib/eina/eina_refcount.h b/src/lib/eina/eina_refcount.h index 6650b01680..775ed2327b 100644 --- a/src/lib/eina/eina_refcount.h +++ b/src/lib/eina/eina_refcount.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 20011 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -20,57 +20,45 @@ #define EINA_REFCOUNT_H_ /** - * @addtogroup Eina_Refcount References counting + * @internal + * @defgroup Eina_Refcount References counting + * @ingroup Eina_Data_Types_Group * - * @brief Small macro that simplify references counting. + * @brief This group discusses the functions of the small macro that simplifies references counting. * * References counting is not a difficult task, but you must - * handle it correctly every where, and that the issue. This - * set of macro do provide helper that will force to use the - * correct code in most case and reduce the bug likeliness. - * Of course this without affecting speed ! - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Refcount References counting + * handle it correctly every where, and that is the issue. This + * set of macros do provide a helper that forces to use the + * correct code in most cases and reduces the likeliness of a bug. + * Of course, this is achieved without affecting the speed. * * @{ */ /** * @typedef Eina_Refcount - * Inlined references counting type. + * @brief The integer type containing inlined references counting type. */ typedef int Eina_Refcount; -/** Used for declaring a reference counting member in a struct */ +/** The definition used for declaring a reference counting member in a struct */ #define EINA_REFCOUNT Eina_Refcount __refcount -/** Used just after allocating a object */ +/** The definition used just after allocating an object */ #define EINA_REFCOUNT_INIT(Variable) (Variable)->__refcount = 1 -/** Used when using referring to an object one more time */ +/** The definition used when referring to an object one more time */ #define EINA_REFCOUNT_REF(Variable) (Variable)->__refcount++ -/** Used when removing a reference to an object. The code just after will automatically be called when necessary */ +/** The definition used when removing a reference to an object. The code just after this is automatically called when necessary */ #define EINA_REFCOUNT_UNREF(Variable) \ if (--((Variable)->__refcount) == 0) -/** Get refcounting value */ +/** The definition to get the reference counting value */ #define EINA_REFCOUNT_GET(Variable) (Variable)->__refcount /** * @} */ -/** - * @} - */ - #endif /* EINA_REFCOUNT_H_ */ diff --git a/src/lib/eina/eina_safety_checks.h b/src/lib/eina/eina_safety_checks.h index d9c22d9ea0..356007c983 100644 --- a/src/lib/eina/eina_safety_checks.h +++ b/src/lib/eina/eina_safety_checks.h @@ -20,13 +20,9 @@ #define EINA_SAFETY_CHECKS_H_ /** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** + * @internal * @defgroup Eina_Safety_Checks_Group Safety Checks + * @ingroup Eina_Tools_Group * * @warning @c eina_safety_checks.h should only be included by source * files, after all other includes and before the source file @@ -50,6 +46,7 @@ * // all these files will emit warning from EINA_ARG_NONNULL() * #include <Evas.h> // third party headers * #include <Ecore.h> + * #include <eina_error.h> // eina own header * * #include <eina_safety_checks.h> * // all these files below will NOT emit warning from EINA_ARG_NONNULL(), @@ -59,10 +56,6 @@ * #include "my_functions2.h" * * @endcode - */ - -/** - * @addtogroup Eina_Safety_Checks_Group Safety Checks * * Safety checks are a set of macros to check for parameters or values * that should never happen, it is similar in concept to assert(), but @@ -76,8 +69,9 @@ * options to @c configure script. * * Whenever these macros capture an error, EINA_LOG_ERR() will be - * called. - * + * called and @c eina_error set to @c EINA_ERROR_SAFETY_FAILED and can + * be checked with eina_error_get() after call. + * * @see EINA_SAFETY_ON_NULL_RETURN(), EINA_SAFETY_ON_NULL_RETURN_VAL() * and other macros. * @@ -87,6 +81,10 @@ #include "eina_config.h" #include "eina_error.h" +/** + * @var EINA_ERROR_SAFETY_FAILED + * Error identifier corresponding to safety check failure. + */ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; #ifdef EINA_SAFETY_CHECKS @@ -98,6 +96,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY((exp) == NULL)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \ return; \ } \ @@ -109,6 +108,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY((exp) == NULL)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \ return (val); \ } \ @@ -120,6 +120,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY((exp) == NULL)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \ goto label; \ } \ @@ -131,6 +132,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(exp)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \ return; \ } \ @@ -142,6 +144,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(exp)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \ return val; \ } \ @@ -153,6 +156,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(exp)) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \ goto label; \ } \ @@ -164,6 +168,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(!(exp))) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \ return; \ } \ @@ -175,6 +180,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(!(exp))) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \ return val; \ } \ @@ -186,6 +192,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; { \ if (EINA_UNLIKELY(!(exp))) \ { \ + eina_error_set(EINA_ERROR_SAFETY_FAILED); \ EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \ goto label; \ } \ @@ -276,7 +283,3 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED; /** * @} */ - -/** - * @} - */ diff --git a/src/lib/eina/eina_sched.h b/src/lib/eina/eina_sched.h index 13f35a4476..6832cef8cd 100644 --- a/src/lib/eina/eina_sched.h +++ b/src/lib/eina/eina_sched.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2010 ProFUSION embedded systems * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -17,8 +17,9 @@ */ /** + * @internal * @defgroup Schedule Schedule - * @ingroup Eina_Tools_Group + * @ingroup Eina_Core_Group * * @{ * @@ -43,6 +44,9 @@ * set the nice level on the current thread. In Linux, it does work and it's the * only one that is implemented as of now. In this case, the nice level is * incremented on this thread by @c NICENESS. + * + * @since_tizen 2.3 + * */ EAPI void eina_sched_prio_drop(void); diff --git a/src/lib/eina/eina_simple_xml_parser.h b/src/lib/eina/eina_simple_xml_parser.h index 8f83c1e01a..bd3730b38c 100644 --- a/src/lib/eina/eina_simple_xml_parser.h +++ b/src/lib/eina/eina_simple_xml_parser.h @@ -2,14 +2,14 @@ * Copyright (C) 2011 Gustavo Sverzut Barbieri * Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -27,115 +27,29 @@ #include "eina_inlist.h" /** - * @page eina_simple_xml_parser_example_01_page - * @dontinclude eina_simple_xml_parser_01.c - * - * We are going to parse an XML sample file and print the data to stdout. - * - * Like all examples we start by including Eina: - * @skipline #include - * - * We declare 2 booleans to keep track of tags: - * @skipline tag_login - * @skipline tag_message - * - * Here we declare some variables and initialize eina: - * @until eina_init - * - * We fill buffer with the XML data from chat.xml: - * @until fread - * - * We will use an Eina_Array to store the data: - * @skipline array - * - * Here we call eina_simple_xml_parse(). We pass the buffer with data, its size, - * we ask to strip leading and trailing whitespace, we give the callback - * function and the array to store the formatted data: - * @until _xml_tag_cb - * - * This will loop over the array and print the data using _print callback: - * @skipline foreach - * - * This is the main XML parser callback, it will check for known tags and get - * the corresponding values: - * @skip static - * @until str - * - * We first check for opening tag: - * @skipline type - * - * If we know the tag should have attributes, then we find them using - * eina_simple_xml_tag_attributes_find() and give them to another parsing - * function using eina_simple_xml_attributes_parse(): - * @until _xml_attr_cb - * - * We check for other known tags: - * @until tag_message - * - * We then check data for corresponding tag: - * @until EINA_FALSE - * - * We are doing the formatting in same time and put all the \<post\> children - * in str. - * @until EINA_FALSE - * - * Finally, we store our string in the array: - * @skipline push - * - * This is the callback to parse the attributes, we check for key name and keep - * the value: - * @skip static - * @until snprintf - * - * This is the function that simply print items of the array: - * @until EINA_TRUE - * - * You can see the full source code - * @ref eina_simple_xml_parser_example_01 "here". - */ - -/** - * @page eina_simple_xml_parser_example_01 - * @include eina_simple_xml_parser_01.c - * @example eina_simple_xml_parser_01.c - */ - -/** * @defgroup Eina_Simple_XML_Group Simple_XML + * @ingroup Eina_Tools_Group * - * Simplistic relaxed SAX-like XML parser. + * @brief This is a simplistic relaxed SAX-like XML parser. * - * This parser is far from being compliant with XML standard, but will - * do for most XMLs out there. If you know that your format is simple - * and will not vary in future with strange corner cases, then you can + * This parser is far from being compliant with XML standards, but + * works for most XMLs out there. If you know that your format is simple + * and won't vary in the future with strange corner cases, then you can * use it safely. * - * The parser is SAX like, that is, it will tokenize contents and call - * you back so you can take some action. No contents are allocated + * The parser is SAX like, that is, it tokenizes content and calls + * you back so that you can take some action. No content is allocated * during this parser work and it's not recursive, so you can use it - * with a very large document without worries. + * with a very large document without any issues. * - * It will not validate the document anyhow, neither it will create a + * It does not validate the document anyhow, neither does it create a * tree hierarchy. That's up to you. * * Accordingly to XML, open tags may contain attributes. This parser - * will not tokenize this. If you want you can use + * does not tokenize this. If you want you can use * eina_simple_xml_tag_attributes_find() and then * eina_simple_xml_attributes_parse(). * - * For more information, see - * @ref eina_simple_xml_parser_example_01_page "this example". - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * @{ - */ - -/** - * @defgroup Eina_Simple_XML_Group Simple_XML - * * @{ */ @@ -160,6 +74,10 @@ struct _Eina_Simple_XML_Attribute const char *value; }; +/** + * @typedef _Eina_Simple_XML_Node_Type + * @brief Enumeration for a simple XML node type. + */ typedef enum _Eina_Simple_XML_Node_Type { EINA_SIMPLE_XML_NODE_ROOT = 0, @@ -195,23 +113,24 @@ struct _Eina_Simple_XML_Node_Data size_t length; char data[]; }; + /** * @typedef _Eina_Simple_XML_Type - * a simple XML type. + * @brief Enumeration for a simple XML type. */ typedef enum _Eina_Simple_XML_Type { - EINA_SIMPLE_XML_OPEN = 0, /*!< \<tag attribute="value"\> */ - EINA_SIMPLE_XML_OPEN_EMPTY, /*!< \<tag attribute="value" /\> */ - EINA_SIMPLE_XML_CLOSE, /*!< \</tag\> */ - EINA_SIMPLE_XML_DATA, /*!< tag text data */ - EINA_SIMPLE_XML_CDATA, /*!< \<![CDATA[something]]\> */ - EINA_SIMPLE_XML_ERROR, /*!< error contents */ - EINA_SIMPLE_XML_PROCESSING, /*!< \<?xml ... ?\> \<?php .. ?\> */ - EINA_SIMPLE_XML_DOCTYPE, /*!< \<!DOCTYPE html */ - EINA_SIMPLE_XML_COMMENT, /*!< \<!-- something --\> */ - EINA_SIMPLE_XML_IGNORED, /*!< whatever is ignored by parser, like whitespace */ - EINA_SIMPLE_XML_DOCTYPE_CHILD /*!< \<!DOCTYPE_CHILD @since 1.8 */ + EINA_SIMPLE_XML_OPEN = 0, /**< \<tag attribute="value"\> */ + EINA_SIMPLE_XML_OPEN_EMPTY, /**< \<tag attribute="value" /\> */ + EINA_SIMPLE_XML_CLOSE, /**< \</tag\> */ + EINA_SIMPLE_XML_DATA, /**< tag text data */ + EINA_SIMPLE_XML_CDATA, /**< \<![CDATA[something]]\> */ + EINA_SIMPLE_XML_ERROR, /**< Error contents */ + EINA_SIMPLE_XML_PROCESSING, /**< \<?xml ... ?\> \<?php .. ?\> */ + EINA_SIMPLE_XML_DOCTYPE, /**< \<!DOCTYPE html */ + EINA_SIMPLE_XML_COMMENT, /**< \<!-- something --\> */ + EINA_SIMPLE_XML_IGNORED, /**< Whatever is ignored by the parser, like whitespace */ + EINA_SIMPLE_XML_DOCTYPE_CHILD /**< \<!DOCTYPE_CHILD @since 1.8 */ } Eina_Simple_XML_Type; typedef Eina_Bool (*Eina_Simple_XML_Cb)(void *data, Eina_Simple_XML_Type type, const char *content, unsigned offset, unsigned length); @@ -219,25 +138,28 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c /** - * Parse a section of XML string text - * - * @param buf the input string. May not contain \0 terminator. - * @param buflen the input string size. - * @param strip whenever this parser should strip leading and trailing - * whitespace. These whitespace will still be issued, but as type - * #EINA_SIMPLE_XML_IGNORED. - * @param func what to call back while parse to do some action. The - * first parameter is the given user @a data, the second is the - * token type, the third is the pointer to content start (it's - * not a NULL terminated string!), the forth is where this - * content is located inside @a buf (does not include tag - * start, for instance "<!DOCTYPE value>" the offset points at - * "value"), the fifth is the size of the content. Whenever this - * function return #EINA_FALSE the parser will abort. @param - * data what to give as context to @a func. - * - * @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or - * parsing error. + * @brief Parses a section of the XML string text. + * + * @since_tizen 2.3 + * + * @param[in] buf The input string \n + * May not contain the \0 terminator. + * @param[in] buflen The input string size + * @param[in] strip The boolean value that indicates when this parser should do strip leading and whitespace trailing \n + * This whitespace is still issued, but as type + * #EINA_SIMPLE_XML_IGNORED. + * @param[in] func The function to call back while parse does some action \n + * The first parameter is the given user @a data, the second is the + * token type, the third is the pointer to the content's start (it's + * not a NULL terminated string), the fourth is where this + * content is located, that is @a buf (does not include tag + * start, for instance "<!DOCTYPE value>" the offset points at + * "value"), the fifth is the size of the content \n + * Whenever this function returns @c EINA_FALSE the parser aborts. + * @param[in] data The data to give as context to @a func + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE if it is aborted by the user or a + * parsing error occurs */ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, Eina_Bool strip, @@ -245,253 +167,305 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, /** - * Given the contents of a tag, find where the attributes start. + * @brief Finds where the attributes start from given the contents of a tag are provided. + * + * @since_tizen 2.3 * - * @param buf the input string. May not contain \0 terminator. - * @param buflen the input string size. - * @return pointer to the start of attributes, it can be used - * to feed eina_simple_xml_attributes_parse(). @c NULL is returned - * if no attributes were found. + * @remarks The tag contents are returned by eina_simple_xml_parse() when + * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY. * - * The tag contents is returned by eina_simple_xml_parse() when - * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY. + * @param[in] buf The input string \n + * May not contain \0 terminator. + * @param[in] buflen The input string size + * @return A pointer to the start of the attributes, it can be used + * to feed eina_simple_xml_attributes_parse() \n + * @c NULL is returned if no attributes are found. * */ EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned buflen); /** - * Given a buffer with xml attributes, parse them to key=value pairs. - * - * @param buf the input string. May not contain \0 terminator. - * @param buflen the input string size. - * @param func what to call back while parse to do some action. The - * first parameter is the given user @a data, the second is the - * key (null-terminated) and the last is the value (null - * terminated). These strings should not be modified and - * reference is just valid until the function return. - * @param data data to pass to the callback function. - * - * @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or - * parsing error. + * @brief Parses a buffer with XML attributes to key=value pairs. + * + * @since_tizen 2.3 + * + * @param[in] buf The input string \n + * May not contain \0 terminator. + * @param[in] buflen The input string size + * @param[in] func The function to call back while parse does some action \n + * The first parameter is the given user @a data, the second is the + * key (null-terminated) and the last is the value (null + * terminated) \n + * These strings should not be modified and the + * reference is just valid till the function returns + * @param[in] data The data to pass to the callback function + * + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE if it is aborted by the user or a + * parsing error occurs */ EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen, Eina_Simple_XML_Attribute_Cb func, const void *data); /** - * Create (and append) new attribute to tag. + * @brief Creates (and appends) a new attribute to the tag. * - * @param parent if provided, will be set in the resulting structure - * as well as the attribute will be appended to attributes list. - * @param key Null-terminated string. Must not be @c NULL. - * @param value Null-terminated string. If @c NULL, the empty string will be used. + * @since_tizen 2.3 * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_attribute_free() or indirectly + * @param[in] parent If provided, this is set in the resulting structure + * and the attribute is appended to the attributes list + * @param[in] key The null-terminated string \n + * Must not be @c NULL. + * @param[in] value The null-terminated string \n + * If @c NULL, the empty string is used. + * + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory should be released directly with eina_simple_xml_attribute_free() or indirectly * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Attribute * eina_simple_xml_attribute_new(Eina_Simple_XML_Node_Tag *parent, const char *key, const char *value); /** - * Remove attribute from parent and delete it. + * @brief Removes an attribute from the parent and deletes it. + * + * @since_tizen 2.3 * - * @param attr attribute to release memory. + * @param[in] attr The attribute to release memory of */ EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr); /** - * Create new tag. If parent is provided, it is automatically appended. + * @brief Creates a new tag. If @a parent is provided, it is automatically appended. + * + * @since_tizen 2.3 * - * @param parent if provided, will be set in the resulting structure - * as well as the tag will be appended to children list. - * @param name Null-terminated string. Must not be @c NULL. + * @param[in] parent If provided, this is set in the resulting structure + * and the tag is appended to the children list + * @param[in] name The null-terminated string \n + * Must not be @c NULL. * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_tag_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_tag_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_Tag * eina_simple_xml_node_tag_new(Eina_Simple_XML_Node_Tag *parent, const char *name); /** - * Remove tag from parent and delete it. + * @brief Removes a tag from the parent and deletes it. + * + * @since_tizen 2.3 * - * @param tag to release memory. + * @param[in] tag The tag to release memory of */ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag); /** - * Create new data. If parent is provided, it is automatically appended. + * @brief Creates new data. If @a parent is provided, it is automatically appended. * - * @param parent if provided, will be set in the resulting structure - * as well as the data will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a contents. + * @since_tizen 2.3 * - * @return Newly allocated memory or NULL on error. This memory should be - * released with eina_simple_xml_node_data_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @param[in] parent If provided, this is set in the resulting structure + * and the data is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents + * + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_data_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove data from parent and delete it. + * @brief Removes data from the parent and deletes it. + * + * @since_tizen 2.3 * - * @param node to release memory. + * @param[in] node The data to release memory of */ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node); /** - * Create new cdata. If parent is provided, it is automatically appended. + * @brief Creates new cdata. If @a parent is provided, it is automatically appended. * - * @param parent if provided, will be set in the resulting structure - * as well as the cdata will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a content. + * @since_tizen 2.3 * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_cdata_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @param[in] parent If provided, this is set in the resulting structure + * and the cdata is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents + * + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_cdata_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove cdata from parent and delete it. + * @brief Removes cdata from the parent and deletes it. * - * @param node to release memory. + * @since_tizen 2.3 + * + * @param[in] node The cdata to release memory of */ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node); /** - * Create new doctype child. If parent is provided, it is automatically appended. + * @brief Creates a new doctype child. If @a parent is provided, it is automatically appended. * - * @param parent if provided, will be set in the resulting structure - * as well as the doctype child will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a content. + * @since 1.8 * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_doctype_child_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @since_tizen 2.3 + * + * @param[in] parent If provided, this is set in the resulting structure + * and the doctype child is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents + * + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_doctype_child_free() or indirectly + * with eina_simple_xml_node_tag_free(). * - * @since 1.8 */ EAPI Eina_Simple_XML_Node_Doctype_Child * eina_simple_xml_node_doctype_child_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove doctype child from parent and delete it. - * - * @param node to release memory. + * @brief Removes the doctype child from the parent and deletes it. * * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] node The doctype child to release memory of + * */ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *node); /** - * Create new processing. If parent is provided, it is automatically appended. + * @brief Creates new processing. If @a parent is provided, it is automatically appended. + * + * @since_tizen 2.3 * - * @param parent if provided, will be set in the resulting structure - * as well as the processing will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a contents. + * @param[in] parent If provided, this is set in the resulting structure + * and the processing is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_processing_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_processing_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove processing from parent and delete it. + * @brief Removes processing from the parent and deletes it. * - * @param node processing to release memory. + * @since_tizen 2.3 + * + * @param[in] node The processing to release memory of */ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node); /** - * Create new doctype. If parent is provided, it is automatically appended. + * @brief Creates a new doctype. If @a parent is provided, it is automatically appended. + * + * @since_tizen 2.3 * - * @param parent if provided, will be set in the resulting structure - * as well as the doctype will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a contents. + * @param[in] parent If provided, this is set in the resulting structure + * and the doctype is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_doctype_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_doctype_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove doctype from parent and delete it. + * @brief Removes the doctype from the parent and deletes it. + * + * @since_tizen 2.3 * - * @param node doctype to release memory. + * @param[in] node The doctype to release memory of */ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node); /** - * Create new comment. If parent is provided, it is automatically appended. + * @brief Creates a new comment. If @a parent is provided, it is automatically appended. * - * @param parent if provided, will be set in the resulting structure - * as well as the comment will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a contents. + * @since_tizen 2.3 * - * @return Newly allocated memory or @c NULL on error. This memory should be - * released with eina_simple_xml_node_comment_free() or indirectly - * with eina_simple_xml_node_tag_free() of the parent. + * @param[in] parent If provided, this is set in the resulting structure + * and the comment is appended to the children list + * @param[in] contents The string to be used \n + * Must not be @c NULL. + * @param[in] length size in bytes of @a contents + * + * @return The newly allocated memory, otherwise @c NULL on error \n + * This memory of the parent should be released directly with eina_simple_xml_node_comment_free() or indirectly + * with eina_simple_xml_node_tag_free(). */ EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); /** - * Remove comment from parent and delete it. + * @brief Removes a comment from the parent and deletes it. * - * @param node comment to release memory. + * @since_tizen 2.3 + * + * @param[in] node The comment to release memory of */ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node); /** - * Load a XML node tree based on the given string. + * @brief Loads an XML node tree based on the given string. + * + * @since_tizen 2.3 * - * @param buf the input string. May not contain \0 terminator. - * @param buflen the input string size. - * @param strip whenever this parser should strip leading and trailing - * whitespace. + * @param[in] buf The input string \n + * May not contain \0 terminator. + * @param[in] buflen The input string size + * @param[in] strip The boolean value that indicates when this parser should do + * strip leading and whitespace trailing * - * @return Document root with children tags, or @c NULL on errors. - * Document with errors may return partial tree instead of @c NULL, - * we'll do our best to avoid returning nothing. + * @return The document root with children tags, otherwise @c NULL on errors \n + * The document with errors may return a partial tree instead of @c NULL, + * we are going to do our best to avoid returning nothing. */ EAPI Eina_Simple_XML_Node_Root * eina_simple_xml_node_load(const char *buf, unsigned buflen, Eina_Bool strip); /** - * Free node tree build with eina_simple_xml_node_load() + * @brief Frees the node tree built with eina_simple_xml_node_load(). + * + * @since_tizen 2.3 * - * @param root memory returned by eina_simple_xml_node_load() + * @param[in] root The memory returned by eina_simple_xml_node_load() */ EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root); /** - * Converts the node tree under the given element to a XML string. + * @brief Converts the node tree under the given element to an XML string. * - * @param node the base node to convert. - * @param indent Indentation string, or @c NULL to disable it. + * @since_tizen 2.3 * - * @return @c NULL on errors or a newly allocated string on success. + * @param[in] node The base node to convert + * @param[in] indent The indentation string, otherwise @c NULL to disable it + * + * @return @c NULL on errors, otherwise a newly allocated string on success */ EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent); - -/** - * @} - */ - /** * @} */ diff --git a/src/lib/eina/eina_str.h b/src/lib/eina/eina_str.h index dae592bac6..4a2439e3ce 100644 --- a/src/lib/eina/eina_str.h +++ b/src/lib/eina/eina_str.h @@ -7,211 +7,172 @@ #include "eina_types.h" /** - * @page tutorial_eina_string Eina String example - * @dontinclude eina_str_01.c - * - * Whenever using eina we need to include it: - * @skipline #include - * @line #include - * - * In our main function we declare(and initialize) some variables and initialize - * eina: - * @until eina_init - * - * It's frequently necessary to split a string into its constituent parts, - * eina_str_split() make's it easy to do so: - * @until printf - * - * Another common need is to make a string uppercase or lowercase, so let's - * create a string and make it uppercase and then make it lowercase again: - * @until printf - * @until printf - * - * Next we use eina to check if our @p names string starts or ends with some - * values: - * @until Has - * - * When strings will be used in a terminal(or a number of other places) it - * necessary to escape certain characters that appear in them: - * @until printf - * - * Much as we previously split a string we will now join two strings: - * @until printf - * - * With strlcpy() we can copy what portion of the @p prologue fits in @p str and - * be sure that it's still NULL terminated: - * @until printf - * - * Since we are done with @p prologue and @p str we should free them: - * @until free(str - * - * Finally we see strlcat in action: - * @until printf(" - * - * And then shut eina down and exit: - * @until } - * @example eina_str_01.c - */ -/** - * @addtogroup Eina_String_Group String + * @defgroup Eina_String_Group String + * @ingroup Eina_Tools_Group * - * @brief Provide useful functions for C string manipulation. + * @brief The group discusses useful functions for C string manipulation. * - * This group of functions allow you to more easily manipulate strings, they - * provide functionality not available through string.h. + * This group of functions allows you to manipulate strings more easily, they + * provide functionality that is not available through string.h. * - * @warning Since these functions modify the strings they can't be used with + * Since these functions modify the strings they can't be used with * shared strings(eina_stringshare). * - * See an example @ref tutorial_eina_string "here". - */ - -/** - * @addtogroup Eina_Tools_Group Tools - * - * For more information refer to the @ref tutorial_eina_string "string example". - * - * @{ - */ - -/** - * @defgroup Eina_String_Group String - * * @{ */ /* strlcpy implementation for libc's lacking it */ /** - * @brief Copy a c-string to another. - * - * @param dst The destination string. - * @param src The source string. - * @param siz The size of the destination string. - * @return The length of the source string. - * - * This function copies up to @p siz - 1 characters from the - * NULL-terminated string @p src to @p dst, NULL-terminating the result - * (unless @p siz is equal to 0). The returned value is the length of - * @p src. If the returned value is greater than @p siz, truncation - * occurred. - * - * @note The main difference between eina_strlcpy and strncpy is that this - * ensures @p dst is NULL-terminated even if no @c NULL byte is found in the first - * @p siz bytes of src. + * @brief Copies one c-string to another. + * + * @details This function copies up to @a siz - 1 characters from the + * NULL-terminated string @a src to @a dst, NULL-terminating the result + * (unless @a siz is equal to 0). The returned value is the length of + * @a src. If the returned value is greater than @a siz, truncation + * occurs. + * + * @since_tizen 2.3 + * + * @remarks The main difference between eina_strlcpy and strncpy is that this + * ensures that @a dst is NULL-terminated even if no @c NULL byte is found in the first + * @a siz bytes of @a src. + * + * @param[in] dst The destination string + * @param[in] src The source string + * @param[in] siz The size of the destination string + * @return The length of the source string + * */ EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a c-string. + * @brief Appends a c-string. + * + * @details This function appends @a src to @a dst of size @a siz (unlike + * strncat, @a siz is the full size of @a dst, no space is left). At + * most @a siz - 1 characters are copied. Always NULL-terminates + * (unless @a siz <= strlen(dst)). This function returns strlen(src) + + * MIN(siz, strlen(initial dst)). If the returned value is greater than or + * equal to @a siz, truncation occurs. * - * @param dst The destination string. - * @param src The source string. - * @param siz The size of the destination string. + * @since_tizen 2.3 + * + * @param[in] dst The destination string + * @param[in] src The source string + * @param[in] siz The size of the destination string * @return The length of the source string plus MIN(siz, strlen(initial dst)) * - * This function appends @p src to @p dst of size @p siz (unlike - * strncat, @p siz is the full size of @p dst, not space left). At - * most @p siz - 1 characters will be copied. Always NULL-terminates - * (unless @p siz <= strlen(dst)). This function returns strlen(src) + - * MIN(siz, strlen(initial dst)). If the returned value is greater or - * equal than @p siz, truncation occurred. */ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2); /** - * @brief Check if the given string has the given prefix. + * @brief Check whether the given string has the given prefix. + * + * @details This function returns @c EINA_TRUE if @a str has the prefix + * @a prefix, otherwise it returns @c EINA_FALSE. If the length of @a prefix is + * greater than @a str, @c EINA_FALSE is returned. * - * @param str The string to work with. - * @param prefix The prefix to check for. - * @return #EINA_TRUE if the string has the given prefix, #EINA_FALSE otherwise. + * @since_tizen 2.3 + * + * @param[in] str The string to work with + * @param[in] prefix The prefix to check for + * @return @c EINA_TRUE if the string has the given prefix, otherwise @c EINA_FALSE * - * This function returns #EINA_TRUE if @p str has the prefix - * @p prefix, #EINA_FALSE otherwise. If the length of @p prefix is - * greater than @p str, #EINA_FALSE is returned. */ EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief Check if the given string has the given suffix. + * @brief Check whether the given string has the given suffix. + * + * @details This function returns @c EINA_TRUE if @a str has the suffix + * @a suffix, otherwise it returns @c EINA_FALSE. If the length of @a suffix is + * greater than @a str, @c EINA_FALSE is returned. * - * @param str The string to work with. - * @param suffix The suffix to check for. - * @return #EINA_TRUE if the string has the given suffix, #EINA_FALSE otherwise. + * @since_tizen 2.3 + * + * @param[in] str The string to work with + * @param[in] suffix The suffix to check for + * @return @c EINA_TRUE if the string has the given suffix, otherwise @c EINA_FALSE * - * This function returns #EINA_TRUE if @p str has the suffix - * @p suffix, #EINA_FALSE otherwise. If the length of @p suffix is - * greater than @p str, #EINA_FALSE is returned. */ EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief Check if the given string has the given extension. + * @brief Check whether the given string has the given extension. + * + * @details This function does the same as eina_str_has_suffix(), except it's case + * insensitive. * - * @param str The string to work with. - * @param ext The extension to check for. - * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise. + * @since_tizen 2.3 + * + * @param[in] str The string to work with + * @param[in] ext The extension to check for + * @return @c EINA_TRUE if the string has the given extension, otherwise @c EINA_FALSE * - * This function does the same as eina_str_has_suffix(), except it's case - * insensitive. */ EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** - * @brief Split a string using a delimiter. - * - * @param string The string to split. - * @param delimiter The string which specifies the places at which to split the string. - * @param max_tokens The maximum number of strings to split string into, or a number less - * than 1 to split as many times as possible. This parameter - * IGNORES the added @c NULL terminator. - * @return A newly-allocated NULL-terminated array of strings or @c NULL if it - * fails to allocate the array. - * - * This function splits @p string into a maximum of @p max_tokens pieces, - * using the given delimiter @p delimiter. @p delimiter is not included in any - * of the resulting strings, unless @p max_tokens is reached. If - * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If - * @p max_tokens is reached, the last string in the returned string - * array contains the remainder of string. The returned value is a - * newly allocated NULL-terminated array of strings or @c NULL if it fails to - * allocate the array. To free it, free the first element of the array and the - * array itself. - * - * @note If you need the number of elements in the returned array see - * eina_str_split_full(). + * @brief Splits a string using a delimiter. + * + * @details This function splits @a string into a maximum of @a max_tokens pieces, + * using the given delimiter @a delimiter. @a delimiter is not included in any + * of the resulting strings, unless @a max_tokens is reached. If + * @a max_tokens is less than @c 1, the string is splitted as many times as possible. If + * @a max_tokens is reached, the last string in the returned string + * array contains the remainder of the string. The returned value is a + * newly allocated NULL-terminated array of strings or @c NULL if it fails to + * allocate the array. To free it, free the first element of the array and the + * array itself. + * + * @since_tizen 2.3 + * + * @remarks If you need the number of elements in the returned array see + * eina_str_split_full(). + * + * @param[in] string The string to split + * @param[in] delimiter The string that specifies the places at which to split the string + * @param[in] max_tokens The maximum number of strings to split the string into, or a number less + * than @c 1 to split as many times as possible \n + * This parameter IGNORES the added @c NULL terminator. + * @return A newly-allocated NULL-terminated array of strings, otherwise @c NULL if it + * fails to allocate the array + * */ EAPI char **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Split a string using a delimiter and returns number of elements. - * - * @param string The string to split. - * @param delimiter The string which specifies the places at which to split the string. - * @param max_tokens The maximum number of strings to split string into, or a number less - * than 1 to split as many times as possible. This parameter - * IGNORES the added @c NULL terminator. - * @param elements Where to return the number of elements in returned - * array. This array is guaranteed to be no greater than @p max_tokens, and - * it will NOT count the @c NULL terminator element. - * @return A newly-allocated NULL-terminated array of strings or @c NULL if it - * fails to allocate the array. - * - * This function splits @p string into a maximum of @p max_tokens pieces, - * using the given delimiter @p delimiter. @p delimiter is not included in any - * of the resulting strings, unless @p max_tokens is reached. If - * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If - * @p max_tokens is reached, the last string in the returned string - * array contains the remainder of string. The returned value is a - * newly allocated NULL-terminated array of strings or @c NULL if it fails to - * allocate the array. To free it, free the first element of the array and the - * array itself. - * - * @note The actual size of the returned array, when @p elements returns greater than zero, - * will always be @p elements + 1. This is due to the @c NULL terminator element that - * is added to the array for safety. If it returns @c 6, the number of split strings returned - * will be 6, but the size of the array (including the @c NULL element) will actually be 7. + * @brief Splits a string using a delimiter and returns the number of elements. + * + * @details This function splits @a string into a maximum of @a max_tokens pieces, + * using the given delimiter @a delimiter. @a delimiter is not included in any + * of the resulting strings, unless @a max_tokens is reached. If + * @a max_tokens is less than @c 1, the string is splitted as many times as possible. If + * @a max_tokens is reached, the last string in the returned string + * array contains the remainder of the string. The returned value is a + * newly allocated NULL-terminated array of strings or @c NULL if it fails to + * allocate the array. To free it, free the first element of the array and the + * array itself. + * + * @since_tizen 2.3 + * + * @remarks The actual size of the returned array, when @a elements returns greater than zero, + * is always @a elements + 1. This is due to the @c NULL terminator element that + * is added to the array for safety. If it returns @c 6, the number of split strings returned + * is 6, but the size of the array (including the @c NULL element) is actually 7. + * + * @param string The string to split + * @param[in] delimiter The string that specifies the places at which to split the string + * @param[in] max_tokens The maximum number of strings to split the string into, or a number less + * than @c 1 to split as many times as possible \n + * This parameter IGNORES the added @c NULL terminator. + * @param[out] elements The number of elements in the returned array \n + * This array is guaranteed to be no greater than @a max_tokens, and + * it does NOT count the @c NULL terminator element. + * @return A newly-allocated NULL-terminated array of strings, otherwise @c NULL if it + * fails to allocate the array * * @see eina_str_split() */ @@ -219,27 +180,29 @@ EAPI char **eina_str_split_full(const char *string, const char *delimit /** - * @brief Join two strings of known length. - * - * @param dst The buffer to store the result. - * @param size Size (in byte) of the buffer. - * @param sep The separator character to use. - * @param a First string to use, before @p sep. - * @param a_len length of @p a. - * @param b Second string to use, after @p sep. - * @param b_len length of @p b. - * @return The number of characters printed. - * - * This function joins the strings @p a and @p b (in that order) and - * separate them with @p sep. The result is stored in the buffer - * @p dst and at most @p size - 1 characters will be written and the - * string is NULL-terminated. @p a_len is the length of @p a (not - * including '\\0') and @p b_len is the length of @p b (not including - * '\\0'). This function returns the number of characters printed (not - * including the trailing '\\0' used to end output to strings). Just - * like snprintf(), it will not write more than @p size bytes, thus a - * returned value of @p size or more means that the output was - * truncated. + * @brief Joins two strings of known length. + * + * @details This function joins the strings @a a and @a b (in that order) and + * separates them with @a sep. The result is stored in the buffer + * @a dst and at most @a size - 1 characters are written and the + * string is NULL-terminated. @a a_len is the length of @a a (not + * including '\\0') and @a b_len is the length of @a b (not including + * '\\0'). This function returns the number of characters printed (not + * including the trailing '\\0' used to end output to the strings). Just + * like snprintf(), it does not write more than @a size bytes, thus a + * returned value of @a size or more means that the output is + * truncated. + * + * @since_tizen 2.3 + * + * @param[in] dst The buffer to store the result + * @param[in] size The size (in byte) of the buffer + * @param[in] sep The separator character to use + * @param[in] a The first string to use, before @a sep + * @param[in] a_len The length of @a a + * @param[in] b The second string to use, after @a sep + * @param[in] b_len The length of @a b + * @return The number of characters printed * * @see eina_str_join() * @see eina_str_join_static() @@ -248,101 +211,125 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c /** - * @brief Use Iconv to convert a text string from one encoding to another. + * @brief Uses Iconv to convert a text string from one encoding to another. + * + * @details This function converts @a text, encoded in @a enc_from. On success, + * the converted text is returned and is encoded in @a enc_to. On + * failure, @c NULL is returned. Iconv is used to convert @a text. If + * Iconv is not available, @c NULL is returned. When not used anymore, + * the returned value must be freed. * - * @param enc_from Encoding to convert from. - * @param enc_to Encoding to convert to. - * @param text The text to convert. - * @return The converted text. + * @since_tizen 2.3 * - * This function converts @p text, encoded in @p enc_from. On success, - * the converted text is returned and is encoded in @p enc_to. On - * failure, @c NULL is returned. Iconv is used to convert @p text. If - * Iconv is not available, @c NULL is returned. When not used anymore, - * the returned value must be freed. + * @param[in] enc_from The encoding to convert from + * @param[in] enc_to The encoding to convert to + * @param[in] text The text to convert + * @return The converted text * - * @warning This function is guaranteed to break when '\0' characters are in @p text. - * DO NOT USE THIS FUNCTION IF YOUR TEXT CONTAINS NON-TERMINATING '\0' CHARACTERS. */ EAPI char *eina_str_convert(const char *enc_from, const char *enc_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3); -/** - * @brief Use Iconv to convert a text string from one encoding to another. - * - * @param enc_from Encoding to convert from. - * @param enc_to Encoding to convert to. - * @param text The text to convert. - * @param len The size in bytes of the text to convert. - * @param retlen The size in bytes of the converted text. - * @return The converted text. - * - * This function converts @p text, encoded in @p enc_from. On success, - * the converted text is returned and is encoded in @p enc_to. On - * failure, @c NULL is returned. Iconv is used to convert @p text. If - * Iconv is not available, @c NULL is returned. When not used anymore, - * the returned value must be freed. - * - * @since 1.8 - */ -EAPI char *eina_str_convert_len(const char *enc_from, const char *enc_to, const char *text, size_t len, size_t *retlen) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3); - /** - * @brief Escape slashes, spaces and apostrophes in strings. + * @brief Escapes back slashes, spaces, and apostrophes in strings. + * + * @since_tizen 2.3 + * + * @remarks Escaping is done by adding a back slash \ before any occurrence of back slashes \, + * spaces " ", or apostrophes "'". This function returns a newly allocated + * escaped string on success or @c NULL on failure. When not used anymore, the + * returned value must be freed. * - * @param str The string to escape. - * @return The escaped string. + * @param[in] str The string to escape + * @return The escaped string * - * Escaping is done by adding a slash "\" before any occurrence of slashes "\", - * spaces " " or apostrophes "'". This function returns a newly allocated - * escaped string on success, @c NULL on failure. When not used anymore, the - * returned value must be freed. */ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1); /** - * @brief Lowercase all the characters in range [A-Z] in the given string. + * @brief Lowercases all the characters in the range [A-Z] in the given string. + * + * @details This function modifies the original string, changing all characters + * in [A-Z] to lowercase. If @a str is @c NULL or is an empty string, + * this function does nothing. + * + * @since_tizen 2.3 * - * @param str The string to lowercase. + * @param[out] str The string to lowercase * - * This function modifies the original string, changing all characters - * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string, - * this function does nothing. */ EAPI void eina_str_tolower(char **str); /** - * @brief Uppercase all the characters in range [a-z] in the given string. + * @brief Uppercases all the characters in the range [a-z] in the given string. * - * @param str The string to uppercase. + * @details This function modifies the original string, changing all characters + * in [a-z] to uppercase. If @a str is @c NULL or is an empty string, + * this function does nothing. + * + * @since_tizen 2.3 + * + * @param[out] str The string to uppercase * - * This function modifies the original string, changing all characters - * in [a-z] to uppercase. If @p str is @c NULL or is an empty string, - * this function does nothing. */ EAPI void eina_str_toupper(char **str); +/** + * @brief Join two strings of known length. + * + * @details This function is similar to eina_str_join_len(), but will compute + * the length of @p a and @p b using strlen(). + * + * @since_tizen 2.3 + * + * @param[in] dst The buffer to store the result. + * @param[in] size Size (in byte) of the buffer. + * @param[in] sep The separator character to use. + * @param[in] a First string to use, before @p sep. + * @param[in] b Second string to use, after @p sep. + * @return The number of characters printed. + * + * @see eina_str_join_len() + * @see eina_str_join_static() + */ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char *a, const char *b) EINA_ARG_NONNULL(1, 4, 5); /** * @def eina_str_join_static(dst, sep, a, b) - * @brief Join two static strings and store the result in a static buffer. + * @brief Joins two static strings and stores the result in a static buffer. * - * @param dst The buffer to store the result. - * @param sep The separator character to use. - * @param a First string to use, before @p sep. - * @param b Second string to use, after @p sep. - * @return The number of characters printed. + * @details This function is similar to eina_str_join_len(), but assumes + * that string sizes are known using sizeof(X). + * + * @since_tizen 2.3 * - * This function is similar to eina_str_join_len(), but will assume - * string sizes are know using sizeof(X). + * @param dst The buffer to store the result + * @param sep The separator character to use + * @param a The first string to use, before @a sep + * @param b The second string to use, after @a sep + * @return The number of characters printed * * @see eina_str_join() * @see eina_str_join_static() */ #define eina_str_join_static(dst, sep, a, b) eina_str_join_len(dst, sizeof(dst), sep, a, (sizeof(a) > 0) ? sizeof(a) - 1 : 0, b, (sizeof(b) > 0) ? sizeof(b) - 1 : 0) +/** + * @brief Count up to a given amount of bytes of the given string. + * + * @details This function returns the size of @p str, up to @p maxlen + * characters. It avoid needless iterations after that size. @p str + * must be a valid pointer and MUST not be @c NULL, otherwise this + * function will crash. This function returns the string size, or + * (size_t)-1 if the size is greater than @a maxlen. + * + * @since_tizen 2.3 + * + * @param[in] str The string pointer. + * @param[in] maxlen The maximum length to allow. + * @return the string size or (size_t)-1 if greater than @a maxlen. + */ static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); #include "eina_inline_str.x" @@ -351,8 +338,4 @@ static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PU * @} */ -/** - * @} - */ - #endif /* EINA_STR_H */ diff --git a/src/lib/eina/eina_strbuf.h b/src/lib/eina/eina_strbuf.h index 1a628b9fef..7ce38705b4 100644 --- a/src/lib/eina/eina_strbuf.h +++ b/src/lib/eina/eina_strbuf.h @@ -6,71 +6,34 @@ #include "eina_types.h" - -/** - * @page tutorial_strbuf Eina_Strbuf example - * @dontinclude eina_strbuf_01.c - * - * First thing always is including Eina: - * @skipline #include - * @until #include - * - * Next we initialize eina and create a string buffer to play with: - * @until strbuf_new - * - * Here you can see two different ways of creating a buffer with the same - * contents. We could create them in simpler ways, but this gives us an - * opportunity to demonstrate several functions in action: - * @until strbuf_reset - * @until strbuf_reset - * - * Next we use the printf family of functions to create a formated string, - * add, remove and replace some content: - * @until strbuf_string_get - * @until strbuf_string_get - * @until strbuf_string_get - * - * Once done we free our string buffer, shut down Eina and end the application: - * @until } - * - * @example eina_strbuf_01.c - */ /** - * @addtogroup Eina_String_Buffer_Group String Buffer - * - * @brief These functions provide string buffers management. - * - * The String Buffer data type is designed to be a mutable string, - * allowing to append, prepend or insert a string to a buffer. + * @defgroup Eina_String_Buffer_Group String Buffer + * @ingroup Eina_Data_Types_Group * - * For more information see @ref tutorial_strbuf "this example". - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types + * @brief This group discusses the functions that provide string buffers management. * - * @{ - */ - -/** - * @defgroup Eina_String_Buffer_Group String Buffer + * @remarks The String Buffer data type is designed to be a mutable string, + * allowing to append, prepend, or insert a string into a buffer. * * @{ */ /** * @typedef Eina_Strbuf - * Type for a string buffer. + * @brief The structure type for a string buffer. */ typedef struct _Eina_Strbuf Eina_Strbuf; /** - * @brief Create a new string buffer. + * @brief Creates a new string buffer. + * + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_strbuf_free(). * - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_strbuf_free(). + * @return A newly allocated string buffer instance * * @see eina_strbuf_free() * @see eina_strbuf_append() @@ -79,89 +42,86 @@ typedef struct _Eina_Strbuf Eina_Strbuf; EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_strbuf_string_steal . The passed string must be malloced. + * @brief Creates a new string buffer using the passed string. The passed + * string is used directly as the buffer, it's somehow the opposite function of + * @ref eina_strbuf_string_steal. The passed string must be malloced. * - * @param str the string to manage - * @return Newly allocated string buffer instance. + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_strbuf_free(). * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_strbuf_free(). + * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] str The string to manage + * @return A newly allocated string buffer instance * * @see eina_strbuf_free() * @see eina_strbuf_append() * @see eina_strbuf_string_get() - * @since 1.1.0 */ EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_strbuf_string_steal . The passed string must be malloced. + * @brief Creates a new string buffer using the passed string. The passed + * string is used directly as the buffer, it's somehow the opposite function of + * @ref eina_strbuf_string_steal. The passed string must be malloced. * - * @param str the string to manage - * @param length the length of the string. - * @return Newly allocated string buffer instance. + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_strbuf_free(). * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_strbuf_free(). - * - * @see eina_strbuf_manage_new() * @since 1.2.0 - */ -EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; - -/** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_strbuf_string_steal . The passed string must be malloced. * - * @param str the string to manage - * @param length the length of the string. - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_strbuf_free(). + * @param[in] str The string to manage + * @param[in] length The length of the string + * @return A newly allocated string buffer instance * * @see eina_strbuf_manage_new() - * @since 1.9.0 */ -EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; +EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free a string buffer. + * @brief Frees a string buffer. * - * @param buf The string buffer to free. + * @details This function frees the memory of @a buf. @a buf must have been + * created by eina_strbuf_new(). * - * This function frees the memory of @p buf. @p buf must have been - * created by eina_strbuf_new(). + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to free */ EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Reset a string buffer. + * @brief Resets a string buffer. + * + * @details This function resets @a buf: the buffer length is set to 0, and the + * string is set to '\\0'. No memory is freed. * - * @param buf The string buffer to reset. + * @since_tizen 2.3 * - * This function reset @p buf: the buffer len is set to 0, and the - * string is set to '\\0'. No memory is free'd. + * @param[in] buf The string buffer to reset */ EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Append a string to a buffer, reallocating as necessary. + * @brief Appends a string to a buffer, reallocating as necessary. + * + * @details This function appends @a str to @a buf. It computes the length of + * @a str, so is slightly slower than eina_strbuf_append_length(). If + * the length is known beforehand, consider using that variant. If + * @a buf can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function appends @p str to @p buf. It computes the length of - * @p str, so is slightly slower than eina_strbuf_append_length(). If - * the length is known beforehand, consider using that variant. If - * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_strbuf_append() * @see eina_strbuf_append_length() @@ -169,35 +129,40 @@ EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); /** - * @brief Append an escaped string to a buffer, reallocating as necessary. + * @brief Appends an escaped string to a buffer, reallocating as necessary. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function escapes and then appends the string @a str to @a buf. If @a str + * cannot be appended, @c EINA_FALSE is returned, otherwise, @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function escapes and then appends the string @p str to @p buf. If @p str - * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is - * returned. */ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a string to a buffer, reallocating as necessary, - * limited by the given length. + * @brief Appends a string to a buffer, reallocating as necessary, + * limited by the given length. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @param maxlen The maximum number of characters to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function appends at most @a maxlen characters of @a str to + * @a buf. It can't append more than the length of @a str. It + * computes the length of @a str, so it is slightly slower than + * eina_strbuf_append_length(). If the length is known beforehand, + * consider using that variant (@a maxlen should then be checked so + * that it is greater than the size of @a str). If @a str cannot be + * appended, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * This function appends at most @p maxlen characters of @p str to - * @p buf. It can't append more than the length of @p str. It - * computes the length of @p str, so it is slightly slower than - * eina_strbuf_append_length(). If the length is known beforehand, - * consider using that variant (@p maxlen should then be checked so - * that it is greater than the size of @p str). If @p str can not be - * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is - * returned. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @param[in] maxlen The maximum number of characters to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_strbuf_append() * @see eina_strbuf_append_length() @@ -205,19 +170,22 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a string of exact length to a buffer, reallocating as necessary. + * @brief Appends a string of exact length to a buffer, reallocating as necessary. + * + * @details This function appends @a str to @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_strbuf_append() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_stringshare. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @param length The exact length to use. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @param[in] length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function appends @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_strbuf_append() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_stringshare. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. * * @see eina_stringshare_length() * @see eina_strbuf_append() @@ -226,130 +194,128 @@ EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t ma EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size_t length) EINA_ARG_NONNULL(1, 2); /** - * @brief Append an Eina_Strbuf to a buffer, reallocating as necessary. - * - * @param buf The string buffer to append to. - * @param data The string buffer to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @brief Appends a character to a string buffer, reallocating as + * necessary. * - * This function appends @p data to @p buf. @p data must be allocated and - * different from @NULL. It is slightly faster than eina_strbuf_append() as - * it does not compute the size of @p str. If @p buf can't append it, - * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. + * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE + * is returned, otherwise @c EINA_TRUE is returned. * - * @see eina_strbuf_append() - * @see eina_strbuf_append_n() - * @see eina_strbuf_append_length() - * @since 1.9.0 - */ -EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2); - -/** - * @brief Append a character to a string buffer, reallocating as - * necessary. + * @since_tizen 2.3 * - * @param buf The string buffer to append to. - * @param c The char to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to append to + * @param[in] c The character to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1); /** - * @brief Append a string to a buffer, reallocating as necessary. + * @brief Appends a string to a buffer, reallocating as necessary. + * + * @details This function appends the string defined by the format @a fmt to @a buf. @a + * fmt must be of a valid format from the printf family of functions. If it can't + * insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is returned. * - * @param buf The string buffer to append to. - * @param fmt The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function appends the string defined by the format @p fmt to @p buf. @p - * fmt must be of a valid format for printf family of functions. If it can't - * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. + * @param[in] buf The string buffer to append to + * @param[in] fmt The string to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_strbuf_append() */ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); /** - * @brief Append a string to a buffer, reallocating as necessary. + * @brief Appends a string to a buffer, reallocating as necessary. + * + * @since_tizen 2.3 * - * @param buf The string buffer to append to. - * @param fmt The string to append. - * @param args The variable arguments. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to append to + * @param[in] fmt The string to append + * @param[in] args The variable arguments + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_strbuf_append_printf() */ EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string to a buffer, reallocating as necessary. + * @brief Inserts a string into a buffer, reallocating as necessary. * - * @param buf The string buffer to insert. - * @param str The string to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a str into @a buf at position @a pos. It + * computes the length of @a str, so is slightly slower than + * eina_strbuf_insert_length(). If the length is known beforehand, + * consider using that variant. If @a buf can't insert it, @c EINA_FALSE + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p str to @p buf at position @p pos. It - * computes the length of @p str, so is slightly slower than - * eina_strbuf_insert_length(). If the length is known beforehand, - * consider using that variant. If @p buf can't insert it, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert an escaped string to a buffer, reallocating as - * necessary. + * @brief Inserts an escaped string into a buffer, reallocating as + * necessary. + * + * @details This function escapes and inserts the string @a str into @a buf at + * position @a pos. If @a buf can't insert @a str, @c EINA_FALSE is + * returned, otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function escapes and inserts the string @p str to @p buf at - * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is - * returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. + * @brief Inserts a string into a buffer, reallocating as necessary. Limited by maxlen. * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param maxlen The maximum number of chars to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a str into @a buf at position @a pos, with at + * most @a maxlen bytes. The number of inserted characters cannot be + * greater than the length of @a str. It computes the length of + * @a str, so is slightly slower than eina_strbuf_insert_length(). If the + * length is known beforehand, consider using that variant (@a maxlen + * should then be checked so that it is greater than the size of + * @a str). If @a str cannot be inserted, @c EINA_FALSE is returned, + * otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] maxlen The maximum number of chars to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p str to @p buf at position @p pos, with at - * most @p maxlen bytes. The number of inserted characters can not be - * greater than the length of @p str. It computes the length of - * @p str, so is slightly slower than eina_strbuf_insert_length(). If the - * length is known beforehand, consider using that variant (@p maxlen - * should then be checked so that it is greater than the size of - * @p str). If @p str can not be inserted, #EINA_FALSE is returned, - * otherwise, #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string of exact length to a buffer, reallocating as necessary. + * @brief Inserts a string of exact length into a buffer, reallocating as necessary. + * + * @details This function inserts @a str into @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_strbuf_insert() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_strngshare. If @a buf + * can't insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param length The exact length to use. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function inserts @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_strbuf_insert() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_strngshare. If @p buf - * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] length The exact length to use + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_strbuf_insert() @@ -358,43 +324,51 @@ EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t ma EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a character to a string buffer, reallocating as - * necessary. + * @brief Inserts a character into a string buffer, reallocating as + * necessary. * - * @param buf The string buffer to insert to. - * @param c The char to insert. - * @param pos The position to insert the char. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a c into @a buf at position @a pos. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] c The character to insert + * @param[in] pos The position at which to insert the char + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf at position @p pos. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1); /** - * @brief Insert a string to a buffer, reallocating as necessary. + * @brief Inserts a string into a buffer, reallocating as necessary. + * + * @details This function inserts a string as described by the format @a fmt into @a buf at + * the position @a pos. @a fmt must be of a valid format from the printf family of + * functions. If it can't insert it, @c EINA_FALSE is returned, + * otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to insert. - * @param fmt The string to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to insert into + * @param[in] fmt The string to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function insert a string as described by the format @p fmt to @p buf at - * the position @p pos. @p fmt must be of a valid format for printf family of - * functions. If it can't insert it, #EINA_FALSE is returned, - * otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); /** - * @brief Insert a string to a buffer, reallocating as necessary. + * @brief Inserts a string into a buffer, reallocating as necessary. * - * @param buf The string buffer to insert. - * @param fmt The string to insert. - * @param pos The position to insert the string. - * @param args The variable arguments. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] fmt The string to insert + * @param[in] pos The position at which to insert the string + * @param[in] args The variable arguments + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_strbuf_insert_printf */ @@ -402,242 +376,294 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz /** * @def eina_strbuf_prepend(buf, str) - * @brief Prepend the given string to the given buffer + * @brief Prepends the given string to the given buffer. + * + * @details This macro calls eina_strbuf_insert() at position 0. If @a buf + * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert() at position 0. If @p buf - * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0) /** * @def eina_strbuf_prepend_escaped(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This macro calls eina_strbuf_insert_escaped() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert_escaped() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0) /** * @def eina_strbuf_prepend_n(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. + * + * @details This macro calls eina_strbuf_insert_n() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @param maxlen The maximum number of chars to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @param maxlen The maximum number of chars to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert_n() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0) /** * @def eina_strbuf_prepend_length(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @param length The exact length to use. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This macro calls eina_strbuf_insert_length() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @param length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert_length() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0) /** * @def eina_strbuf_prepend_char(buf, str) - * @brief Prepend the given character to the given buffer + * @brief Prepends the given character to the given buffer. + * + * @details This macro calls eina_strbuf_insert_char() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE + * is returned. * - * @param buf The string buffer to prepend to. - * @param c The character to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param c The character to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure. * - * This macro is calling eina_strbuf_insert_char() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE - * is returned. */ #define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0) /** * @def eina_strbuf_prepend_printf(buf, fmt, ...) - * @brief Prepend the given string to the given buffer + * @brief Prepends the given string to the given buffer. + * + * @details This macro calls eina_strbuf_insert_printf() at position 0. If @a buf + * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to prepend to. - * @param fmt The string to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param fmt The string to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert_printf() at position 0. If @p buf - * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__) /** * @def eina_strbuf_prepend_vprintf(buf, fmt, args) - * @brief Prepend the given string to the given buffer + * @brief Prepends the given string to the given buffer. + * + * @details This macro calls eina_strbuf_insert_vprintf() at position 0. If @a buf + * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to prepend to. - * @param fmt The string to prepend. - * @param args The variable arguments. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param fmt The string to prepend + * @param args The variable arguments + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_insert_vprintf() at position 0.If @p buf - * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args) /** - * @brief Remove a slice of the given string buffer. + * @brief Removes a slice of the given string buffer. + * + * @details This function removes a slice of @a buf, starting from @a start + * (inclusive) and ending at @a end (non-inclusive). Both the values are + * in bytes. It returns @c EINA_FALSE on failure, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 * - * @param buf The string buffer to remove a slice. + * @param buf The string buffer to remove a slice of * @param start The initial (inclusive) slice position to start - * removing, in bytes. + * removing from, in bytes * @param end The final (non-inclusive) slice position to finish - * removing, in bytes. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * removing at, in bytes + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function removes a slice of @p buf, starting at @p start - * (inclusive) and ending at @p end (non-inclusive). Both values are - * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. */ EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); /** - * @brief Retrieve a pointer to the contents of a string buffer + * @brief Gets a pointer to the contents of a string buffer. * - * @param buf The string buffer. - * @return The current string in the string buffer. + * @details This function returns the string contained in @a buf. The returned + * value must not be modified as it is longer valid if @a buf is + * modified. In other words, any eina_strbuf_append() or similar + * makes that pointer invalid. The pointer returned by this function <b>must + * not</b> be freed. * - * This function returns the string contained in @p buf. The returned - * value must not be modified and will no longer be valid if @p buf is - * modified. In other words, any eina_strbuf_append() or similar will - * make that pointer invalid. The pointer returned by this function <b>must - * not</b> be freed. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer + * @return The current string in the string buffer * * @see eina_strbuf_string_steal() */ EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Steal the contents of a string buffer. + * @brief Steals the contents of a string buffer. + * + * @details This function returns the string contained in @a buf. @a buf is + * then initialized and does not own the returned string anymore. The + * caller must release the memory of the returned string by calling + * free(). * - * @param buf The string buffer to steal. - * @return The current string in the string buffer. + * @since_tizen 2.3 * - * This function returns the string contained in @p buf. @p buf is - * then initialized and does not own the returned string anymore. The - * caller must release the memory of the returned string by calling - * free(). + * @param[in] buf The string buffer to steal from + * @return The current string in the string buffer * * @see eina_strbuf_string_get() */ EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Free the contents of a string buffer but not the buffer. + * @brief Frees the contents of a string buffer but not the buffer. + * + * @details This function frees the string contained in @a buf without freeing + * @a buf. + * + * @since_tizen 2.3 * - * @param buf The string buffer to free the string of. + * @param[in] buf The string buffer to free the string from * - * This function frees the string contained in @p buf without freeing - * @p buf. */ EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Retrieve the length of the string buffer content. + * @brief Gets the length of the string buffer's content. * - * @param buf The string buffer. - * @return The current length of the string, in bytes. + * @details This function returns the length of @a buf. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer + * @return The current length of the string, in bytes * - * This function returns the length of @p buf. */ EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Replace the n-th string with an other string. + * @brief Replaces the nth string with another string. + * + * @details This function replaces the nth occurrence of @a str in @a buf with + * @a with. It returns @c EINA_FALSE on failure, otherwise @c EINA_TRUE. * - * @param buf The string buffer to work with. - * @param str The string to replace. - * @param with The replaceing string. - * @param n The number of the fitting string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to work with + * @param[in] str The string to replace + * @param[in] with The string to replace with + * @param[in] n The number of the fitting string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function replaces the n-th occurrence of @p str in @p buf with - * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. */ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); /** * @def eina_strbuf_replace_first(buf, str, with) - * @brief Prepend the given character to the given buffer + * @brief Prepends the given character to the given buffer. + * + * @details This macro calls eina_strbuf_replace() with the nth occurrence + * equal to @c 1. If @a buf can't replace it, @c EINA_FALSE is returned, + * otherwise @c EINA_TRUE is returned. * - * @param buf The string buffer to work with. - * @param str The string to replace. - * @param with The replaceing string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param buf The string buffer to work with + * @param str The string to replace + * @param with The string to replace with + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_strbuf_replace() with the n-th occurrence - * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, - * otherwise #EINA_TRUE is returned. */ #define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1) /** - * @brief Replace all strings with an other string. - - * @param buf the string buffer to work with. - * @param str The string to replace. - * @param with The replaceing string. - * @return How often the string was replaced. + * @brief Replaces all strings with another string. + * + * @details This function replaces all the occurrences of @a str in @a buf with + * the string @a with. This function returns the number of times @a str + * has been replaced. On failure, it returns @c 0. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to work with + * @param[in] str The string to replace + * @param[in] with The string to replace with + * @return The frequency with which the string is replaced * - * This function replaces all the occurrences of @p str in @p buf with - * the string @p with. This function returns the number of times @p str - * has been replaced. On failure, it returns @c 0. */ EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Trim the string buffer - - * @param buf the string buffer to work with. + * @brief Trims the string buffer. + * + * @details This function skips whitespaces at the beginning and the end of the buffer. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to work with * - * This function skips whitespaces in the beginning and the end of the buffer. */ EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Left trim the string buffer - - * @param buf the string buffer to work with. + * @brief Left trims the string buffer. + * + * @details This function skips whitespaces at the beginning of the buffer. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to work with * - * This function skips whitespaces in the beginning of the buffer. */ EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Right trim the string buffer - - * @param buf the string buffer to work with. + * @brief Right trims the string buffer. + * + * @details This function skips whitespaces at the end of the buffer. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to work with * - * This function skips whitespaces in the end of the buffer. */ EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); @@ -645,12 +671,4 @@ EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); * @} */ -/** - * @} - */ - -/** - * @} - */ - #endif /* EINA_STRBUF_H */ diff --git a/src/lib/eina/eina_stringshare.h b/src/lib/eina/eina_stringshare.h index 080e951624..4241e7f0e9 100644 --- a/src/lib/eina/eina_stringshare.h +++ b/src/lib/eina/eina_stringshare.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2002-2008 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -22,29 +22,29 @@ * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to - * deal in the Software without restriction, including without limitation the + * deal with the Software without restriction, including without limitation, the * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or * sell copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in - * all copies of the Software and its Copyright notices. In addition publicly - * documented acknowledgment must be given that this software has been used if no + * all copies of the Software and its Copyright notices. In addition, a publicly + * documented acknowledgement must be given that this software has been used if no * source code of this software is made available publicly. This includes - * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing + * acknowledgements in either Copyright notices, Manuals, Publicity, and Marketing * documents or any documentation provided with any product containing this * software. This License does not apply to any software that links to the * libraries provided by this software (statically or dynamically), but only to * the software provided. * - * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice - * and it's intent. + * Please see OLD-COPYING.PLAIN for a plain-english explanation of this notice + * and its intent. * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS, OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER - * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER + * IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ @@ -56,64 +56,13 @@ #include "eina_types.h" /** - * @page eina_stringshare_example_01_page - * @dontinclude eina_stringshare_01.c - * - * Like all examples we start by including Eina: - * @skip #include - * @line #include - * - * Here we declare some variables and initialize eina: - * @until eina_init - * - * We start the substantive part of the example by showing how to make a part - * of a string shared and how to get the length of a shared string: - * @until stringshare_strlen - * As we add shared strings we also need to delete them when done using them: - * @line del - * - * There are many ways of creating shared strings including an equivalent to - * sprintf: - * @until del - * - * An equivalent to snprintf: - * @until printf - * - * But the simplest way of creating a shared string is through - * eina_stringshare_add(): - * @until printf - * - * Sometimes you already have a pointer to a shared string and want to use it, - * so to make sure the provider of the pointer won't free it while you're using - * it you can increase the shared string's ref count: - * @until printf - * - * Whenever you have a pointer to a shared string and would like to change it's - * value you should use eina_stringshare_replace(): - * @until printf - * @warning @b Don't use eina_stringshare_del() followed by - * eina_share_common_add(), under some circunstances you might end up deleting - * a shared string some other piece of code is using. - * - * We created str but haven't deleted it yet, and while we called - * eina_stringshare_del() on str2, we created it and then increased the ref - * count so it's still alive: - * @until str2 - * - * You can see the full source code @ref eina_stringshare_example_01 "here". - */ -/** - * @page eina_stringshare_example_01 - * @include eina_stringshare_01.c - * @example eina_stringshare_01.c - */ -/** - * @addtogroup Eina_Stringshare_Group Stringshare + * @defgroup Eina_Stringshare_Group Stringshare + * @ingroup Eina_Data_Types_Group * - * These functions allow you to store a single copy of a string, and use in - * multiple places throughout your program. + * @brief This group discusses the functions that allow you to store a single copy of a string, and use it in + * multiple places throughout your program. * - * This is a method to reduce the number of duplicated strings kept in + * This is a method to reduce the number of duplicated strings kept in the * memory. It's pretty common for the same strings to be dynamically * allocated repeatedly between applications and libraries, especially in * circumstances where you could have multiple copies of a structure that @@ -121,12 +70,12 @@ * strings, you request a read-only pointer to an existing string and * only incur the overhead of a hash lookup. * - * It sounds like micro-optimizing, but profiling has shown this can have - * a significant impact as you scale the number of copies up. It improves - * string creation/destruction speed, reduces memory use and decreases + * It sounds like micro-optimizing, but profiling has shown that this can have + * a significant impact as you scale the number of copies up. It improves the + * string creation/destruction speed, reduces memory use, and decreases * memory fragmentation, so a win all-around. * - * Using eina stringshares usually boils down to: + * @remarks Using eina stringshares usually boils down to: * @code * const char *str = eina_stringshare_add("My string"); * ... @@ -134,30 +83,18 @@ * ... * eina_stringshare_del(str); * @endcode - * @note It's very important to note that string shares are @b @c const, - * changing them will result in undefined behavior. - * @note eina_stringshare_del() @b doesn't guarantee the string share will be + * + * It's very important to note that string shares are @b @c const, + * changing them results in an undefined behavior. + * eina_stringshare_del() @b doesn't guarantee that the string share is * freed, it releases a reference to it, but if other references to it still - * exist the string share will live until those are released. + * exist the string share lives until those are released. * * The following diagram gives an idea of what happens as you create strings * with eina_stringshare_add(): * * @image html eina_stringshare.png - * @image latex eina_stringshare.eps height=\textheight - * - * For more information, see @ref eina_stringshare_example_01_page - * "this example". - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Stringshare_Group Stringshare + * @image latex eina_stringshare.eps "eina stringshare" height=\textheight * * @{ */ @@ -165,181 +102,230 @@ /** * @typedef Eina_Stringshare * - * "Eina_Stringshare *" is interchangeable with "const char *" but still a good - * visual hint for the purpose. Maybe in the far far future we'll even add - * strict type checking. + * @brief Interchangeable with "const char *", but still a good visual hint for the + * purpose. Maybe in the future we may even add strict type checking. * * @since 1.2.0 */ typedef const char Eina_Stringshare; /** - * @brief Retrieve an instance of a string with a specific size for use in a - * program. + * @brief Retrieves an instance of a string for use in a program. + * + * @details This function retrieves an instance of @a str. If @a str is + * @c NULL, then @c NULL is returned. If @a str is already stored, it + * is just returned and its reference counter is increased. Otherwise + * a duplicated string of @a str is returned. * - * @param str The string to retrieve an instance of. - * @param slen The string size (<= strlen(str)). - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @since_tizen 2.3 * - * This function retrieves an instance of @p str. If @p str is - * @c NULL, then @c NULL is returned. If @p str is already stored, it - * is just returned and its reference counter is increased. Otherwise - * a duplicated string of @p str is returned. + * @remarks This function does not check the string size, but uses the + * exact given size. This can be used to share_common parts of a larger + * buffer or substring. * - * This function does not check string size, but uses the - * exact given size. This can be used to share_common part of a larger - * buffer or substring. + * @param[in] str The string to retrieve an instance of + * @param[in] slen The string size (<= strlen(str)) + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_share_common_add() */ EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; /** - * @brief Retrieve an instance of a string for use in a program. + * @brief Retrieves an instance of a string for use in a program. * - * @param str The NULL-terminated string to retrieve an instance of. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @details This function retrieves an instance of @a str. If @a str is + * @c NULL, then @c NULL is returned. If @a str is already stored, it + * is just returned and its reference counter is increased. Otherwise + * a duplicated string of @a str is returned. * - * This function retrieves an instance of @p str. If @p str is - * @c NULL, then @c NULL is returned. If @p str is already stored, it - * is just returned and its reference counter is increased. Otherwise - * a duplicated string of @p str is returned. + * @since_tizen 2.3 * - * The string @p str must be NULL terminated ('@\0') and its full - * length will be used. To use part of the string or non-null - * terminated, use eina_stringshare_add_length() instead. + * @remarks The string @a str must be @c NULL terminated ('@\0') and its full + * length should be used. To use a part of the string or non-null + * terminated, use eina_stringshare_add_length() instead. + * + * @param[in] str The NULL-terminated string to retrieve an instance of + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_stringshare_add_length() */ EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT; /** - * @brief Retrieve an instance of a string for use in a program - * from a format string. + * @brief Retrieves an instance of a string for use in a program + * from a format string. + * + * @details This function retrieves an instance of @a fmt. If @a fmt is + * @c NULL, then @c NULL is returned. If @a fmt is already stored, it + * is just returned and its reference counter is increased. Otherwise + * a duplicated string is returned. * - * @param fmt The NULL-terminated format string to retrieve an instance of. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * The format string @a fmt must be NULL-terminated ('@\0') and its full + * length should be used. To use a part of the format string or non-null + * terminated, use eina_stringshare_nprintf() instead. * - * This function retrieves an instance of @p fmt. If @p fmt is - * @c NULL, then @c NULL is returned. If @p fmt is already stored, it - * is just returned and its reference counter is increased. Otherwise - * a duplicated string is returned. + * @since_tizen 2.3 * - * The format string @p fmt must be NULL-terminated ('@\0') and its full - * length will be used. To use part of the format string or non-null - * terminated, use eina_stringshare_nprintf() instead. + * @param[in] fmt The NULL-terminated format string to retrieve an instance of + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_stringshare_nprintf() */ EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2); /** - * @brief Retrieve an instance of a string for use in a program - * from a format string. + * @brief Retrieves an instance of a string for use in a program + * from a format string. + * + * @details This function retrieves an instance of @a fmt with @a args. If @a fmt is + * @c NULL, then @c NULL is returned. If @a fmt with @a args is already stored, it + * is just returned and its reference counter is increased. Otherwise + * a duplicated string is returned. * - * @param fmt The NULL-terminated format string to retrieve an instance of. - * @param args The va_args for @p fmt - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * The format string @a fmt must be NULL-terminated ('@\0') and its full + * length should be used. To use a part of the format string or non-null + * terminated, use eina_stringshare_nprintf() instead. * - * This function retrieves an instance of @p fmt with @p args. If @p fmt is - * @c NULL, then @c NULL is returned. If @p fmt with @p args is already stored, it - * is just returned and its reference counter is increased. Otherwise - * a duplicated string is returned. + * @since_tizen 2.3 * - * The format string @p fmt must be NULL-terminated ('@\0') and its full - * length will be used. To use part of the format string or non-null - * terminated, use eina_stringshare_nprintf() instead. + * @param[in] fmt The NULL-terminated format string to retrieve an instance of + * @param[in] args The va_args for @a fmt + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_stringshare_nprintf() */ EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT; /** - * @brief Retrieve an instance of a string for use in a program - * from a format string with size limitation. - * @param len The length of the format string to use - * @param fmt The format string to retrieve an instance of. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @brief Retrieves an instance of a string for use in a program + * from a format string with size limitation. + * + * @details This function retrieves an instance of @a fmt limited by @a len. If @a fmt is + * @c NULL or @a len is < 1, then @c NULL is returned. If the resulting string + * is already stored, it is just returned and its reference counter is increased. + * Otherwise a duplicated string is returned. + * + * @a len length of the format string is used. To use the + * entire format string, use eina_stringshare_printf() instead. * - * This function retrieves an instance of @p fmt limited by @p len. If @p fmt is - * @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string - * is already stored, it is returned and its reference counter is increased. - * Otherwise a duplicated string is returned. + * @since_tizen 2.3 * - * @p len length of the format string will be used. To use the - * entire format string, use eina_stringshare_printf() instead. + * @param[in] len The length of the format string to use + * @param[in] fmt The format string to retrieve an instance of + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_stringshare_printf() */ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3); /** - * Increment references of the given shared string. + * @brief Increments references of the given shared string. * - * @param str The shared string. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @since_tizen 2.3 * - * This is similar to eina_share_common_add(), but it's faster since it will - * avoid lookups if possible, but on the down side it requires the parameter - * to be shared string. In other words, it must be the return of a previous - * call to one of the stringshare functions. + * @remarks This is similar to eina_share_common_add(), but it's faster since it + * avoids lookups if possible, but on the down side it requires the parameter + * to be a shared string. In other words, it must be the return of a previous + * call to one of the stringshare functions. * - * There is no unref since this is the work of eina_share_common_del(). + * @remarks There is no unref since this is the work of eina_share_common_del(). + * + * @param[in] str The shared string + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure */ EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str); /** - * @brief Note that the given string has lost an instance. + * @brief Notes that the given string has lost an instance. + * + * @details This function decreases the reference counter associated to @a str + * if it exists. If that counter reaches @c 0, the memory associated to + * @a str is freed. If @a str is @c NULL, the function returns + * immediately. + * + * @since_tizen 2.3 * - * @param str string The given string. + * @remarks If the given pointer is not shared, bad things happen, mostly a + * segmentation fault. * - * This function decreases the reference counter associated to @p str - * if it exists. If that counter reaches 0, the memory associated to - * @p str is freed. If @p str is @c NULL, the function returns - * immediately. + * @param[in] str string The given string * - * @note If the given pointer is not shared, bad things will happen, likely a - * segmentation fault. */ EAPI void eina_stringshare_del(Eina_Stringshare *str); /** - * @brief Note that the given string @b must be shared. + * @brief Notes that the given string @b must be shared. * - * @param str the shared string to know the length. It is safe to - * give @c NULL, in that case @c 0 is returned. - * @return The length of a shared string. + * @details This function is a cheap way to known the length of a shared + * string. * - * This function is a cheap way to known the length of a shared - * string. + * @since_tizen 2.3 + * + * @remarks If the given pointer is not shared, bad things happen, mostly a + * segmentation fault. If in doubt, try strlen(). + * + * @param[in] str The shared string to know the length of \n + * It is safe to give @c NULL, in which case @c 0 is returned. + * @return The length of a shared string * - * @note If the given pointer is not shared, bad things will happen, likely a - * segmentation fault. If in doubt, try strlen(). */ EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Dump the contents of the share_common. + * @brief Dumps the contents of share_common. + * + * @details This function dumps all the strings from share_common to stdout with a + * DDD: prefix per line and a memory usage summary. * - * This function dumps all strings in the share_common to stdout with a - * DDD: prefix per line and a memory usage summary. + * @since_tizen 2.3 */ EAPI void eina_stringshare_dump(void); +/** + * @brief Replace the previously stringshared pointer with new content. + * + * @details The string pointed by @a p_str must be previously stringshared or + * @c NULL and it will be eina_stringshare_del(). The new string will + * be passed to eina_stringshare_add() and then assigned to @c *p_str. + * + * @since_tizen 2.3 + * + * @param[in] p_str pointer to the stringhare to be replaced. Must not be + * @c NULL, but @c *p_str may be @c NULL as it is a valid + * stringshare handle. + * @param[in] news new string to be stringshared, may be @c NULL. + * @return @c EINA_TRUE if the strings were different and thus replaced, + * @c EINA_FALSE if the strings were the same after shared. + */ static inline Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_stringshare_replace_length(Eina_Stringshare **p_str, const char *news, unsigned int slen) EINA_ARG_NONNULL(1); - -#include "eina_inline_stringshare.x" /** - * @} + * @brief Replace the previously stringshared pointer with a new content. + * + * @details The string pointed by @a p_str must be previously stringshared or + * @c NULL and it will be eina_stringshare_del(). The new string will + * be passed to eina_stringshare_add_length() and then assigned to @c *p_str. + * + * @since_tizen 2.3 + * + * @param[in] p_str pointer to the stringhare to be replaced. Must not be + * @c NULL, but @c *p_str may be @c NULL as it is a valid + * stringshare handle. + * @param[in] news new string to be stringshared, may be @c NULL. + * @param[in] slen The string size (<= strlen(str)). + * @return @c EINA_TRUE if the strings were different and thus replaced, + * @c EINA_FALSE if the strings were the same after shared. */ +static inline Eina_Bool eina_stringshare_replace_length(Eina_Stringshare **p_str, const char *news, unsigned int slen) EINA_ARG_NONNULL(1); + +#include "eina_inline_stringshare.x" /** * @} diff --git a/src/lib/eina/eina_tiler.h b/src/lib/eina/eina_tiler.h index 8006cca4e3..1cc2aa247d 100644 --- a/src/lib/eina/eina_tiler.h +++ b/src/lib/eina/eina_tiler.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -24,81 +24,22 @@ #include "eina_rectangle.h" /** - * @page eina_tiler_example_01 - * @dontinclude eina_tiler_01.c - * - * This is an example that illustrates how Eina_Tiler works for a given set of - * rectangles. The rectangles must be given in the command line in the form: - * \<width\>x\<height\>+\<x offset\>+\<y offset\> - * The example will show two panels, the first(input) will show the given - * rectangles(in different colors) and in the seconds(output) it will show the - * rectangles given by the tiler. The rectangles will be added one by one every - * two seconds. A lot of the example deals with actually painting the rectangles - * so we'll skip over quite a bit of code, but you can see all of it in @ref - * eina_tiler_01.c "eina_tiler_01.c". - * - * The first thing of note in our example is the creation of the tiler: - * @skipline eina_tiler_new - * @note @p maxw and @p maxh are calculated such that the tiler's size will - * fully encompass all given rectangles. - * - * We'll now look at the function that actually adds rectangles to our tiler. It - * first checks if we added all rectangles already and if so stops right there: - * @dontinclude eina_tiler_01.c - * @skip static Eina_Bool - * @until } - * - * Our function then clears all rectangles given to us by tiler from the last - * execution. It does this because each rectangle we add may change everything - * about the output of eina_tiler: - * @until output_rects_reset - * - * Next we get another rectangle, print it and show it in the input panel: - * @until add_input_rect - * - * We now come to the tiler stuff, we add our new rectangle to it and get a new - * iterator for the tiler: - * @until itr - * - * We now iterate over our tiler printing every rect it gives us and sowing it - * in the output panel: - * @until } - * - * We of course must remember to free our iterator and that's it for this - * function: - * @until } - * - * You should try many different inputs to see how the tiler works, here are a - * few suggestions: - * @li 100x100+0+0 100x100+200+200 - * @li 100x100+0+0 100x100+5+5 100x100+10+10 100x100+15+15 100x100+20+20 - * @li 100x100+0+0 100x100+100+100 100x100+200+0 100x100+0+200 100x100+200+200 - * @li 10x10+0+0 10x10+10+10 10x10+20+0 10x10+0+20 10x10+20+20 - * - * @example eina_tiler_01.c - */ -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** * @defgroup Eina_Tiler_Group Tiler + * @ingroup Eina_Data_Types_Group + * @brief Eina_Tiler is a tool to facilitate calculations of areas that are damaged + * and thus need to be re-rendered. * - * @warning This is a very low level tool, in most situations(for example if - * you're using evas) you won't need this. + * @remarks This is a very low level tool, in most situations(for example if + * you're using evas) you won't need this. * * @section basic Basic usage * - * Eina_Tiler is a tool to facilitate calculations of which areas are damaged - * and thus need to be re-rendered. The basic usage of Eina_Tiler is to give it - * the size of your canvas and a set of rectangular areas that need - * re-rendering, from that and using heuristics it'll tell you an efficient way - * to re-render in the form of a set of non-overlapping rectangles that covers - * the whole area that needs re-rendering. + * The basic usage of Eina_Tiler is to give it the size of your canvas and a + * set of rectangular areas that need re-rendering. From that and using + * heuristics, it tells you an efficient way to re-render in the form of a set + * of non-overlapping rectangles that cover the whole area that needs re-rendering. * - * The following is pseudo-code showing some simple use of Eina_Tiler: + * The following is a pseudo-code showing some simple uses of Eina_Tiler: * @code * tiler = eina_tiler_new(MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT); * EINA_LIST_FOREACH(list_of_areas_that_need_re_rendering, l, rect) @@ -112,18 +53,18 @@ * @see eina_tiler_rect_add() * @see eina_tiler_iterator_new() * - * @warning There are no guarantees that this will be the most efficient way to - * re-render for any particular case. + * @remarks There is no guarantee that this is the most efficient way to + * re-render for any particular case. * * @section grid_slicer Grid Slicer * * Grid slicer and Eina_Tiler are usually used together, that is however @b not * necessary, they can be used independently. Grid slicer provides an easy API - * to divide an area in tiles which is useful in certain applications to divide - * the area that will be rendered into tiles. It's customary to, then create one + * to divide an area into tiles, which is useful in certain applications to divide + * the area that is rendered into tiles. It's customary to, then create one * Eina_Tiler for each tile. * - * The following is pseudo-code showing a very simplified use of grid slicer + * The following is a pseudo-code showing a very simplified use of a grid slicer * together with Eina_Tiler: * @code * itr = eina_tile_grid_slicer_iterator_new(0, 0, MY_CANVAS_WIDTH, MY_CANVAS_HEIGHT, TILE_WIDTH, TILE_HEIGHT); @@ -149,115 +90,79 @@ /** * @typedef Eina_Tiler - * Tiler type. + * @brief The structure type for the tiler type. */ typedef struct _Eina_Tiler Eina_Tiler; /** * @typedef Eina_Tile_Grid_Info - * Grid type of a tiler. + * @brief The structure type for the grid type of a tiler. */ typedef struct Eina_Tile_Grid_Info Eina_Tile_Grid_Info; /** * @struct Eina_Tile_Grid_Info - * Grid type of a tiler. + * @brief The structure type for the grid type of a tiler. */ struct Eina_Tile_Grid_Info { - unsigned long col; /**< column of the tile grid */ - unsigned long row; /**< row of the tile grid*/ - Eina_Rectangle rect; /**< rectangle of the tile grid, coordinates are - relative to tile*/ - Eina_Bool full; /**< whether the grid is full or not */ + unsigned long col; /**< Column of the tile grid */ + unsigned long row; /**< Row of the tile grid */ + Eina_Rectangle rect; /**< Rectangle of the tile grid, coordinates are + relative to the tile */ + Eina_Bool full; /**< Whether the grid is full or not */ }; typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer; /** - * @brief Creates a new tiler with @p w width and @p h height. + * @brief Creates a new tiler with @a w width and @a h height. + * + * @since_tizen 2.3 * - * @param w Width of the tiler - * @param h Height of the tiler + * @param[in] w The width of the tiler + * @param[in] h The height of the tiler * @return The newly created tiler * * @see eina_tiler_free() */ EAPI Eina_Tiler *eina_tiler_new(int w, int h); -/** - * @brief Frees a tiler. - * - * @param t The tiler to free. - * - * This function frees @p t. It does not free the memory allocated for the - * elements of @p t. - */ -EAPI void eina_tiler_free(Eina_Tiler *t); -/** - * @brief Sets the size of tiles for a tiler. - * - * @param t The tiler whose tile size will be set. - * @param w Width of the tiles. - * @param h Height of the tiles. - * - * @warning @p w and @p h @b must be greater than zero, otherwise tile size - * won't be changed. - * @warning Tile size is not used! - */ -EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); /** - * @brief Change the size of the area covered by the tiler. + * @brief Frees a tiler. * - * @param t The tiler whose area size will be set. - * @param w Width of the area. - * @param h Height of the area. + * @details This function frees @a t. It does not free the memory allocated for the + * elements of @a t. * - * @since 1.8 + * @since_tizen 2.3 * - * @warning Must clear the tiler before changing its size. - */ -EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h); - -/** - * @brief Get the size of the area covered by the tiler. + * @param[in] t The tiler to free * - * @param t The tiler whose area size will be fetched. - * @param w Width of the area. - * @param h Height of the area. - * - * @since 1.8 */ -EAPI void eina_tiler_area_size_get(const Eina_Tiler *t, int *w, int *h); - +EAPI void eina_tiler_free(Eina_Tiler *t); /** - * @brief Define if we need to follow a strict grid of tile or a loosy one - * - * @param t The tiler to apply the strict rules to. - * @param strict Define if it will be strict or loosy + * @brief Sets the size of the tiles for a tiler. * - * By default it will be loosy. + * @since_tizen 2.3 * - * @since 1.8 - */ -EAPI void eina_tiler_strict_set(Eina_Tiler *t, Eina_Bool strict); - -/** - * @brief Tell if a tiler is empty or not + * @remarks @a w and @a h @b must be greater than zero, otherwise the tile size + * won't be changed. + * @remarks The tile size is not used. * - * @param t The tiler to apply the strict rules to. - * @return EINA_TRUE when empty, EINA_FALSE when not. + * @param[in] t The tiler whose tile size are set + * @param[in] w The width of the tiles + * @param[in] h The height of the tiles * - * @since 1.8 */ -EAPI Eina_Bool eina_tiler_empty(Eina_Tiler *t); - +EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); /** * @brief Adds a rectangle to a tiler. * - * @param t The tiler in which to add a container. - * @param r The rectangle to be added. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param[in] t The tiler in which to add a container + * @param[in] r The rectangle to be added + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_tiler_rect_del() */ @@ -265,134 +170,100 @@ EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle /** * @brief Removes a rectangle from a tiler. * - * @param t The tiler in which to add a container. - * @param r The rectangle to be removed. + * @since_tizen 2.3 + * + * @param[in] t The tiler in which to add a container + * @param[in] r The rectangle to be removed * * @see eina_tiler_rect_add() * @see eina_tiler_clear() */ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle *r); /** - * @brief Removes all rectangles from tiles. + * @brief Removes all rectangles from the tiles. * - * @param t The tiler to clear. + * @since_tizen 2.3 + * + * @param[in] t The tiler to clear * * @see eina_tiler_rect_del() */ EAPI void eina_tiler_clear(Eina_Tiler *t); /** - * @brief Create a iterator to access the tilers calculated rectangles. + * @brief Creates an iterator to access the tiler's calculated rectangles. + * + * @since_tizen 2.3 * - * @param t The tiler to iterate over. - * @return A iterator containing Eina_Rectangle. + * @param[in] t The tiler to iterate over + * @return An iterator containing Eina_Rectangle */ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); /** * @brief Creates a new Eina_Iterator that iterates over a list of tiles. * - * @param x X axis coordinate. - * @param y Y axis coordinate. - * @param w width. - * @param h height. - * @param tile_w tile width. - * @param tile_h tile height. - * @return A pointer to the Eina_Iterator. @c NULL on failure. - * - * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of - * tiles of width @a tile_w and height @p tile_h, the returned iterator will - * iterate over every tile in the grid having as its data a #Eina_Tile_Grid_Info. - * - * @note This is a convenience function, iterating over the returned iterator is - * equivalent to calling eina_tile_grid_slicer_setup() and calling - * eina_tile_grid_slicer_next() untill it returns #EINA_FALSE. - */ -EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h); - -/** - * @brief Gets the union of two tilers. + * @since_tizen 2.3 * - * @param dst The first tiler, will store the result. - * @param src The second tiler. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @remarks The region defined by @a x, @a y, @a w, and @a h is divided into a grid of + * tiles of width @a tile_w and height @a tile_h, the returned iterator then + * iterates over every tile in the grid having #Eina_Tile_Grid_Info as its data. * - * This fuction get the union of tilers @p dst and @p src. - * The result is stored in @p dst. It returns #EINA_TRUE if it succeeds. - * @since 1.11 - */ -EAPI Eina_Bool eina_tiler_union(Eina_Tiler *dst, Eina_Tiler *src); - -/** - * @brief Subtracts two tilers. + * @remarks This is a convenience function, iterating over the returned iterator is + * equivalent to calling eina_tile_grid_slicer_setup() and calling + * eina_tile_grid_slicer_next() until it returns @c EINA_FALSE. * - * @param dst The first tiler, will store the result. - * @param src The second tiler. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @param[in] x The x axis coordinate + * @param[in] y The y axis coordinate + * @param[in] w The width + * @param[in] h The height + * @param[in] tile_w The tile width + * @param[in] tile_h The tile height + * @return A pointer to the Eina_Iterator \n + * @c NULL on failure. * - * This fuction subtracts two tilers @p dst and @p src. - * The result is stored in @p dst. It returns #EINA_TRUE if it succeeds. - * @since 1.11 */ -EAPI Eina_Bool eina_tiler_subtract(Eina_Tiler *dst, Eina_Tiler *src); +EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h); /** - * @brief Gets the intersection of two tilers. + * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). * - * @param t1 The first tile. - * @param t2 The second tiler. - * @return A pointer of intersection result. @c NULL if intersection doesn't exist. + * @details This function iterates over each Eina_Tile_Grid_Info *rect of the grid. + * eina_tile_grid_slicer_setup() must be called first, and *rect is only valid + * if this function returns @c EINA_TRUE. Its content shouldn't be modified. * - * This fuction gest intersection of two tilers @p t1 and @p t2. - * It returns a pointer of result if intersection of two tilers exists., otherwise returns NULL. - * @since 1.11 - */ -EAPI Eina_Tiler *eina_tiler_intersection(Eina_Tiler *t1, Eina_Tiler *t2); - -/** - * @brief Gets whether two tilers are equal in rects or not. + * @since_tizen 2.3 + * + * @remarks Consider using eina_tile_grid_slicer_iterator_new() instead. * - * @param t1 The first tiler. - * @param t2 The second tiler. - * @return #EINA_TRUE is equal, #EINA_FALSE is unequal. + * @param[in] slc A pointer to an Eina_Tile_Grid_Slicer struct + * @param[out] rect A pointer to a struct Eina_Tile_Grid_Info + * @return @c EINA_TRUE if the current rectangle is valid, otherwise @c EINA_FALSE if there + * are no more rectangles to iterate over (and thus the current one isn't valid) * - * This fuction gets result of comparison for @p t1 and @p t2. - * It returns #EINA_TRUE if tilers are equal. - * @since 1.11 */ -EAPI Eina_Bool eina_tiler_equal(Eina_Tiler *t1, Eina_Tiler *t2); +static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect); /** - * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). + * @brief Sets up an Eina_Tile_Grid_Slicer struct. * - * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. - * @param rect Pointer to a struct Eina_Tile_Grid_Info *. - * @return #EINA_TRUE if the current rect is valid. #EINA_FALSE if there - * is no more rects to iterate over (and thus the current one isn't valid). + * @since_tizen 2.3 * - * This functions iterates over each Eina_Tile_Grid_Info *rect of the grid. - * eina_tile_grid_slicer_setup() must be called first, and *rect is only valid - * if this function returns #EINA_TRUE. Its content shouldn't be modified. + * @remarks The region defined by @a x, @a y, @a w, and @a h is divided into a grid of + * tiles of width @a tile_w and height @a tile_h, @a slc can then be used with + * eina_tile_grid_slicer_next() to access each tile. + * + * @remarks Consider using eina_tile_grid_slicer_iterator_new() instead. + * + * @param[in] slc A pointer to an Eina_Tile_Grid_Slicer struct + * @param[in] x The x axis coordinate + * @param[in] y The y axis coordinate + * @param[in] w The width + * @param[in] h The height + * @param[in] tile_w The tile width + * @param[in] tile_h The tile height + * @return A pointer to the Eina_Iterator \n + * @c NULL on failure. * - * @note Consider using eina_tile_grid_slicer_iterator_new() instead. - */ -static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect); -/** - * @brief Setup an Eina_Tile_Grid_Slicer struct. - * - * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. - * @param x X axis coordinate. - * @param y Y axis coordinate. - * @param w width. - * @param h height. - * @param tile_w tile width. - * @param tile_h tile height. - * @return A pointer to the Eina_Iterator. @c NULL on failure. - * - * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of - * tiles of width @a tile_w and height @p tile_h, @p slc can then be used with - * eina_tile_grid_slicer_next() to access each tile. - * - * @note Consider using eina_tile_grid_slicer_iterator_new() instead. */ static inline Eina_Bool eina_tile_grid_slicer_setup(Eina_Tile_Grid_Slicer *slc, int x, int y, int w, int h, int tile_w, int tile_h); @@ -402,8 +273,4 @@ static inline Eina_Bool eina_tile_grid_slicer_setup(Eina_Tile_Grid_Slicer *slc, * @} */ -/** - * @} - */ - #endif /* EINA_TILER_H_ */ diff --git a/src/lib/eina/eina_tmpstr.h b/src/lib/eina/eina_tmpstr.h index 7460356930..6f0d5587bb 100644 --- a/src/lib/eina/eina_tmpstr.h +++ b/src/lib/eina/eina_tmpstr.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2002-2012 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -28,23 +28,23 @@ * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in - * all copies of the Software and its Copyright notices. In addition publicly - * documented acknowledgment must be given that this software has been used if no + * all copies of the Software and its Copyright notices. In addition, publicly + * documented acknowledgement must be given that this software has been used if no * source code of this software is made available publicly. This includes - * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing + * acknowledgements in either Copyright notices, Manuals, Publicity, and Marketing * documents or any documentation provided with any product containing this * software. This License does not apply to any software that links to the * libraries provided by this software (statically or dynamically), but only to * the software provided. * - * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice + * Please see OLD-COPYING.PLAIN for a plain-english explanation of this notice * and it's intent. * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS, OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER - * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER + * IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ @@ -54,34 +54,34 @@ #include "eina_types.h" /** - * @page eina_tmpstr_ppage - * + * @page eina_tmpstr_page + * * Eina tmpstr is intended for being able to conveniently pass strings back * to a calling parent without having to use single static buffers (which - * don't work with multiple threads or when returning multilpe times as + * don't work with multiple threads or when returning multiple times as * parameters to a single function. - * + * * The traditional way to "return" a string in C is either to provide a buffer - * as a paramater to return it in, return a pointer to a single static buffer, + * as a parameter to return it in, return a pointer to a single static buffer, * which has issues, or return a duplicated string. All cases are inconvenient * and return special handling. This is intended to make this easier. Now you * can do something like this: - * + * * @code * Eina_Tmpstr *my_homedir(void) { * return eina_tmpstr_add(getenv("HOME")); * } - * + * * Eina_Tmpstr *my_tmpdir(void) { * return eina_tmpstr_add(getenv("TMP")); * } - * + * * void my_movefile(Eina_Tmpstr *src, Eina_Tmpstr *dst) { * rename(src, dst); * eina_tmpstr_del(src); * eina_tmpstr_del(dst); * } - * + * * char buf[500]; * my_movefile(my_homedir(), my_tmpdir()); * my_movefile("/tmp/file", "/tmp/newname"); @@ -89,21 +89,23 @@ * snprintf(buf, sizeof(buf), "/tmp/%i.file", rand()); * my_movefile("/tmp.file", buf); * @endcode - * + * * Notice that you can interchange standard C strings (static ones or even * generated buffers) with tmpstrings. The Eina_Tmpstr type is merely a - * type marker letting you know that the function will clean up those + * type marker letting you know that the function cleans up those * strings after use, and it is totally interchangeable with const char. */ /** - * @addtogroup Eina_Data_Types_Group Data Types + * @defgroup Eina_Tmpstr_Group Tmpstr + * @ingroup Eina_Data_Types_Group * - * @{ - */ - -/** - * @defgroup Eina_Stringshare_Group Stringshare + * @brief Eina tmpstr is intended for being able to conveniently pass strings back + * to a calling parent without having to use single static buffers (which + * don't work with multiple threads or when returning multiple times as + * parameters to a single function. + * + * @ref eina_tmpstr_page * * @{ */ @@ -111,9 +113,9 @@ /** * @typedef Eina_Tmpstr * - * Interchangeable with "const char *" but still a good visual hint for the - * purpose. This indicates the string is temporary and should be freed after - * use. + * @brief Interchangeable with "const char *", but still a good visual hint for the + * purpose. This indicates that the string is temporary and should be freed after + * use. * * @since 1.8.0 */ @@ -121,106 +123,115 @@ typedef const char Eina_Tmpstr; /** - * @brief Add a new temporary string based on the input string. - * - * @param str This is the input stringthat is copied into the temp string. - * @return A pointer to the tmp string that is a standard C string. - * - * When you add a temporary string (tmpstr) it is expected to have a very - * short lifespan, and at any one time only a few of these are intended to - * exist. This is not intended for longer term storage of strings. The - * intended use is the ability to safely pass strings as return values from - * functions directly into parameters of new functions and then have the - * string be cleaned up automatically by the caller. - * - * If @p str is NULL, or no memory space exists to store the tmpstr, then - * NULL will be returned, otherwise a valid string pointer will be returned - * that you can treat as any other C string (eg strdup(tmpstr) or - * printf("%s\n", tmpstr) etc.). This string should be considered read-only - * and immutable, and when youa re done with the string yo should delete it - * with eina_tmpstr_del(). - * + * @brief Adds a new temporary string based on the input string. + * + * @since 1.8.0 + * + * @since_tizen 2.3 + * + * @remarks When you add a temporary string (tmpstr) it is expected to have a very + * short lifespan, and at any one time only a few of these are intended to + * exist. This is not intended for long term storage of strings. The + * intended use is the ability to safely pass strings as return values from + * functions directly into parameters of new functions and then have the + * string cleaned up automatically by the caller. + * + * @remarks If @a str is @c NULL, or no memory space exists to store the tmpstr, then + * @c NULL is returned, otherwise a valid string pointer is returned + * that you can treat as any other C string (eg: strdup(tmpstr) or + * printf("%s\n", tmpstr) etc.). This string should be considered read-only + * and immutable, and when you are done with the string you should delete it + * using eina_tmpstr_del(). + * * Example usage: - * + * * @code * Eina_Tmpstr *my_homedir(void) { * return eina_tmpstr_add(getenv("HOME")); * } - * + * * void my_rmfile(Eina_Tmpstr *str) { * if (!str) return; * unlink(str); * eina_tmpstr_del(str); * } - * + * * my_rmfile(my_homedir()); * my_rmfile("/tmp/file"); * @endcode - * + * + * @param[in] str The input string that is copied into the temp string + * @return A pointer to the tmp string that is a standard C string + * * @see eina_tmpstr_del() * @see eina_tmpstr_add_length() - * - * @since 1.8.0 */ EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT; /** - * @brief Add a new temporary string based on the input string and length. - * - * @param str This is the input stringthat is copied into the temp string. - * @param length This is the maximum length and the allocated length of the temp string. - * @return A pointer to the tmp string that is a standard C string. - * - * When you add a temporary string (tmpstr) it is expected to have a very - * short lifespan, and at any one time only a few of these are intended to - * exist. This is not intended for longer term storage of strings. The - * intended use is the ability to safely pass strings as return values from - * functions directly into parameters of new functions and then have the - * string be cleaned up automatically by the caller. - * - * If @p str is NULL, or no memory space exists to store the tmpstr, then - * NULL will be returned, otherwise a valid string pointer will be returned - * that you can treat as any other C string (eg strdup(tmpstr) or - * printf("%s\n", tmpstr) etc.). This string should be considered read-only - * and immutable, and when youa re done with the string yo should delete it - * with eina_tmpstr_del(). + * @brief Adds a new temporary string based on the input string and length. + * + * @since 1.8.0 + * + * @since_tizen 2.3 + * + * @remarks When you add a temporary string (tmpstr) it is expected to have a very + * short lifespan, and at any one time only a few of these are intended to + * exist. This is not intended for long term storage of strings. The + * intended use is the ability to safely pass strings as return values from + * functions directly into parameters of new functions and then have the + * string cleaned up automatically by the caller. + * + * @remarks If @a str is @c NULL, or no memory space exists to store the tmpstr, then + * @c NULL is returned, otherwise a valid string pointer is returned + * that you can treat as any other C string (eg strdup(tmpstr) or + * printf("%s\n", tmpstr) etc.). This string should be considered read-only + * and immutable, and when you are done with the string you should delete it + * using eina_tmpstr_del(). * * @note If the length is greater than the actual string, but still '\0' * terminateed. Their won't be any crash and the string will be correct, * but eina_tmpstr_strlen will return an erroneous length. So if you * want to have the correct length always call eina_tmpstr_add_length * with length == strlen(str). + * + * @param[in] str The input string that is copied into the temp string + * @param[in] length The maximum length and the allocated length of the temp string + * @return A pointer to the tmp string that is a standard C string + * * @see eina_tmpstr_del() * @see eina_tmpstr_add() - * - * @since 1.8.0 */ EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length); /** - * @brief Return the length of a temporary string including the '\0'. - * - * @param tmpstr This is any C string pointer, but if it is a tmp string - * it will return the length faster. - * @return The length of the string including the '\0'; + * @brief Returns the length of a temporary string including the '\0'. * * @since 1.8.0 + * + * @since_tizen 2.3 + * + * @param[in] tmpstr A C string pointer, but if it is a tmp string + * it returns the length faster + * @return The length of the string including the '\0' */ EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr); /** - * @brief Delete the temporary string if it is one, or ignore it if it is not. - * - * @param tmpstr This is any C string pointer, but if it is a tmp string - * it is freed. - * - * This will delete the given temporary string @p tmpstr if it is a valid - * temporary string, or otherwise it will ignore it and do nothing so this - * can be used safely with non-temporary strings. - * - * @see eina_tmpstr_add() - * + * @brief Deletes the temporary string if it is one, or ignores it if it is not. + * + * @details This deletes the given temporary string @a tmpstr if it is a valid + * temporary string, otherwise it ignores it and does nothing, so this + * can be used safely with non-temporary strings. + * * @since 1.8.0 + * + * @since_tizen 2.3 + * + * @param[in] tmpstr A C string pointer, but if it is a tmp string + * it is freed + * + * @see eina_tmpstr_add() */ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1); @@ -228,8 +239,4 @@ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1); * @} */ -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_types.h b/src/lib/eina/eina_types.h index b0ce44b3ea..4d9f8925f6 100644 --- a/src/lib/eina/eina_types.h +++ b/src/lib/eina/eina_types.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2007-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -20,13 +20,10 @@ #define EINA_TYPES_H_ /** - * @addtogroup Eina_Core_Group Core - * - * @{ - */ - -/** * @defgroup Eina_Types_Group Types + * @ingroup Eina_Core_Group + * + * @brief This provides fundamental types and macros, etc. * * @{ */ @@ -55,7 +52,7 @@ # else /** * @def EAPI - * @brief Used to export functions(by changing visibility). + * @brief Definition used to export functions(by changing visibility). */ # define EAPI # endif @@ -164,11 +161,10 @@ # define EINA_SENTINEL # endif -#elif defined(_MSC_VER) -# define EINA_UNUSED +#elif defined(_WIN32) # define EINA_WARN_UNUSED_RESULT # define EINA_ARG_NONNULL(...) -# if _MSC_VER >= 1300 +# if defined(_MSC_VER) && _MSC_VER >= 1300 # define EINA_DEPRECATED __declspec(deprecated) # else # define EINA_DEPRECATED @@ -185,7 +181,6 @@ # define EINA_SENTINEL #elif defined(__SUNPRO_C) -# define EINA_UNUSED # define EINA_WARN_UNUSED_RESULT # define EINA_ARG_NONNULL(...) # define EINA_DEPRECATED @@ -209,91 +204,85 @@ # define EINA_LIKELY(exp) exp # define EINA_SENTINEL -#else /* ! __GNUC__ && ! _MSC_VER && ! __SUNPRO_C */ - -/** - * @def EINA_UNUSED - * Used to warn when an argument of the function is not used. - */ -# define EINA_UNUSED +#else /* ! __GNUC__ && ! _WIN32 && ! __SUNPRO_C */ /** * @def EINA_WARN_UNUSED_RESULT - * Used to warn when the returned value of the function is not used. + * @brief Definition used to warn when the returned value of the function is not used. */ # define EINA_WARN_UNUSED_RESULT /** * @def EINA_ARG_NONNULL - * Used to warn when the specified arguments of the function are @c NULL. - * - * @param ... Oridnals of the parameters to check for nullity (1..n) - * - * @returns Nothing, but Doxygen will complain if it's not documented :-P - * + * @brief Definition used to warn when the specified arguments of the function are @c NULL. */ # define EINA_ARG_NONNULL(...) /** * @def EINA_DEPRECATED - * Used to warn when the function is considered as deprecated. + * @brief Definition used to warn when the function is considered as deprecated. */ # define EINA_DEPRECATED /** * @def EINA_MALLOC - * @brief EINA_MALLOC is used to tell the compiler that a function may be treated - * as if any non-NULL pointer it returns cannot alias any other pointer valid when - * the function returns and that the memory has undefined content. + * @brief Definition used to tell the compiler that a function may be treated + * as if any non-NULL pointer it returns cannot alias any other pointer valid when + * the function returns and that the memory has undefined content. */ # define EINA_MALLOC /** * @def EINA_PURE - * @brief EINA_PURE is used to tell the compiler this functions has no effects - * except the return value and their return value depends only on the parameters - * and/or global variables. + * @brief Definition used to tell the compiler that this function has no effect + * except that the return value depends only on the parameters + * and/or global variables. */ # define EINA_PURE /** * @def EINA_PRINTF - * @param fmt The format to be used. - * @param arg The argument to be used. + * @brief Write formatted string to the standard output + * @param fmt The format to be used + * @param arg The argument to be used */ # define EINA_PRINTF(fmt, arg) /** * @def EINA_SCANF - * @param fmt The format to be used. - * @param arg The argument to be used. + * @brief Read formatted string from stdin + * @param fmt The format to be used + * @param arg The argument to be used */ # define EINA_SCANF(fmt, arg) /** * @def EINA_FORMAT - * @param fmt The format to be used. + * @brief Assign printf-like or scanf-like characteristics + * @param fmt The format to be used */ # define EINA_FORMAT(fmt) /** * @def EINA_CONST - * @brief Attribute from gcc to prevent the function to read/modify any global memory. + * @brief Definition of the attribute from gcc to prevent the function to read/modify any global memory. */ # define EINA_CONST /** * @def EINA_NOINSTRUMENT - * @brief Attribute from gcc to disable instrumentation for a specific function. + * @brief Definition of the attribute from gcc to disable instrumentation for a specific function. */ # define EINA_NOINSTRUMENT /** * @def EINA_UNLIKELY - * @param exp The expression to be used. + * @brief Give branch prediction information + * @param exp The expression to be used */ # define EINA_UNLIKELY(exp) exp /** * @def EINA_LIKELY - * @param exp The expression to be used. + * @brief Give branch prediction information + * @param exp The expression to be used */ # define EINA_LIKELY(exp) exp /** * @def EINA_SENTINEL - * @brief Attribute from gcc to prevent calls without the necessary NULL - * sentinel in certain variadic functions + * @brief Definition of the attribute from gcc to prevent calls without the necessary @c NULL + * sentinel in certain variadic functions. * @since 1.7.0 */ # define EINA_SENTINEL @@ -301,23 +290,29 @@ /** * @typedef Eina_Bool - * Type to mimic a boolean. + * @brief The boolean type to mimic a boolean. * - * @note it differs from stdbool.h as this is defined as an unsigned - * char to make it usable by bitfields (Eina_Bool name:1) and - * also take as few bytes as possible. + * @since_tizen 2.3 + * + * @remarks It differs from stdbool.h as this is defined as an unsigned + * char to make it usable by bitfields (Eina_Bool name:1) and + * also take as few bytes as possible. */ typedef unsigned char Eina_Bool; /** * @def EINA_FALSE - * boolean value FALSE (numerical value 0) + * @brief Definition of the boolean value FALSE (numerical value 0). + * + * @since_tizen 2.3 */ #define EINA_FALSE ((Eina_Bool)0) /** * @def EINA_TRUE - * boolean value TRUE (numerical value 1) + * @brief Definition of the boolean value TRUE (numerical value 1). + * + * @since_tizen 2.3 */ #define EINA_TRUE ((Eina_Bool)1) @@ -325,65 +320,69 @@ EAPI extern const unsigned int eina_prime_table[]; /** * @typedef Eina_Compare_Cb - * Function used in functions using sorting. It compares @p data1 and - * @p data2. If @p data1 is 'less' than @p data2, -1 must be returned, - * if it is 'greater', 1 must be returned, and if they are equal, 0 - * must be returned. + * + * @brief The integer type used in functions that use sorting. It compares @a data1 and + * @a data2. If @a data1 is 'less' than @a data2, @c -1 must be returned, + * if it is 'greater', @c 1 must be returned, and if they are equal, @c 0 + * must be returned. + * + * @since_tizen 2.3 */ typedef int (*Eina_Compare_Cb)(const void *data1, const void *data2); /** * @def EINA_COMPARE_CB - * Macro to cast to Eina_Compare_Cb. - */ -#define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function) - -/** - * @typedef Eina_Random_Cb - * Function used in shuffling functions. An integer betwen min and max - * inclusive must be returned. + * @brief Definition of the macro to cast to Eina_Compare_Cb. * - * @since 1.8 - */ -typedef int (*Eina_Random_Cb)(const int min, const int max); - -/** - * @def EINA_RANDOM_CB - * Macro to cast to Eina_Random_Cb. + * @since_tizen 2.3 */ -#define EINA_RANDOM_CB(function) ((Eina_Random_Cb)function) +#define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function) /** * @typedef Eina_Each_Cb - * A callback type used when iterating over a container. + * @brief The boolean type used when iterating over a container. + * + * @since_tizen 2.3 */ typedef Eina_Bool (*Eina_Each_Cb)(const void *container, void *data, void *fdata); /** * @def EINA_EACH_CB - * Macro to cast to Eina_Each. + * @brief Definition of the macro to cast to Eina_Each. + * + * @since_tizen 2.3 */ #define EINA_EACH_CB(Function) ((Eina_Each_Cb)Function) /** * @typedef Eina_Free_Cb - * A callback type used to free data when iterating over a container. + * @brief The boolean type used to free data when iterating over a container. + * + * @since_tizen 2.3 */ typedef void (*Eina_Free_Cb)(void *data); /** * @def EINA_FREE_CB - * Macro to cast to Eina_Free_Cb. + * @brief Definition of the macro to cast to Eina_Free_Cb. + * + * @since_tizen 2.3 */ #define EINA_FREE_CB(Function) ((Eina_Free_Cb)Function) /** * @def EINA_C_ARRAY_LENGTH - * Macro to return the array length of a standard c array. + * @brief Definition of the macro to return the array length of a standard C array. + * + * @code * For example: * int foo[] = { 0, 1, 2, 3 }; * would return 4 and not 4 * sizeof(int). + * @endcode + * * @since 1.2.0 + * + * @since_tizen 2.3 */ #define EINA_C_ARRAY_LENGTH(arr) (sizeof(arr) / sizeof((arr)[0])) @@ -391,8 +390,4 @@ typedef void (*Eina_Free_Cb)(void *data); * @} */ -/** - * @} - */ - #endif /* EINA_TYPES_H_ */ diff --git a/src/lib/eina/eina_unicode.h b/src/lib/eina/eina_unicode.h index e58b8532d2..b8679f1a02 100644 --- a/src/lib/eina/eina_unicode.h +++ b/src/lib/eina/eina_unicode.h @@ -7,14 +7,10 @@ #include "eina_types.h" /** - * @addtogroup Eina_Data_Types_Group Data Types + * @defgroup Eina_Unicode_String Unicode String + * @ingroup Eina_Data_Types_Group * - * @{ - */ -/** - * @addtogroup Eina_Unicode_String Unicode String - * - * @brief These functions provide basic unicode string handling + * @brief This group discusses the functions that provide basic unicode string handling. * * Eina_Unicode is a type that holds unicode codepoints. * @@ -23,176 +19,230 @@ /** * @typedef Eina_Unicode - * A type that holds Unicode codepoints. + * @brief A type that holds Unicode codepoints. */ #if EINA_SIZEOF_WCHAR_T >= 4 # include <wchar.h> typedef wchar_t Eina_Unicode; -#else +#elif defined(EINA_HAVE_INTTYPES_H) # include <inttypes.h> typedef uint32_t Eina_Unicode; +#elif defined(EINA_HAVE_STDINT_H) +# include <stdint.h> +typedef uint32_t Eina_Unicode; +#else +/* Hope that int is big enough */ +typedef unsigned int Eina_Unicode; #endif + /** * @brief Same as the standard strlen just with Eina_Unicode instead of char. + * + * @since_tizen 2.3 */ EAPI extern const Eina_Unicode *EINA_UNICODE_EMPTY_STRING; +/** + * @brief Returns the length of a Eina_Unicode string. + * + * @details This function returns the number of characters in a string. + * + * @since_tizen 2.3 + * + * @remarks If the terminating character is not found in the string, it can + * go infinite loop + * + * @param[in] ustr The string to search + * @return The number of characters + */ EAPI size_t eina_unicode_strlen(const Eina_Unicode *ustr) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; /** * @brief Returns the length of a Eina_Unicode string, up to a limit. * - * This function returns the number of characters in string, up to a maximum - * of n. If the terminating character is not found in the string, it returns - * n. + * @details This function returns the number of characters in a string, up to a maximum + * of @a n. If the terminating character is not found in the string, it returns + * @a n. + * + * @since_tizen 2.3 * - * @param ustr String to search - * @param n Max length to search - * @return Number of characters or n. + * @param[in] ustr The string to search + * @param[in] n The maximum length to search + * @return The number of characters or @a n */ EAPI size_t eina_unicode_strnlen(const Eina_Unicode *ustr, int n) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; /** * @brief Same as the standard strdup just with Eina_Unicode instead of char. + * + * @param[in] text The string to be duplicated + * @return A new string + * + * @since_tizen 2.3 */ EAPI Eina_Unicode *eina_unicode_strdup(const Eina_Unicode *text) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** - * @brief Same as strdup but cuts on the given size. Assumes n < len + * @brief Same as strdup but cuts on the given size. Assumes n < len. * - * @param text The text to duplicate. - * @param n The maximum size of the text to duplicate. - * @return The duplicated string. - * - * This function duplicates @p text. The resuting string is cut on @p - * n. @p n is assumed to be lesser (<) than the length of @p - * text. When not needed anymore, the returned string must be freed. + * @details This function duplicates @a text. The resulting string is cut on @a n. + * @a n is assumed to be lesser (<) than the length of @a + * text. When not needed anymore, the returned string must be freed. * * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] text The text to duplicate + * @param[in] n The maximum size of the text to duplicate + * @return The duplicated string + * */ EAPI Eina_Unicode *eina_unicode_strndup(const Eina_Unicode *text, size_t n) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** * @brief Same as the standard strcmp just with Eina_Unicode instead of char. + * + * @param[in] a A string to be compared + * @param[in] b A string to be compared + * @return an integer less than, equal to, or greater than zero if a is found, + * respectively, to be less than, to match, or be greater than b. + * + * @since_tizen 2.3 */ EAPI int eina_unicode_strcmp(const Eina_Unicode *a, const Eina_Unicode *b) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; /** * @brief Same as the standard strcpy just with Eina_Unicode instead of char. + * + * @param[in] dest The destination string + * @param[in] source The source string + * @return The copied string pointer + * + * @since_tizen 2.3 */ EAPI Eina_Unicode *eina_unicode_strcpy(Eina_Unicode *dest, const Eina_Unicode *source) EINA_ARG_NONNULL(1, 2); - /** * @brief Same as the standard strstr just with Eina_Unicode instead of char. + * + * @param[in] haystack The string + * @param[in] needle The substring to be found + * @return haystack is returned + * + * @since_tizen 2.3 */ EAPI Eina_Unicode *eina_unicode_strstr(const Eina_Unicode *haystack, const Eina_Unicode *needle) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; - /** * @brief Same as the standard strncpy just with Eina_Unicode instead of char. + * + * @param[in] dest The destination string + * @param[in] source The source string + * @param[in] n Bytes to be copied + * @return The copied string pointer + * + * @since_tizen 2.3 */ EAPI Eina_Unicode *eina_unicode_strncpy(Eina_Unicode *dest, const Eina_Unicode *source, size_t n) EINA_ARG_NONNULL(1, 2); /** - * @see eina_str_escape() + * @brief Escapes a unicode string. + * + * @since_tizen 2.3 * - * @param str The string to escape. - * @return The escaped string. + * @param[in] str The string to escape + * @return The escaped string + * + * @see eina_str_escape() */ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT; -/* UTF-8 Handling */ +/* UTF-8 handling */ /** - * Reads UTF8 bytes from @p buf, starting at @p iindex and returns - * the decoded code point at @p iindex offset, and advances @p iindex - * to the next code point after this. @p iindex is always advanced, - * unless if the advancement is after the @c NULL. - * On error: return a codepoint between DC80 to DCFF where the low 8 bits - * are the byte's value. + * @brief Reads UTF8 bytes from @a buf, starting at @a iindex and returns + * the decoded code point at @a iindex offset, and advances @a iindex + * to the next code point after this. @a iindex is always advanced, + * unless the advancement is after @c NULL. + * On error, return a code point between DC80 and DCFF where the lower 8 bits + * are the byte's value. * - * @param buf the string - * @param iindex the index to look at and return by. - * @return the codepoint found, 0 if @p buf or @p iindex are NULL - * @since 1.8.0 - */ -static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2); - -/** - * Reads UTF8 bytes from @p buf, starting at @p iindex and returns - * the decoded code point at @p iindex offset, and advances @p iindex - * to the next code point after this. @p iindex is always advanced, - * unless if the advancement is after the @c NULL. - * On error: return a codepoint between DC80 to DCFF where the low 8 bits - * are the byte's value. - * - * @param buf the string - * @param iindex the index to look at and return by. - * @return the codepoint found, 0 if @p buf or @p iindex are NULL * @since 1.1.0 - * @deprecated use eina_unicode_utf8_next_get + * + * @since_tizen 2.3 + * + * @param[in] buf The string + * @param[out] iindex The index to look at and return from + * @return The found code point */ -EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2) EINA_DEPRECATED; +EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2); /** - * Reads UTF8 bytes from @p buf, starting at @p iindex and returns - * the decoded code point at @p iindex offset, and moves àp iindex - * to the previous code point. @p iindex is always moved, as long - * as it's not past the start of the string. - * On error: return a codepoint between DC80 to DCFF where the low 8 bits - * are the byte's value. + * @brief Reads UTF8 bytes from @a buf, starting at @a iindex and returns + * the decoded code point at @a iindex offset, and moves @a iindex + * to the previous code point. @a iindex is always moved, as long + * as it's not past the start of the string. + * On error, return a code point between DC80 and DCFF where the lower 8 bits + * are the byte's value. * - * @param buf the string - * @param iindex the index to look at and return by. - * @return the codepoint found. * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] buf The string + * @param[out] iindex The index to look at and return from + * @return The found code point, @c 0 if @a buf or @a iindex are @c NULL */ EAPI Eina_Unicode eina_unicode_utf8_get_prev(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2); /** - * Returns the number of unicode characters in the string. That is, - * the number of Eina_Unicodes it'll take to store this string in - * an Eina_Unicode string. + * @brief Returns the number of unicode characters in the string. That is, + * the number of Eina_Unicodes it takes to store this string in + * an Eina_Unicode string. * - * @param buf the string - * @return the number of unicode characters (not bytes) in the string * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] buf The string + * @return The number of unicode characters (not bytes) in the string */ EAPI int eina_unicode_utf8_get_len(const char *buf) EINA_ARG_NONNULL(1); /** - * Converts a utf-8 string to a newly allocated Eina_Unicode string. + * @brief Converts a UTF-8 string to a newly allocated Eina_Unicode string. * - * @param utf the string in utf-8 - * @param _len the length of the returned Eina_Unicode string. - * @return the newly allocated Eina_Unicode string. * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] utf The string in UTF-8 + * @param[out] _len The length of the returned Eina_Unicode string + * @return The newly allocated Eina_Unicode string */ EAPI Eina_Unicode *eina_unicode_utf8_to_unicode(const char *utf, int *_len) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** - * Converts an Eina_Unicode string to a newly allocated utf-8 string. + * @brief Converts an Eina_Unicode string to a newly allocated UTF-8 string. * - * @param uni the Eina_Unicode string - * @param _len the length byte length of the return utf8 string. - * @return the newly allocated utf-8 string. * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @param[in] uni The Eina_Unicode string + * @param[out] _len The length of the returned UTF-8 string in bytes + * @return The newly allocated UTF-8 string */ EAPI char * eina_unicode_unicode_to_utf8(const Eina_Unicode *uni, int *_len) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; -#include "eina_inline_unicode.x" - -/** - * @} - */ /** * @} */ diff --git a/src/lib/eina/eina_ustrbuf.h b/src/lib/eina/eina_ustrbuf.h index 888d8a2989..48fd62a234 100644 --- a/src/lib/eina/eina_ustrbuf.h +++ b/src/lib/eina/eina_ustrbuf.h @@ -7,39 +7,33 @@ #include "eina_unicode.h" /** - * @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @defgroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @ingroup Eina_Data_Types_Group * - * @brief These functions provide unicode string buffers management. + * @brief This group discusses the functions that provide unicode string buffers management. * - * The Unicode String Buffer data type is designed to be a mutable string, - * allowing to append, prepend or insert a string to a buffer. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @remarks The Unicode String Buffer data type is designed to be a mutable string, + * allowing to append, prepend, or insert a string into a buffer. * * @{ */ /** * @typedef Eina_UStrbuf - * Type for a string buffer. + * @brief The structure type for a string buffer. */ typedef struct _Eina_Strbuf Eina_UStrbuf; /** - * @brief Create a new string buffer. + * @brief Creates a new string buffer. + * + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_ustrbuf_free(). * - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_ustrbuf_free(). + * @return A newly allocated string buffer instance * * @see eina_ustrbuf_free() * @see eina_ustrbuf_append() @@ -48,72 +42,88 @@ typedef struct _Eina_Strbuf Eina_UStrbuf; EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_ustrbuf_string_steal . The passed string must be malloced. + * @brief Creates a new string buffer using the passed string. The passed + * string is used directly as the buffer, it's somehow the opposite function of + * @ref eina_ustrbuf_string_steal . The passed string must be malloced. + * + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_strbuf_free(). + * + * @since 1.1.0 * - * @param str the string to manage - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_strbuf_free(). + * @param[in] str The string to manage + * @return A newly allocated string buffer instance * * @see eina_ustrbuf_free() * @see eina_ustrbuf_append() * @see eina_ustrbuf_string_get() - * @since 1.1.0 */ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Create a new string buffer using the passed string. The passed - * string is used directly as the buffer, it's somehow the opposite function of - * @ref eina_ustrbuf_string_steal . The passed string must be malloced. + * @brief Creates a new string buffer using the passed string. The passed + * string is used directly as the buffer, it's somehow the opposite function of + * @ref eina_ustrbuf_string_steal . The passed string must be malloced. + * + * @details This function creates a new string buffer. On error, @c NULL is + * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To + * free the resources, use eina_ustrbuf_free(). + * + * @since 1.2.0 * - * @param str the string to manage - * @param length the length of the string. - * @return Newly allocated string buffer instance. + * @since_tizen 2.3 * - * This function creates a new string buffer. On error, @c NULL is - * returned. To free the resources, use eina_ustrbuf_free(). + * @param[in] str The string to manage + * @param[in] length The length of the string + * @return A newly allocated string buffer instance * * @see eina_ustrbuf_manage_new() - * @since 1.2.0 */ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free a string buffer. + * @brief Frees a string buffer. + * + * @details This function frees the memory of @a buf. @a buf must have been + * created by eina_ustrbuf_new(). * - * @param buf The string buffer to free. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to free * - * This function frees the memory of @p buf. @p buf must have been - * created by eina_ustrbuf_new(). */ EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Reset a string buffer. + * @brief Resets a string buffer. + * + * @details This function resets @a buf: the buffer length is set to 0, and the + * string is set to '\\0'. No memory is freed. * - * @param buf The string buffer to reset. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to reset * - * This function reset @p buf: the buffer len is set to 0, and the - * string is set to '\\0'. No memory is free'd. */ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Append a string to a buffer, reallocating as necessary. + * @brief Appends a string to a buffer, reallocating as necessary. + * + * @details This function appends @a str to @a buf. It computes the length of + * @a str, so is slightly slower than eina_ustrbuf_append_length(). If + * the length is known beforehand, consider using that variant. If + * @a buf can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function appends @p str to @p buf. It computes the length of - * @p str, so is slightly slower than eina_ustrbuf_append_length(). If - * the length is known beforehand, consider using that variant. If - * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_ustrbuf_append() * @see eina_ustrbuf_append_length() @@ -121,35 +131,40 @@ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); /** - * @brief Append an escaped string to a buffer, reallocating as necessary. + * @brief Appends an escaped string to a buffer, reallocating as necessary. + * + * @details This function appends the escaped string @a str to @a buf. If @a str + * cannot be appended, @c EINA_FALSE is returned, otherwise, @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to append to. - * @param str The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function appends the escaped string @p str to @p buf. If @p - * str can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is - * returned. */ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a string to a buffer, reallocating as necessary, - * limited by the given length. - * - * @param buf The string buffer to append to. - * @param str The string to append. - * @param maxlen The maximum number of characters to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function appends at most @p maxlen characters of @p str to - * @p buf. It can't appends more than the length of @p str. It - * computes the length of @p str, so is slightly slower than - * eina_ustrbuf_append_length(). If the length is known beforehand, - * consider using that variant (@p maxlen should then be checked so - * that it is greater than the size of @p str). If @p str can not be - * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is - * returned. + * @brief Appends a string to a buffer, reallocating as necessary, + * limited by the given length. + * + * @details This function appends at most @a maxlen characters of @a str to + * @a buf. It can't append more than the length of @a str. It + * computes the length of @a str, so is slightly slower than + * eina_ustrbuf_append_length(). If the length is known beforehand, + * consider using that variant (@a maxlen should then be checked so + * that it is greater than the size of @a str). If @a str cannot be + * appended, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @param[in] maxlen The maximum number of characters to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_ustrbuf_append() * @see eina_ustrbuf_append_length() @@ -157,19 +172,21 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a string of exact length to a buffer, reallocating as necessary. + * @brief Appends a string of exact length to a buffer, reallocating as necessary. + * + * @details This function appends @a str to @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_ustrbuf_append() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_strngshare. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to append to. - * @param str The string to append. - * @param length The exact length to use. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function appends @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_ustrbuf_append() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_strngshare. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to append to + * @param[in] str The string to append + * @param[in] length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_ustrbuf_append() @@ -178,84 +195,98 @@ EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a character to a string buffer, reallocating as - * necessary. + * @brief Appends a character to a string buffer, reallocating as + * necessary. * - * @param buf The string buffer to append to. - * @param c The char to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE + * is returned, otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] c The char to append + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1); /** - * @brief Insert a string to a buffer, reallocating as necessary. - * - * @param buf The string buffer to insert. - * @param str The string to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function inserts @p str to @p buf at position @p pos. It - * computes the length of @p str, so is slightly slower than - * eina_ustrbuf_insert_length(). If the length is known beforehand, - * consider using that variant. If @p buf can't insert it, #EINA_FALSE - * is returned, otherwise #EINA_TRUE is returned. + * @brief Inserts a string into a buffer, reallocating as necessary. + * + * @details This function inserts @a str into @a buf at position @a pos. It + * computes the length of @a str, so is slightly slower than + * eina_ustrbuf_insert_length(). If the length is known beforehand, + * consider using that variant. If @a buf can't insert it, @c EINA_FALSE + * is returned, otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert an escaped string to a buffer, reallocating as - * necessary. + * @brief Inserts an escaped string into a buffer, reallocating as + * necessary. + * + * @details This function inserts the escaped string @a str into @a buf at + * position @a pos. If @a buf can't insert @a str, @c EINA_FALSE is + * returned, otherwise @c EINA_TRUE is returned. * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts the escaped string @p str to @p buf at - * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is - * returned, otherwise #EINA_TRUE is returned. */ EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. - * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param maxlen The maximum number of chars to insert. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This function inserts @p str ot @p buf at position @p pos, with at - * most @p maxlen bytes. The number of inserted characters can not be - * greater than the length of @p str. It computes the length of - * @p str, so is slightly slower than eina_ustrbuf_insert_length(). If the - * length is known beforehand, consider using that variant (@p maxlen - * should then be checked so that it is greater than the size of - * @p str). If @p str can not be inserted, #EINA_FALSE is returned, - * otherwise, #EINA_TRUE is returned. + * @brief Inserts a string into a buffer, reallocating as necessary. Limited by maxlen. + * + * @details This function inserts @a str into @a buf at position @a pos, with at + * most @a maxlen bytes. The number of inserted characters cannot be + * greater than the length of @a str. It computes the length of + * @a str, so is slightly slower than eina_ustrbuf_insert_length(). If the + * length is known beforehand, consider using that variant (@a maxlen + * should then be checked so that it is greater than the size of + * @a str). If @a str cannot be inserted, @c EINA_FALSE is returned, + * otherwise @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] maxlen The maximum number of characters to insert + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string of exact length to a buffer, reallocating as necessary. + * @brief Inserts a string of exact length into a buffer, reallocating as necessary. + * + * @details This function inserts @a str into @a buf. @a str must be at most of size + * @a length. It is slightly faster than eina_ustrbuf_insert() as + * it does not compute the size of @a str. It is useful when dealing + * with strings of known size, such as eina_strngshare. If @a buf + * can't insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. * - * @param buf The string buffer to insert to. - * @param str The string to insert. - * @param length The exact length to use. - * @param pos The position to insert the string. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @since_tizen 2.3 * - * This function inserts @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_ustrbuf_insert() as - * it does not compute the size of @p str. It is useful when dealing - * with strings of known size, such as eina_strngshare. If @p buf - * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. + * @param[in] buf The string buffer to insert into + * @param[in] str The string to insert + * @param[in] length The exact length to use + * @param[in] pos The position at which to insert the string + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_ustrbuf_insert() @@ -264,119 +295,142 @@ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a character to a string buffer, reallocating as - * necessary. + * @brief Inserts a character into a string buffer, reallocating as + * necessary. * - * @param buf The string buffer to insert to. - * @param c The char to insert. - * @param pos The position to insert the char. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This function inserts @a c into @a buf at position @a pos. If @a buf + * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to insert into + * @param[in] c The character to insert + * @param[in] pos The position at which to insert the char + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function inserts @p c to @p buf at position @p pos. If @p buf - * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1); /** * @def eina_ustrbuf_prepend(buf, str) - * @brief Prepend the given string to the given buffer + * @brief Prepends the given string to the given buffer. + * + * @details This macro calls eina_ustrbuf_insert() at position 0.If @a buf + * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert() at position 0.If @p buf - * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0) /** * @def eina_ustrbuf_prepend_escaped(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This macro calls eina_ustrbuf_insert_escaped() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_escaped() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0) /** * @def eina_ustrbuf_prepend_n(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. + * + * @details This macro calls eina_ustrbuf_insert_n() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @param maxlen The maximum number of Eina_Unicode *s to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @param maxlen The maximum number of Eina_Unicode characters to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_n() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0) /** * @def eina_ustrbuf_prepend_length(buf, str) - * @brief Prepend the given escaped string to the given buffer + * @brief Prepends the given escaped string to the given buffer. * - * @param buf The string buffer to prepend to. - * @param str The string to prepend. - * @param length The exact length to use. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @details This macro calls eina_ustrbuf_insert_length() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 + * + * @param buf The string buffer to prepend to + * @param str The string to prepend + * @param length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_length() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0) /** * @def eina_ustrbuf_prepend_char(buf, c) - * @brief Prepend the given unicode character to the given buffer + * @brief Prepends the given unicode character to the given buffer. + * + * @details This macro calls eina_ustrbuf_insert_Eina_Unicode *() at position 0. If + * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is + * returned. + * + * @since_tizen 2.3 * - * @param buf The string buffer to prepend to. - * @param c The Eina_Unicode character to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param c The Eina_Unicode character to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0) /** - * @brief Remove a slice of the given string buffer. + * @brief Removes a slice of the given string buffer. * - * @param buf The string buffer to remove a slice. + * @details This function removes a slice of @a buf, starting from @a start + * (inclusive) and ending at @a end (non-inclusive). Both the values are + * in bytes. It returns @c EINA_FALSE on failure, otherwise it returns @c EINA_TRUE. + * + * @since_tizen 2.3 + * + * @param buf The string buffer to remove a slice of * @param start The initial (inclusive) slice position to start - * removing, in bytes. + * removing from, in bytes * @param end The final (non-inclusive) slice position to finish - * removing, in bytes. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * removing at, in bytes. + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This function removes a slice of @p buf, starting at @p start - * (inclusive) and ending at @p end (non-inclusive). Both values are - * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. */ EAPI Eina_Bool eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); /** - * @brief Retrieve a pointer to the contents of a string buffer + * @brief Gets a pointer to the contents of a string buffer. * - * @param buf The string buffer. - * @return The current string in the string buffer. + * @details This function returns the string contained in @a buf. The returned + * value must not be modified and is longer be valid if @a buf is + * modified. In other words, any eina_ustrbuf_append() or similar + * makes that pointer invalid. * - * This function returns the string contained in @p buf. The returned - * value must not be modified and will no longer be valid if @p buf is - * modified. In other words, any eina_ustrbuf_append() or similar will - * make that pointer invalid. + * @since_tizen 2.3 + * + * @param buf The string buffer + * @return The current string in the string buffer * * @see eina_ustrbuf_string_steal() */ @@ -384,15 +438,17 @@ EAPI const Eina_Unicode * eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Steal the contents of a string buffer. + * @brief Steals the contents of a string buffer. + * + * @details This function returns the string contained in @a buf. @a buf is + * then initialized and does not own the returned string anymore. The + * caller must release the memory of the returned string by calling + * free(). * - * @param buf The string buffer to steal. - * @return The current string in the string buffer. + * @since_tizen 2.3 * - * This function returns the string contained in @p buf. @p buf is - * then initialized and does not own the returned string anymore. The - * caller must release the memory of the returned string by calling - * free(). + * @param[in] buf The string buffer to steal from + * @return The current string in the string buffer * * @see eina_ustrbuf_string_get() */ @@ -400,23 +456,29 @@ EAPI Eina_Unicode * eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** - * @brief Free the contents of a string buffer but not the buffer. + * @brief Frees the contents of a string buffer but not the buffer. * - * @param buf The string buffer to free the string of. + * @details This function frees the string contained in @a buf without freeing + * @a buf. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to free the string of * - * This function frees the string contained in @p buf without freeing - * @p buf. */ EAPI void eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Retrieve the length of the string buffer content. + * @brief Gets the length of the string buffer's content. + * + * @details This function returns the length of @a buf. + * + * @since_tizen 2.3 * - * @param buf The string buffer. - * @return The current length of the string, in bytes. + * @param[in] buf The string buffer + * @return The current length of the string, in bytes * - * This function returns the length of @p buf. */ EAPI size_t eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -425,8 +487,4 @@ eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U * @} */ -/** - * @} - */ - #endif /* EINA_STRBUF_H */ diff --git a/src/lib/eina/eina_ustringshare.h b/src/lib/eina/eina_ustringshare.h index f97f305fdf..5750693b5f 100644 --- a/src/lib/eina/eina_ustringshare.h +++ b/src/lib/eina/eina_ustringshare.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2002-2008 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -28,23 +28,23 @@ * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in - * all copies of the Software and its Copyright notices. In addition publicly - * documented acknowledgment must be given that this software has been used if no + * all copies of the Software and its Copyright notices. In addition, publicly + * documented acknowledgement must be given that this software has been used if no * source code of this software is made available publicly. This includes - * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing + * acknowledgements in either Copyright notices, Manuals, Publicity, and Marketing * documents or any documentation provided with any product containing this * software. This License does not apply to any software that links to the * libraries provided by this software (statically or dynamically), but only to * the software provided. * - * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice + * Please see OLD-COPYING.PLAIN for a plain-english explanation of this notice * and it's intent. * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS, OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER - * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER + * IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ @@ -55,12 +55,13 @@ #include "eina_unicode.h" /** - * @addtogroup Eina_UStringshare_Group Unicode Stringshare + * @defgroup Eina_UStringshare_Group Unicode Stringshare + * @ingroup Eina_Data_Types_Group Data * - * These functions allow you to store one copy of a string, and use it - * throughout your program. + * @brief This group discusses functions that allow you to store one copy of a string, and use it + * throughout your program. * - * This is a method to reduce the number of duplicated strings kept in + * This is a method to reduce the number of duplicated strings kept in the * memory. It's pretty common for the same strings to be dynamically * allocated repeatedly between applications and libraries, especially in * circumstances where you could have multiple copies of a structure that @@ -68,131 +69,163 @@ * strings, you request a read-only pointer to an existing string and * only incur the overhead of a hash lookup. * - * It sounds like micro-optimizing, but profiling has shown this can have - * a significant impact as you scale the number of copies up. It improves - * string creation/destruction speed, reduces memory use and decreases + * It sounds like micro-optimizing, but profiling has shown that this can have + * a significant impact as you scale the number of copies up. It improves the + * string creation/destruction speed, reduces memory use, and decreases * memory fragmentation, so a win all-around. * - * For more information, you can look at the @ref tutorial_ustringshare_page. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * * @{ */ /** - * @defgroup Eina_UStringshare_Group Unicode Stringshare + * @brief Retrieves an instance of a string for use in a program. * - * @{ - */ - - -/** - * @brief Retrieve an instance of a string for use in a program. + * @details This function retrieves an instance of @a str. If @a str is + * @c NULL, then @c NULL is returned. If @a str is already stored, it + * is just returned and its reference counter is increased. Otherwise + * it is added to the strings to be searched and a duplicated string + * of @a str is returned. * - * @param str The string to retrieve an instance of. - * @param slen The string size (<= strlen(str)). - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @since_tizen 2.3 * - * This function retrieves an instance of @p str. If @p str is - * @c NULL, then @c NULL is returned. If @p str is already stored, it - * is just returned and its reference counter is increased. Otherwise - * it is added to the strings to be searched and a duplicated string - * of @p str is returned. + * @remarks This function does not check the string size, but uses the + * exact given size. This can be used to share_common part of a larger + * buffer or substring. * - * This function does not check string size, but uses the - * exact given size. This can be used to share_common part of a larger - * buffer or substring. + * @param [in] str The string to retrieve an instance of + * @param [in] slen The string size (<= strlen(str)) + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_ustringshare_add() */ EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; /** - * @brief Retrieve an instance of a string for use in a program. + * @brief Retrieves an instance of a string for use in a program. * - * @param str The NULL-terminated string to retrieve an instance of. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @details This function retrieves an instance of @a str. If @a str is + * @c NULL, then @c NULL is returned. If @a str is already stored, it + * is just returned and its reference counter is increased. Otherwise + * it is added to the strings to be searched and a duplicated string + * of @a str is returned. * - * This function retrieves an instance of @p str. If @p str is - * @c NULL, then @c NULL is returned. If @p str is already stored, it - * is just returned and its reference counter is increased. Otherwise - * it is added to the strings to be searched and a duplicated string - * of @p str is returned. + * @since_tizen 2.3 * - * The string @p str must be NULL-terminated ('@\0') and its full - * length will be used. To use part of the string or non-null - * terminated, use eina_stringshare_add_length() instead. + * @remarks The string @a str must be NULL-terminated ('@\0') and its full + * length should be used. To use part of the string or non-null + * terminated, use eina_stringshare_add_length() instead. + * + * @param [in] str The NULL-terminated string to retrieve an instance of + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure * * @see eina_ustringshare_add_length() */ EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT; /** - * Increment references of the given shared string. + * @brief Increments references of the given shared string. + * + * @since_tizen 2.3 * - * @param str The shared string. - * @return A pointer to an instance of the string on success. - * @c NULL on failure. + * @remarks This is similar to eina_share_common_add(), but it's faster since it + * avoids lookups if possible, but on the down side it requires the parameter + * to be shared before, in other words, it must be the return of a previous + * eina_ustringshare_add(). * - * This is similar to eina_share_common_add(), but it's faster since it will - * avoid lookups if possible, but on the down side it requires the parameter - * to be shared before, in other words, it must be the return of a previous - * eina_ustringshare_add(). + * @remarks There is no unref since this is the work of eina_ustringshare_del(). * - * There is no unref since this is the work of eina_ustringshare_del(). + * @param[in] str The shared string + * @return A pointer to an instance of the string on success, + * otherwise @c NULL on failure */ EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str); /** - * @brief Note that the given string has lost an instance. + * @brief Notes that the given string has lost an instance. * - * @param str string The given string. + * @details This function decreases the reference counter associated to @a str + * if it exists. If that counter reaches @c 0, the memory associated to + * @a str is freed. If @a str is @c NULL, the function returns + * immediately. * - * This function decreases the reference counter associated to @p str - * if it exists. If that counter reaches 0, the memory associated to - * @p str is freed. If @p str is @c NULL, the function returns - * immediately. + * @since_tizen 2.3 * - * @note If the given pointer is not shared, bad things will happen, likely a - * segmentation fault. + * @remarks If the given pointer is not shared, bad things happen, mostly a + * segmentation fault. + * + * @param[in] str string The given string */ EAPI void eina_ustringshare_del(const Eina_Unicode *str); /** - * @brief Note that the given string @b must be shared. + * @brief Notes that the given string @b must be shared. + * + * @since_tizen 2.3 * - * @param str the shared string to know the length. It is safe to - * give @c NULL, in that case @c -1 is returned. + * @remarks This function is a cheap way to know the length of a shared + * string. * - * This function is a cheap way to known the length of a shared - * string. + * @remarks If the given pointer is not shared, bad things happen, mostly a + * segmentation fault. If in doubt, try strlen(). * - * @note If the given pointer is not shared, bad things will happen, likely a - * segmentation fault. If in doubt, try strlen(). + * @param[in] str The shared string to know the length \n + * It is safe to give @c NULL, in which case @c -1 is returned. + * @return The string length */ EAPI int eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT; /** - * @brief Dump the contents of the share_common. + * @brief Dumps the contents of share_common. * - * This function dumps all strings in the share_common to stdout with a - * DDD: prefix per line and a memory usage summary. + * @details This function dumps all the strings from share_common to stdout with a + * DDD: prefix per line and a memory usage summary. + * + * @since_tizen 2.3 */ EAPI void eina_ustringshare_dump(void); +/** + * @brief Replace the previously stringshared pointer with new content. + * + * @details The string pointed by @a p_str should be previously stringshared or + * @c NULL and it will be eina_ustringshare_del(). The new string will + * be passed to eina_ustringshare_add() and then assigned to @c *p_str. + * + * @since_tizen 2.3 + * + * @param[in] p_str pointer to the stringhare to be replaced. Must not be + * @c NULL, but @c *p_str may be @c NULL as it is a valid + * stringshare handle. + * @param[in] news new string to be stringshared, may be @c NULL. + * + * @return @c EINA_TRUE if the strings were different and thus replaced, + * @c EINA_FALSE if the strings were the same after shared. + */ static inline Eina_Bool eina_ustringshare_replace(const Eina_Unicode **p_str, const Eina_Unicode *news) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_ustringshare_replace_length(const Eina_Unicode **p_str, const Eina_Unicode *news, unsigned int slen) EINA_ARG_NONNULL(1); - -#include "eina_inline_ustringshare.x" /** - * @} + * @brief Replace the previously stringshared pointer with a new content. + * + * @details The string pointed by @a p_str should be previously stringshared or + * @c NULL and it will be eina_ustringshare_del(). The new string will + * be passed to eina_ustringshare_add_length() and then assigned to @c *p_str. + * + * @since_tizen 2.3 + * + * @param[in] p_str pointer to the stringhare to be replaced. Must not be + * @c NULL, but @c *p_str may be @c NULL as it is a valid + * stringshare handle. + * @param[in] news new string to be stringshared, may be @c NULL. + * @param[in] slen The string size (<= strlen(str)). + * + * @return @c EINA_TRUE if the strings were different and thus replaced, + * @c EINA_FALSE if the strings were the same after shared. */ +static inline Eina_Bool eina_ustringshare_replace_length(const Eina_Unicode **p_str, const Eina_Unicode *news, unsigned int slen) EINA_ARG_NONNULL(1); + +#include "eina_inline_ustringshare.x" /** * @} diff --git a/src/lib/eina/eina_value.h b/src/lib/eina/eina_value.h index a64d3b4dd8..77e3cd1b22 100644 --- a/src/lib/eina/eina_value.h +++ b/src/lib/eina/eina_value.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2012 ProFUSION embedded systems * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -28,269 +28,23 @@ #include "eina_hash.h" /** - * @page eina_value_example_01_page Eina_Value usage - * @dontinclude eina_value_01.c - * - * This very simple example shows how to use some of the basic features of eina - * value: setting and getting values, converting between types and printing a - * value as a string. - * - * Our main function starts out with the basic, declaring some variables and - * initializing eina: - * @until eina_init - * - * Now we can jump into using eina value. We set a value, get this value and - * then print it: - * @until printf - * - * In the above snippet of code we printed an @c int value, we can however print - * the value as a string: - * @until free - * - * And once done with a value it's good practice to destroy it: - * @until eina_value_flush - * - * We now reuse @c v to store a string, get its value and print it: - * @until printf - * @note Since @c s is the value and not returned by @c eina_value_to_string() - * we don't need to free it. - * - * Just because we stored a string doesn't mean we can't use the @c - * eina_value_to_string() function, we can and it's important to note that it - * will return not the stored string but rather a copy of it(one we have to - * free): - * @until eina_value_flush - * - * And now to explore conversions between two type we'll create another value: - * @until eina_value_setup - * - * And make sure @c v and @c otherv have different types: - * @until eina_value_setup - * - * We then set a value to @c v and have it converted, to do this we don't need - * to tell to which type we want to convert, we just say were we want to store - * the converted value and eina value will figure out what to convert to, and - * how: - * @until eina_value_convert - * - * And now let's check the conversion worked: - * @until printf - * - * But converting to strings is not particularly exciting, @c - * eina_value_to_string() already did that, so now let's make the conversion the - * other way around, from string to @c int: - * @until printf - * - * And once done, destroy the values: - * @until } - * - * Full source code: @ref eina_value_01_c - */ - -/** - * @page eina_value_01_c eina_value_01.c - * @include eina_value_01.c - * @example eina_value_01.c - */ - -/** - * @page eina_value_example_02_page Eina_Value struct usage - * @dontinclude eina_value_02.c - * - * This example will examine a hypothetical situation in which we had a - * structure(which represented parameters) with two fields, and then need to add - * a third field to our structure. If using structs directly we'd need to - * rewrite every piece of code that touches the struct, by using eina value, and - * thus having the compiler not even know the struct, we can reduce the amount - * of changes needed and retain interoperability between the old and new format. - * - * Our example will start with a function that creates descriptions of both of - * our structs for eina value usage. The first step is to create a struct and - * describe its members: - * @until v1_members[1] - * @note We can't pass the types of the members to EINA_VALUE_STRUCT_MEMBER - * macro because they are not constant initializers. - * - * So far it should be pretty easy to understand, we said @c My_Struct_V1 has - * two members, one of type @c int and another of type @c char. We now create - * the description of the actual struct, again nothing overly complex, we signal - * which version of EINA_VALUE_STRUCT we're using, we declare no special - * operations, our members and our size: - * @until V1_DESC - * - * We now repeat the process for the second version of our struct, the only - * difference is the addition of a third parameter of type @c int : - * @until V2_DESC - * @until } - * - * We'll now look at a function that sets the values of our structs. For - * simplicity's sake we initialize it we random values, a real world case would - * read these values from a file, a database or even from the network. The - * fundamental detail here is that this function works for both V1 and V2 - * structs, this is because setting a parameter that a struct that doesn't have - * does nothing without throwing any errors: - * @until } - * @note While using eina_value_struct_set() with an in-existing parameter - * causes no error, it does return #EINA_FALSE, to notify it was not possible - * to set the value. This could be used to determine that we're handling a V1 - * struct and take some action based on that. - * - * The next thing is to do is see what a function that uses the values of the - * struct looks like. We'll again be very simplistic in our usage, we'll just - * print the values, but a real world case, might send these values to another - * process use them to open a network/database connection or anything else. - * Since all versions of the struct have @c param1 and @c param2 we'll - * unconditionally use them: - * @until printf - * - * The next step is to conditionally use @c param3, which can fortunately be - * done in the same step in which we get it's value: - * @until } - * - * There we've now got functions that can both populate and use values from both - * our structs, so now let's actually use them in our main function by creating - * a struct of each type, initializing them and them using them: - * @until } - * - * This concludes our example. For the full source code see @ref - * eina_value_02_c. - */ - -/** - * @page eina_value_02_c eina_value_02.c - * @include eina_value_02.c - * @example eina_value_02.c - */ - -/** - * @page eina_value_example_03_page Eina value custom type example - * @dontinclude eina_value_03.c - * - * For this example we'll be creating our own custom type of eina value. Eina - * value can already store struct timeval(man gettimeofday for more information) - * but it has no type to store struct timezone, so that's what this example will - * do. - * @note struct timezone is actually obsolete, so using it in real world - * programs is probably not a good idea, but this is an example so, bear with - * us. - * - * To create our own custom eina value type we need to define functions to - * do the following operations on it: - * @li Setup - * @li Flush - * @li Copy - * @li Compare - * @li Set - * @li Get - * @li Conversion - * - * Most of this functions are very simple, so let's look at them, starting with - * setup which only clear the memory so that we can be certain we won't be using - * stale data: - * @until } - * - * Now the flush function, which is even simpler, it does nothing, that's - * because there is nothing we need to do, all the necessary steps are taken by - * eina value itself: - * @until } - * - * Our next function, copy, is a bit more interesting, but not much, it just - * casts our void pointers to struct timezone pointers and does the copy: - * @until } - * @note By now you might be wondering why our functions receive void pointers - * instead of pointers to struct timezone, and this is a good point. The reason - * for this is that eina value doesn't know anything about our type so it must - * use a generic void pointer, casting that pointer into a proper value is the - * job of the implementor of the new type. - * - * Next we have the comparison function, which compares the @c tz_minuteswest - * field of struct timezone, we don't compare @c tz_dsttime because that field - * is not used in linux: - * @until } - * - * Next we have setting, this however requires not one but rather two functions, - * the reason for this is because to be able to receive arguments of any type - * eina value uses <a href="https://wikipedia.org/wiki/Variadic_functions"> - * variadic functions</a>, so we need a function to get the argument from a - * va_list and another to actually to the setting. - * - * Lets first look at the pset function which sets the received value to a - * pointer: - * @until } - * - * Next we have the vset function which get the argument from the va_list and - * passes it to the pset function: - * @until } - * - * And now the function to get the value, a very simple copying of the value to - * the given pointer: - * @until } - * - * And finally our conversion function, this is our longest and most interesting - * one. For numeric type we simply assign the value of @c tz_minuteswest to the - * new type and call a set function using it: - * @until EINA_VALUE_TYPE_DOUBLE - * @until return - * @note It would be a good idea to add checks for over and underflow for these - * types and return #EINA_FALSE in thoses cases, we omit this here for brevity. - * - * For string types we use @c snprintf() to format our @c tz_minuteswest field - * and put it in a string(again @c tz_dsttime is ignored because it's not used): - * @until } - * - * Finally we handle any other types by returning an error in that case: - * @until } - * - * Now that we have all the functions, we can populate an @c Eina_Value_Type to - * later use it with @c eina_value_setup(): - * @until } - * - * We can now finally use our new TZ_TYPE with eina value, so lets conclude our - * example by practicing that by setting its value and printing it: - * @until } - * - * For the full source code see @ref eina_value_03_c. - */ - -/** - * @page eina_value_03_c eina_value_03.c - * @include eina_value_03.c - * @example eina_value_03.c - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @since 1.2 - * - * @{ - */ - -/** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** + * @internal * @defgroup Eina_Value_Group Generic Value Storage + * @ingroup Eina_Containers_Group * - * Abstracts generic data storage and access to it in an extensible - * and efficient way. + * @since 1.2 * - * It comes with pre-defined types for numbers, array, list, hash, - * blob and structs. It is able to convert between data types, - * including to string. + * @brief Abstracts generic data storage and access to it in an extensible + * and efficient way. * - * It is meant for simple data types, providing uniform access and - * release functions, useful to exchange data preserving their - * types. For more complex hierarchical data, with properties and - * children, reference counting, inheritance and interfaces, + * @remarks It comes with pre-defined types for numbers, array, list, hash, + * blob, and structs. It is able to convert between data types, + * including string. * - * Examples of usage of the Eina_Value API: - * @li @ref eina_value_example_01_page - * @li @ref eina_value_example_02_page - * @li @ref eina_value_example_03_page + * It is meant for simple data types, providing uniform access and + * release functions, useful to exchange data by preserving their + * types. For more complex hierarchical data, with properties and + * children, reference counting, inheritance, and interfaces are also included. * * @{ */ @@ -298,58 +52,67 @@ /** * @typedef Eina_Value - * Store generic values. + * @brief The structure type that stores generic values. * * @since 1.2 + * + * @since_tizen 2.3 */ typedef struct _Eina_Value Eina_Value; /** * @typedef Eina_Value_Type - * Describes the data contained by the value + * @brief The strcuture type that describes the data contained by the value. * * @since 1.2 + * + * @since_tizen 2.3 */ typedef struct _Eina_Value_Type Eina_Value_Type; /** * @typedef Eina_Value_Union - * Union of all known value types. + * @brief Union of all known value types. * - * This is only used to specify the minimum payload memory for #Eina_Value. + * @remarks This is only used to specify the minimum payload memory for #Eina_Value. * - * @internal * @since 1.2 + * + * @since_tizen 2.3 */ typedef union _Eina_Value_Union Eina_Value_Union; /** + * @internal * @union _Eina_Value_Union - * All possible value types. + * @brief All possible value types. * - * This is only used to specify the minimum payload memory for #Eina_Value. + * @remarks This is only used to specify the minimum payload memory for #Eina_Value. * - * @internal * @since 1.2 + * + * @since_tizen 2.3 */ union _Eina_Value_Union { - unsigned char buf[8]; /**< just hold 8-bytes, more goes into ptr */ - void *ptr; /**< used as generic pointer */ - uint64_t _guarantee; /**< guarantees 8-byte alignment */ + unsigned char buf[8]; /**< Just hold 8-bytes, more goes into ptr */ + void *ptr; /**< Used as a generic pointer */ + uint64_t _guarantee; /**< Guarantees 8-byte alignment */ }; /** * @var EINA_VALUE_TYPE_UCHAR - * manages unsigned char type. + * @brief Manages unsigned char type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UCHAR; /** * @var EINA_VALUE_TYPE_USHORT - * manages unsigned short type. + * @brief Manages unsigned short type. * * @since 1.2 */ @@ -357,15 +120,17 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_USHORT; /** * @var EINA_VALUE_TYPE_UINT - * manages unsigned int type. + * @brief Manages unsigned int type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT; /** * @var EINA_VALUE_TYPE_ULONG - * manages unsigned long type. + * @brief Manages unsigned long type. * * @since 1.2 */ @@ -373,16 +138,18 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ULONG; /** * @var EINA_VALUE_TYPE_TIMESTAMP - * manages unsigned long type used for timestamps. - * @note this is identical in function to EINA_VALUE_TYPE_ULONG + * @brief Manages unsigned long type used for timestamps. + * @remarks This is identical in function to @c EINA_VALUE_TYPE_ULONG. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMESTAMP; /** * @var EINA_VALUE_TYPE_UINT64 - * manages unsigned integer of 64 bits type. + * @brief Manages unsigned integer of 64 bits type. * * @since 1.2 */ @@ -390,15 +157,17 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_UINT64; /** * @var EINA_VALUE_TYPE_CHAR - * manages char type. + * @brief Manages char type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_CHAR; /** * @var EINA_VALUE_TYPE_SHORT - * manages short type. + * @brief Manages short type. * * @since 1.2 */ @@ -406,15 +175,17 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_SHORT; /** * @var EINA_VALUE_TYPE_INT - * manages int type. + * @brief Manages int type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT; /** * @var EINA_VALUE_TYPE_LONG - * manages long type. + * @brief Manages long type. * * @since 1.2 */ @@ -422,15 +193,17 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LONG; /** * @var EINA_VALUE_TYPE_INT64 - * manages integer of 64 bits type. + * @brief Manages integer of 64 bits type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_INT64; /** * @var EINA_VALUE_TYPE_FLOAT - * manages float type. + * @brief Manages float type. * * @since 1.2 */ @@ -438,15 +211,17 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_FLOAT; /** * @var EINA_VALUE_TYPE_DOUBLE - * manages double type. + * @brief Manages double type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_DOUBLE; /** * @var EINA_VALUE_TYPE_STRINGSHARE - * manages stringshared string type. + * @brief Manages stringshared string type. * * @since 1.2 */ @@ -454,9 +229,11 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRINGSHARE; /** * @var EINA_VALUE_TYPE_STRING - * manages string type. + * @brief Manages string type. * * @since 1.2 + * + * @since_tizen 2.3 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRING; @@ -464,263 +241,314 @@ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRING; /** * @var EINA_VALUE_TYPE_ARRAY * - * manages array type. Use the value get/set for arrays: + * @brief Manages array type. Use the value get/set for arrays: * @li eina_value_array_get() and eina_value_array_set() * @li eina_value_array_vget() and eina_value_array_vset() * @li eina_value_array_pget() and eina_value_array_pset() * - * eina_value_set() takes an #Eina_Value_Array where just @c subtype - * and @c step are used. If there is an @c array, it will be copied - * (including each item) and its contents must be properly - * configurable as @c subtype expects. eina_value_pset() takes a - * pointer to an #Eina_Value_Array. For your convenience, use - * eina_value_array_setup(). + * @since 1.2 * - * eina_value_get() and eina_value_pget() takes a pointer - * to #Eina_Value_Array, it's an exact copy of the current structure in - * use by value, no copies are done. + * @since_tizen 2.3 * - * @since 1.2 + * @remarks eina_value_set() takes an #Eina_Value_Array where just @c subtype + * and @c step are used. If there is an @c array, it is copied + * (including each item) and its contents must be properly + * configurable as @c subtype expects. eina_value_pset() takes a + * pointer to an #Eina_Value_Array. For your convenience, use + * eina_value_array_setup(). + * + * @remarks eina_value_get() and eina_value_pget() take a pointer + * to #Eina_Value_Array, it's an exact copy of the current structure in + * use by value, no copies are done. */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_ARRAY; /** * @var EINA_VALUE_TYPE_LIST * - * manages list type. Use the value get/set for lists: + * @brief Manages list type. Use the value get/set for lists: * @li eina_value_list_get() and eina_value_list_set() * @li eina_value_list_vget() and eina_value_list_vset() * @li eina_value_list_pget() and eina_value_list_pset() * - * eina_value_set() takes an #Eina_Value_List where just @c subtype is - * used. If there is an @c list, it will be copied (including each - * item) and its contents must be properly configurable as @c - * subtype expects. eina_value_pset() takes a pointer to an #Eina_Value_List. - * For your convenience, use eina_value_list_setup(). + * @since 1.2 * - * eina_value_get() and eina_value_pget() takes a pointer to #Eina_Value_List, - * it's an exact copy of the current structure in use by value, no copies are - * done. + * @since_tizen 2.3 * - * @since 1.2 + * @remarks eina_value_set() takes an #Eina_Value_List where just @c subtype is + * used. If there is a @c list, it is copied (including each + * item) and its contents must be properly configurable as @c + * subtype expects. eina_value_pset() takes a pointer to an #Eina_Value_List. + * For your convenience, use eina_value_list_setup(). + * + * @remarks eina_value_get() and eina_value_pget() take a pointer to #Eina_Value_List, + * it's an exact copy of the current structure in use by value, no copies are + * done. */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_LIST; /** * @var EINA_VALUE_TYPE_HASH * - * manages hash type. Use the value get/set for hashes: + * @brief Manages hash type. Use the value get/set for hashes: * @li eina_value_hash_get() and eina_value_hash_set() * @li eina_value_hash_vget() and eina_value_hash_vset() * @li eina_value_hash_pget() and eina_value_hash_pset() * - * eina_value_set() takes an #Eina_Value_Hash where just @c subtype - * and @c buckets_power_size are used. If there is an @c hash, it will - * be copied (including each item) and its contents must be - * properly configurable as @c subtype expects. eina_value_pset() - * takes a pointer to an #Eina_Value_Hash. For your convenience, use - * eina_value_hash_setup(). + * @since 1.2 + * + * @since_tizen 2.3 * - * eina_value_get() and eina_value_pget() takes a pointer to #Eina_Value_Hash, - * it's an exact copy of the current structure in use by value, no copies are - * done. + * @remarks eina_value_set() takes an #Eina_Value_Hash where just @c subtype + * and @c buckets_power_size are used. If there is an @c hash, it is + * copied (including each item) and its contents must be + * properly configurable as @c subtype expects. eina_value_pset() + * takes a pointer to an #Eina_Value_Hash. For your convenience, use + * eina_value_hash_setup(). * - * @note be aware that hash data is always an allocated memory of size - * defined by @c subtype->value_size. If your @c subtype is an - * integer, add as data malloc(sizeof(int)). If your @c subtype - * is an string, add as data malloc(sizeof(char*)) and this data - * value must point to strdup(string)! + * @remarks eina_value_get() and eina_value_pget() take a pointer to #Eina_Value_Hash, + * it's an exact copy of the current structure in use by value, no copies are + * done. * - * @since 1.2 + * @remarks Be aware that hash data is always an allocated memory of size + * defined by @c subtype->value_size. If your @c subtype is an + * integer, add as data malloc(sizeof(int)). If your @c subtype + * is a string, add as data malloc(sizeof(char*)) and this data + * value must point to strdup(string). */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_HASH; /** * @var EINA_VALUE_TYPE_TIMEVAL - * manages 'struct timeval' type + * @brief Manages 'struct timeval' type. * - * eina_value_set() takes a "struct timeval" from sys/time.h. - * eina_value_pset() takes a pointer to "struct timeval". + * @since 1.2 * - * eina_value_get() and eina_value_pget() takes a pointer to "struct - * timeval" and it's an exact copy of value. + * @since_tizen 2.3 * - * @since 1.2 + * @remarks eina_value_set() takes a "struct timeval" from sys/time.h. + * eina_value_pset() takes a pointer to "struct timeval". + * + * @remarks eina_value_get() and eina_value_pget() take a pointer to "struct + * timeval" and it's an exact copy of the value. */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_TIMEVAL; /** * @var EINA_VALUE_TYPE_BLOB - * manages blob of bytes type, see @ref Eina_Value_Blob + * @brief Manages blob of bytes type, see @ref Eina_Value_Blob * - * eina_value_set() takes an #Eina_Value_Blob - * eina_value_pset() takes a pointer to #Eina_Value_Blob. + * @since 1.2 * - * eina_value_get() and eina_value_pget() takes a pointer to #Eina_Value_Blob - * and it's an exact copy of value, no allocations are made. + * @since_tizen 2.3 * - * Memory is untouched unless you provide @c ops (operations) pointer. + * @remarks eina_value_set() takes an #Eina_Value_Blob + * eina_value_pset() takes a pointer to #Eina_Value_Blob. + * + * @remarks eina_value_get() and eina_value_pget() take a pointer to #Eina_Value_Blob + * and it's an exact copy of value, no allocations are made. + * + * @remarks Memory is untouched unless you provide an @c ops (operations) pointer. * - * @since 1.2 */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_BLOB; /** * @var EINA_VALUE_TYPE_STRUCT * - * manages struct type. Use the value get/set for structs: + * @brief Manages struct type. Use the value get/set for structs: * @li eina_value_struct_get() and eina_value_struct_set() * @li eina_value_struct_vget() and eina_value_struct_vset() * @li eina_value_struct_pget() and eina_value_struct_pset() * - * eina_value_set() takes an #Eina_Value_Struct where just @c desc is - * used. If there is an @c memory, it will be copied (including each - * member) and its contents must be properly configurable as @c desc - * expects. eina_value_pset() takes a pointer to an #Eina_Value_Struct. For - * your convenience, use eina_value_struct_setup(). + * @since 1.2 * - * eina_value_get() and eina_value_pget() takes a pointer - * to #Eina_Value_Struct, it's an exact copy of the current structure in - * use by value, no copies are done. + * @since_tizen 2.3 * - * @since 1.2 + * @remarks eina_value_set() takes an #Eina_Value_Struct where just @c desc is + * used. If there is a @c memory, it is copied (including each + * member) and its contents must be properly configurable as @c desc + * expects. eina_value_pset() takes a pointer to an #Eina_Value_Struct. For + * your convenience, use eina_value_struct_setup(). + * + * @remarks eina_value_get() and eina_value_pget() take a pointer + * to #Eina_Value_Struct, it's an exact copy of the current structure in + * use by value, no copies are done. */ EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_STRUCT; -EAPI extern Eina_Error EINA_ERROR_VALUE_FAILED; +/** + * @var EINA_ERROR_VALUE_FAILED + * @brief Error identifier corresponding to a value check failure. + * + * @since 1.2 + * + * @since_tizen 2.3 + */ +EAPI extern int EINA_ERROR_VALUE_FAILED; /** + * @internal * @defgroup Eina_Value_Value_Group Generic Value management * * @{ */ /** + * @internal * @struct _Eina_Value - * defines the contents of a value + * @brief The structure type defining the contents of a value. * * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value { - const Eina_Value_Type *type; /**< how to access values */ - Eina_Value_Union value; /**< to be accessed with type descriptor */ + const Eina_Value_Type *type; /**< How to access values */ + Eina_Value_Union value; /**< To be accessed with type descriptor */ }; /** - * @brief Create generic value storage. - * @param type how to manage this value. - * @return The new value or @c NULL on failure. + * @brief Creates a generic value storage. * - * Create a new generic value storage. The members are managed using - * the description specified by @a type. + * @details This creates a new generic value storage. The members are managed using + * the description specified by @a type. * - * Some types may specify more operations: - * eg. #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), - * eina_value_array_get() and so on. + * Some types may specify more operations: + * eg. #EINA_VALUE_TYPE_ARRAY uses eina_value_array_set(), + * eina_value_array_get(), and so on. * - * On failure, @c NULL is returned. + * On failure, @c NULL is returned and either #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. * - * @note this calls creates from mempool and then uses - * eina_value_setup(). Consider using eina_value_flush() and - * eina_value_setup() instead to avoid memory allocations. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks This call creates from mempool and then uses + * eina_value_setup(). Consider using eina_value_flush() and + * eina_value_setup() instead to avoid memory allocations. + * + * @param[in] type The type used to manage this value + * @return The new value, otherwise @c NULL on failure * * @see eina_value_free() * - * @since 1.2 */ EAPI Eina_Value *eina_value_new(const Eina_Value_Type *type) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free value and its data. - * @param value value object - * - * @see eina_value_flush() + * @brief Frees a value and its data. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * + * @see eina_value_flush() */ -EAPI void eina_value_free(Eina_Value *value); +EAPI void eina_value_free(Eina_Value *value) EINA_ARG_NONNULL(1); /** - * @brief Initialize generic value storage. - * @param value value object - * @param type how to manage this value. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes a generic value storage. * - * Initializes existing generic value storage. The members are managed using the - * description specified by @a type. + * @details This initializes an existing generic value storage. The members are managed using the + * description specified by @a type. * - * Some types may specify more operations, as an example #EINA_VALUE_TYPE_ARRAY - * uses eina_value_array_set(), eina_value_array_get() and so on. + * Some types may specify more operations, as an example #EINA_VALUE_TYPE_ARRAY + * uses eina_value_array_set(), eina_value_array_get(), and so on. * - * @note Existing contents are ignored! If the value was previously used, then - * use eina_value_flush() first. + * On failure, @c EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. * - * On failure, #EINA_FALSE is returned. + * @since 1.2 * - * @see eina_value_flush() + * @since_tizen 2.3 * - * @since 1.2 + * @remarks Existing contents are ignored. If the value is previously used, then + * use eina_value_flush() first. + * + * @param[in] value The value object + * @param[in] type The type used to manage this value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * + * @see eina_value_flush() */ static inline Eina_Bool eina_value_setup(Eina_Value *value, const Eina_Value_Type *type) EINA_ARG_NONNULL(1, 2); /** - * @brief Create generic value storage. - * @param value value object + * @brief Creates a generic value storage. + * + * @details This releases all the resources associated with an #Eina_Value. The + * value must be already set with eina_value_setup() or + * eina_value_new(). * - * Releases all the resources associated with an #Eina_Value. The - * value must be already set with eina_value_setup() or - * eina_value_new(). + * After this call returns, the contents of the value are undefined, + * but the value can be reused by calling eina_value_setup() again. * - * After this call returns, the contents of the value are undefined, - * but the value can be reused by calling eina_value_setup() again. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object * * @see eina_value_setup() * @see eina_value_free() * - * @since 1.2 */ static inline void eina_value_flush(Eina_Value *value) EINA_ARG_NONNULL(1); /** - * @brief Copy generic value storage. - * @param value source value object - * @param copy destination value object - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Copies a generic value storage. * - * The @a copy object is considered uninitialized and its existing - * contents are overwritten (just as if eina_value_flush() was called on - * it). + * @since 1.2 * - * The copy happens by calling eina_value_setup() on @a copy, followed - * by getting the contents of @a value and setting it to @a copy. + * @since_tizen 2.3 + * + * + * @remarks The @a copy object is considered uninitialized and its existing + * contents are overwritten (just as if eina_value_flush() is called on + * it). + * + * The copy happens by calling eina_value_setup() on @a copy, followed + * by getting the contents of @a value and setting it to @a copy. + * + * @param[in] value The source value object + * @param[in] copy The destination value object + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @since 1.2 */ EAPI Eina_Bool eina_value_copy(const Eina_Value *value, Eina_Value *copy) EINA_ARG_NONNULL(1, 2); /** - * @brief Compare generic value storage. - * @param a left side of comparison - * @param b right side of comparison - * @return less than zero if a < b, greater than zero if a > b, zero - * if a == b + * @brief Compares a generic value storage. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] a The left side of comparison + * @param[in] b The right side of comparison + * @return Less than zero if a < b, greater than zero if a > b, zero + * if a == b */ static inline int eina_value_compare(const Eina_Value *a, const Eina_Value *b) EINA_ARG_NONNULL(1, 2); /** - * @brief Set the generic value. - * @param value source value object - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets the generic value. * - * The variable argument is dependent on chosen type. The list for - * basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -757,31 +585,35 @@ static inline int eina_value_compare(const Eina_Value *a, * eina_value_free(value); * @endcode * - * @note for array member see eina_value_array_set() - * @note for list member see eina_value_list_set() - * @note for hash member see eina_value_hash_set() + * @remarks For array member see eina_value_array_set(). + * @remarks For list member see eina_value_list_set(). + * @remarks For hash member see eina_value_hash_set(). + * + * @param[in] value The source value object + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_get() * @see eina_value_vset() * @see eina_value_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_set(Eina_Value *value, ...) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value. - * @param value source value object - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. * - * The variable argument is dependent on chosen type. The list for - * basic types: + * @remarks The variable argument is dependent on the chosen type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -821,70 +653,79 @@ static inline Eina_Bool eina_value_set(Eina_Value *value, * eina_value_free(value); * @endcode * - * @note for array member see eina_value_array_get() - * @note for list member see eina_value_list_get() - * @note for hash member see eina_value_hash_get() + * @remarks For array member see eina_value_array_get(). + * @remarks For list member see eina_value_list_get(). + * @remarks For hash member see eina_value_hash_get(). + * + * @param[in] value The source value object + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_set() * @see eina_value_vset() * @see eina_value_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_get(const Eina_Value *value, ...) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value. - * @param value source value object - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks For array member see eina_value_array_vset(). + * @remarks For list member see eina_value_list_vset(). + * @remarks For hash member see eina_value_hash_vset(). * - * @note for array member see eina_value_array_vset() - * @note for list member see eina_value_list_vset() - * @note for hash member see eina_value_hash_vset() + * @param[in] value The source value object + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_vget() * @see eina_value_set() * @see eina_value_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_vset(Eina_Value *value, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value. - * @param value source value object - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value. * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @since 1.2 * - * @note for array member see eina_value_array_vget() - * @note for list member see eina_value_list_vget() - * @note for hash member see eina_value_hash_vget() + * @since_tizen 2.3 + * + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. + * + * @remarks For array member see eina_value_array_vget(). + * @remarks For list member see eina_value_list_vget(). + * @remarks For hash member see eina_value_hash_vget(). + * + * @param[in] value The source value object + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_vset() * @see eina_value_get() * @see eina_value_pget() - * - * @since 1.2 */ static inline Eina_Bool eina_value_vget(const Eina_Value *value, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value from pointer. - * @param value source value object - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a pointer. + * + * @since 1.2 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -907,8 +748,8 @@ static inline Eina_Bool eina_value_vget(const Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by the + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_new(EINA_VALUE_TYPE_INT); @@ -925,32 +766,35 @@ static inline Eina_Bool eina_value_vget(const Eina_Value *value, * eina_value_free(value); * @endcode * - * @note for array member see eina_value_array_pset() - * @note for list member see eina_value_list_pset() - * @note for hash member see eina_value_hash_pset() + * @remarks For array member see eina_value_array_pset(). + * @remarks For list member see eina_value_list_pset(). + * @remarks For hash member see eina_value_hash_pset(). + * + * @param[in] value The source value object + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise EINA_FALSE * * @see eina_value_pget() * @see eina_value_set() * @see eina_value_vset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_pset(Eina_Value *value, const void *ptr) EINA_ARG_NONNULL(1, 2); /** - * @brief Get the generic value to pointer. - * @param value source value object - * @param ptr pointer to receive the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a pointer. + * + * @since 1.2 * - * The value is returned in pointer contents, the actual value is - * type-dependent, but usually it will be what is stored inside the - * object. There shouldn't be any memory allocation, thus the contents - * should @b not be freed. + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The value is returned as pointer contents, the actual value is + * type-dependent, but usually it is what is stored inside the + * object. There shouldn't be any memory allocation, thus the contents + * should @b not be freed. + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -990,66 +834,81 @@ static inline Eina_Bool eina_value_pset(Eina_Value *value, * eina_value_free(value); * @endcode * - * @note for array member see eina_value_array_get() - * @note for list member see eina_value_list_get() - * @note for hash member see eina_value_hash_get() + * @remarks For array member see eina_value_array_get(). + * @remarks For list member see eina_value_list_get(). + * @remarks For hash member see eina_value_hash_get(). + * + * @param[in] value The source value object + * @param[in] ptr A pointer to receive the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_set() * @see eina_value_vset() * @see eina_value_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_pget(const Eina_Value *value, void *ptr) EINA_ARG_NONNULL(1, 2); /** - * @brief Convert one value to another type. - * @param value source value object. - * @param convert destination value object. - * @return #EINA_TRUE if converted, #EINA_FALSE otherwise. + * @brief Converts one value type to another. * - * Converts one value to another trying first @a value type - * @c convert_to() function. If unsuccessful, tries using @c convert_from() - * function in @a convert. + * @details This converts one value to another by first trying the @a value type + * using the @c convert_to() function. If unsuccessful, it tries using the @c convert_from() + * function with the @a convert type. * - * Conversion functions are type defined, and the basic types can convert - * between themselves, but conversion is strict! That is, if - * converting from negative value to unsigned type, it will fail. It - * also fails on value overflow. + * @since 1.2 * - * It is recommended that all types implement at least convert to - * string, used by eina_value_to_string(). + * @since_tizen 2.3 * - * @note Both objects must have eina_value_setup() called on them beforehand! + * @remarks Conversion functions are type defined, and the basic types can convert + * between themselves, but conversion is strict. That is, when + * converting from a negative value to an unsigned type, it fails. It + * also fails on value overflow. + * + * @remarks It is recommended that all types implement at least convert to + * string, used by eina_value_to_string(). + * + * @remarks Both objects must have eina_value_setup() called on them beforehand. + * + * @param[in] value The source value object. + * @param[in] convert The destination value object. + * @return @c EINA_TRUE if converted, otherwise @c EINA_FALSE * - * @since 1.2 */ EAPI Eina_Bool eina_value_convert(const Eina_Value *value, Eina_Value *convert) EINA_ARG_NONNULL(1, 2); /** - * @brief Convert value to string. - * @param value value object. - * @return newly allocated memory or @c NULL on failure. + * @brief Converts a value to the string type. * - * @see eina_value_convert() * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @return The newly allocated memory, otherwise @c NULL on failure + * + * @see eina_value_convert() */ EAPI char *eina_value_to_string(const Eina_Value *value) EINA_ARG_NONNULL(1); /** - * @brief Query value type. - * @param value value object. - * @return type instance or @c NULL if type is invalid. + * @brief Queries a value type. * - * Check if value type is valid and returns it. A type is invalid if - * it does not exist or if it is using a different version field. + * @details This checks whether the value type is valid and returns that value type. A type is invalid if + * it does not exist or if it is using a different version field. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @return The type instance, otherwise @c NULL if the type is invalid * * @see eina_value_type_check() * - * @since 1.2 */ static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -1059,6 +918,7 @@ static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value /** + * @internal * @defgroup Eina_Value_Array_Group Generic Value Array management * * @{ @@ -1067,98 +927,124 @@ static inline const Eina_Value_Type *eina_value_type_get(const Eina_Value *value /** * @typedef Eina_Value_Array - * Value type for #EINA_VALUE_TYPE_ARRAY. + * @brief The structure type defining the value type for #EINA_VALUE_TYPE_ARRAY. * - * @see #_Eina_Value_Array explains fields. * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_Array explains fields. */ typedef struct _Eina_Value_Array Eina_Value_Array; /** + * @internal * @struct _Eina_Value_Array - * Used to store the array and its subtype. + * The structure type used to store the array and its subtype. * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_Array { - const Eina_Value_Type *subtype; /**< how to allocate and access items */ - unsigned int step; /**< how to grow the members array */ - Eina_Inarray *array; /**< the array that holds data, members are of subtype->value_size bytes. */ + const Eina_Value_Type *subtype; /**< How to allocate and access items */ + unsigned int step; /**< How to grow the members array */ + Eina_Inarray *array; /**< The array that holds data, members are of subtype->value_size bytes */ }; /** - * @brief Create generic value storage of type array. - * @param subtype how to manage this array members. - * @param step how to grow the members array. - * @return The new value or @c NULL on failure. - * - * Create a new generic value storage of type array. The members are - * managed using the description specified by @a subtype. + * @brief Creates a generic value storage of type array. * - * On failure, @c NULL is returned. + * @details This creates a new generic value storage of type array. The members are + * managed using the description specified by @a subtype. * - * @note this creates from mempool and then uses - * eina_value_array_setup(). @see eina_value_free() @see - * eina_value_array_setup() + * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks This creates from the mempool and then uses + * eina_value_array_setup(). + * + * @param subtype The subtype to manage these array members + * @param step The step value used to make the members array grow + * @return The new value, otherwise @c NULL on failure + * + * @see eina_value_free() + * @see eina_value_array_setup() */ EAPI Eina_Value *eina_value_array_new(const Eina_Value_Type *subtype, unsigned int step) EINA_ARG_NONNULL(1); /** - * @brief Initialize generic value storage of type array. - * @param value value object - * @param subtype how to manage array members. - * @param step how to grow the members array. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes a generic value storage of type array. * - * Initializes new generic value storage of type array with the given - * @a subtype. + * @details This initializes a new generic value storage of type array with the given + * @a subtype. + * + * This is same as calling eina_value_set() + * with #EINA_VALUE_TYPE_ARRAY followed by eina_value_pset() with + * the #Eina_Value_Array description configured. + * + * On failure, @c EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. + * + * @since 1.2 * - * This is the same as calling eina_value_set() - * with #EINA_VALUE_TYPE_ARRAY followed by eina_value_pset() with - * the #Eina_Value_Array description configured. + * @since_tizen 2.3 * - * @note Existing contents are ignored! If the value was previously used, then - * use eina_value_flush() first. + * @remarks Existing contents are ignored. If the value is previously used, then + * use eina_value_flush() first. * - * On failure, #EINA_FALSE is returned. + * @param[in] value The value object + * @param[in] subtype how to manage array members. + * @param[in] step The step value used to make the members array grow + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_flush() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_setup(Eina_Value *value, const Eina_Value_Type *subtype, unsigned int step) EINA_ARG_NONNULL(1, 2); /** - * @brief Query number of elements in value of array type. - * @param value value object. - * @return number of child elements. + * @brief Queries the number of elements in a value of array type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @return The number of child elements */ static inline unsigned int eina_value_array_count(const Eina_Value *value); /** - * @brief Remove element at given position in value of array type. - * @param value value object. - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Removes the element at the given position in a value of array type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_array_remove(Eina_Value *value, unsigned int position) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an array member. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for an array member. + * + * @since 1.2 * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1191,6 +1077,10 @@ static inline Eina_Bool eina_value_array_remove(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_get() * @see eina_value_array_vset() * @see eina_value_array_pset() @@ -1201,25 +1091,25 @@ static inline Eina_Bool eina_value_array_remove(Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_set(Eina_Value *value, unsigned int position, ...) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an array member. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from an array member. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in the variable argument parameter, and the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation; - * thus the contents should @b not be freed. + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation; + * thus the contents should @b not be freed. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1251,24 +1141,28 @@ static inline Eina_Bool eina_value_array_set(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_vset() * @see eina_value_array_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_get(const Eina_Value *value, unsigned int position, ...) EINA_ARG_NONNULL(1); /** - * @brief Insert a generic value in an array member position. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at an array member position. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1300,6 +1194,10 @@ static inline Eina_Bool eina_value_array_get(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1310,7 +1208,6 @@ static inline Eina_Bool eina_value_array_get(const Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_insert(Eina_Value *value, unsigned int position, @@ -1318,12 +1215,14 @@ static inline Eina_Bool eina_value_array_insert(Eina_Value *value, /** - * @brief Append a generic value in an array. - * @param value source value object - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to an array. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1355,6 +1254,9 @@ static inline Eina_Bool eina_value_array_insert(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1365,17 +1267,21 @@ static inline Eina_Bool eina_value_array_insert(Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_append(Eina_Value *value, ...) EINA_ARG_NONNULL(1); /** - * @brief Set a generic value to an array member. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for an array member. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_pset() @@ -1386,39 +1292,47 @@ static inline Eina_Bool eina_value_array_append(Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_vset(Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an array member. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from an array member. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_array_vset() * @see eina_value_array_get() * @see eina_value_array_pget() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_vget(const Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Insert a generic value to an array member position. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at an array member position. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1428,18 +1342,21 @@ static inline Eina_Bool eina_value_array_vget(const Eina_Value *value, * @see eina_value_array_append() * @see eina_value_array_vappend() * @see eina_value_array_pappend() - * - * @since 1.2 */ static inline Eina_Bool eina_value_array_vinsert(Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Append a generic value to an array. - * @param value source value object - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to an array. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vget() @@ -1449,22 +1366,20 @@ static inline Eina_Bool eina_value_array_vinsert(Eina_Value *value, * @see eina_value_array_pinsert() * @see eina_value_array_append() * @see eina_value_array_pappend() - * - * @since 1.2 */ static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Set a generic value to an array member from a pointer. - * @param value source value object - * @param position index of the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for an array member from a pointer. * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1487,8 +1402,8 @@ static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); @@ -1500,6 +1415,11 @@ static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to specify the contents. + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1510,26 +1430,25 @@ static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_pset(Eina_Value *value, unsigned int position, const void *ptr) EINA_ARG_NONNULL(1, 3); /** - * @brief Retrieve a generic value into a pointer from an array member. - * @param value source value object - * @param position index of the member - * @param ptr pointer to receive the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value into a pointer from an array member. + * + * @since 1.2 * - * The value is returned in pointer contents, the actual value is - * type-dependent, but usually it will be what is stored inside the - * object. There shouldn't be any memory allocation, thus the contents - * should @b not be freed. + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The value is returned as pointer contents, the actual value is + * type-dependent, but usually it is what is stored inside the + * object. There shouldn't be any memory allocation, thus the contents + * should @b not be freed. + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1561,25 +1480,29 @@ static inline Eina_Bool eina_value_array_pset(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to receive the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_vset() * @see eina_value_array_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, unsigned int position, void *ptr) EINA_ARG_NONNULL(1, 3); /** - * @brief Insert a generic value to an array member position from a pointer. - * @param value source value object - * @param position index of the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at an array member position from a pointer. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1602,8 +1525,8 @@ static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); @@ -1614,6 +1537,11 @@ static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1624,20 +1552,20 @@ static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, unsigned int position, const void *ptr) EINA_ARG_NONNULL(1); /** - * @brief Append a generic value to an array from a pointer. - * @param value source value object - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to an array from a pointer. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1660,8 +1588,8 @@ static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_array_new(EINA_VALUE_TYPE_INT, 0); @@ -1672,6 +1600,10 @@ static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_array_set() * @see eina_value_array_get() * @see eina_value_array_vset() @@ -1682,22 +1614,25 @@ static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, * @see eina_value_array_vappend() * @see eina_value_array_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, const void *ptr) EINA_ARG_NONNULL(1); /** - * @brief Retrieves a value from the array as an Eina_Value copy. - * @param src source value object - * @param position index of the member - * @param dst where to return the array member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * The argument @a dst is considered uninitialized and it's setup to - * the type of the member. + * @brief Gets a value from the array as an Eina_Value copy. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The argument @a dst is considered as uninitialized and it's setup to + * the type of the member. + * + * @param[in] src The source value object + * @param[in] position The index of the member + * @param[in] dst The location to return the array member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, unsigned int position, @@ -1709,6 +1644,7 @@ static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, /** + * @internal * @defgroup Eina_Value_List_Group Generic Value List management * * @{ @@ -1717,17 +1653,23 @@ static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, /** * @typedef Eina_Value_List - * Value type for #EINA_VALUE_TYPE_LIST. + * @brief The structure type defining the value type for #EINA_VALUE_TYPE_LIST. * - * @see #_Eina_Value_List explains fields. * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_List explains fields. */ typedef struct _Eina_Value_List Eina_Value_List; /** + * @internal * @struct _Eina_Value_List - * Used to store the list and its subtype. + * @brief The structure type used to store the list and its subtype. * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_List { @@ -1736,76 +1678,94 @@ struct _Eina_Value_List }; /** - * @brief Create generic value storage of type list. - * @param subtype how to manage this list members. - * @return The new value or @c NULL on failure. + * @brief Creates a generic value storage of type list. + * + * @details This creates a new generic value storage of type list. The members are + * managed using the description specified by @a subtype. + * + * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. + * + * @since 1.2 * - * Create a new generic value storage of type list. The members are - * managed using the description specified by @a subtype. + * @since_tizen 2.3 * - * On failure, @c NULL is returned. + * @remarks This creates from the mempool and then uses + * eina_value_list_setup(). * - * @note this creates from mempool and then uses - * eina_value_list_setup(). + * @param[in] subtype The subtype to manage these list members + * @return The new value, otherwise @c NULL on failure * * @see eina_value_free() * @see eina_value_list_setup() * - * @since 1.2 */ EAPI Eina_Value *eina_value_list_new(const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1); /** - * @brief Initialize generic value storage of type list. - * @param value value object - * @param subtype how to manage this list members. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes a generic value storage of type list. * - * Initializes new generic value storage of type list with the given - * @a subtype. + * @details This initializes a new generic value storage of type list with the given + * @a subtype. * - * This is the same as calling eina_value_set() - * with #EINA_VALUE_TYPE_LIST followed by eina_value_pset() with - * the #Eina_Value_List description configured. + * This is same as calling eina_value_set() + * with #EINA_VALUE_TYPE_LIST followed by eina_value_pset() with + * the #Eina_Value_List description configured. * - * @note Existing contents are ignored! If the value was previously used, then - * use eina_value_flush() first. + * @since 1.2 * - * On failure, #EINA_FALSE is returned. + * @since_tizen 2.3 * - * @see eina_value_flush() + * @remarks Existing contents are ignored. If the value is previously used, then + * use eina_value_flush() first. * - * @since 1.2 + * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. + * + * @param[in] value The value object + * @param[in] subtype The subtype to manage these list members + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * + * @see eina_value_flush() */ static inline Eina_Bool eina_value_list_setup(Eina_Value *value, const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1, 2); /** - * @brief Query number of elements in value of list type. - * @param value value object. - * @return number of child elements. + * @brief Queries the number of elements in a value of list type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @return The number of child elements */ static inline unsigned int eina_value_list_count(const Eina_Value *value); /** - * @brief Remove element at given position in value of list type. - * @param value value object. - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Removes the element at the given position in a value of list type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_list_remove(Eina_Value *value, unsigned int position) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an list member. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a list member. + * + * @since 1.2 * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1837,6 +1797,10 @@ static inline Eina_Bool eina_value_list_remove(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_get() * @see eina_value_list_vset() * @see eina_value_list_pset() @@ -1847,25 +1811,25 @@ static inline Eina_Bool eina_value_list_remove(Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_set(Eina_Value *value, unsigned int position, ...) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an list member. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a list member. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -1896,24 +1860,28 @@ static inline Eina_Bool eina_value_list_set(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_vset() * @see eina_value_list_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_get(const Eina_Value *value, unsigned int position, ...) EINA_ARG_NONNULL(1); /** - * @brief Insert the generic value in an list member position. - * @param value source value object - * @param position index of the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at a list member position. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1944,6 +1912,10 @@ static inline Eina_Bool eina_value_list_get(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -1954,7 +1926,6 @@ static inline Eina_Bool eina_value_list_get(const Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_insert(Eina_Value *value, unsigned int position, @@ -1962,12 +1933,14 @@ static inline Eina_Bool eina_value_list_insert(Eina_Value *value, /** - * @brief Append the generic value in an list. - * @param value source value object - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to a list. + * + * @since 1.2 * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -1998,6 +1971,9 @@ static inline Eina_Bool eina_value_list_insert(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -2008,17 +1984,21 @@ static inline Eina_Bool eina_value_list_insert(Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_append(Eina_Value *value, ...) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an list member. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a list member. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_pset() @@ -2029,39 +2009,47 @@ static inline Eina_Bool eina_value_list_append(Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_vset(Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an list member. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a list member. * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_list_vset() * @see eina_value_list_get() * @see eina_value_list_pget() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_vget(const Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Insert the generic value in an list member position. - * @param value source value object - * @param position index of the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at a list member position. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -2071,18 +2059,21 @@ static inline Eina_Bool eina_value_list_vget(const Eina_Value *value, * @see eina_value_list_append() * @see eina_value_list_vappend() * @see eina_value_list_pappend() - * - * @since 1.2 */ static inline Eina_Bool eina_value_list_vinsert(Eina_Value *value, unsigned int position, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Append the generic value in an list. - * @param value source value object - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to a list. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vget() @@ -2093,21 +2084,20 @@ static inline Eina_Bool eina_value_list_vinsert(Eina_Value *value, * @see eina_value_list_append() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an list member from pointer. - * @param value source value object - * @param position index of the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a list member from a pointer. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2129,8 +2119,8 @@ static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); @@ -2142,6 +2132,11 @@ static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -2152,26 +2147,25 @@ static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_pset(Eina_Value *value, unsigned int position, const void *ptr) EINA_ARG_NONNULL(1, 3); /** - * @brief Get the generic value to pointer from an list member. - * @param value source value object - * @param position index of the member - * @param ptr pointer to receive the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value into a pointer from a list member. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in pointer contents, the actual value is - * type-dependent, but usually it will be what is stored inside the - * object. There shouldn't be any memory allocation, thus the contents - * should @b not be freed. + * @remarks The value is returned in pointer contents, the actual value is + * type-dependent, but usually it is what is stored inside the + * object. There shouldn't be any memory allocation, thus the contents + * should @b not be freed. * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2202,25 +2196,29 @@ static inline Eina_Bool eina_value_list_pset(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to receive the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_vset() * @see eina_value_list_pset() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, unsigned int position, void *ptr) EINA_ARG_NONNULL(1, 3); /** - * @brief Insert the generic value in an list member position from pointer. - * @param value source value object - * @param position index of the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Inserts a generic value at a list member position from a pointer. + * + * @since 1.2 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2242,8 +2240,8 @@ static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); @@ -2254,6 +2252,11 @@ static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] position The index of the member + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -2264,20 +2267,20 @@ static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, * @see eina_value_list_vappend() * @see eina_value_list_pappend() * - * @since 1.2 */ static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, unsigned int position, const void *ptr) EINA_ARG_NONNULL(1); /** - * @brief Append the generic value in an list from pointer. - * @param value source value object - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Appends a generic value to a list from a pointer. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2299,8 +2302,8 @@ static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_list_new(EINA_VALUE_TYPE_INT); @@ -2311,6 +2314,10 @@ static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_list_set() * @see eina_value_list_get() * @see eina_value_list_vset() @@ -2320,8 +2327,6 @@ static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, * @see eina_value_list_append() * @see eina_value_list_vappend() * @see eina_value_list_pappend() - * - * @since 1.2 */ static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, const void *ptr) EINA_ARG_NONNULL(1); @@ -2331,6 +2336,7 @@ static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, */ /** + * @internal * @defgroup Eina_Value_Hash_Group Generic Value Hash management * * @{ @@ -2338,101 +2344,122 @@ static inline Eina_Bool eina_value_list_pappend(Eina_Value *value, /** * @typedef Eina_Value_Hash - * Value type for #EINA_VALUE_TYPE_HASH. + * @brief The structure type containing the value type for #EINA_VALUE_TYPE_HASH. * * @see #_Eina_Value_Hash explains fields. * @since 1.2 + * + * @since_tizen 2.3 */ typedef struct _Eina_Value_Hash Eina_Value_Hash; /** + * @internal * @struct _Eina_Value_Hash - * Used to store the hash and its subtype. + * @brief The structure type used to store the hash and its subtype. * @since 1.2 */ struct _Eina_Value_Hash { - const Eina_Value_Type *subtype; /**< how to allocate and access items */ - unsigned int buckets_power_size; /**< how to allocate hash buckets, if zero a sane default is chosen. */ - Eina_Hash *hash; /**< the hash that holds data, members are of subtype->value_size bytes. */ + const Eina_Value_Type *subtype; /**< How to allocate and access items */ + unsigned int buckets_power_size; /**< How to allocate hash buckets, if zero a default value is chosen */ + Eina_Hash *hash; /**< The hash that holds data, members are of subtype->value_size bytes */ }; /** - * @brief Create generic value storage of type hash. - * @param subtype how to manage this hash members. - * @param buckets_power_size how to allocate hash buckets (2 ^ - * buckets_power_size), if zero then a sane value is chosen. - * @return The new value or @c NULL on failure. + * @brief Creates a generic value storage of type hash. + * + * @details This creates a new generic value storage of type hash. The members are + * managed using the description specified by @a subtype. + * + * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. + * + * @since 1.2 * - * Create a new generic value storage of type hash. The members are - * managed using the description specified by @a subtype. + * @since_tizen 2.3 * - * On failure, @c NULL is returned. + * @remarks This creates from the mempool and then uses + * eina_value_hash_setup(). * - * @note this creates from mempool and then uses - * eina_value_hash_setup(). + * @param[in] subtype The subtype to manage these hash members + * @param[in] buckets_power_size The buckets power size based on which to allocate hash buckets (2 ^ + * buckets_power_size), if zero then a default value is chosen + * @return The new value, otherwise @c NULL on failure * * @see eina_value_free() * @see eina_value_hash_setup() * - * @since 1.2 */ EAPI Eina_Value *eina_value_hash_new(const Eina_Value_Type *subtype, unsigned int buckets_power_size) EINA_ARG_NONNULL(1); /** - * @brief Initialize generic value storage of type hash. - * @param value value object - * @param subtype how to manage this hash members. - * @param buckets_power_size how to allocate hash buckets (2 ^ - * buckets_power_size), if zero then a sane value is chosen. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes a generic value storage of type hash. * - * Initializes new generic value storage of type hash with the given - * @a subtype. + * @details This initializes a new generic value storage of type hash with the given + * @a subtype. * - * This is the same as calling eina_value_set() - * with #EINA_VALUE_TYPE_HASH followed by eina_value_pset() with - * the #Eina_Value_Hash description configured. + * This is same as calling eina_value_set() + * with #EINA_VALUE_TYPE_HASH followed by eina_value_pset() with + * the #Eina_Value_Hash description configured. * - * @note Existing contents are ignored! If the value was previously used, then - * use eina_value_flush() first. + * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. * - * On failure, #EINA_FALSE is returned. + * @since 1.2 * - * @see eina_value_flush() + * @since_tizen 2.3 * - * @since 1.2 + * @remarks Existing contents are ignored. If the value is previously used, then + * use eina_value_flush() first. + * + * @param[in] value The value object + * @param[in] subtype The subtype to manage these hash members + * @param[in] buckets_power_size The buckets power size based on which to allocate hash buckets (2 ^ + * buckets_power_size), if zero then a default value is chosen + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * + * @see eina_value_flush() */ static inline Eina_Bool eina_value_hash_setup(Eina_Value *value, const Eina_Value_Type *subtype, unsigned int buckets_power_size) EINA_ARG_NONNULL(1, 2); /** - * @brief Query number of elements in value of hash type. - * @param value value object. - * @return number of child elements. + * @brief Queries the number of elements in a value of hash type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @return The number of child elements */ static inline unsigned int eina_value_hash_population(const Eina_Value *value); /** - * @brief Remove element at given position in value of hash type. - * @param value value object. - * @param key key to find the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Removes the element at the given position in a value of hash type. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The value object + * @param[in] key The key to find the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_hash_del(Eina_Value *value, const char *key) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an hash member. - * @param value source value object - * @param key key to find the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a hash member. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -2462,30 +2489,34 @@ static inline Eina_Bool eina_value_hash_del(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_hash_get() * @see eina_value_hash_vset() * @see eina_value_hash_pset() * @see eina_value_hash_del() * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_set(Eina_Value *value, const char *key, ...) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an hash member. - * @param value source value object - * @param key key to find the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a hash member. * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. * - * The variable argument is dependent on chosen subtype. The list for - * basic types: + * @remarks The variable argument is dependent on the chosen subtype. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2515,63 +2546,72 @@ static inline Eina_Bool eina_value_hash_set(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_hash_set() * @see eina_value_hash_vset() * @see eina_value_hash_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_get(const Eina_Value *value, const char *key, ...) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an hash member. - * @param value source value object - * @param key key to find the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a hash member. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_hash_set() * @see eina_value_hash_get() * @see eina_value_hash_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_vset(Eina_Value *value, const char *key, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Get the generic value from an hash member. - * @param value source value object - * @param key key to find the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a hash member. + * + * @since 1.2 * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @since_tizen 2.3 + * + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. + * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_hash_vset() * @see eina_value_hash_get() * @see eina_value_hash_pget() * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, const char *key, va_list args) EINA_ARG_NONNULL(1); /** - * @brief Set the generic value in an hash member from pointer. - * @param value source value object - * @param key key to find the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a hash member from a pointer. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2592,8 +2632,8 @@ static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * Eina_Value *value = eina_value_hash_new(EINA_VALUE_TYPE_INT, 0); @@ -2604,30 +2644,33 @@ static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_hash_set() * @see eina_value_hash_get() * @see eina_value_hash_vset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_pset(Eina_Value *value, const char *key, const void *ptr) EINA_ARG_NONNULL(1, 3); /** - * @brief Get the generic value to pointer from an hash member. - * @param value source value object - * @param key key to find the member - * @param ptr pointer to receive the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value into a pointer from a hash member. * - * The value is returned in pointer contents, the actual value is - * type-dependent, but usually it will be what is stored inside the - * object. There shouldn't be any memory allocation, thus the contents - * should @b not be freed. + * @since 1.2 + * + * @since_tizen 2.3 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @remarks The value is returned in pointer contents, the actual value is + * type-dependent, but usually it is what is stored inside the + * object. There shouldn't be any memory allocation, thus the contents + * should @b not be freed. + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -2657,11 +2700,14 @@ static inline Eina_Bool eina_value_hash_pset(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] key The key to find the member + * @param[in] ptr A pointer to receive the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_hash_set() * @see eina_value_hash_vset() * @see eina_value_hash_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, const char *key, @@ -2672,6 +2718,7 @@ static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, */ /** + * @internal * @defgroup Eina_Value_Blob_Group Generic Value Blob management * * @{ @@ -2679,26 +2726,33 @@ static inline Eina_Bool eina_value_hash_pget(const Eina_Value *value, /** * @typedef Eina_Value_Blob_Operations - * How to manage blob. Any @c NULL callback is ignored. - * @see #_Eina_Value_Blob_Operations explains fields. + * @brief The structure type for the operations used to manage a blob. Any @c NULL callback is ignored. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_Blob_Operations explains fields. */ typedef struct _Eina_Value_Blob_Operations Eina_Value_Blob_Operations; /** * @def EINA_VALUE_BLOB_OPERATIONS_VERSION - * Current API version, used to validate #_Eina_Value_Blob_Operations. + * @brief Definition of the current API version, used to validate #_Eina_Value_Blob_Operations. */ #define EINA_VALUE_BLOB_OPERATIONS_VERSION (1) /** + * @internal * @struct _Eina_Value_Blob_Operations - * How to manage blob. Any @c NULL callback is ignored. + * @brief The structure type for the operations used to manage a blob. Any @c NULL callback is ignored. * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_Blob_Operations { - unsigned int version; /**< must be #EINA_VALUE_BLOB_OPERATIONS_VERSION */ + unsigned int version; /**< Must be #EINA_VALUE_BLOB_OPERATIONS_VERSION */ void (*free)(const Eina_Value_Blob_Operations *ops, void *memory, size_t size); void *(*copy)(const Eina_Value_Blob_Operations *ops, const void *memory, size_t size); int (*compare)(const Eina_Value_Blob_Operations *ops, const void *data1, size_t size_data1, const void *data2, size_t size_data2); @@ -2708,31 +2762,37 @@ struct _Eina_Value_Blob_Operations /** * @var EINA_VALUE_BLOB_OPERATIONS_MALLOC * - * Assumes @c memory was create with malloc() and applies free() to it - * during flush (Eina_Value_Blob_Operations::free). Copy is done with - * malloc() as well. + * @brief Assumes that @c memory is created with malloc() and applies free() to it + * during flush (Eina_Value_Blob_Operations::free). Copy is done with + * malloc() as well. * - * No compare or to_string are provided, defaults will be used. + * @remarks No compare or to_string is provided, defaults are used. */ EAPI extern const Eina_Value_Blob_Operations *EINA_VALUE_BLOB_OPERATIONS_MALLOC; /** * @typedef Eina_Value_Blob - * Value type for #EINA_VALUE_TYPE_BLOB. + * @brief The structure type containing the value type for #EINA_VALUE_TYPE_BLOB. * - * @see #_Eina_Value_Blob explains fields. * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_Blob explains fields. */ typedef struct _Eina_Value_Blob Eina_Value_Blob; /** + * @internal * @struct _Eina_Value_Blob - * Used to store the blob information and management operations. + * @brief The structure type used to store blob information and management operations. * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_Blob { - const Eina_Value_Blob_Operations *ops; /**< if @c NULL, nothing is freed, copy will just copy the memory pointer, not its value. */ + const Eina_Value_Blob_Operations *ops; /**< If @c NULL, nothing is freed, copy just copies the memory pointer, not its value */ const void *memory; unsigned int size; }; @@ -2742,6 +2802,7 @@ struct _Eina_Value_Blob */ /** + * @internal * @defgroup Eina_Value_Struct_Group Generic Value Struct management * * @{ @@ -2749,151 +2810,176 @@ struct _Eina_Value_Blob /** * @typedef Eina_Value_Struct_Operations - * How to manage struct. Any @c NULL callback is ignored. + * @brief The structure type for the operations used to manage a struct. Any @c NULL callback is ignored. * - * A structure can specify alternative methods to allocate, free and - * copy itself. See structure definition for all methods. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks A structure can specify alternative methods to allocate, free, and + * copy itself. See structure definition for all methods. * * @see #_Eina_Value_Struct_Operations explains fields. - * @since 1.2 */ typedef struct _Eina_Value_Struct_Operations Eina_Value_Struct_Operations; /** * @typedef Eina_Value_Struct_Member - * Describes a single member of struct. + * @brief The structure type that describes a single member of struct. * - * The member holds a name, type and its byte offset within the struct - * memory. Most Eina_Value_Struct functions takes the member name as - * parameter, as in eina_value_struct_set(). + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The member holds a name, type, and its byte offset within the struct + * memory. Most Eina_Value_Struct functions take the member name as + * a parameter, for example eina_value_struct_set(). * * @see #_Eina_Value_Struct_Member explains fields. - * @since 1.2 */ typedef struct _Eina_Value_Struct_Member Eina_Value_Struct_Member; /** * @typedef Eina_Value_Struct_Desc - * Describes the struct by listing its size, members and operations. - * @see #_Eina_Value_Struct_Desc explains fields. + * @brief The structure type that describes the struct by listing its size, members, and operations. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_Struct_Desc explains fields. */ typedef struct _Eina_Value_Struct_Desc Eina_Value_Struct_Desc; /** * @typedef Eina_Value_Struct - * Value type for #EINA_VALUE_TYPE_STRUCT. + * @brief The structure type containing the value type for #EINA_VALUE_TYPE_STRUCT. * - * @see #_Eina_Value_Struct explains fields. * @since 1.2 + * + * @since_tizen 2.3 + * + * @see #_Eina_Value_Struct explains fields. */ typedef struct _Eina_Value_Struct Eina_Value_Struct; /** * @def EINA_VALUE_STRUCT_OPERATIONS_VERSION - * Current API version, used to validate #_Eina_Value_Struct_Operations. + * @brief Definition of the current API version, used to validate #_Eina_Value_Struct_Operations. */ #define EINA_VALUE_STRUCT_OPERATIONS_VERSION (1) /** + * @internal * @struct _Eina_Value_Struct_Operations - * How to manage struct. Any @c NULL callback is ignored. + * @brief The structure type for the operations used to manage a struct. Any @c NULL callback is ignored. * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_Struct_Operations { unsigned int version; /**< must be #EINA_VALUE_STRUCT_OPERATIONS_VERSION */ - void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); /**< How to allocate struct memory to be managed by the Eina_Value */ - void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); /**< How to release memory managed by the Eina_Value */ - void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); /**< How to copy struct memory from an existing Eina_Value, if not provided alloc() will be used, then every member is copied using eina_value_type_copy() with member's type. */ + void *(*alloc)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc); /**< How to allocate struct memory to be managed by Eina_Value */ + void (*free)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, void *memory); /**< How to release memory managed by Eina_Value */ + void *(*copy)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *memory); /**< How to copy struct memory from an existing Eina_Value, if not provided, alloc() is used and then every member is copied using eina_value_type_copy() with the member's type */ int (*compare)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const void *data1, const void *data2); /**< How to compare two struct memories */ - const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< How to find description for member. For huge structures consider using binary search, stringshared, hash or gperf. The default function does linear search using strcmp(). */ + const Eina_Value_Struct_Member *(*find_member)(const Eina_Value_Struct_Operations *ops, const Eina_Value_Struct_Desc *desc, const char *name); /**< How to find a description for a member. For huge structures consider using binary search, stringshared, hash, or gperf. The default function does linear search using strcmp() */ }; /** * @var EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH * - * Assumes @c members is sorted by name and applies binary search for - * names. + * @brief Assumes that @c members is sorted by name and applies binary search for + * names. * - * Ideally the @c member_count field is set to speed it up. + * @remarks Ideally the @c member_count field is set to speed it up. * - * No other methods are set (alloc, free, copy, compare), then it uses - * the default operations. + * If no other methods are set (alloc, free, copy, compare), then it uses + * the default operations. */ EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH; /** * @var EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE * - * Assumes @c members name are stringshared and can be compared for - * equality without using its contents (simple pointer comparison). + * @brief Assumes that @c members name is stringshared and can be compared for + * equality without using its contents (simple pointer comparison). * - * Ideally the search @c name will be stringshared as well, but it - * will do a second loop with a forced stringshare if it did not find - * the member. + * @remarks Ideally the search @c name is stringshared as well, but it + * does a second loop with a forced stringshare if it does not find + * the member. * - * No other methods are set (alloc, free, copy, compare), then it uses - * the default operations. + * If no other methods are set (alloc, free, copy, compare), then it uses + * the default operations. */ EAPI extern const Eina_Value_Struct_Operations *EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE; /** + * @internal * @struct _Eina_Value_Struct_Member - * Describes a single member of struct. + * @brief The structure type that describes a single member of struct. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The name is used to lookup the member description. This is done as - * specified as _Eina_Value_Struct_Operations::find_member(). For - * structures with huge number of members, consider using a better - * find_member function to quickly finding it! There are two helper - * operations provided to help this: #EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH - * and #EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE, both depend on properly - * set #_Eina_Value_Struct_Desc and #_Eina_Value_Struct_Member. + * @remarks The name is used to lookup the member description. This is done as + * specified by _Eina_Value_Struct_Operations::find_member(). For + * structures with huge number of members, consider using a better + * find_member function to quickly find it. There are two helper + * operations provided to help this: #EINA_VALUE_STRUCT_OPERATIONS_BINSEARCH + * and #EINA_VALUE_STRUCT_OPERATIONS_STRINGSHARE, both depend on properly + * set #_Eina_Value_Struct_Desc and #_Eina_Value_Struct_Member. * * @see #EINA_VALUE_STRUCT_MEMBER * @see #EINA_VALUE_STRUCT_MEMBER_SENTINEL - * - * @since 1.2 */ struct _Eina_Value_Struct_Member { - const char *name; /**< member name, used in lookups such as eina_value_struct_get() */ - const Eina_Value_Type *type; /**< how to use this member */ - unsigned int offset; /**< where this member is located within the structure memory */ + const char *name; /**< Member name, used in lookups such as eina_value_struct_get() */ + const Eina_Value_Type *type; /**< How to use this member */ + unsigned int offset; /**< Where is this member located within the structure memory */ }; /** * @def EINA_VALUE_STRUCT_DESC_VERSION - * Current API version, used to validate #_Eina_Value_Struct_Desc. + * @brief Definition of the current API version, used to validate #_Eina_Value_Struct_Desc. */ #define EINA_VALUE_STRUCT_DESC_VERSION (1) /** + * @internal * @struct _Eina_Value_Struct_Desc - * Describes the struct by listing its size, members and operations. - * - * This is the root of Eina_Value knowledge about the memory it's - * handling as a structure. It adds introspection, saying the byte - * size of the structure, its members and how to manage such members. + * @brief The structure type that describes the struct by listing its size, members, and operations. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks This is the root of Eina_Value knowledge about the memory it's + * handling as a structure. It adds introspection specifying the byte + * size of the structure, its members, and how to manage such members. + * */ struct _Eina_Value_Struct_Desc { - unsigned int version; /**< must be #EINA_VALUE_STRUCT_DESC_VERSION */ - const Eina_Value_Struct_Operations *ops; /**< operations, if @c NULL defaults will be used. You may use operations to optimize member lookup using binary search or gperf hash. */ - const Eina_Value_Struct_Member *members; /**< array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated. */ - unsigned int member_count; /**< if > 0, specifies number of members. If zero then @c members must be NULL terminated. */ - unsigned int size; /**< byte size to allocate, may be bigger than sum of members */ + unsigned int version; /**< Must be #EINA_VALUE_STRUCT_DESC_VERSION */ + const Eina_Value_Struct_Operations *ops; /**< Operations, if @c NULL defaults are used. You may use operations to optimize a member lookup using binary search or gperf hash */ + const Eina_Value_Struct_Member *members; /**< Array of member descriptions, if @c member_count is zero, then it must be @c NULL terminated */ + unsigned int member_count; /**< If > 0, it specifies the number of members. If zero then @c members must be @c NULL terminated */ + unsigned int size; /**< The byte size to allocate, may be bigger than the sum of the members */ }; /** * @def EINA_VALUE_STRUCT_MEMBER * - * Helper to define Eina_Value_Struct_Member fields, uses offsetof() - * with type and member. + * @brief Definition of the helper used to define Eina_Value_Struct_Member fields that use offsetof() + * with type and member. * * @since 1.2 + * + * @since_tizen 2.3 */ #define EINA_VALUE_STRUCT_MEMBER(eina_value_type, type, member) \ {#member, eina_value_type, offsetof(type, member)} @@ -2901,17 +2987,20 @@ struct _Eina_Value_Struct_Desc /** * @def EINA_VALUE_STRUCT_MEMBER_SENTINEL * - * Helper to define Eina_Value_Struct_Member fields for sentinel (last - * item), useful if you did not define @c member_count. + * @brief Definition of the helper to define Eina_Value_Struct_Member fields for a sentinel (last + * item), that are useful if you did not define @c member_count. * * @since 1.2 + * + * @since_tizen 2.3 */ #define EINA_VALUE_STRUCT_MEMBER_SENTINEL {NULL, NULL, 0} /** + * @internal * @struct _Eina_Value_Struct - * Used to store the memory and its description. + * @brief The structure type used to store the memory and its description. * @since 1.2 */ struct _Eina_Value_Struct @@ -2921,58 +3010,67 @@ struct _Eina_Value_Struct }; /** - * @brief Create generic value storage of type struct. - * @param desc how to manage this struct members. - * @return The new value or @c NULL on failure. + * @brief Creates a generic value storage of type struct. + * + * @details This creates a new generic value storage of type struct. The members are + * managed using the description specified by @a desc. * - * Create a new generic value storage of type struct. The members are - * managed using the description specified by @a desc. + * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. + * + * @since 1.2 * - * On failure, @c NULL is returned. + * @since_tizen 2.3 * - * @note this creates from mempool and then uses - * eina_value_struct_setup(). + * @remarks This creates from the mempool and then uses + * eina_value_struct_setup(). + * + * @param[in] desc The description used to manage these struct members + * @return The new value, otherwise @c NULL on failure * * @see eina_value_free() * @see eina_value_struct_setup() - * - * @since 1.2 */ EAPI Eina_Value *eina_value_struct_new(const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1); /** - * @brief Initialize generic value storage of type struct. - * @param value value object - * @param desc how to manage this struct members. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes a generic value storage of type struct. * - * Initializes new generic value storage of type struct with the given - * @a desc. + * @details This initializes a new generic value storage of type struct with the given + * @a desc. * - * This is the same as calling eina_value_set() - * with #EINA_VALUE_TYPE_STRUCT followed by eina_value_pset() with - * the #Eina_Value_Struct description configured. + * This is same as calling eina_value_set() + * with #EINA_VALUE_TYPE_STRUCT followed by eina_value_pset() with + * the #Eina_Value_Struct description configured. * - * @note Existing contents are ignored! If the value was previously used, then - * use eina_value_flush() first. + * On failure, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY + * or #EINA_ERROR_VALUE_FAILED is set. * - * On failure, #EINA_FALSE is returned. + * @since 1.2 * - * @see eina_value_flush() + * @since_tizen 2.3 * - * @since 1.2 + * @remarks Existing contents are ignored. If the value is previously used, then + * use eina_value_flush() first. + * + * @param[in] value The value object + * @param[in] desc The description used to manage these struct members + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * + * @see eina_value_flush() */ static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1, 2); /** - * @brief Set the generic value in an struct member. - * @param value source value object - * @param name name to find the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for an struct member. * - * The variable argument is dependent on chosen member type. The list - * for basic types: + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The variable argument is dependent on the chosen member type. The list + * of basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char * @li EINA_VALUE_TYPE_USHORT: unsigned short @@ -3018,29 +3116,32 @@ static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_struct_get() * @see eina_value_struct_vset() * @see eina_value_struct_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_set(Eina_Value *value, const char *name, ...) EINA_ARG_NONNULL(1, 2); /** - * @brief Get the generic value from an struct member. - * @param value source value object - * @param name name to find the member - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a struct member. + * + * @since 1.2 + * + * @since_tizen 2.3 * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. * - * The variable argument is dependent on chosen member type. The list - * for basic types: + * @remarks The variable argument is dependent on the chosen member type. The list + * of basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -3086,63 +3187,71 @@ static inline Eina_Bool eina_value_struct_set(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_struct_set() * @see eina_value_struct_vset() * @see eina_value_struct_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, const char *name, ...) EINA_ARG_NONNULL(1, 2); /** - * @brief Set the generic value in an struct member. - * @param value source value object - * @param name name to find the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a struct member. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * @see eina_value_struct_set() * @see eina_value_struct_get() * @see eina_value_struct_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, const char *name, va_list args) EINA_ARG_NONNULL(1, 2); /** - * @brief Get the generic value from an struct member. - * @param value source value object - * @param name name to find the member - * @param args variable argument - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value from a struct member. * - * The value is returned in the variable argument parameter, the - * actual value is type-dependent, but usually it will be what is - * stored inside the object. There shouldn't be any memory allocation, - * thus the contents should @b not be freed. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The value is returned in the variable argument parameter, the + * actual value is type-dependent, but usually it is what is + * stored inside the object. There shouldn't be any memory allocation, + * thus the contents should @b not be freed. + * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @param[in] args The variable argument + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * * @see eina_value_struct_vset() * @see eina_value_struct_get() * @see eina_value_struct_pget() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, const char *name, va_list args) EINA_ARG_NONNULL(1, 2); /** - * @brief Set the generic value in an struct member from pointer. - * @param value source value object - * @param name name to find the member - * @param ptr pointer to specify the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a generic value for a struct member from a pointer. + * + * @since 1.2 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -3163,8 +3272,8 @@ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, * @li EINA_VALUE_TYPE_BLOB: Eina_Value_Blob* * @li EINA_VALUE_TYPE_STRUCT: Eina_Value_Struct* * - * @note the pointer contents are written using the size defined by - * type. It can be larger than void* or uint64_t. + * @remarks The pointer contents are written using the size defined by + * type. It can be larger than void* or uint64_t. * * @code * struct myst { @@ -3191,30 +3300,33 @@ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @param[in] ptr A pointer to specify the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_struct_set() * @see eina_value_struct_get() * @see eina_value_struct_vset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, const char *name, const void *ptr) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Get the generic value to pointer from an struct member. - * @param value source value object - * @param name name to find the member - * @param ptr pointer to receive the contents. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets a generic value into pointer from a struct member. * - * The value is returned in pointer contents, the actual value is - * type-dependent, but usually it will be what is stored inside the - * object. There shouldn't be any memory allocation, thus the contents - * should @b not be freed. + * @since 1.2 * - * The pointer type is dependent on chosen value type. The list for - * basic types: + * @since_tizen 2.3 + * + * @remarks The value is returned in pointer contents, the actual value is + * type-dependent, but usually it is what is stored inside the + * object. There shouldn't be any memory allocation, thus the contents + * should @b not be freed. + * + * @remarks The pointer type is dependent on the chosen value type. The list of + * basic types: * * @li EINA_VALUE_TYPE_UCHAR: unsigned char* * @li EINA_VALUE_TYPE_USHORT: unsigned short* @@ -3260,69 +3372,88 @@ static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, * eina_value_free(value); * @endcode * + * @param[in] value The source value object + * @param[in] name The name used to find the member + * @param[in] ptr A pointer to receive the contents + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * * @see eina_value_struct_set() * @see eina_value_struct_vset() * @see eina_value_struct_pset() - * - * @since 1.2 */ static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, const char *name, void *ptr) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Get the member as Eina_Value copy - * @param src source value object - * @param name name to find the member - * @param dst where to return the member value. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * The argument @a dst is considered uninitialized and it's setup to - * the type of the member. + * @brief Gets a member as an Eina_Value copy. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The argument @a dst is considered as uninitialized and it's setup to + * the type of the member. + * + * @param[in] src The source value object + * @param[in] name The name used to find the member + * @param[in] dst An object used to return the member value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ static inline Eina_Bool eina_value_struct_value_get(const Eina_Value *src, const char *name, Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Set the member from Eina_Value source - * @param dst destination value object - * @param name name to find the member - * @param src source value - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @brief Sets a member from an Eina_Value source. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] dst The destination value object + * @param[in] name The name used to find the member + * @param[in] src The source value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure. + * */ static inline Eina_Bool eina_value_struct_value_set(Eina_Value *dst, const char *name, const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Get the member as Eina_Value copy given its member description. - * @param src source value object - * @param member the member description to use - * @param dst where to return the member value. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * The argument @a dst is considered uninitialized and it's setup to - * the type of the member. + * @brief Gets a member as a Eina_Value copy given that its member description is provided. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The argument @a dst is considered as uninitialized and it's setup to + * the type of the member. + * + * @param[in] src The source value object + * @param[in] member The member description to use + * @param[in] dst An object used to return the member value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ static inline Eina_Bool eina_value_struct_member_value_get(const Eina_Value *src, const Eina_Value_Struct_Member *member, Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Set the member from Eina_Value source - * @param dst destination value object - * @param member the member description to use - * @param src source value - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @brief Sets a member from an Eina_Value source. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] dst The destination value object + * @param[in] member The member description to use + * @param[in] src The source value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, const Eina_Value_Struct_Member *member, @@ -3335,6 +3466,7 @@ static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, /** + * @internal * @defgroup Eina_Value_Type_Group Generic Value Type management * * @{ @@ -3342,139 +3474,186 @@ static inline Eina_Bool eina_value_struct_member_value_set(Eina_Value *dst, /** * @def EINA_VALUE_TYPE_VERSION - * Current API version, used to validate type. + * @brief Definition of the current API version, used to validate type. */ #define EINA_VALUE_TYPE_VERSION (1) /** + * @internal * @struct _Eina_Value_Type - * API to access values. + * @brief The structure type containing the API to access values. * * @since 1.2 + * + * @since_tizen 2.3 */ struct _Eina_Value_Type { - unsigned int version; /**< must be #EINA_VALUE_TYPE_VERSION */ - unsigned int value_size; /**< byte size of value */ - const char *name; /**< name for debug and introspection */ - Eina_Bool (*setup)(const Eina_Value_Type *type, void *mem); /**< mem will be malloc(value_size) and should be configured */ - Eina_Bool (*flush)(const Eina_Value_Type *type, void *mem); /**< clear any values from mem */ - Eina_Bool (*copy)(const Eina_Value_Type *type, const void *src, void *dst); /**< how to copy values, both memory are @c value_size */ - int (*compare)(const Eina_Value_Type *type, const void *a, const void *b); /**< how to compare values, both memory are @c value_size */ - Eina_Bool (*convert_to)(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); /**< how to convert values, both memory are @c value_size */ - Eina_Bool (*convert_from)(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); /**< how to convert values, both memory are @c value_size */ - Eina_Bool (*vset)(const Eina_Value_Type *type, void *mem, va_list args); /**< how to set memory from variable argument */ - Eina_Bool (*pset)(const Eina_Value_Type *type, void *mem, const void *ptr); /**< how to set memory from pointer */ - Eina_Bool (*pget)(const Eina_Value_Type *type, const void *mem, void *ptr); /**< how to read memory */ + unsigned int version; /**< Must be #EINA_VALUE_TYPE_VERSION */ + unsigned int value_size; /**< Byte size of value */ + const char *name; /**< Name for debug and introspection */ + Eina_Bool (*setup)(const Eina_Value_Type *type, void *mem); /**< Mem is malloc(value_size) and should be configured */ + Eina_Bool (*flush)(const Eina_Value_Type *type, void *mem); /**< Clear any values from mem */ + Eina_Bool (*copy)(const Eina_Value_Type *type, const void *src, void *dst); /**< How to copy values, both memories are @c value_size */ + int (*compare)(const Eina_Value_Type *type, const void *a, const void *b); /**< How to compare values, both memories are @c value_size */ + Eina_Bool (*convert_to)(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); /**< How to convert values, both memories are @c value_size */ + Eina_Bool (*convert_from)(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); /**< How to convert values, both memories are @c value_size */ + Eina_Bool (*vset)(const Eina_Value_Type *type, void *mem, va_list args); /**< How to set memory from a variable argument */ + Eina_Bool (*pset)(const Eina_Value_Type *type, void *mem, const void *ptr); /**< How to set memory from a pointer */ + Eina_Bool (*pget)(const Eina_Value_Type *type, const void *mem, void *ptr); /**< How to read memory */ }; /** - * @brief Query type name. - * @param type type reference. - * @return string or @c NULL if type is invalid. + * @brief Queries type name. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference + * @return A string, otherwise @c NULL if the type is invalid */ EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Check if type is valid. - * @param type type reference. - * @return #EINA_TRUE if valid, #EINA_FALSE otherwise. - * - * A type is invalid if it's NULL or if version field is not the same - * as runtime #EINA_VALUE_TYPE_VERSION. + * @brief Checks whether the type is valid. * * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks A type is invalid if it's NULL or if the version field is not same + * as the runtime #EINA_VALUE_TYPE_VERSION. + * + * @param[in] type The type reference + * @return @c EINA_TRUE if valid, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_value_type_check(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Initialize memory using type descriptor. - * @param type type reference. - * @param mem memory to operate, must be of size @c type->value_size. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Initializes the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference + * @param[in] mem The memory to operate, must be of size @c type->value_size + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void *mem); /** - * @brief Flush (clear) memory using type descriptor. - * @param type type reference. - * @param mem memory to operate, must be of size @c type->value_size. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Flushes (clears) the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference + * @param[in] mem The memory to operate, must be of size @c type->value_size + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void *mem); /** - * @brief Copy memory using type descriptor. - * @param type type reference. - * @param src memory to operate, must be of size @c type->value_size. - * @param dst memory to operate, must be of size @c type->value_size. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Copies the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference + * @param[in] src The memory to operate, must be of size @c type->value_size + * @param[in] dst The memory to operate, must be of size @c type->value_size + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const void *src, void *dst); /** - * @brief Compare memory using type descriptor. - * @param type type reference. - * @param a memory to operate, must be of size @c type->value_size. - * @param b memory to operate, must be of size @c type->value_size. - * @return less than zero if a < b, greater than zero if a > b, zero if equal. + * @brief Compares the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference + * @param[in] a The memory to operate, must be of size @c type->value_size + * @param[in] b The memory to operate, must be of size @c type->value_size + * @return Less than zero if a < b, greater than zero if a > b, and zero if a = b */ static inline int eina_value_type_compare(const Eina_Value_Type *type, const void *a, const void *b); /** - * @brief Convert memory using type descriptor. - * @param type type reference of the source. - * @param convert type reference of the destination. - * @param type_mem memory to operate, must be of size @c type->value_size. - * @param convert_mem memory to operate, must be of size @c convert->value_size. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Converts the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference of the source + * @param[in] convert The type reference of the destination + * @param[in] type_mem The memory to operate, must be of size @c type->value_size + * @param[in] convert_mem The memory to operate, must be of size @c convert->value_size + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem); /** - * @brief Convert memory using type descriptor. - * @param type type reference of the destination. - * @param convert type reference of the source. - * @param type_mem memory to operate, must be of size @c type->value_size. - * @param convert_mem memory to operate, must be of size @c convert->value_size. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Converts the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference of the destination + * @param[in] convert The type reference of the source + * @param[in] type_mem The memory to operate, must be of size @c type->value_size + * @param[in] convert_mem The memory to operate, must be of size @c convert->value_size + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem); /** - * @brief Set memory using type descriptor and variable argument. - * @param type type reference of the source. - * @param mem memory to operate, must be of size @c type->value_size. - * @param args input value. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets the memory using a type descriptor and a variable argument. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference of the source + * @param[in] mem The memory to operate, must be of size @c type->value_size + * @param[in] args The input value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void *mem, va_list args); /** - * @brief Set memory using type descriptor and pointer. - * @param type type reference of the source. - * @param mem memory to operate, must be of size @c type->value_size. - * @param ptr pointer to input value. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets the memory using a type descriptor and a pointer. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference of the source + * @param[in] mem The memory to operate, must be of size @c type->value_size + * @param[in] ptr A pointer to the input value. + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr); /** - * @brief Get memory using type descriptor. - * @param type type reference of the source. - * @param mem memory to operate, must be of size @c type->value_size. - * @param ptr pointer to output. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Gets the memory using a type descriptor. + * * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] type The type reference of the source + * @param[in] mem The memory to operate, must be of size @c type->value_size + * @param[in] ptr A pointer to the output + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE */ static inline Eina_Bool eina_value_type_pget(const Eina_Value_Type *type, const void *mem, void *ptr); @@ -3488,11 +3667,4 @@ static inline Eina_Bool eina_value_type_pget(const Eina_Value_Type *type, const * @} */ -/** - * @} - */ - -/** - * @} - */ #endif diff --git a/src/lib/eina/eina_xattr.h b/src/lib/eina/eina_xattr.h index b37262ee31..a5237d18ef 100644 --- a/src/lib/eina/eina_xattr.h +++ b/src/lib/eina/eina_xattr.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2011 Cedric Bail * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -29,253 +29,218 @@ /** * @typedef Eina_Xattr_Flags - * define extended attribute creation + * @brief Enumeration of extended attribute creation. * * @since 1.1 */ typedef enum { - EINA_XATTR_INSERT, /**< This is the default behaviour, it will either create or replace the extended attribute */ - EINA_XATTR_REPLACE, /**< This will only succeed if the extended attribute previously existed */ - EINA_XATTR_CREATED /**< This will only succeed if the extended attribute wasn't previously set */ + EINA_XATTR_INSERT, /**< This is the default behaviour, it either creates or replaces the extended attribute */ + EINA_XATTR_REPLACE, /**< This only succeeds if the extended attribute previously existed */ + EINA_XATTR_CREATED /**< This only succeeds if the extended attribute isn't previously set */ } Eina_Xattr_Flags; typedef struct _Eina_Xattr Eina_Xattr; struct _Eina_Xattr { - const char *name; /**< The eXtended attribute name @since 1.2 */ - const char *value; /**< The eXtended attribute value @since 1.2 */ + const char *name; /**< The extended attribute name @since 1.2 */ + const char *value; /**< The extended attribute value @since 1.2 */ - size_t length; /**< The length of the eXtended attribute value @since 1.2 */ + size_t length; /**< The length of the extended attribute value @since 1.2 */ }; /** - * @brief Get an iterator that list all extended attribute of a file. - * - * @param file The filename to retrieve the extended attribute list from. - * @return an iterator. - * - * The iterator will not allocate any data during the iteration step, so you need to copy them yourself - * if you need. + * @brief Gets an iterator that lists all the extended attributes of a file. * * @since 1.1 - */ -EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; - -/** - * @brief Get an iterator that list all extended attribute value related to a fd. * - * @param file The filename to retrieve the extended attribute list from. - * @return an iterator. + * @since_tizen 2.3 * - * The iterator will not allocate any data during the iteration step, so you need to copy them yourself - * if you need. The iterator will provide an Eina_Xattr structure. + * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself + * if you need. + * + * @param[in] file The file name to retrieve the extended attribute list from + * @return An iterator * - * @since 1.2 */ -EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; +EAPI Eina_Iterator *eina_xattr_ls(const char *file); /** - * @brief Get an iterator that list all extended attribute related to a fd. + * @brief Gets an iterator that lists all the extended attribute values related to a file. * - * @param fd The file descriptor to retrieve the extended attribute list from. - * @return an iterator. + * @since 1.2 * - * The iterator will not allocate any data during the iteration step, so you need to copy them yourself - * if you need. + * @since_tizen 2.3 + * + * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself + * if you need them. The iterator provides an Eina_Xattr structure. + * + * @param[in] file The file name to retrieve the extended attribute list from + * @return An iterator * - * @since 1.2 */ -EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; +EAPI Eina_Iterator *eina_xattr_value_ls(const char *file); /** - * @brief Get an iterator that list all extended attribute value related to a fd. + * @brief Gets an iterator that lists all extended attribute related to a file. * - * @param fd The file descriptor to retrieve the extended attribute list from. - * @return an iterator. + * @since 1.2 * - * The iterator will not allocate any data during the iteration step, so you need to copy them yourself - * if you need. The iterator will provide an Eina_Xattr structure. + * @since_tizen 2.3 + * + * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself + * if you need them. + * + * @param[in] fd The file descriptor to retrieve the extended attribute list from + * @return An iterator * - * @since 1.2 - */ -EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; - -/** - * @brief Copy the extended attribute from one file to another. - * @param src source file to use as input. - * @param dst destination file to use as output. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * @see eina_xattr_fd_copy() - * @since 1.8 - */ -EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNULL(1, 2); - -/** - * @brief Copy the extended attribute from one file descriptor to another. - * @param src source file descriptor to use as input. - * @param dst destination file descriptor to use as output. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * @see eina_xattr_copy() - * @since 1.8 */ -EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst); +EAPI Eina_Iterator *eina_xattr_fd_ls(int fd); /** - * @brief Retrieve an extended attribute from a file. + * @brief Gets an iterator that lists all extended attribute value related to a file. * - * @param file The file to retrieve the extended attribute from. - * @param attribute The extended attribute name to retrieve. - * @param size The size of the retrieved extended attribute. - * @return the allocated data that hold the extended attribute value. + * @since 1.2 * - * It will return @c NULL and *size will be @c 0 if it fails. + * @since_tizen 2.3 + * + * @remarks The iterator does not allocate any data during the iteration step, so you need to copy them yourself + * if you need them. The iterator provides an Eina_Xattr structure. + * + * @param[in] fd The file descriptor to retrieve the extended attribute list from + * @return An iterator * - * @since 1.1 */ -EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; +EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd); /** - * @brief Retrieve an extended attribute from a file descriptor. + * @brief Gets an extended attribute from a file. * - * @param fd The file descriptor to retrieve the extended attribute from. - * @param attribute The extended attribute name to retrieve. - * @param size The size of the retrieved extended attribute. - * @return the allocated data that hold the extended attribute value. + * @since 1.1 * - * It will return @c NULL and *size will be @c 0 if it fails. + * @since_tizen 2.3 * - * @since 1.8 - */ -EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; - -/** - * @brief Set an extended attribute on a file. + * @remarks It returns @c NULL and *size is @c 0 if it fails. * - * @param file The file to set the extended attribute to. - * @param attribute The attribute to set. - * @param data The data to set. - * @param length The length of the data to set. - * @param flags Define the set policy. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @param[in] file The file to retrieve the extended attribute from + * @param[in] attribute The extended attribute name to retrieve + * @param[out] size The size of the retrieved extended attribute + * @return The allocated data that hold the extended attribute value * - * @since 1.1 */ -EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(1, 2, 3); +EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size); /** - * @brief Set an extended attribute on a file descriptor. + * @brief Sets an extended attribute to a file. * - * @param fd The file descriptor to set the extended attribute to. - * @param attribute The attribute to set. - * @param data The data to set. - * @param length The length of the data to set. - * @param flags Define the set policy. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @since 1.1 * - * @since 1.8 - */ -EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(2, 3); - - -/** - * @brief Delete (remove) an extended attribute from a file. + * @since_tizen 2.3 * - * @param file The file to del the extended attribute from. - * @param attribute The attribute to del. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @param[in] file The file to set the extended attribute to + * @param[in] attribute The attribute to set + * @param[in] data The data to set + * @param[in] length The length of the data to set + * @param[in] flags The flag that defines the set policy + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @since 1.8 */ -EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags); /** - * @brief Delete (remove) an extended attribute from a file descriptor. + * @brief Sets a string as an extended attribute property. * - * @param fd The file descriptor to del the extended attribute from. - * @param attribute The attribute to del. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @since 1.1 * - * @since 1.8 - */ -EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL(2); - -/** - * @brief Set a string as a extended attribute properties. + * @since_tizen 2.3 * - * @param file The file to set the string to. - * @param attribute The attribute to set. - * @param data The NULL-terminated string to set. - * @param flags Define the set policy. - * @return EINA_TRUE on success, EINA_FALSE otherwise. + * @param[in] file The file to set the string to + * @param[in] attribute The attribute to set + * @param[in] data The NULL-terminated string to set + * @param[in] flags The flag that defines the set policy + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @since 1.1 */ EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags); /** - * @brief Get a string from an extended attribute properties. + * @brief Gets a string from an extended attribute property. * - * @param file The file to get the string from. - * @param attribute The attribute to get. - * @return A valid string on success, @c NULL otherwise. + * @since 1.1 * - * This call check that the string is properly NULL-terminated before returning it. + * @since_tizen 2.3 + * + * @remarks This call makes sure that the string is properly NULL-terminated before returning it. + * + * @param[in] file The file to get the string from + * @param[in] attribute The attribute to get + * @return A valid string on success, otherwise @c NULL * - * @since 1.1 */ EAPI char *eina_xattr_string_get(const char *file, const char *attribute); /** - * @brief Set a double as a extended attribute properties. - * - * @param file The file to set the double to. - * @param attribute The attribute to set. - * @param value The NULL-terminated double to set. - * @param flags Define the set policy. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets a double as an extended attribute property. * * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] file The file to set the double to + * @param[in] attribute The attribute to set + * @param[in] value The NULL-terminated double to set + * @param[in] flags The flag that defines the set policy + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags); /** - * @brief Get a double from an extended attribute properties. + * @brief Gets a double from an extended attribute property. + * + * @since 1.1 * - * @param file The file to get the string from. - * @param attribute The attribute to get. - * @param value Where to put the extracted value - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @since_tizen 2.3 * - * This call check that the double is correctly set. + * @remarks This call makes sure that the double is correctly set. + * + * @param[in] file The file to get the string from + * @param[in] attribute The attribute to get + * @param[out] value The extracted value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @since 1.1 */ EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value); /** - * @brief Set an int as a extended attribute properties. - * - * @param file The file to set the int to. - * @param attribute The attribute to set. - * @param value The NULL-terminated int to set. - * @param flags Define the set policy. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @brief Sets an integer as a extended attribute property. * * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] file The file to set the integer to + * @param[in] attribute The attribute to set + * @param[in] value The NULL-terminated integer to set + * @param[in] flags The flag that defines the set policy + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags); /** - * @brief Get a int from an extended attribute properties. + * @brief Gets a integer from an extended attribute property. * - * @param file The file to get the string from. - * @param attribute The attribute to get. - * @param value Where to put the extracted value - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @since 1.1 * - * This call check that the int is correctly set. + * @since_tizen 2.3 + * + * @remarks This call makes sure that the integer is correctly set. + * + * @param[in] file The file to get the string from + * @param[in] attribute The attribute to get + * @param[out] value The extracted value + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @since 1.1 */ EAPI Eina_Bool eina_xattr_int_get(const char *file, const char *attribute, int *value); diff --git a/src/lib/eio/Eio.h b/src/lib/eio/Eio.h index 0eb38c88b0..4cff518d4a 100644 --- a/src/lib/eio/Eio.h +++ b/src/lib/eio/Eio.h @@ -1,10 +1,8 @@ -/* EIO - Core asynchronous input/output operation library. +/* EIO - EFL data type library * Copyright (C) 2010 Enlightenment Developers: * Cedric Bail <cedric.bail@free.fr> - * Gustavo Sverzut Barbieri <barbieri@gmail.com> * Vincent "caro" Torri <vtorri at univ-evry dot fr> - * Stephen "okra" Houston <unixtitan@gmail.com> - * Guillaume "kuri" Friloux <guillaume.friloux@asp64.com> + * Stephen "okra" Houston <unixtitan@gmail.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -30,7 +28,6 @@ #include <Eina.h> #include <Eet.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI @@ -63,8 +60,8 @@ extern "C" { #endif -#define EIO_VERSION_MAJOR EFL_VERSION_MAJOR -#define EIO_VERSION_MINOR EFL_VERSION_MINOR +#define EIO_VERSION_MAJOR 1 +#define EIO_VERSION_MINOR 8 /** * @typedef Eio_Version @@ -81,77 +78,18 @@ extern "C" { EAPI extern Eio_Version *eio_version; /** - * @file - * @brief Eio asynchronous input/output library + * @internal + * @defgroup Eio_Group Eio + * @ingroup EFL_Group * - * These routines are used for Eio. - */ - -/** - * @page eio_main Eio - * - * @date 2012 (created) - * - * @section toc Table of Contents - * - * @li @ref eio_main_intro - * @li @ref eio_main_compiling - * @li @ref eio_main_next_steps - * @li @ref eio_main_intro_example - * - * @section eio_main_intro Introduction - * - * The Eio library is a library that implements an API for asynchronous - * input/output operation. Most operation are done in a separated thread - * to prevent lock. See @ref Eio_Group. Some helper to work on data - * received in Eio callback are also provided see @ref Eio_Helper. - * It is also possible to work asynchronously on Eina_File with @ref Eio_Map - * or on Eet_File with @ref Eio_Eet. It come with way to manipulate - * eXtended attribute assynchronously with @ref Eio_Xattr. - * - * This library is cross-platform and can be compiled and used on - * Linux, BSD, Opensolaris and Windows (XP and CE). It is heavily - * based on @ref Ecore_Main_Loop_Group. - * - * @section eio_main_compiling How to compile - * - * Eio is a library your application links to. The procedure for this is - * very simple. You simply have to compile your application with the - * appropriate compiler flags that the @c pkg-config script outputs. For - * example: - * - * Compiling C or C++ files into object files: - * - * @verbatim - gcc -c -o main.o main.c `pkg-config --cflags eio` - @endverbatim - * - * Linking object files into a binary executable: - * - * @verbatim - gcc -o my_application main.o `pkg-config --libs eio` - @endverbatim - * - * See @ref pkgconfig - * - * @section eio_main_next_steps Next Steps - * - * After you understood what Eio is and installed it in your system - * you should proceed understanding the programming interface. + * @brief This is the core asynchronous input/output operation * - * Recommended reading: + * All the functions in this group perform input/output operations + * in a separate thread using the infrastructure provided by + * Ecore_Thread and Eina, this means that all functions here are non-blocking. * - * @li @ref Eio_Helper for common functions and library initialization. - * @li @ref Eio_Map to manipulate files asynchronously (mmap). - * @li @ref Eio_Xattr to access file extended attributes (xattr). - * @li @ref Eio_Monitor to monitor for file changes (inotify). - * @li @ref Eio_Eet to access Eet files asynchronously. - * - * @section eio_main_intro_example Introductory Example - * - * @include eio_file_ls.c - * - * More examples can be found at @ref eio_examples. + * The functions displayed here are used to make basic file operations, like + * listing the content of a directory, creating a new directory, etc. * * @{ */ @@ -240,12 +178,13 @@ struct _Eio_Progress /** * @brief List contents of a directory without locking your app. - * @param dir The directory to list. - * @param filter_cb Callback used to decide if the file will be passed to main_cb - * @param main_cb Callback called for each listed file if it was not filtered. - * @param done_cb Callback called when the ls operation is done. - * @param error_cb Callback called when either the directory could not be opened or the operation has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] dir The directory to list. + * @param[in] filter_cb Callback used to decide if the file will be passed to main_cb + * @param[in] main_cb Callback called for each listed file if it was not filtered. + * @param[in] done_cb Callback called when the ls operation is done. + * @param[in] error_cb Callback called when either the directory could not be opened or the operation has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * This function is responsible for listing the content of a directory without blocking your application. @@ -263,12 +202,13 @@ EAPI Eio_File *eio_file_ls(const char *dir, /** * @brief List contents of a directory without locking your app. - * @param dir The directory to list. - * @param filter_cb Callback used to decide if the file will be passed to main_cb - * @param main_cb Callback called from the main loop for each accepted file (not filtered). - * @param done_cb Callback called from the main loop after the contents of the directory has been listed. - * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] dir The directory to list. + * @param[in] filter_cb Callback used to decide if the file will be passed to main_cb + * @param[in] main_cb Callback called from the main loop for each accepted file (not filtered). + * @param[in] done_cb Callback called from the main loop after the contents of the directory has been listed. + * @param[in] error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_direct_ls runs eina_file_direct_ls in a separate thread using @@ -286,12 +226,13 @@ EAPI Eio_File *eio_file_direct_ls(const char *dir, /** * @brief List content of a directory without locking your app. - * @param dir The directory to list. - * @param filter_cb Callback used to decide if the file will be passed to main_cb - * @param main_cb Callback called from the main loop for each accepted file (not filtered). - * @param done_cb Callback called from the main loop after the contents of the directory has been listed. - * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] dir The directory to list. + * @param[in] filter_cb Callback used to decide if the file will be passed to main_cb + * @param[in] main_cb Callback called from the main loop for each accepted file (not filtered). + * @param[in] done_cb Callback called from the main loop after the contents of the directory has been listed. + * @param[in] error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * Every file will be passed to the filter_cb, so it's your job to decide if you @@ -307,13 +248,14 @@ EAPI Eio_File *eio_file_stat_ls(const char *dir, const void *data); /** - * @brief List the content of a directory and all its sub-content asynchronously - * @param dir The directory to list. - * @param filter_cb Callback used to decide if the file will be passed to main_cb - * @param main_cb Callback called from the main loop for each accepted file (not filtered). - * @param done_cb Callback called from the main loop after the contents of the directory has been listed. - * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. - * @param data Unmodified user data passed to callbacks + * @brief List the content of a directory and all it's sub-content asynchronously + * + * @param[in] dir The directory to list. + * @param[in] filter_cb Callback used to decide if the file will be passed to main_cb + * @param[in] main_cb Callback called from the main loop for each accepted file (not filtered). + * @param[in] done_cb Callback called from the main loop after the contents of the directory has been listed. + * @param[in] error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_dir_stat_ls() runs eina_file_stat_ls() recursively in a separate thread using @@ -331,13 +273,14 @@ EAPI Eio_File *eio_dir_stat_ls(const char *dir, const void *data); /** - * @brief List the content of a directory and all its sub-content asynchronously - * @param dir The directory to list. - * @param filter_cb Callback used to decide if the file will be passed to main_cb - * @param main_cb Callback called from the main loop for each accepted file (not filtered). - * @param done_cb Callback called from the main loop after the contents of the directory has been listed. - * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. - * @param data Unmodified user data passed to callbacks + * @brief List the content of a directory and all it's sub-content asynchronously + * + * @param[in] dir The directory to list. + * @param[in] filter_cb Callback used to decide if the file will be passed to main_cb + * @param[in] main_cb Callback called from the main loop for each accepted file (not filtered). + * @param[in] done_cb Callback called from the main loop after the contents of the directory has been listed. + * @param[in] error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_dir_direct_ls() runs eina_file_direct_ls() recursively in a separate thread using @@ -355,10 +298,11 @@ EAPI Eio_File *eio_dir_direct_ls(const char *dir, /** * @brief Stat a file/directory. - * @param path The path to stat. - * @param done_cb Callback called from the main loop when stat was successfully called. - * @param error_cb Callback called from the main loop when stat failed or has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to stat. + * @param[in] done_cb Callback called from the main loop when stat was successfully called. + * @param[in] error_cb Callback called from the main loop when stat failed or has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_direct_stat calls stat in another thread. This prevents any blocking in your apps. @@ -370,11 +314,12 @@ EAPI Eio_File *eio_file_direct_stat(const char *path, /** * @brief Change right of a path. - * @param path The directory path to change access right. - * @param mode The permission to set, follow (mode & ~umask & 0777). - * @param done_cb Callback called when the operation is completed. - * @param error_cb Callback called from if something goes wrong. - * @param data Unmodified user data passed to callbacks. + * + * @param[in] path The directory path to change access right. + * @param[in] mode The permission to set, follow (mode & ~umask & 0777). + * @param[in] done_cb Callback called when the operation is completed. + * @param[in] error_cb Callback called from if something goes wrong. + * @param[in] data Unmodified user data passed to callbacks. * @return A reference to the I/O operation. * * Set a new permission of a path changing it to the mode passed as argument. @@ -388,12 +333,13 @@ EAPI Eio_File *eio_file_chmod(const char *path, /** * @brief Change owner of a path. - * @param path The directory path to change owner. - * @param user The new user to set (can be NULL). - * @param group The new group to set (can be NULL). - * @param done_cb Callback called when the operation is completed. - * @param error_cb Callback called from if something goes wrong. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The directory path to change owner. + * @param[in] user The new user to set (can be NULL). + * @param[in] group The new group to set (can be NULL). + * @param[in] done_cb Callback called when the operation is completed. + * @param[in] error_cb Callback called from if something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * This function will change the owner of a path, setting it to the user and @@ -408,10 +354,11 @@ EAPI Eio_File *eio_file_chown(const char *path, /** * @brief Unlink a file/directory. - * @param path The path to unlink. - * @param done_cb Callback called when the operation is completed. - * @param error_cb Callback called from if something goes wrong. - * @param data Unmodified user data passed to callbacks. + * + * @param[in] path The path to unlink. + * @param[in] done_cb Callback called when the operation is completed. + * @param[in] error_cb Callback called from if something goes wrong. + * @param[in] data Unmodified user data passed to callbacks. * @return A reference to the I/O operation. * * This function will erase a file. @@ -423,11 +370,12 @@ EAPI Eio_File *eio_file_unlink(const char *path, /** * @brief Create a new directory. - * @param path The directory path to create. - * @param mode The permission to set, follow (mode & ~umask & 0777). - * @param done_cb Callback called when the operation is completed. - * @param error_cb Callback called from if something goes wrong. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The directory path to create. + * @param[in] mode The permission to set, follow (mode & ~umask & 0777). + * @param[in] done_cb Callback called when the operation is completed. + * @param[in] error_cb Callback called from if something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * Creates a new directory using the mode provided. @@ -440,15 +388,13 @@ EAPI Eio_File *eio_file_mkdir(const char *path, /** * @brief Move a file asynchronously - * @param source Should be the name of the file to move the data from. - * @param dest Should be the name of the file to move the data to. - * @param progress_cb Callback called to know the progress of the move. - * @param done_cb Callback called when the move is done. - * @param error_cb Callback called when something goes wrong. - * @param data Unmodified user data passed to callbacks - * @return A reference to the I/O operation. * - * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation + * @param[in] source Should be the name of the file to move the data from. + * @param[in] dest Should be the name of the file to move the data to. + * @param[in] progress_cb Callback called to know the progress of the move. + * @param[in] done_cb Callback called when the move is done. + * @param[in] error_cb Callback called when something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * * This function will copy a file from source to dest. It will try to use splice * if possible, if not it will fallback to mmap/write. It will try to preserve @@ -463,14 +409,13 @@ EAPI Eio_File *eio_file_move(const char *source, /** * @brief Copy a file asynchronously - * @param source Should be the name of the file to copy the data from. - * @param dest Should be the name of the file to copy the data to. - * @param progress_cb Callback called to know the progress of the copy. - * @param done_cb Callback called when the copy is done. - * @param error_cb Callback called when something goes wrong. - * @param data Unmodified user data passed to callbacks * - * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation + * @param[in] source Should be the name of the file to copy the data from. + * @param[in] dest Should be the name of the file to copy the data to. + * @param[in] progress_cb Callback called to know the progress of the copy. + * @param[in] done_cb Callback called when the copy is done. + * @param[in] error_cb Callback called when something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * * This function will copy a file from source to dest. It will try to use splice * if possible, if not it will fallback to mmap/write. It will try to preserve @@ -484,19 +429,17 @@ EAPI Eio_File *eio_file_copy(const char *source, const void *data); /** - * @brief Move a directory and its content asynchronously - * @param source Should be the name of the directory to copy the data from. - * @param dest Should be the name of the directory to copy the data to. - * @param filter_cb Possible to deny the move of some files/directories. - * @param progress_cb Callback called to know the progress of the copy. - * @param done_cb Callback called when the copy is done. - * @param error_cb Callback called when something goes wrong. - * @param data Unmodified user data passed to callbacks - * @return A reference to the I/O operation. + * @brief Move a directory and it's content asynchronously * - * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation + * @param[in] source Should be the name of the directory to copy the data from. + * @param[in] dest Should be the name of the directory to copy the data to. + * @param[in] filter_cb Possible to deny the move of some files/directories. + * @param[in] progress_cb Callback called to know the progress of the copy. + * @param[in] done_cb Callback called when the copy is done. + * @param[in] error_cb Callback called when something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * - * This function will move a directory and all its content from source to dest. + * This function will move a directory and all it's content from source to dest. * It will try first to rename the directory, if not it will try to use splice * if possible, if not it will fallback to mmap/write. * It will try to preserve access right, but not user/group identity. @@ -515,7 +458,7 @@ EAPI Eio_File *eio_dir_move(const char *source, const void *data); /** - * @brief Copy a directory and its content asynchronously + * @brief Copy a directory and it's content asynchronously * @param source Should be the name of the directory to copy the data from. * @param dest Should be the name of the directory to copy the data to. * @param filter_cb Possible to deny the move of some files/directories. @@ -523,11 +466,8 @@ EAPI Eio_File *eio_dir_move(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks - * @return A reference to the I/O operation. * - * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation - * - * This function will copy a directory and all its content from source to dest. + * This function will copy a directory and all it's content from source to dest. * It will try to use splice if possible, if not it will fallback to mmap/write. * It will try to preserve access right, but not user/group identity. * Every file will be passed to the filter_cb, so it's your job to decide if you @@ -543,18 +483,16 @@ EAPI Eio_File *eio_dir_copy(const char *source, const void *data); /** - * @brief Remove a directory and its content asynchronously - * @param path Should be the name of the directory to destroy. - * @param filter_cb Possible to deny the move of some files/directories. - * @param progress_cb Callback called to know the progress of the copy. - * @param done_cb Callback called when the copy is done. - * @param error_cb Callback called when something goes wrong. - * @param data Unmodified user data passed to callbacks - * @return A reference to the I/O operation. + * @brief Remove a directory and it's content asynchronously * - * @return an Eio_File pointer, handler to the unlink operation, can be used to cancel the operation + * @param[in] path Should be the name of the directory to destroy. + * @param[in] filter_cb Possible to deny the move of some files/directories. + * @param[in] progress_cb Callback called to know the progress of the copy. + * @param[in] done_cb Callback called when the copy is done. + * @param[in] error_cb Callback called when something goes wrong. + * @param[in] data Unmodified user data passed to callbacks * - * This function will remove a directory and all its content. + * This function will remove a directory and all it's content. * Every file will be passed to the filter_cb, so it's your job to decide if you * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to * the main_cb or EINA_FALSE to ignore it. @@ -571,8 +509,9 @@ EAPI Eio_File *eio_dir_unlink(const char *path, /** + * @internal * @defgroup Eio_Xattr Eio manipulation of eXtended attribute. - * @ingroup Eio + * @ingroup Eio_Group * * @brief A set of function to manipulate data associated with a specific file * @@ -583,12 +522,13 @@ EAPI Eio_File *eio_dir_unlink(const char *path, /** * @brief Assynchronously list all eXtended attribute - * @param path The path to get the eXtended attribute from. - * @param filter_cb Callback called in the thread to validate the eXtended attribute. - * @param main_cb Callback called in the main loop for each accepted eXtended attribute. - * @param done_cb Callback called in the main loop when the all the eXtended attribute have been listed. - * @param error_cb Callback called in the main loop when something goes wrong during the listing of the eXtended attribute. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to get the eXtended attribute from. + * @param[in] filter_cb Callback called in the thread to validate the eXtended attribute. + * @param[in] main_cb Callback called in the main loop for each accepted eXtended attribute. + * @param[in] done_cb Callback called in the main loop when the all the eXtended attribute have been listed. + * @param[in] error_cb Callback called in the main loop when something goes wrong during the listing of the eXtended attribute. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. */ EAPI Eio_File *eio_file_xattr(const char *path, @@ -600,13 +540,14 @@ EAPI Eio_File *eio_file_xattr(const char *path, /** * @brief Define an extented attribute on a file/directory. - * @param path The path to set the attribute on. - * @param attribute The name of the attribute to define. - * @param xattr_int The value to link the attribute with. - * @param flags Whether to insert, replace or create the attribute. - * @param done_cb The callback called from the main loop when setxattr succeeded. - * @param error_cb The callback called from the main loop when setxattr failed. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to set the attribute on. + * @param[in] attribute The name of the attribute to define. + * @param[in] xattr_int The value to link the attribute with. + * @param[in] flags Wether to insert, replace or create the attribute. + * @param[in] done_cb The callback called from the main loop when setxattr succeeded. + * @param[in] error_cb The callback called from the main loop when setxattr failed. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_int_set calls eina_xattr_int_set from another thread. This prevents blocking in your apps. If @@ -622,13 +563,14 @@ EAPI Eio_File *eio_file_xattr_int_set(const char *path, /** * @brief Define an extented attribute on a file/directory. - * @param path The path to set the attribute on. - * @param attribute The name of the attribute to define. - * @param xattr_double The value to link the attribute with. - * @param flags Whether to insert, replace or create the attribute. - * @param done_cb The callback called from the main loop when setxattr succeeded. - * @param error_cb The callback called from the main loop when setxattr failed. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to set the attribute on. + * @param[in] attribute The name of the attribute to define. + * @param[in] xattr_double The value to link the attribute with. + * @param[in] flags Wether to insert, replace or create the attribute. + * @param[in] done_cb The callback called from the main loop when setxattr succeeded. + * @param[in] error_cb The callback called from the main loop when setxattr failed. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_double_set calls eina_xattr_double_set from another thread. This prevents blocking in your apps. If @@ -646,7 +588,7 @@ EAPI Eio_File *eio_file_xattr_double_set(const char *path, * @param path The path to set the attribute on. * @param attribute The name of the attribute to define. * @param xattr_string The string to link the attribute with. - * @param flags Whether to insert, replace or create the attribute. + * @param flags Wether to insert, replace or create the attribute. * @param done_cb The callback called from the main loop when setxattr succeeded. * @param error_cb The callback called from the main loop when setxattr failed. * @param data Unmodified user data passed to callbacks @@ -664,14 +606,15 @@ EAPI Eio_File *eio_file_xattr_string_set(const char *path, const void *data); /** * @brief Define an extented attribute on a file/directory. - * @param path The path to set the attribute on. - * @param attribute The name of the attribute to define. - * @param xattr_data The data to link the attribute with. - * @param xattr_size The size of the data to set. - * @param flags Whether to insert, replace or create the attribute. - * @param done_cb The callback called from the main loop when setxattr succeeded. - * @param error_cb The callback called from the main loop when setxattr failed. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to set the attribute on. + * @param[in] attribute The name of the attribute to define. + * @param[in] xattr_data The data to link the attribute with. + * @param[in] xattr_size The size of the data to set. + * @param[in] flags Wether to insert, replace or create the attribute. + * @param[in] done_cb The callback called from the main loop when setxattr succeeded. + * @param[in] error_cb The callback called from the main loop when setxattr failed. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_set calls setxattr from another thread. This prevents blocking in your apps. If @@ -688,11 +631,12 @@ EAPI Eio_File *eio_file_xattr_set(const char *path, /** * @brief Retrieve the extended attribute of a file/directory. - * @param path The path to retrieve the extended attribute from. - * @param attribute The name of the attribute to retrieve. - * @param done_cb Callback called from the main loop when getxattr succeeded. - * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to retrieve the extended attribute from. + * @param[in] attribute The name of the attribute to retrieve. + * @param[in] done_cb Callback called from the main loop when getxattr succeeded. + * @param[in] error_cb Callback called from the main loop when getxattr failed or has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_get calls getxattr from another thread. This prevents blocking in your apps. @@ -704,11 +648,12 @@ EAPI Eio_File *eio_file_xattr_get(const char *path, const void *data); /** * @brief Retrieve a extended attribute of a file/directory. - * @param path The path to retrieve the extended attribute from. - * @param attribute The name of the attribute to retrieve. - * @param done_cb Callback called from the main loop when getxattr succeeded. - * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to retrieve the extended attribute from. + * @param[in] attribute The name of the attribute to retrieve. + * @param[in] done_cb Callback called from the main loop when getxattr succeeded. + * @param[in] error_cb Callback called from the main loop when getxattr failed or has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_int_get calls eina_xattr_int_get from another thread. This prevents blocking in your apps. @@ -720,11 +665,12 @@ EAPI Eio_File *eio_file_xattr_int_get(const char *path, const void *data); /** * @brief Retrieve a extended attribute of a file/directory. - * @param path The path to retrieve the extended attribute from. - * @param attribute The name of the attribute to retrieve. - * @param done_cb Callback called from the main loop when getxattr succeeded. - * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to retrieve the extended attribute from. + * @param[in] attribute The name of the attribute to retrieve. + * @param[in] done_cb Callback called from the main loop when getxattr succeeded. + * @param[in] error_cb Callback called from the main loop when getxattr failed or has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_double_get calls eina_xattr_double_get from another thread. This prevents blocking in your apps. @@ -736,11 +682,12 @@ EAPI Eio_File *eio_file_xattr_double_get(const char *path, const void *data); /** * @brief Retrieve a string extended attribute of a file/directory. - * @param path The path to retrieve the extended attribute from. - * @param attribute The name of the attribute to retrieve. - * @param done_cb Callback called from the main loop when getxattr succeeded. - * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. - * @param data Unmodified user data passed to callbacks + * + * @param[in] path The path to retrieve the extended attribute from. + * @param[in] attribute The name of the attribute to retrieve. + * @param[in] done_cb Callback called from the main loop when getxattr succeeded. + * @param[in] error_cb Callback called from the main loop when getxattr failed or has been canceled. + * @param[in] data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * * eio_file_xattr_string_get calls eina_xattr_string_get from another thread. This prevents blocking in your apps. @@ -756,8 +703,9 @@ EAPI Eio_File *eio_file_xattr_string_get(const char *path, */ /** + * @internal * @defgroup Eio_Helper Eio Reference helper API - * @ingroup Eio + * @ingroup Eio_Group * * @brief This are helper provided around core Eio API. * @@ -769,47 +717,21 @@ EAPI Eio_File *eio_file_xattr_string_get(const char *path, /** - * @brief Initialize eio and all its required submodule. + * @brief Initialize eio and all it's required submodule. * @return the current number of eio users. */ EAPI int eio_init(void); /** - * @brief Shutdown eio and all its submodule if possible. + * @brief Shutdown eio and all it's submodule if possible. * @return the number of pending users of eio. */ EAPI int eio_shutdown(void); /** - * @brief Set the limit to the maximum amount of memory used - * @param limit The actual limit to set. - * - * Eio work by burst, allocating memory in a thread and moving it - * back to the main loop. This result in quite some huge memory - * usage if the main loop is to slow to cope with the speed of the - * thread. By setting this limit, the thread will block until - * enough memory has been freed to be below the limit again. - * - * By default no limit is set and any value < 0 will mean no limit. - * - * @note You should give at least a reasonable amount of memory or - * the thread might stall. - * @since 1.10 - */ -EAPI void eio_memory_burst_limit_set(size_t limit); - -/** - * @brief Get the actual limit to the maximum amount of memory used - * @return The current limit being set. - * - * @since 1.10 - * @see eio_memory_burst_limit_set - */ -EAPI size_t eio_memory_burst_limit_get(void); - -/** * @brief Return the container during EIO operation - * @param ls The asynchronous I/O operation to retrieve container from. + * + * @param[in] ls The asynchronous I/O operation to retrieve container from. * @return NULL if not available, a DIRP if it is. * * This is only available and make sense in the thread callback, not in @@ -819,7 +741,8 @@ EAPI void *eio_file_container_get(Eio_File *ls); /** * @brief Cancel any Eio_File. - * @param ls The asynchronous I/O operation to cancel. + * + * @param[in] ls The asynchronous I/O operation to cancel. * @return EINA_FALSE if the destruction is delayed, EINA_TRUE if it's done. * * This will cancel any kind of I/O operation and cleanup the mess. This means @@ -829,7 +752,8 @@ EAPI Eina_Bool eio_file_cancel(Eio_File *ls); /** * @brief Check if an Eio_File operation has been cancelled. - * @param ls The asynchronous I/O operation to check. + * + * @param[in] ls The asynchronous I/O operation to check. * @return EINA_TRUE if it was canceled, EINA_FALSE other wise. * * In case of an error it also return EINA_TRUE. @@ -838,11 +762,12 @@ EAPI Eina_Bool eio_file_check(Eio_File *ls); /** * @brief Associate data with the current filtered file. - * @param ls The Eio_File ls request currently calling the filter callback. - * @param key The key to associate data to. - * @param data The data to associate the data to. - * @param free_cb Optionally a function to call to free the associated data, - * @p data is passed as the callback data parameter. If no @p free_cb is provided + * + * @param[in] ls The Eio_File ls request currently calling the filter callback. + * @param[in] key The key to associate data to. + * @param[in] data The data to associate the data to. + * @param[in] free_cb Optionally a function to call to free the associated data, + * @p data is passed as the callback data parameter. If no @a free_cb is provided * the user @p data remains untouched. * @return EINA_TRUE if insertion was fine. * @@ -855,10 +780,11 @@ EAPI Eina_Bool eio_file_associate_add(Eio_File *ls, /** * @brief Associate data with the current filtered file. - * @param ls The Eio_File ls request currently calling the filter callback. - * @param key The key to associate data to (will not be copied, and the pointer will not be used as long as the file is not notified). - * @param data The data to associate the data to. - * @param free_cb The function to call to free the associated data, @p free_cb will be called if not specified. + * + * @param[in] ls The Eio_File ls request currently calling the filter callback. + * @param[in] key The key to associate data to (will not be copied, and the pointer will not be used as long as the file is not notified). + * @param[in] data The data to associate the data to. + * @param[in] free_cb The function to call to free the associated data, @p free will be called if not specified. * @return EINA_TRUE if insertion was fine. * * This function can only be safely called from within the filter callback. @@ -871,15 +797,17 @@ EAPI Eina_Bool eio_file_associate_direct_add(Eio_File *ls, /** * @brief Get the data associated during the filter callback inside the main loop - * @param ls The Eio_File ls request currently calling the notify callback. - * @param key The key pointing to the data to retrieve. + * + * @param[in] ls The Eio_File ls request currently calling the notify callback. + * @param[in] key The key pointing to the data to retrieve. * @return the data associated with the key or @p NULL if not found. */ EAPI void *eio_file_associate_find(Eio_File *ls, const char *key); /** * @brief get access time from a Eina_Stat - * @param stat the structure to get the atime from + * + * @param[in] stat the structure to get the atime from * @return the last accessed time * * This take care of doing type conversion to match rest of EFL time API. @@ -889,7 +817,8 @@ static inline double eio_file_atime(const Eina_Stat *stat); /** * @brief get modification time from a Eina_Stat - * @param stat the structure to get the mtime from + * + * @param[in] stat the structure to get the mtime from * @return the last modification time * * This take care of doing type conversion to match rest of EFL time API. @@ -898,21 +827,24 @@ static inline double eio_file_mtime(const Eina_Stat *stat); /** * @brief get the size of the file described in Eina_Stat - * @param stat the structure to get the size from + * + * @param[in] stat the structure to get the size from * @return the size of the file */ static inline long long eio_file_size(const Eina_Stat *stat); /** * @brief tell if the stated path was a directory or not. - * @param stat the structure to get the size from + * + * @param[in] stat the structure to get the size from * @return EINA_TRUE, if it was. */ static inline Eina_Bool eio_file_is_dir(const Eina_Stat *stat); /** * @brief tell if the stated path was a link or not. - * @param stat the structure to get the size from + * + * @param[in] stat the structure to get the size from * @return EINA_TRUE, if it was. */ static inline Eina_Bool eio_file_is_lnk(const Eina_Stat *stat); @@ -926,8 +858,9 @@ static inline Eina_Bool eio_file_is_lnk(const Eina_Stat *stat); */ /** + * @internal * @defgroup Eio_Map Manipulate an Eina_File asynchronously - * @ingroup Eio + * @ingroup Eio_Group * * @brief This function help manipulating file asynchronously. * @@ -939,11 +872,12 @@ static inline Eina_Bool eio_file_is_lnk(const Eina_Stat *stat); /** * @brief Assynchronously open a file. - * @param name The file to open. - * @param shared If it's a shared memory file. - * @param open_cb Callback called in the main loop when the file has been successfully opened. - * @param error_cb Callback called in the main loop when the file couldn't be opened. - * @param data Unmodified user data passed to callbacks + * + * @param[in] name The file to open. + * @param[in] shared If it's a shared memory file. + * @param[in] open_cb Callback called in the main loop when the file has been successfully opened. + * @param[in] error_cb Callback called in the main loop when the file couldn't be opened. + * @param[in] data Unmodified user data passed to callbacks * @return Pointer to the file if successfull or NULL otherwise. * */ @@ -954,10 +888,11 @@ EAPI Eio_File *eio_file_open(const char *name, Eina_Bool shared, /** * @brief Assynchronously close a file. - * @param f The file to close. - * @param done_cb Callback called in the main loop when the file has been successfully closed. - * @param error_cb Callback called in the main loop when the file couldn't be closed. - * @param data Unmodified user data passed to callbacks + * + * @param[in] f The file to close. + * @param[in] done_cb Callback called in the main loop when the file has been successfully closed. + * @param[in] error_cb Callback called in the main loop when the file couldn't be closed. + * @param[in] data Unmodified user data passed to callbacks * @return Pointer to the file if successfull or NULL otherwise. */ EAPI Eio_File *eio_file_close(Eina_File *f, @@ -967,12 +902,13 @@ EAPI Eio_File *eio_file_close(Eina_File *f, /** * @brief Assynchronously map a file in memory. - * @param f The file to map. - * @param rule The rule to apply to the map. - * @param filter_cb Callback called in the thread to validate the content of the map. - * @param map_cb Callback called in the main loop when the file has been successfully mapped. - * @param error_cb Callback called in the main loop when the file can't be mapped. - * @param data Unmodified user data passed to callbacks + * + * @param[in] f The file to map. + * @param[in] rule The rule to apply to the map. + * @param[in] filter_cb Callback called in the thread to validate the content of the map. + * @param[in] map_cb Callback called in the main loop when the file has been successfully mapped. + * @param[in] error_cb Callback called in the main loop when the file can't be mapped. + * @param[in] data Unmodified user data passed to callbacks * @return Pointer to the file if successfull or NULL otherwise. * * The container of the Eio_File is the Eina_File. @@ -986,14 +922,15 @@ EAPI Eio_File *eio_file_map_all(Eina_File *f, /** * @brief Assynchronously map a part of a file in memory. - * @param f The file to map. - * @param rule The rule to apply to the map. - * @param offset The offset inside the file - * @param length The length of the memory to map - * @param filter_cb Callback called in the thread to validate the content of the map. - * @param map_cb Callback called in the main loop when the file has been successfully mapped. - * @param error_cb Callback called in the main loop when the file can't be mapped. - * @param data Unmodified user data passed to callbacks + * + * @param[in] f The file to map. + * @param[in] rule The rule to apply to the map. + * @param[in] offset The offset inside the file + * @param[in] length The length of the memory to map + * @param[in] filter_cb Callback called in the thread to validate the content of the map. + * @param[in] map_cb Callback called in the main loop when the file has been successfully mapped. + * @param[in] error_cb Callback called in the main loop when the file can't be mapped. + * @param[in] data Unmodified user data passed to callbacks * @return Pointer to the file if successfull or NULL otherwise. * * The container of the Eio_File is the Eina_File. @@ -1012,8 +949,9 @@ EAPI Eio_File *eio_file_map_new(Eina_File *f, */ /** + * @internal * @defgroup Eio_Eet Eio asynchronous API for Eet file. - * @ingroup Eio + * @ingroup Eio_Group * * @brief This set of functions help in the asynchronous use of Eet * @@ -1022,12 +960,13 @@ EAPI Eio_File *eio_file_map_new(Eina_File *f, /** * @brief Open an eet file on disk, and returns a handle to it asynchronously. - * @param filename The file path to the eet file. eg: @c "/tmp/file.eet". - * @param mode The mode for opening. Either EET_FILE_MODE_READ, + * + * @param[in] filename The file path to the eet file. eg: @c "/tmp/file.eet". + * @param[in] mode The mode for opening. Either EET_FILE_MODE_READ, * EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE. - * @param eet_cb The callback to call when the file has been successfully opened. - * @param error_cb Callback called in the main loop when the file can't be opened. - * @param data Unmodified user data passed to callbacks + * @param[in] eet_cb The callback to call when the file has been successfully opened. + * @param[in] error_cb Callback called in the main loop when the file can't be opened. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. * * This function calls eet_open() from another thread using Ecore_Thread. @@ -1039,10 +978,11 @@ EAPI Eio_File *eio_eet_open(const char *filename, const void *data); /** * @brief Close an eet file handle and flush pending writes asynchronously. - * @param ef A valid eet file handle. - * @param done_cb Callback called from the main loop when the file has been closed. - * @param error_cb Callback called in the main loop when the file can't be closed. - * @param data Unmodified user data passed to callbacks + * + * @param[in] ef A valid eet file handle. + * @param[in] done_cb Callback called from the main loop when the file has been closed. + * @param[in] error_cb Callback called in the main loop when the file can't be closed. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. * * This function will call eet_close() from another thread by @@ -1056,10 +996,11 @@ EAPI Eio_File *eio_eet_close(Eet_File *ef, /** * @brief Sync content of an eet file handle, flushing pending writes asynchronously. - * @param ef A valid eet file handle. - * @param done_cb Callback called from the main loop when the file has been synced. - * @param error_cb Callback called in the main loop when the file can't be synced. - * @param data Unmodified user data passed to callbacks + * + * @param[in] ef A valid eet file handle. + * @param[in] done_cb Callback called from the main loop when the file has been synced. + * @param[in] error_cb Callback called in the main loop when the file can't be synced. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. * * This function will call eet_sync() from another thread. As long as the done_cb or @@ -1073,15 +1014,16 @@ EAPI Eio_File *eio_eet_sync(Eet_File *ef, /** * @brief Write a data structure from memory and store in an eet file * using a cipher asynchronously. - * @param ef The eet file handle to write to. - * @param edd The data descriptor to use when encoding. - * @param name The key to store the data under in the eet file. - * @param cipher_key The key to use as cipher. - * @param write_data A pointer to the data structure to save and encode. - * @param compress Compression flags for storage. - * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. - * @param error_cb Callback called in the main loop when the file can't be written. - * @param user_data Private data given to each callback. + * + * @param[in] ef The eet file handle to write to. + * @param[in] edd The data descriptor to use when encoding. + * @param[in] name The key to store the data under in the eet file. + * @param[in] cipher_key The key to use as cipher. + * @param[in] write_data A pointer to the data structure to save and encode. + * @param[in] compress Compression flags for storage. + * @param[in] done_cb Callback called from the main loop when the data has been put in the Eet_File. + * @param[in] error_cb Callback called in the main loop when the file can't be written. + * @param[in] user_data Private data given to each callback. * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_data_write_cipher(Eet_File *ef, @@ -1096,13 +1038,14 @@ EAPI Eio_File *eio_eet_data_write_cipher(Eet_File *ef, /** * @brief Read a data structure from an eet file and decodes it using a cipher asynchronously. - * @param ef The eet file handle to read from. - * @param edd The data descriptor handle to use when decoding. - * @param name The key the data is stored under in the eet file. - * @param cipher_key The key to use as cipher. - * @param done_cb Callback called from the main loop when the data has been read and decoded. - * @param error_cb Callback called in the main loop when the data can't be read. - * @param data Unmodified user data passed to callbacks + * + * @param[in] ef The eet file handle to read from. + * @param[in] edd The data descriptor handle to use when decoding. + * @param[in] name The key the data is stored under in the eet file. + * @param[in] cipher_key The key to use as cipher. + * @param[in] done_cb Callback called from the main loop when the data has been read and decoded. + * @param[in] error_cb Callback called in the main loop when the data can't be read. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_data_read_cipher(Eet_File *ef, @@ -1115,19 +1058,20 @@ EAPI Eio_File *eio_eet_data_read_cipher(Eet_File *ef, /** * @brief Write image data to the named key in an eet file asynchronously. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param write_data A pointer to the image pixel data. - * @param w The width of the image in pixels. - * @param h The height of the image in pixels. - * @param alpha The alpha channel flag. - * @param compress The compression amount. - * @param quality The quality encoding amount. - * @param lossy The lossiness flag. - * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. - * @param error_cb Callback called in the main loop when the file can't be written. - * @param user_data Private data given to each callback. + * + * @param[in] ef A valid eet file handle opened for writing. + * @param[in] name Name of the entry. eg: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher. + * @param[in] write_data A pointer to the image pixel data. + * @param[in] w The width of the image in pixels. + * @param[in] h The height of the image in pixels. + * @param[in] alpha The alpha channel flag. + * @param[in] compress The compression amount. + * @param[in] quality The quality encoding amount. + * @param[in] lossy The lossiness flag. + * @param[in] done_cb Callback called from the main loop when the data has been put in the Eet_File. + * @param[in] error_cb Callback called in the main loop when the file can't be written. + * @param[in] user_data Private data given to each callback. * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_data_image_write_cipher(Eet_File *ef, @@ -1146,11 +1090,12 @@ EAPI Eio_File *eio_eet_data_image_write_cipher(Eet_File *ef, /** * @brief Read a specified entry from an eet file and return data - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param done_cb Callback called from the main loop when the data has been read. - * @param error_cb Callback called in the main loop when the data can't be read. - * @param data Unmodified user data passed to callbacks + * + * @param[in] ef A valid eet file handle opened for reading. + * @param[in] name Name of the entry. eg: "/base/file_i_want". + * @param[in] done_cb Callback called from the main loop when the data has been read. + * @param[in] error_cb Callback called in the main loop when the data can't be read. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_read_direct(Eet_File *ef, @@ -1161,12 +1106,13 @@ EAPI Eio_File *eio_eet_read_direct(Eet_File *ef, /** * @brief Read a specified entry from an eet file and return data - * @param ef A valid eet file handle opened for reading. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param cipher_key The key to use as cipher. - * @param done_cb Callback called from the main loop when the data has been read. - * @param error_cb Callback called in the main loop when the data can't be read. - * @param data Unmodified user data passed to callbacks + * + * @param[in] ef A valid eet file handle opened for reading. + * @param[in] name Name of the entry. eg: "/base/file_i_want". + * @param[in] cipher_key The key to use as cipher. + * @param[in] done_cb Callback called from the main loop when the data has been read. + * @param[in] error_cb Callback called in the main loop when the data can't be read. + * @param[in] data Unmodified user data passed to callbacks * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_read_cipher(Eet_File *ef, @@ -1178,15 +1124,16 @@ EAPI Eio_File *eio_eet_read_cipher(Eet_File *ef, /** * @brief Write a specified entry to an eet file handle using a cipher. - * @param ef A valid eet file handle opened for writing. - * @param name Name of the entry. eg: "/base/file_i_want". - * @param write_data Pointer to the data to be stored. - * @param size Length in bytes in the data to be stored. - * @param compress Compression flags (1 == compress, 0 = don't compress). - * @param cipher_key The key to use as cipher. - * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. - * @param error_cb Callback called in the main loop when the file can't be written. - * @param user_data Private data given to each callback. + * + * @param[in] ef A valid eet file handle opened for writing. + * @param[in] name Name of the entry. eg: "/base/file_i_want". + * @param[in] write_data Pointer to the data to be stored. + * @param[in] size Length in bytes in the data to be stored. + * @param[in] compress Compression flags (1 == compress, 0 = don't compress). + * @param[in] cipher_key The key to use as cipher. + * @param[in] done_cb Callback called from the main loop when the data has been put in the Eet_File. + * @param[in] error_cb Callback called in the main loop when the file can't be written. + * @param[in] user_data Private data given to each callback. * @return NULL in case of a failure. */ EAPI Eio_File *eio_eet_write_cipher(Eet_File *ef, @@ -1204,8 +1151,9 @@ EAPI Eio_File *eio_eet_write_cipher(Eet_File *ef, */ /** + * @internal * @defgroup Eio_Monitor Eio file and directory monitoring API - * @ingroup Eio + * @ingroup Eio_Group * * @brief These function monitor changes in directories and files * @@ -1247,7 +1195,8 @@ struct _Eio_Monitor_Event /** * @brief Adds a file/directory to monitor (inotify mechanism) - * @param path file/directory to monitor + * + * @param[in] path file/directory to monitor * @return NULL in case of a failure or a pointer to the monitor in case of * success. * @@ -1259,7 +1208,8 @@ EAPI Eio_Monitor *eio_monitor_add(const char *path); /** * @brief Adds a file/directory to monitor - * @param path file/directory to monitor + * + * @param[in] path file/directory to monitor * @return NULL in case of a failure or a pointer to the monitor in case of * success. * @warning Do NOT pass non-stringshared strings to this function! @@ -1272,7 +1222,8 @@ EAPI Eio_Monitor *eio_monitor_stringshared_add(const char *path); /** * @brief Deletes a path from the “watched” list - * @param monitor The Eio_Monitor you want to stop watching. + * + * @param[in] monitor The Eio_Monitor you want to stop watching. * It can only be an Eio_Monitor returned to you from calling * eio_monitor_add() or eio_monitor_stringshared_add() */ @@ -1281,7 +1232,8 @@ EAPI void eio_monitor_del(Eio_Monitor *monitor); /** * @brief returns the path being watched by the given * Eio_Monitor. - * @param monitor Eio_Monitor to return the path of + * + * @param[in] monitor Eio_Monitor to return the path of * @return The stringshared path belonging to @p monitor */ EAPI const char *eio_monitor_path_get(Eio_Monitor *monitor); diff --git a/src/lib/embryo/Embryo.h b/src/lib/embryo/Embryo.h index 413c38bf1a..62cd10ddce 100644 --- a/src/lib/embryo/Embryo.h +++ b/src/lib/embryo/Embryo.h @@ -1,20 +1,19 @@ -/** +/** +@internal @brief Embryo Library - -These routines are used for Embryo. -@page embryo_main Embryo +These routines are used for Embryo. -@date 2004 (created) -@note based on Compuphase (http://www.compuphase.com) PAWN language. +@page Embryo Library Documentation -@section toc Table of Contents +@image html e_big.png -@li @ref embryo_main_intro -@li @ref embryo_main_compiling -@li @ref embryo_main_next_steps +@version 1.7.0 +@author Carsten Haitzler <raster\@rasterman.com> +@author Compuphase http://www.compuphase.com +@date 2004-2012 -@section embryo_main_intro Introduction +@section intro What is Embryo? Embryo is a tiny library designed to interpret limited Small programs compiled by the included compiler, @c embryo_cc. It is mostly a cleaned @@ -28,40 +27,16 @@ For more information about the Pawn language, see @latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly For the basics about the Small language, see @ref Small_Page. -@section embryo_main_compiling How to compile - -Embryo 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 embryo` -@endverbatim - -Linking object files into a binary executable: - -@verbatim -gcc -o my_application main.o `pkg-config --libs embryo` -@endverbatim - -See @ref pkgconfig - -@section embryo_main_next_steps Next Steps - -After you understood what Embryo is and installed it in your system you -should proceed understanding the programming interface. - -Recommended reading: - -@li @ref Embryo_Program_Creation_Group to create Embryo from memory or file. -@li @ref Embryo_Func_Group to expose functions to Embryo. -@li @ref Embryo_Program_VM_Group to push pop virtual machine. -@li @ref Embryo_Run_Group to run it. +@section How_to_Use How to Use Embryo? +To use Embryo in your code, you need to do at least the following: +@li Include Embryo.h. +@li Load the Embryo program using one of the + @ref Embryo_Program_Creation_Group. +@li Set up the native calls with #embryo_program_native_call_add. +@li Create a virtual machine with #embryo_program_vm_push. +@li Then run the program with @ref embryo_program_run. @todo Clean up compiler code. @todo Proper overview of the operation of the interpreter, that is how @@ -95,7 +70,7 @@ The scope and usage of a variable depends on its declaration. @li A stock variable is one that may not be compiled into a program if it is not used. It is declared using @c stock. @li A public variable is one that can be read by the host program using - @ref embryo_program_variable_find. It is declared using @c public + #embryo_program_variable_find. It is declared using @c public keyword. Remember that the keywords above are to be used on their own. That is, @@ -336,8 +311,6 @@ This is the @e only file you need to include. #ifndef _EMBRYO_H #define _EMBRYO_H -#include <Efl_Config.h> - #ifdef EAPI # undef EAPI #endif @@ -368,19 +341,15 @@ This is the @e only file you need to include. extern "C" { #endif -#define EMBRYO_VERSION_MAJOR EFL_VERSION_MAJOR -#define EMBRYO_VERSION_MINOR EFL_VERSION_MINOR - - /** - * @typedef Embryo_Version - * Represents the current version of Embryo - */ +#define EMBRYO_VERSION_MAJOR 1 +#define EMBRYO_VERSION_MINOR 8 + typedef struct _Embryo_Version { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Embryo is built from) */ + int major; + int minor; + int micro; + int revision; } Embryo_Version; EAPI extern Embryo_Version *embryo_version; @@ -456,14 +425,15 @@ extern "C" { # define EMBRYO_CELL_TO_FLOAT(c) ((Embryo_Float_Cell) c).f #endif - /** - * @defgroup Embryo_Library_Group Library Maintenance Functions - * @ingroup Embryo - * - * Functions that start up and shutdown the Embryo library. - */ - - +/** + * @internal + * @defgroup Embryo_Library_Group Embryo + * @ingroup EFL_Group + * + * Functions that start up and shutdown the Embryo library. + * @{ + */ + /** * Initialises the Embryo library. * @return The number of times the library has been initialised without being @@ -471,82 +441,85 @@ extern "C" { * @ingroup Embryo_Library_Group */ EAPI int embryo_init(void); - + /** - * Shuts down the Embryo library. + * @brief Shuts down the Embryo library. * @return The number of times the library has been initialised without being * shutdown. * @ingroup Embryo_Library_Group */ EAPI int embryo_shutdown(void); - /** - * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions - * @ingroup Embryo - * - * Functions that set up programs, and destroy them. - */ - /** - * Creates a new Embryo program, with bytecode data that can be freed. - * @param data Pointer to the bytecode of the program. - * @param size Number of bytes of bytecode. + * @internal + * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions + * @ingroup Embryo_Library_Group + * + * Functions that set up programs, and destroy them. + */ + +/** + * @brief Creates a new Embryo program, with bytecode data that can be freed. + * + * @param[in] data Pointer to the bytecode of the program. + * @param[in] size Number of bytes of bytecode. * @return A new Embryo program. * @ingroup Embryo_Program_Creation_Group */ EAPI Embryo_Program *embryo_program_new(void *data, int size); - + /** - * Creates a new Embryo program, with bytecode data that cannot be + * @brief Creates a new Embryo program, with bytecode data that cannot be * freed. - * @param data Pointer to the bytecode of the program. - * @param size Number of bytes of bytecode. + * + * @param[in] data Pointer to the bytecode of the program. + * @param[in] size Number of bytes of bytecode. * @return A new Embryo program. * @ingroup Embryo_Program_Creation_Group */ EAPI Embryo_Program *embryo_program_const_new(void *data, int size); - + /** - * Creates a new Embryo program based on the bytecode data stored in the + * @brief Creates a new Embryo program based on the bytecode data stored in the * given file. - * @param file Filename of the given file. + * + * @param[in] file Filename of the given file. * @return A new Embryo program. * @ingroup Embryo_Program_Creation_Group */ EAPI Embryo_Program *embryo_program_load(const char *file); /** - * Frees the given Embryo program. - * @param ep The given program. + * @brief Frees the given Embryo program. + * + * @param[in] ep The given program. * @ingroup Embryo_Program_Creation_Group */ EAPI void embryo_program_free(Embryo_Program *ep); /** - * Adds a native program call to the given Embryo program. - * @param ep The given Embryo program. - * @param name The name for the call used in the script. - * @param func The function to use when the call is made. - * @ingroup Embryo_Func_Group + * @internal + * @defgroup Embryo_Func_Group Function Functions + * @ingroup Embryo_Library_Group + * + * @brief Functions that deal with Embryo program functions. */ /** - * @defgroup Embryo_Func_Group Function Functions - * @ingroup Embryo + * @brief Adds a native program call to the given Embryo program. * - * Functions that deal with Embryo program functions. + * @param[in] ep The given Embryo program. + * @param[in] name The name for the call used in the script. + * @param[in] func The function to use when the call is made. + * @ingroup Embryo_Func_Group */ + EAPI void embryo_program_native_call_add(Embryo_Program *ep, const char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params)); /** - * Resets the current virtual machine session of the given program. - * @param ep The given program. - * @ingroup Embryo_Program_VM_Group - */ - -/** + * @internal * @defgroup Embryo_Program_VM_Group Virtual Machine Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * Functions that deal with creating and destroying virtual machine sessions * for a given program. @@ -559,71 +532,91 @@ EAPI void embryo_program_native_call_add(Embryo_Program *ep, const c * to the old session. * * A new virtual machine session is created by pushing a new virtual machine - * onto the session stack of a program using @ref embryo_program_vm_push. + * onto the session stack of a program using #embryo_program_vm_push. * The current virtual machine session can be destroyed by calling * @ref embryo_program_vm_pop. */ + +/** + * @brief Resets the current virtual machine session of the given program. + * @param ep The given program. + * @ingroup Embryo_Program_VM_Group + */ + EAPI void embryo_program_vm_reset(Embryo_Program *ep); /** - * Starts a new virtual machine session for the given program. + * @brief Starts a new virtual machine session for the given program. * * See @ref Embryo_Program_VM_Group for more information about how this works. * - * @param ep The given program. + * @param[in] ep The given program. * @ingroup Embryo_Program_VM_Group */ EAPI void embryo_program_vm_push(Embryo_Program *ep); /** - * Frees the current virtual machine session associated with the given program. + * @brief Frees the current virtual machine session associated with the given program. * * See @ref Embryo_Program_VM_Group for more information about how this works. * Note that you will need to retrieve any return data or data on the stack * before you pop. * - * @param ep The given program. + * @param[in] ep The given program. * @ingroup Embryo_Program_VM_Group */ EAPI void embryo_program_vm_pop(Embryo_Program *ep); - -/** - * Ensures that the given unsigned short integer is in the small - * endian format. - * @param v Pointer to the given integer. - * @ingroup Embryo_Swap_Group - */ /** + * @internal * @defgroup Embryo_Swap_Group Byte Swapping Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * - * Functions that are used to ensure that integers passed to the + * @brief Functions that are used to ensure that integers passed to the * virtual machine are in small endian format. These functions are * used to ensure that the virtual machine operates correctly on big * endian machines. */ + +/** + * @brief Ensures that the given unsigned short integer is in the small + * endian format. + * @param v Pointer to the given integer. + * @ingroup Embryo_Swap_Group + */ EAPI void embryo_swap_16(unsigned short *v); - + /** - * Ensures that the given unsigned integer is in the small endian + * @brief Ensures that the given unsigned integer is in the small endian * format. - * @param v Pointer to the given integer. + * + * @param[in] v Pointer to the given integer. * @ingroup Embryo_Swap_Group */ EAPI void embryo_swap_32(unsigned int *v); /** - * Returns the function in the given program with the given name. - * @param ep The given program. - * @param name The given function name. + * @brief Returns the function in the given program with the given name. + * + * @param[in] ep The given program. + * @param[in] name The given function name. * @return The function if successful. Otherwise, @c EMBRYO_FUNCTION_NONE. * @ingroup Embryo_Func_Group */ EAPI Embryo_Function embryo_program_function_find(Embryo_Program *ep, const char *name); - + /** - * Retrieves the location of the public variable in the given program + * @internal + * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions + * @ingroup Embryo_Library_Group + * + * @brief In an Embryo program, a global variable can be declared public, as + * described in @ref Small_Scope_Subsection. The functions here allow + * the host program to access these public variables. + */ + +/** + * @brief Retrieves the location of the public variable in the given program * with the given name. * @param ep The given program. * @param name The given name. @@ -631,191 +624,198 @@ EAPI Embryo_Function embryo_program_function_find(Embryo_Program *ep, const cha * otherwise. * @ingroup Embryo_Public_Variable_Group */ +EAPI Embryo_Cell embryo_program_variable_find(Embryo_Program *ep, const char *name); /** - * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions - * @ingroup Embryo + * @brief Retrieves the number of public variables in the given program. * - * In an Embryo program, a global variable can be declared public, as - * described in @ref Small_Scope_Subsection. The functions here allow - * the host program to access these public variables. - */ -EAPI Embryo_Cell embryo_program_variable_find(Embryo_Program *ep, const char *name); - -/** - * Retrieves the number of public variables in the given program. - * @param ep The given program. + * @param[in] ep The given program. * @return The number of public variables. * @ingroup Embryo_Public_Variable_Group */ EAPI int embryo_program_variable_count_get(Embryo_Program *ep); /** - * Retrieves the location of the public variable in the given program + * @brief Retrieves the location of the public variable in the given program * with the given identifier. - * @param ep The given program. - * @param num The identifier of the public variable. + * + * @param[in] ep The given program. + * @param[in] num The identifier of the public variable. * @return The virtual machine address of the variable if found. * @c EMBRYO_CELL_NONE otherwise. * @ingroup Embryo_Public_Variable_Group */ EAPI Embryo_Cell embryo_program_variable_get(Embryo_Program *ep, int num); - -/** - * Sets the error code for the given program to the given code. - * @param ep The given program. - * @param error The given error code. - * @ingroup Embryo_Error_Group - */ /** + * @internal * @defgroup Embryo_Error_Group Error Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * Functions that set and retrieve error codes in Embryo programs. */ -EAPI void embryo_program_error_set(Embryo_Program *ep, Embryo_Error error); - + /** - * Retrieves the current error code for the given program. + * @brief Sets the error code for the given program to the given code. * @param ep The given program. - * @return The current error code. + * @param error The given error code. * @ingroup Embryo_Error_Group */ -EAPI Embryo_Error embryo_program_error_get(Embryo_Program *ep); +EAPI void embryo_program_error_set(Embryo_Program *ep, Embryo_Error error); /** - * Sets the data associated to the given program. - * @param ep The given program. - * @param data New bytecode data. - * @ingroup Embryo_Program_Data_Group + * @brief Retrieves the current error code for the given program. + * + * @param[in] ep The given program. + * @return The current error code. + * @ingroup Embryo_Error_Group */ +EAPI Embryo_Error embryo_program_error_get(Embryo_Program *ep); /** + * @internal * @defgroup Embryo_Program_Data_Group Program Data Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * Functions that set and retrieve data associated with the given * program. */ + +/** + * @brief Sets the data associated to the given program. + * @param ep The given program. + * @param data New bytecode data. + * @ingroup Embryo_Program_Data_Group + */ EAPI void embryo_program_data_set(Embryo_Program *ep, void *data); /** - * Retrieves the data associated to the given program. + * @brief Retrieves the data associated to the given program. * @param ep The given program. * @ingroup Embryo_Program_Data_Group */ EAPI void *embryo_program_data_get(Embryo_Program *ep); /** - * Retrieves a string describing the given error code. - * @param error The given error code. + * @brief Retrieves a string describing the given error code. + * + * @param[in] error The given error code. * @return String describing the given error code. If the given code is not * known, the string "(unknown)" is returned. * @ingroup Embryo_Error_Group */ EAPI const char *embryo_error_string_get(Embryo_Error error); - -/** - * Retrieves the length of the string starting at the given cell. - * @param ep The program the cell is part of. - * @param str_cell Pointer to the first cell of the string. - * @return The length of the string. @c 0 is returned if there is an error. - * @ingroup Embryo_Data_String_Group - */ /** + * @internal * @defgroup Embryo_Data_String_Group Embryo Data String Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * Functions that operate on strings in the memory of a virtual machine. */ -EAPI int embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell); - + /** - * Copies the string starting at the given cell to the given buffer. + * @brief Retrieves the length of the string starting at the given cell. * @param ep The program the cell is part of. * @param str_cell Pointer to the first cell of the string. - * @param dst The given buffer. + * @return The length of the string. @c 0 is returned if there is an error. + * @ingroup Embryo_Data_String_Group + */ +EAPI int embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell); + +/** + * @brief Copies the string starting at the given cell to the given buffer. + * + * @param[in] ep The program the cell is part of. + * @param[in] str_cell Pointer to the first cell of the string. + * @param[out] dst The given buffer. * @ingroup Embryo_Data_String_Group */ EAPI void embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst); - + /** - * Copies string in the given buffer into the virtual machine memory + * @brief Copies string in the given buffer into the virtual machine memory * starting at the given cell. - * @param ep The program the cell is part of. - * @param src The given buffer. - * @param str_cell Pointer to the first cell to copy the string to. + * + * @param[in] ep The program the cell is part of. + * @param[in] src The given buffer. + * @param[in] str_cell Pointer to the first cell to copy the string to. * @ingroup Embryo_Data_String_Group */ EAPI void embryo_data_string_set(Embryo_Program *ep, const char *src, Embryo_Cell *str_cell); /** - * Retreives a pointer to the address in the virtual machine given by the + * @brief Retreives a pointer to the address in the virtual machine given by the * given cell. - * @param ep The program whose virtual machine address is being queried. - * @param addr The given cell. + * + * @param[in] ep The program whose virtual machine address is being queried. + * @param[in] addr The given cell. * @return A pointer to the cell at the given address. * @ingroup Embryo_Data_String_Group */ EAPI Embryo_Cell *embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr); -/** - * Increases the size of the heap of the given virtual machine by the given - * number of Embryo_Cells. - * @param ep The program with the given virtual machine. - * @param cells The given number of Embryo_Cells. - * @return The address of the new memory region on success. - * @c EMBRYO_CELL_NONE otherwise. - * @ingroup Embryo_Heap_Group - */ /** + * @internal * @defgroup Embryo_Heap_Group Heap Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * The heap is an area of memory that can be allocated for program * use at runtime. The heap functions here change the amount of heap * memory available. */ + +/** + * @brief Increases the size of the heap of the given virtual machine by the given + * number of Embryo_Cells. + * + * @param[in] ep The program with the given virtual machine. + * @param[in] cells The given number of Embryo_Cells. + * @return The address of the new memory region on success. + * @c EMBRYO_CELL_NONE otherwise. + * @ingroup Embryo_Heap_Group + */ EAPI Embryo_Cell embryo_data_heap_push(Embryo_Program *ep, int cells); - + /** - * Decreases the size of the heap of the given virtual machine down to the + * @brief Decreases the size of the heap of the given virtual machine down to the * given size. - * @param ep The program with the given virtual machine. - * @param down_to The given size. + * + * @param[in] ep The program with the given virtual machine. + * @param[in] down_to The given size. * @ingroup Embryo_Heap_Group */ EAPI void embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to); -/** - * Returns the number of virtual machines are running for the given program. - * @param ep The given program. - * @return The number of virtual machines running. - * @ingroup Embryo_Run_Group - */ /** + * @internal * @defgroup Embryo_Run_Group Program Run Functions - * @ingroup Embryo + * @ingroup Embryo_Library_Group * * Functions that are involved in actually running functions in an * Embryo program. */ + +/** + * @brief Returns the number of virtual machines are running for the given program. + * @param ep The given program. + * @return The number of virtual machines running. + * @ingroup Embryo_Run_Group + */ EAPI int embryo_program_recursion_get(Embryo_Program *ep); /** - * Runs the given function of the given Embryo program in the current + * @brief Runs the given function of the given Embryo program in the current * virtual machine. The parameter @p fn can be found using * @ref embryo_program_function_find. * * @note For Embryo to be able to run a function, it must have been * declared @c public in the Small source code. * - * @param ep The given program. - * @param func The given function. Normally "main", in which case the + * @param[in] ep The given program. + * @param[in] func The given function. Normally "main", in which case the * constant @c EMBRYO_FUNCTION_MAIN can be used. * @return @c EMBRYO_PROGRAM_OK on success. @c EMBRYO_PROGRAM_SLEEP if the * program is halted by the Small @c sleep call. @@ -827,9 +827,10 @@ EAPI int embryo_program_recursion_get(Embryo_Program *ep); EAPI Embryo_Status embryo_program_run(Embryo_Program *ep, Embryo_Function func); /** - * Retreives the return value of the last called function of the given + * @brief Retreives the return value of the last called function of the given * program. - * @param ep The given program. + * + * @param[in] ep The given program. * @return An Embryo_Cell representing the return value of the function * that was last called. * @ingroup Embryo_Run_Group @@ -837,11 +838,11 @@ EAPI Embryo_Status embryo_program_run(Embryo_Program *ep, Embryo_Function fun EAPI Embryo_Cell embryo_program_return_value_get(Embryo_Program *ep); /** - * Sets the maximum number of abstract machine cycles any given program run + * @brief Sets the maximum number of abstract machine cycles any given program run * can execute before being put to sleep and returning. * - * @param ep The given program. - * @param max The number of machine cycles as a limit. + * @param[in] ep The given program. + * @param[in] max The number of machine cycles as a limit. * * This sets the maximum number of abstract machine (virtual machine) * instructions that a single run of an embryo function (even if its main) @@ -887,9 +888,10 @@ EAPI Embryo_Cell embryo_program_return_value_get(Embryo_Program *ep); EAPI void embryo_program_max_cycle_run_set(Embryo_Program *ep, int max); /** - * Retreives the maximum number of abstract machine cycles a program is allowed + * @brief Retreives the maximum number of abstract machine cycles a program is allowed * to run. - * @param ep The given program. + * + * @param[in] ep The given program. * @return The number of cycles a run cycle is allowed to run for this * program. * @@ -900,44 +902,52 @@ EAPI void embryo_program_max_cycle_run_set(Embryo_Program *ep, int m */ EAPI int embryo_program_max_cycle_run_get(Embryo_Program *ep); + +/** + * @internal + * @defgroup Embryo_Parameter_Group Function Parameter Functions + * @ingroup Embryo_Library_Group + * + * Functions that set parameters for the next function that is called. + */ + /** - * Pushes an Embryo_Cell onto the function stack to use as a parameter for + * @brief Pushes an Embryo_Cell onto the function stack to use as a parameter for * the next function that is called in the given program. * @param ep The given program. * @param cell The Embryo_Cell to push onto the stack. * @return @c 1 if successful. @c 0 otherwise. * @ingroup Embryo_Parameter_Group */ - -/** - * @defgroup Embryo_Parameter_Group Function Parameter Functions - * @ingroup Embryo - * - * Functions that set parameters for the next function that is called. - */ EAPI int embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell); /** - * Pushes a string onto the function stack to use as a parameter for the + * @brief Pushes a string onto the function stack to use as a parameter for the * next function that is called in the given program. - * @param ep The given program. - * @param str The string to push onto the stack. + * + * @param[in] ep The given program. + * @param[in] str The string to push onto the stack. * @return @c 1 if successful. @c 0 otherwise. * @ingroup Embryo_Parameter_Group */ EAPI int embryo_parameter_string_push(Embryo_Program *ep, const char *str); /** - * Pushes an array of Embryo_Cells onto the function stack to be used as + * @brief Pushes an array of Embryo_Cells onto the function stack to be used as * parameters for the next function that is called in the given program. - * @param ep The given program. - * @param cells The array of Embryo_Cells. - * @param num The number of cells in @p cells. + * + * @param[in] ep The given program. + * @param[in] cells The array of Embryo_Cells. + * @param[in] num The number of cells in @p cells. * @return @c 1 if successful. @c 0 otherwise. * @ingroup Embryo_Parameter_Group */ EAPI int embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num); +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 5d1fb0c31c..d506be2996 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -2,7 +2,6 @@ #define __ETHUMB_H__ 1 #include <Eina.h> -#include <Efl_Config.h> #ifdef EAPI # undef EAPI @@ -34,94 +33,31 @@ extern "C" { #endif -#define ETHUMB_VERSION_MAJOR EFL_VERSION_MAJOR -#define ETHUMB_VERSION_MINOR EFL_VERSION_MINOR - /** - * @typedef Ethumb_Version - * Represents the current version of Ethumb - */ +#define ETHUMB_VERSION_MAJOR 1 +#define ETHUMB_VERSION_MINOR 8 + typedef struct _Ethumb_Version { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Ethumb is built from) */ + int major; + int minor; + int micro; + int revision; } Ethumb_Version; - + EAPI extern Ethumb_Version *ethumb_version; - -/** - * @page ethumb_main Ethumb - * - * @date 2009 (created) - * - * @section toc Table of Contents - * - * @li @ref ethumb_main_intro - * @li @ref ethumb_main_compiling - * @li @ref ethumb_main_next_steps - * - * @section ethumb_main_intro Introduction - * - * Ethumb will use @ref Evas to generate thumbnail images of given - * files. The API allows great customization of the generated files - * and also helps compling to FreeDesktop.Org Thumbnail Specification - * (http://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html) - * - * However, thumbnailing can be an expensive process that will impact - * your application experience, blocking animations and user - * interaction during the generation. Another problem is that one - * should try to cache the thumbnails in a place that other - * applications can benefit from the file. - * - * @ref Ethumb_Client exists to solve this. It will communicate with a - * server using standard D-Bus protocol. The server will use @ref - * Ethumb itself to generate the thumbnail images and cache them using - * FreeDesktop.Org standard. It is recommended that most applications - * use @ref Ethumb_Client instead of @ref Ethumb directly. - * - * @section ethumb_main_compiling How to compile - * - * Ethumb is a library your application links to. The procedure for - * this is very simple. Note that usually you want the D-Bus client - * library. You simply have to compile your application with the - * appropriate compiler flags that the @c pkg-config script - * outputs. For example: - * - * Compiling C or C++ files into object files: - * - * @verbatim - gcc -c -o main.o main.c `pkg-config --cflags ethumb_client` - @endverbatim - * - * Linking object files into a binary executable: - * - * @verbatim - gcc -o my_application main.o `pkg-config --libs ethumb_client` - @endverbatim - * - * See @ref pkgconfig - * - * @section ethumb_main_next_steps Next Steps - * - * After you understood what Ethumb is and installed it in your system - * you should proceed understanding the programming interface. - * - * Recommended reading: - * - * @li @ref Ethumb_Client to generate thumbnails using a server - * (recommended). - * @li @ref Ethumb to generate thumbnails in the local process. - * - */ - + /** - * @defgroup Ethumb Ethumb + * @internal + * @defgroup Ethumb_Group Ethumb + * @ingroup EFL_Group * * @{ */ + /** - * @defgroup Ethumb_Basics Ethumb Basics + * @internal + * @defgroup Ethumb_Basics_Group Ethumb Basics + * @ingroup Ethumb_Group * * Functions that all users must know of to use Ethumb. * @@ -144,34 +80,34 @@ typedef struct _Ethumb Ethumb; */ typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success); -/** - * @brief Initialize ethumb. - * @return 1 or greater on success, 0 otherwise. - */ EAPI int ethumb_init(void); -/** - * @brief Shutdown ethumb, unloading all currently-loaded modules. - * @return 0 if ethumb shuts down, an integer greater than 0 otherwise. - */ EAPI int ethumb_shutdown(void); -/** - * @brief Create a new ethumb object. - * return The newly-created ethumb object - */ EAPI Ethumb * ethumb_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; - -/** - * @brief Free an ethumb object. - */ EAPI void ethumb_free(Ethumb *e); +EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2); +EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1); +EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); + +EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1); +EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; +EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; +EAPI int ethumb_key_cmp(const void *key1, int key1_length, + const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE; +EAPI unsigned int ethumb_length(const void *key) EINA_PURE EINA_WARN_UNUSED_RESULT; + /** * @} */ /** - * @defgroup Ethumb_Setup Ethumb Fine Tune Setup + * @internal + * @defgroup Ethumb_Setup_Group Ethumb Fine Tune Setup + * @ingroup Ethumb_Group * * How to fine tune thumbnail generation, setting size, aspect, * frames, quality and so on. @@ -179,64 +115,13 @@ EAPI void ethumb_free(Ethumb *e); * @{ */ -/** - * - * @brief Set the Ethumb Frame - * - * This can be used to simulate wood frames in the Thumbnails - * - * @param e handle of the current thumbnailer. - * @param theme_file the edje theme file - * @param group the edje group in theme - * @param swallow the edje swallow in theme - * - * @return EINA_TRUE on success and EINA_FALSE on failure - */ EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1); - -/** - * @brief Retreives the current ethumb frame of and Ethumb instance. - * - * @param e handle of the current thumbnailer. - * @param theme_file will be setted with the edje theme - * @param group will be setted with the edje group - * @param swallow will be setted with the edje swallow - */ EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1); -/** - * @brief Set the ethumb thumbnails path - * - * @param e handle of the current thumbnailer. - * @param path The thumbnails path - * - */ EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1); - -/** - * @brief Get the ethumb thumbnails path - * - * @param e handle of the current thumbnailer. - * - * @return The thumbnails path for the current thumbnailer - */ EAPI const char *ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -/** - * @brief Set the thumbnails category - * - * @param e handle of the current thumbnailer. - * @param category the category to set - */ EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1); - -/** - * @brief Get the thumbnails category - * - * @param e handle of the current thumbnailer - * - * @return the current thumbnailer thumbnails category - */ EAPI const char *ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1); @@ -244,12 +129,18 @@ EAPI void ethumb_thumb_path_get(Ethumb *e, const char **path, const char EAPI void ethumb_thumb_hash(Ethumb *e) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_hash_copy(Ethumb *dst, const Ethumb *src) EINA_ARG_NONNULL(1, 2); +/** + * @brief Enumeration of Ethumb thumb FDO size + */ typedef enum _Ethumb_Thumb_FDO_Size { ETHUMB_THUMB_NORMAL, /**< 128x128 as defined by FreeDesktop.Org standard */ ETHUMB_THUMB_LARGE /**< 256x256 as defined by FreeDesktop.Org standard */ } Ethumb_Thumb_FDO_Size; +/** + * @brief Enumeration of Ethumb thumb format type + */ typedef enum _Ethumb_Thumb_Format { ETHUMB_THUMB_FDO, /**< PNG as defined by FreeDesktop.Org standard */ @@ -257,6 +148,9 @@ typedef enum _Ethumb_Thumb_Format ETHUMB_THUMB_EET /**< EFL's own storage system, supports key parameter */ } Ethumb_Thumb_Format; +/** + * @brief Enumeration of Ethumb thumb aspect type + */ typedef enum _Ethumb_Thumb_Aspect { ETHUMB_THUMB_KEEP_ASPECT, /**< keep original proportion between width and height */ @@ -264,6 +158,9 @@ typedef enum _Ethumb_Thumb_Aspect ETHUMB_THUMB_CROP /**< keep aspect but crop (cut) the largest dimension */ } Ethumb_Thumb_Aspect; +/** + * @brief Enumeration of Ethumb orientation type + */ typedef enum _Ethumb_Thumb_Orientation { ETHUMB_THUMB_ORIENT_NONE, /**< keep orientation as pixel data is */ @@ -279,300 +176,46 @@ typedef enum _Ethumb_Thumb_Orientation EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1); -/** - * @brief Set the size of thumbnails. - * - * @param e A pointer to an Ethumb object. - * @param tw Thumbnail width. - * @param th Thumbnail height. - */ EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1); -/** - * @brief Get the size of thumbnails. - * - * @param e A pointer to an Ethumb object. - * @param[out] tw Pointer to an int to store the thumbnail width. - * @param[out] th Pointer to an int to store the thumbnail height. - */ EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1); -/** - * @brief Set the fileformat of the thumbnails - * - * Thumbnails are sent compressed; possible formats are PNG, JPEG and EET. - * - * @param e A pointer to an Ethumb object. - */ EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1); -/** - * @brief Get the fileformat of the thumbnails - * - * @param e A pointer to an Ethumb object. - * @return The thumbnail fileformat - * - * @see ethumb_thumb_format_set - */ EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -/** - * @brief Set the aspect ratio policy. - * - * When the source and thumbnail aspect ratios don't match, this policy sets - * how to adapt from the former to the latter: resize keeping source aspect - * ratio, resize ignoring it or crop. - * - * @param e A pointer to an Ethumb object. - * @param aspect The new aspect ratio policy. - */ -EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect aspect) EINA_ARG_NONNULL(1); -/** - * @brief Get the aspect ratio policy. - * - * @param e A pointer to an Ethumb object. - * @return The aspect ratio policy. - */ +EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect a) EINA_ARG_NONNULL(1); EAPI Ethumb_Thumb_Aspect ethumb_thumb_aspect_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -/** - * @brief Set the thumbnail rotation or flip. - * - * @param e A pointer to an Ethumb object. - * @param orientation The new orientation. - */ -EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation orientation) EINA_ARG_NONNULL(1); -/** - * @brief Get the thumbnail rotation. - * - * @param e A pointer to an Ethumb object. - * @return The current rotation. - */ +EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation o) EINA_ARG_NONNULL(1); EAPI Ethumb_Thumb_Orientation ethumb_thumb_orientation_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_crop_align_set(Ethumb *e, float x, float y) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_crop_align_get(const Ethumb *e, float *x, float *y) EINA_ARG_NONNULL(1); -/** - * @brief Set the thumbnail compression quality. - * - * @param e A pointer to an Ethumb object. - * @param quality Compression quality (from 0 to 100, 100 being the best; default is 80) - */ EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1); -/** - * @brief Get the thumbnail compression quality. - * - * @param e A pointer to an Ethumb object. - * @return The current compression quality (from 0 to 100, 100 being the best) - */ EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; -/** - * @brief Set the compression rate - * - * @param e handle of the current thumbnailer. - * @param compress the compression rate (in percentage) - * - */ EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1); - -/** - * @brief Get the compression rate - * - * @param e handle of the current thumbnailer. - * - * @return the compression rate (in percentage) - */ EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; -/** - * @brief set the video play start point - * - * Set the start point of video thumbnail - * - * @param e handle of the current thumbnailer. - * @param start the start point (float from 0.0 to 1.0) - */ EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1); - -/** - * @brief get the video play start point - * - * Get the start point of video thumbnail - * - * @param e handle of the current thumbnailer. - * - * @return the start point (float from 0.0 to 1.0) - */ EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - -/** - * @brief Set the video time (duration) in seconds. - * - * @param e handle of the current thumbnailer. - * @param time the video duration in seconds - */ EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1); - -/** - * @brief Get the video time (duration) in seconds. - * - * @param e handle of the current thumbnailer. - * @return the video duration in seconds - */ EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - -/** - * @brief Set the video frame interval, in seconds - * - * This is useful for animated thumbnail and will define skip time - * before going to the next frame. Note that video backends might not - * be able to precisely skip that amount as it will depend on various - * factors, including video encoding. - * - * @param e handle of the current thumbnailer. - * @param interval the frame display interval in seconds - */ EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1); - -/** - * @brief Get the video frame interval, in seconds - * - * @param e handle of the current thumbnailer. - * @return the frame display interval in seconds - */ EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - -/** - * @brief Set the number of times the video loops (if applicable). - * - * @param e A pointer to an Ethumb object. - * @param ntimes The number of times the video loops. - */ EAPI void ethumb_video_ntimes_set(Ethumb *e, unsigned int ntimes) EINA_ARG_NONNULL(1); -/** - * @brief Get the number of times the video loops (if applicable). - * - * @param e A pointer to an Ethumb object. - * @return The number of times the video loops. - */ EAPI unsigned int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - -/** - * @brief Set the thumbnail framerate. - * - * @param e A pointer to an Ethumb object. - * @param fps New framerate of the thumbnail (default 10). - */ EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NONNULL(1); -/** - * @brief Get the thumbnail framerate. - * - * @param e A pointer to an Ethumb object. - * @return Current framerate of the thumbnail. - */ EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -/** - * @brief Set the page number to thumbnail in paged documents - * - * @param e handle of the current thumbnailer. - * @param page the page number. - */ -EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1); -/** - * @brief Get the page number thumbnailed in paged documents - * - * @param e handle of the current thumbnailer. - * @return the page number. - */ +EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1); EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @} */ /** - * @addtogroup Ethumb_Basics Ethumb Basics - * @{ - */ - -/** - * @brief Set the file for which to generate thumbnails. - * - * @param e A pointer to an Ethumb object. - * @param path The file to use. - * @param key If @a path allows storing multiple resources in a single file - * (EET or Edje for instance), @a key is the key used to locate the - * right resource inside the file. NULL if not applicable. - */ -EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2); -/** - * @brief Get the file for which to generate thumbnails. - * - * @param e A pointer to an Ethumb object. - * @param[out] path The file being used. - * @param[out] key The key used to locate the right resource in case the file - * can store several of them. NULL if not applicable. - * @see ethumb_file_set - */ -EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1); - -/** - * @brief Reset the source file information. - * - * @param e A pointer to an Ethumb object. - */ -EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); - -/** - * @brief Generate the thumbnail. - * - * @param e handle of the current thumbnailer. - * @param finished_cb The callback function to run on opertaion end - * @param free_data The callback function to run on free data. - * - * @return EINA_TRUE on success and EINA_FALSE on failure - */ -EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); - -/** - * @brief test if the thumbnailer exists - * - * @param e handle of the thumbnailer to test. - * - * @return EINA_TRUE if thumbnailer exists and EINA_FALSE otherwise. - */ -EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - -/** - * @brief Duplicate an thumbnailer - * - * @param e Handle of the thumbnailer to duplicate - * - * @return a new allocated copy of the thumbnailer. - */ -EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1); - -/** - * @brief Compare two thumbnailers. - * - * @param e1 First handle of thumbnailer to compare - * @param e2 Second handle of thumbnailer to compare - * - * @return EINA_TRUE if the thumbnailers are equal and EINA_FALSE otherwise - */ -EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; - -EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; -EAPI int ethumb_key_cmp(const void *key1, int key1_length, - const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE; -EAPI unsigned int ethumb_length(const void *key) EINA_PURE EINA_WARN_UNUSED_RESULT; - - /** - * @} - */ - -/** * @} */ diff --git a/src/lib/ethumb/Ethumb_Plugin.h b/src/lib/ethumb/Ethumb_Plugin.h index 483399d212..3eb6f020cd 100644 --- a/src/lib/ethumb/Ethumb_Plugin.h +++ b/src/lib/ethumb/Ethumb_Plugin.h @@ -9,17 +9,11 @@ typedef struct _Ethumb_Plugin Ethumb_Plugin; struct _Ethumb_Plugin { -#define ETHUMB_PLUGIN_API_VERSION (1U) - unsigned int version; - const char *name; const char **extensions; void *(*thumb_generate)(Ethumb *); void (*thumb_cancel)(Ethumb *, void *); }; -EAPI Eina_Bool ethumb_plugin_register(const Ethumb_Plugin *plugin); -EAPI Eina_Bool ethumb_plugin_unregister(const Ethumb_Plugin *plugin); - EAPI void ethumb_calculate_aspect_from_ratio(Ethumb *e, float ia, int *w, int *h); EAPI void ethumb_calculate_aspect(Ethumb *e, int iw, int ih, int *w, int *h); EAPI void ethumb_calculate_fill_from_ratio(Ethumb *e, float ia, int *fx, int *fy, int *fw, int *fh); diff --git a/src/lib/ethumb_client/Ethumb_Client.h b/src/lib/ethumb_client/Ethumb_Client.h index 3c3f95d87e..3736797576 100644 --- a/src/lib/ethumb_client/Ethumb_Client.h +++ b/src/lib/ethumb_client/Ethumb_Client.h @@ -34,14 +34,17 @@ extern "C" { #endif /** - * @defgroup Ethumb_Client Ethumb Client - * @ingroup Ethumb + * @internal + * @defgroup Ethumb_Client_Group Ethumb Client + * @ingroup Ethumb_Group * * @{ */ /** - * @defgroup Ethumb_Client_Basics Ethumb Client Basics + * @internal + * @defgroup Ethumb_Client_Basics_Group Ethumb Client Basics + * @ingroup Ethumb_Client_Group * * Functions that all users must know of to use Ethumb_Client. * @@ -128,16 +131,39 @@ typedef void (*Ethumb_Client_Generate_Cancel_Cb)(void *data, Eina_Bool success); EAPI int ethumb_client_init(void); EAPI int ethumb_client_shutdown(void); -EAPI Ethumb_Client *ethumb_client_connect(Ethumb_Client_Connect_Cb connect_cb, const void *data, Eina_Free_Cb free_data); +EAPI Ethumb_Client * ethumb_client_connect(Ethumb_Client_Connect_Cb connect_cb, const void *data, Eina_Free_Cb free_data); EAPI void ethumb_client_disconnect(Ethumb_Client *client); EAPI void ethumb_client_on_server_die_callback_set(Ethumb_Client *client, Ethumb_Client_Die_Cb server_die_cb, const void *data, Eina_Free_Cb free_data); +EAPI Eina_Bool ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key); +EAPI void ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **key); +EAPI void ethumb_client_file_free(Ethumb_Client *client); + +EAPI Ethumb_Exists *ethumb_client_thumb_exists(Ethumb_Client *client, Ethumb_Client_Thumb_Exists_Cb exists_cb, const void *data); +EAPI void ethumb_client_thumb_exists_cancel(Ethumb_Exists *exists); +EAPI Eina_Bool ethumb_client_thumb_exists_check(Ethumb_Exists *exists); +EAPI int ethumb_client_generate(Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data); +EAPI void ethumb_client_generate_cancel(Ethumb_Client *client, int id, Ethumb_Client_Generate_Cancel_Cb cancel_cb, const void *data, Eina_Free_Cb free_data); +EAPI void ethumb_client_generate_cancel_all(Ethumb_Client *client); + +typedef void (*Ethumb_Client_Async_Done_Cb)(Ethumb_Client *ethumbd, const char *thumb_path, const char *thumb_key, void *data); +typedef void (*Ethumb_Client_Async_Error_Cb)(Ethumb_Client *ethumbd, void *data); + +typedef struct _Ethumb_Client_Async Ethumb_Client_Async; + +EAPI Ethumb_Client_Async *ethumb_client_thumb_async_get(Ethumb_Client *client, + Ethumb_Client_Async_Done_Cb done, + Ethumb_Client_Async_Error_Cb error, + const void *data); +EAPI void ethumb_client_thumb_async_cancel(Ethumb_Client *client, Ethumb_Client_Async *request); /** * @} */ /** - * @defgroup Ethumb_Client_Setup Ethumb Client Fine Tune Setup + * @internal + * @defgroup Ethumb_Client_Setup_Group Ethumb Client Fine Tune Setup + * @ingroup Ethumb_Client_Group * * How to fine tune thumbnail generation, setting size, aspect, orientation, * frames, quality and so on. @@ -181,35 +207,6 @@ EAPI void ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, */ /** - * @addtogroup Ethumb_Client_Basics Ethumb Client Basics - * @{ - */ -EAPI Eina_Bool ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key); -EAPI void ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **key); -EAPI void ethumb_client_file_free(Ethumb_Client *client); - -EAPI Ethumb_Exists *ethumb_client_thumb_exists(Ethumb_Client *client, Ethumb_Client_Thumb_Exists_Cb exists_cb, const void *data); -EAPI void ethumb_client_thumb_exists_cancel(Ethumb_Exists *exists); -EAPI Eina_Bool ethumb_client_thumb_exists_check(Ethumb_Exists *exists); -EAPI int ethumb_client_generate(Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data); -EAPI void ethumb_client_generate_cancel(Ethumb_Client *client, int id, Ethumb_Client_Generate_Cancel_Cb cancel_cb, const void *data, Eina_Free_Cb free_data); -EAPI void ethumb_client_generate_cancel_all(Ethumb_Client *client); - -typedef void (*Ethumb_Client_Async_Done_Cb)(Ethumb_Client *ethumbd, const char *thumb_path, const char *thumb_key, void *data); -typedef void (*Ethumb_Client_Async_Error_Cb)(Ethumb_Client *ethumbd, void *data); - -typedef struct _Ethumb_Client_Async Ethumb_Client_Async; - -EAPI Ethumb_Client_Async *ethumb_client_thumb_async_get(Ethumb_Client *client, - Ethumb_Client_Async_Done_Cb done, - Ethumb_Client_Async_Error_Cb error, - const void *data); -EAPI void ethumb_client_thumb_async_cancel(Ethumb_Client *client, Ethumb_Client_Async *request); - /** - * @} - */ - -/** * @} */ diff --git a/src/lib/evas/Evas.h b/src/lib/evas/Evas.h index 71d91eab8b..8a4f23630a 100644..100755 --- a/src/lib/evas/Evas.h +++ b/src/lib/evas/Evas.h @@ -1,260 +1,233 @@ /** - @page evas_main Evas - - @date 2000 (created) - - @section toc Table of Contents - - @li @ref evas_main_intro - @li @ref evas_main_work - @li @ref evas_main_compiling - @li @ref evas_main_next_steps - @li @ref evas_main_intro_example - - - @section evas_main_intro Introduction - - Evas is a clean display canvas API for several target display systems - that can draw anti-aliased text, smooth super and sub-sampled scaled - images, alpha-blend objects and much more. - - It abstracts any need to know much about what the characteristics of - your display system are or what graphics calls are used to draw them - and how. It deals on an object level where all you do is create and - manipulate objects in a canvas, set their properties, and the rest is - done for you. - - Evas optimises the rendering pipeline to minimise effort in redrawing - changes made to the canvas and so takes this work out of the - programmers hand, saving a lot of time and energy. - - It is small and lean, and is designed to work on embedded systems all the way - to large and powerful multi-CPU workstations. It can be compiled to - only have the features you need for your target platform if you so - wish, thus keeping it small and lean. It has several display - back-ends, letting it display on several display systems, making it - portable for cross-device and cross-platform development. - - @subsection evas_main_intro_not_evas What Evas is not? - - Evas is not a widget set or widget toolkit, however it is their - base. See Elementary (http://docs.enlightenment.org/auto/elementary/) - for a toolkit based on @ref Evas, @ref Edje, @ref Ecore and other - Enlightenment technologies. - - It is not dependent or aware of main loops, input or output - systems. Input should be polled from various sources and fed to - Evas. Similarly, it does not create windows or report windows updates - to your system, but just draws the pixels and report to the - user the areas that were changed. Of course these operations are quite - common and thus they are ready to use in @ref Ecore, particularly in - @ref Ecore_Evas_Group. - - - @section evas_main_work How does Evas work? - - Evas is a canvas display library. This is markedly different from most - display and windowing systems as a canvas is structural and is also a - state engine, whereas most display and windowing systems are immediate - mode display targets. Evas handles the logic between a structural - display via its state engine, and controls the target windowing system - in order to produce rendered results of the current canvas' state on - the display. - - Immediate mode display systems retain very little, or no state. A - program executes a series of commands, as in the pseudo code: - - @verbatim - draw line from position (0, 0) to position (100, 200); - - draw rectangle from position (10, 30) to position (50, 500); - - bitmap_handle = create_bitmap(); - scale bitmap_handle to size 100 x 100; - draw image bitmap_handle at position (10, 30); - @endverbatim - - The series of commands is executed by the windowing system and the - results are displayed on the screen (normally). Once the commands are - executed the display system has little or no idea of how to reproduce - this image again, and so has to be instructed by the application on how - to redraw sections of the screen whenever needed. Each successive - command is executed as instructed by the application and either - emulated by software or sent to the graphics hardware on the device to - be performed. - - The advantage of such a system is that it is simple, and gives a - program tight control over how something looks and is drawn. Given the - increasing complexity of displays and demands by users to have better - looking interfaces, more and more work is needing to be done at this - level by the internals of widget sets, custom display widgets and - other programs. This means that more and more logic and display rendering - code needs to be written each time the application needs to figure out - how to minimise redraws so that display is fast and interactive, and - keeps track of redraw logic. The power comes at a high-price with lots - of extra code and work. Programmers not very familiar with graphics - programming often make mistakes at this level and produce code that - is sub optimal. Those familiar with this kind of programming simply - get bored by writing the same code again and again. - - For example, if in the above scene, the windowing system requires the - application to redraw the area from 0, 0 to 50, 50 (also referred as - "expose event"), then the programmer must calculate manually the - updates and repaint it again: - - @verbatim - Redraw from position (0, 0) to position (50, 50): - - // what is in area (0, 0, 50, 50)? - - // 1. intersection part of line (0, 0) to (100, 200)? - draw line from position (0, 0) to position (25, 50); - - // 2. intersection part of rectangle (10, 30) to (50, 500)? - draw rectangle from position (10, 30) to position (50, 50) - - // 3. intersection part of image at (10, 30), size 100 x 100? - bitmap_subimage = subregion from position (0, 0) to position (40, 20) - draw image bitmap_subimage at position (10, 30); - @endverbatim - - You might have noticed that, if all elements in the - above scene are opaque, then the system is doing useless paints: part - of the line is behind the rectangle, and part of the rectangle is - behind the image. These useless paints tend to be very costly, as - pixels tend to be 4 bytes in size; thus an overlapping region of 100 x - 100 pixels is around 40000 useless writes! You could write - code to calculate the overlapping areas and avoid painting then, but - then it should be mixed with the "expose event" handling mentioned - above and you quickly realize that the initially simpler method became - really complex. - - Evas is a structural system in which the programmer creates and - manages display objects and their properties, and as a result of this - higher level state management, the canvas is able to redraw the set of - objects when needed to represent the current state of the canvas. - - For example, the pseudo code: - - @verbatim - line_handle = create_line(); - set line_handle from position (0, 0) to position (100, 200); - show line_handle; - - rectangle_handle = create_rectangle(); - move rectangle_handle to position (10, 30); - resize rectangle_handle to size 40 x 470; - show rectangle_handle; - - bitmap_handle = create_bitmap(); - scale bitmap_handle to size 100 x 100; - move bitmap_handle to position (10, 30); - show bitmap_handle; - - render scene; - @endverbatim - - This may look longer, but when the display needs to be refreshed or - updated, you move, resize, show, or hide the objects that need to change. - You can simply think at the object logic level, and the canvas software - does the rest of the work for you, figuring out what actually changed in the - canvas since it had been last drawn, how to most efficiently redraw the canvas and - its contents to reflect the current state, and then it can go off and do - the actual drawing of the canvas. - - This lets you think in a more natural way when dealing with - a display, and saves time and effort of working out how to load and - display images, render given the current display system, and so on. Since - Evas also is portable across different display systems, this also - gives you the ability to have their code ported and - displayed on different display systems with very little work. - - Evas can be seen as a display system that stands somewhere between a - widget set and an immediate mode display system. It retains basic - display logic, but does very little high-level logic such as - scrollbars, sliders, and push buttons. - - - @section evas_main_compiling How to compile - - Evas is a library your application links to. The procedure for this is - very simple. You simply have to compile your application with the - appropriate compiler flags that the @c pkg-config script outputs. For - example: - - Compiling C or C++ files into object files: - - @verbatim - gcc -c -o main.o main.c `pkg-config --cflags evas` - @endverbatim - - Linking object files into a binary executable: - - @verbatim - gcc -o my_application main.o `pkg-config --libs evas` - @endverbatim - - See @ref pkgconfig - - @section evas_main_next_steps Next Steps - - After you understood what Evas is and installed it in your system - you should proceed understanding the programming interface for all - objects, then see the specific for the most used elements. We'd - recommend you to take a while to learn @ref Ecore, @ref Edje and - Elementary (http://docs.enlightenment.org/auto/elementary/) as they - will likely save you tons of work compared to using just Evas - directly. - - Recommended reading: - - @li @ref Evas_Object_Group, where you'll get how to basically - manipulate generic objects lying on an Evas canvas, handle canvas - and object events, etc. - @li @ref Evas_Object_Rectangle, to learn about the most basic object - type on Evas -- the rectangle. - @li @ref Evas_Object_Polygon, to learn how to create polygon elements - on the canvas. - @li @ref Evas_Line_Group, to learn how to create line elements on the - canvas. - @li @ref Evas_Object_Image, to learn about image objects, over which - Evas can do a plethora of operations. - @li @ref Evas_Object_Text, to learn how to create textual elements on - the canvas. - @li @ref Evas_Object_Textblock, to learn how to create multiline - textual elements on the canvas. - @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define - new objects that provide @b custom functions to handle clipping, - hiding, moving, resizing, color setting and more. These could - be as simple as a group of objects that move together (see @ref - Evas_Smart_Object_Clipped) up to implementations of what - ends to be a widget, providing some intelligence (thus the name) - to Evas objects -- like a button or check box, for example. - - @section evas_main_intro_example Introductory Example - - @include evas-buffer-simple.c - - More examples can be found at @ref evas_examples. + * @defgroup Evas Evas + * @ingroup EFL_Group + * + * @brief Evas provide a clean display canvas API. + * + * See @ref evas_main for more details + * + * @{ + */ +/** + * @page evas_main Evas + * + * @date 2000 (created) + * + * @section toc Table of Contents + * + * @li @ref evas_main_intro + * @li @ref evas_main_work + * @li @ref evas_main_next_steps + * + * + * @section evas_main_intro Introduction + * + * Evas is a clean display canvas API for several target display systems + * that can draw anti-aliased text, smooth super and sub-sampled scaled + * images, alpha-blend objects, and much more. + * + * It abstracts any need to know much about what the characteristics of + * your display system are or what graphics calls are used to draw them + * and how. It deals on an object level where all you do is create and + * manipulate objects in a canvas, set their properties, and the rest is + * done for you. + * + * Evas optimises the rendering pipeline to minimise effort in redrawing + * changes made to the canvas and so takes this work out of the + * programmers hand, saving a lot of time and energy. + * + * It is small and lean, and is designed to work on embedded systems all the way + * to large and powerful multi-CPU workstations. It can be compiled to + * only have the features you need for your target platform if you so + * wish, thus keeping it small and lean. It has several display + * back-ends, letting it display on several display systems, making it + * portable for cross-device and cross-platform development. + * + * @subsection evas_main_intro_not_evas What Evas is not? + * + * Evas is not a widget set or widget toolkit, however it is their + * base. See @ref Elementary for a toolkit based on @ref Evas, @ref Edje_Group, + * @ref Ecore_Group and other Enlightenment technologies. + * + * It is not dependent or aware of main loops, input or output + * systems. Input should be polled from various sources and fed to + * Evas. Similarly, it does not create windows or report windows updates + * to your system, but just draws the pixels and report to the + * user the areas that were changed. + * @internal + * Of course, these operations are quite + * common and thus they are ready to use in Ecore, particularly in @ref + * Ecore_Evas_Group. + * @endinternal + * + * + * @section evas_main_work How does Evas work? + * + * Evas is a canvas display library. This is markedly different from most + * display and windowing systems as a canvas is structural and is also a + * state engine, whereas most display and windowing systems are immediate + * mode display targets. Evas handles the logic between a structural + * display via its state engine, and controls the target windowing system + * in order to produce rendered results of the current canvas' state on + * the display. + * + * Immediate mode display systems retain very little, or no state. A + * program executes a series of commands, as in the pseudo code: + * + * @verbatim + * draw line from position (0, 0) to position (100, 200); + * + * draw rectangle from position (10, 30) to position (50, 500); + * + * bitmap_handle = create_bitmap(); + * scale bitmap_handle to size 100 x 100; + * draw image bitmap_handle at position (10, 30); + * @endverbatim + * + * The series of commands is executed by the windowing system and the + * results are displayed on the screen (normally). Once the commands are + * executed the display system has little or no idea of how to reproduce + * this image again, and so has to be instructed by the application on how + * to redraw sections of the screen whenever needed. Each successive + * command is executed as instructed by the application and either + * emulated by software or sent to the graphics hardware on the device to + * be performed. + * + * The advantage of such a system is that it is simple, and gives a + * program tight control over how something looks and is drawn. Given the + * increasing complexity of displays and demands by users to have better + * looking interfaces, more and more work is needing to be done at this + * level by the internals of widget sets, custom display widgets and + * other programs. This means that more and more logic and display rendering + * code needs to be written each time the application needs to figure + * out how to minimise redraws so that display is fast and interactive, + * and keeps track of redraw logic. The power comes at a high-price, + * with lots of extra code and work. Programmers not very familiar with + * graphics programming often make mistakes at this level and produce + * code that is sub optimal. Those familiar with this kind of programming + * simply get bored by writing the same code again and again. + * + * For example, if in the above scene, the windowing system requires the + * application to redraw the area from 0, 0 to 50, 50 (also referred as + * "expose event"), then the programmer must calculate manually the + * updates and repaint it again: + * + * @verbatim + * Redraw from position (0, 0) to position (50, 50): + * + * // what is in area (0, 0, 50, 50)? + * + * // 1. intersection part of line (0, 0) to (100, 200)? + * draw line from position (0, 0) to position (25, 50); + * + * // 2. intersection part of rectangle (10, 30) to (50, 500)? + * draw rectangle from position (10, 30) to position (50, 50) + * + * // 3. intersection part of image at (10, 30), size 100 x 100? + * bitmap_subimage = subregion from position (0, 0) to position (40, 20) + * draw image bitmap_subimage at position (10, 30); + * @endverbatim + * + * You might have noticed that, if all elements in the above scene are + * opaque, then the system is doing useless paints: part of the line is + * behind the rectangle, and part of the rectangle is behind the image. + * These useless paints tend to be very costly, as pixels tend to be 4 bytes + * in size; thus an overlapping region of 100 x 100 pixels is around 40000 + * useless writes! You could write code to calculate the overlapping + * areas and avoid painting then, but then it should be mixed with the + * "expose event" handling mentioned above and you quickly realize that + * the initially simpler method became really complex. + * + * Evas is a structural system in which the programmer creates and + * manages display objects and their properties, and as a result of this + * higher level state management, the canvas is able to redraw the set of + * objects when needed to represent the current state of the canvas. + * + * For example, the pseudo code: + * + * @verbatim + * line_handle = create_line(); + * set line_handle from position (0, 0) to position (100, 200); + * show line_handle; + * + * rectangle_handle = create_rectangle(); + * move rectangle_handle to position (10, 30); + * resize rectangle_handle to size 40 x 470; + * show rectangle_handle; + * + * bitmap_handle = create_bitmap(); + * scale bitmap_handle to size 100 x 100; + * move bitmap_handle to position (10, 30); + * show bitmap_handle; + * + * render scene; + * @endverbatim + * + * This may look longer, but when the display needs to be refreshed or + * updated, you move, resize, show, or hide the objects that need to change. + * You can simply think at the object logic level, and the canvas software + * does the rest of the work for you, figuring out what actually changed in the + * canvas since it had been last drawn, how to most efficiently redraw the canvas and + * its contents to reflect the current state, and then it can go off and do + * the actual drawing of the canvas. + * + * This lets you think in a more natural way when dealing with + * a display, and saves time and effort of working out how to load and + * display images, render given the current display system, and so on. Since + * Evas also is portable across different display systems, this also + * gives you the ability to have their code ported and + * displayed on different display systems with very little work. + * + * Evas can be seen as a display system that stands somewhere between a + * widget set and an immediate mode display system. It retains basic + * display logic, but does very little high-level logic such as + * scrollbars, sliders, and push buttons. + * + * @section evas_main_next_steps Next Steps + * + * After you understood what Evas is and installed it in your system you + * should proceed to understand the programming interface for all + * objects, and then see the specifics for the most used elements. + * You should take a while to learn @ref Ecore_Group and @ref Edje_Group as they + * likely save you tons of work compared to using just Evas directly. + * + * Recommended reading: + * + * @li @ref Evas_Object_Group, where you get information on how to basically + * manipulate generic objects lying on an Evas canvas, handle canvas + * and object events, and so on. + * @li @ref Evas_Object_Rectangle, to learn about the most basic object + * type on Evas -- the rectangle. + * @li @ref Evas_Object_Polygon, to learn how to create polygon elements + * on the canvas. + * @li @ref Evas_Line_Group, to learn how to create line elements on the + * canvas. + * @li @ref Evas_Object_Image, to learn about image objects, over which + * Evas can do a plethora of operations. + * @li @ref Evas_Object_Text, to learn how to create textual elements on + * the canvas. + * @li @ref Evas_Object_Textblock, to learn how to create multiline + * textual elements on the canvas. + * @internal + * @li @ref Evas_Smart_Object_Group and @ref Evas_Smart_Group, to define + * new objects that provide @b custom functions to handle clipping, + * hiding, moving, resizing, color setting and more. These could + * be as simple as a group of objects that move together (see @ref + * Evas_Smart_Object_Clipped) up to implementations of what + * ends to be a widget, providing some intelligence (thus the name) + * to Evas objects -- like a button or check box, for example. + * @endinternal + * */ #ifndef _EVAS_H #define _EVAS_H -#include <Efl_Config.h> - #include <time.h> #include <Eina.h> -/* This include has been added to support Eo in Evas */ -#include <Eo.h> -#include <Efl.h> - - -#include <Evas_Loader.h> - #ifdef EAPI # undef EAPI #endif @@ -285,13 +258,14268 @@ extern "C" { #endif -#include <Evas_Common.h> -#ifndef EFL_NOLEGACY_API_SUPPORT -#include <Evas_Legacy.h> -#endif -#ifdef EFL_EO_API_SUPPORT -#include <Evas_Eo.h> -#endif +#define EVAS_VERSION_MAJOR 1 +#define EVAS_VERSION_MINOR 8 + +/** + * @typedef Evas_Version + * @brief The version of Evas. + */ +typedef struct _Evas_Version +{ + int major; /**< Major component of the version */ + int minor; /**< Minor component of the version */ + int micro; /**< Micro component of the version */ + int revision; /**< Revision component of the version */ +} Evas_Version; + +EAPI extern Evas_Version * evas_version; + +/** + * @file + * @brief These routines are used for Evas library interaction. + * + * @todo check boolean return values and convert to Eina_Bool + * @todo change all api to use EINA_SAFETY_* + * @todo finish api documentation + */ + +/* BiDi exposed stuff */ +/*FIXME: document */ +typedef enum _Evas_BiDi_Direction +{ + EVAS_BIDI_DIRECTION_NATURAL, + EVAS_BIDI_DIRECTION_NEUTRAL = EVAS_BIDI_DIRECTION_NATURAL, + EVAS_BIDI_DIRECTION_LTR, + EVAS_BIDI_DIRECTION_RTL +} Evas_BiDi_Direction; + +/** + * @brief Identifier of callbacks to be set for Evas canvases or Evas objects. + * + * The following figure illustrates some Evas callbacks: + * + * @image html evas-callbacks.png + * @image rtf evas-callbacks.png + * @image latex evas-callbacks.eps + * + * @see evas_object_event_callback_add() + * @see evas_event_callback_add() + */ +typedef enum _Evas_Callback_Type +{ + /* + * The following events are only for use with Evas objects, with + * evas_object_event_callback_add(): + */ + EVAS_CALLBACK_MOUSE_IN, /**< Mouse In Event */ + EVAS_CALLBACK_MOUSE_OUT, /**< Mouse Out Event */ + EVAS_CALLBACK_MOUSE_DOWN, /**< Mouse Button Down Event */ + EVAS_CALLBACK_MOUSE_UP, /**< Mouse Button Up Event */ + EVAS_CALLBACK_MOUSE_MOVE, /**< Mouse Move Event */ + EVAS_CALLBACK_MOUSE_WHEEL, /**< Mouse Wheel Event */ + EVAS_CALLBACK_MULTI_DOWN, /**< Multi-touch Down Event */ + EVAS_CALLBACK_MULTI_UP, /**< Multi-touch Up Event */ + EVAS_CALLBACK_MULTI_MOVE, /**< Multi-touch Move Event */ + EVAS_CALLBACK_FREE, /**< Object Being Freed (Called after Del) */ + EVAS_CALLBACK_KEY_DOWN, /**< Key Press Event */ + EVAS_CALLBACK_KEY_UP, /**< Key Release Event */ + EVAS_CALLBACK_FOCUS_IN, /**< Focus In Event */ + EVAS_CALLBACK_FOCUS_OUT, /**< Focus Out Event */ + EVAS_CALLBACK_SHOW, /**< Show Event */ + EVAS_CALLBACK_HIDE, /**< Hide Event */ + EVAS_CALLBACK_MOVE, /**< Move Event */ + EVAS_CALLBACK_RESIZE, /**< Resize Event */ + EVAS_CALLBACK_RESTACK, /**< Restack Event */ + EVAS_CALLBACK_DEL, /**< Object Being Deleted (called before Free) */ + EVAS_CALLBACK_HOLD, /**< Hold Event, Informational purpose event to indicate something */ + EVAS_CALLBACK_CHANGED_SIZE_HINTS, /**< Size hints changed event */ + EVAS_CALLBACK_IMAGE_PRELOADED, /**< Image has been preloaded */ + + /* + * The following events are only for use with Evas canvases, with + * evas_event_callback_add(): + */ + EVAS_CALLBACK_CANVAS_FOCUS_IN, /**< Canvas got focus as a whole */ + EVAS_CALLBACK_CANVAS_FOCUS_OUT, /**< Canvas lost focus as a whole */ + EVAS_CALLBACK_RENDER_FLUSH_PRE, /**< Called just before rendering is updated on the canvas target */ + EVAS_CALLBACK_RENDER_FLUSH_POST, /**< Called just after rendering is updated on the canvas target */ + EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN, /**< Canvas object got focus */ + EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT, /**< Canvas object lost focus */ + + /* + * More Evas object event types - see evas_object_event_callback_add(): + */ + EVAS_CALLBACK_IMAGE_UNLOADED, /**< Image data has been unloaded (by some mechanism in Evas that throw out original image data) */ + + EVAS_CALLBACK_RENDER_PRE, /**< Called just before rendering starts on the canvas target @since 1.2 */ + EVAS_CALLBACK_RENDER_POST, /**< Called just after rendering stops on the canvas target @since 1.2 */ + + EVAS_CALLBACK_IMAGE_RESIZE, /**< Image size is changed @since 1.8 */ + EVAS_CALLBACK_DEVICE_CHANGED, /**< Devices added, removed or changed on canvas @since 1.8 */ + EVAS_CALLBACK_LAST /**< Last element/sentinel -- not really an event */ +} Evas_Callback_Type; /**< The types of events triggering a callback */ + +/** + * @def EVAS_CALLBACK_PRIORITY_BEFORE + * @brief Slightly more prioritized than default. + * @since 1.1 + */ +#define EVAS_CALLBACK_PRIORITY_BEFORE -100 +/** + * @def EVAS_CALLBACK_PRIORITY_DEFAULT + * @brief Default callback priority level + * @since 1.1 + */ +#define EVAS_CALLBACK_PRIORITY_DEFAULT 0 +/** + * @def EVAS_CALLBACK_PRIORITY_AFTER + * @brief Slightly less prioritized than default. + * @since 1.1 + */ +#define EVAS_CALLBACK_PRIORITY_AFTER 100 + +/** + * @typedef Evas_Callback_Priority + * + * @brief Callback priority value. Range is -32k to 32k. The lower the number, the + * higher the priority. + * + * @since 1.1 + * + * @see EVAS_CALLBACK_PRIORITY_AFTER + * @see EVAS_CALLBACK_PRIORITY_BEFORE + * @see EVAS_CALLBACK_PRIORITY_DEFAULT + */ +typedef short Evas_Callback_Priority; + +/** + * @brief Enumeration for Mouse Button events. + */ +typedef enum _Evas_Button_Flags +{ + EVAS_BUTTON_NONE = 0, /**< No extra mouse button data */ + EVAS_BUTTON_DOUBLE_CLICK = (1 << 0), /**< Second press of a double click */ + EVAS_BUTTON_TRIPLE_CLICK = (1 << 1) /**< Third press of a triple click */ +} Evas_Button_Flags; /**< Flags for Mouse Button events */ + +/** + * @brief Enumeration for events. + */ +typedef enum _Evas_Event_Flags +{ + EVAS_EVENT_FLAG_NONE = 0, /**< No fancy flags set */ + EVAS_EVENT_FLAG_ON_HOLD = (1 << 0), /**< The event is being delivered but should be put "on hold" until the on hold flag is unset \n + The event should be used for informational purposes and maybe for some indications visually, but should not actually perform anything. */ + EVAS_EVENT_FLAG_ON_SCROLL = (1 << 1) /**< The event occurs while scrolling \n + For example, DOWN event occurs during scrolling; the event should be used for informational purposes and maybe for some indications visually, but should not actually perform anything. */ +} Evas_Event_Flags; /**< Flags for Events */ + +/** + * @brief Enumeration for touch point states. + */ +typedef enum _Evas_Touch_Point_State +{ + EVAS_TOUCH_POINT_DOWN, /**< Touch point is pressed down */ + EVAS_TOUCH_POINT_UP, /**< Touch point is released */ + EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */ + EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */ + EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */ +} Evas_Touch_Point_State; + +/** + * @brief Enumeration for font hinting. + * @ingroup Evas_Font_Group + */ +typedef enum _Evas_Font_Hinting_Flags +{ + EVAS_FONT_HINTING_NONE, /**< No font hinting */ + EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */ + EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */ +} Evas_Font_Hinting_Flags; /**< Flags for Font Hinting */ + +/** + * @brief Enumeration for pixel data of colorspaces supported by Evas. + * @ingroup Evas_Object_Image + */ +typedef enum _Evas_Colorspace +{ + EVAS_COLORSPACE_ARGB8888, /**< ARGB 32 bits per pixel, high-byte is Alpha, accessed 1 32bit word at a time */ + /* The following are not currently supported - but planned for the future */ + EVAS_COLORSPACE_YCBCR422P601_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */ + EVAS_COLORSPACE_YCBCR422P709_PL, /**< YCbCr 4:2:2 Planar, ITU.BT-709 specifications. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb, then Cr rows */ + EVAS_COLORSPACE_RGB565_A5P, /**< 16bit rgb565 + Alpha plane at end - 5 bits of the 8 being used per alpha byte */ + EVAS_COLORSPACE_GRY8, /**< 8bit grayscale */ + EVAS_COLORSPACE_YCBCR422601_PL, /**< YCbCr 4:2:2, ITU.BT-601 specifications. The data pointed to is just an array of row pointer, pointing to line of Y,Cb,Y,Cr bytes */ + EVAS_COLORSPACE_YCBCR420NV12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of row pointer, pointing to the Y rows, then the Cb,Cr rows. */ + EVAS_COLORSPACE_YCBCR420TM12601_PL, /**< YCbCr 4:2:0, ITU.BT-601 specification. The data pointed to is just an array of tiled row pointer, pointing to the Y rows, then the Cb,Cr rows. */ + EVAS_COLORSPACE_AGRY88, /**< AY 8bits Alpha and 8bits Grey, accessed 1 16bits at a time */ + EVAS_COLORSPACE_ETC1, /**< OpenGL ETC1 encoding of RGB texture (4 bit per pixel) @since 1.10 */ + EVAS_COLORSPACE_RGB8_ETC2, /**< OpenGL GL_COMPRESSED_RGB8_ETC2 texture compression format (4 bit per pixel) @since 1.10 */ + EVAS_COLORSPACE_RGBA8_ETC2_EAC, /**< OpenGL GL_COMPRESSED_RGBA8_ETC2_EAC texture compression format, supports alpha (8 bit per pixel) @since 1.10 */ + EVAS_COLORSPACE_ETC1_ALPHA, /**< ETC1 with alpha support using two planes: ETC1 RGB and ETC1 grey for alpha @since 1.11 */ +} Evas_Colorspace; /**< Colorspaces for pixel data supported by Evas */ + +/** + * @brief Enumeration for modes of packing items into cells in a table. + * + * @see evas_object_table_homogeneous_set() for an explanation of the function of + * each one. + * @ingroup Evas_Object_Table + */ +typedef enum _Evas_Object_Table_Homogeneous_Mode +{ + EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, + EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, + EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 +} Evas_Object_Table_Homogeneous_Mode; /**< Table cell pack mode */ + +typedef struct _Evas_Coord_Rectangle Evas_Coord_Rectangle; /**< @brief A generic rectangle handle */ +typedef struct _Evas_Point Evas_Point; /**< @brief Integer point */ + +typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< @brief Evas_Coord point */ +typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< @brief Evas_Coord point with sub-pixel precision */ + +typedef struct _Evas_Coord_Size Evas_Coord_Size; /**< @brief Evas_Coord size @since 1.8 */ +typedef struct _Evas_Position Evas_Position; /**< @brief Associates the given point in Canvas and Output */ +typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< @brief Associates the given point in Canvas and Output, with sub-pixel precision */ + +/** + * @typedef Evas_Smart_Class + * + * @brief A smart object @b base class definition. + * + * @ingroup Evas_Smart_Group + */ +typedef struct _Evas_Smart_Class Evas_Smart_Class; + +/** + * @typedef Evas_Smart_Interface + * + * @brief A smart object @b base interface definition. + * + * @since 1.7 + * + * @remarks An Evas interface is exactly like the OO-concept: It is a 'contract' or + * API that the object is declared to support. A smart object may have + * more than one interface, thus extending the behavior it gets from + * sub-classing. + * + * @ingroup Evas_Smart_Group + */ +typedef struct _Evas_Smart_Interface Evas_Smart_Interface; + +/** + * @typedef Evas_Smart_Cb_Description + * + * @brief A smart object callback description, used to provide introspection. + * + * @ingroup Evas_Smart_Group + */ +typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description; + +/** + * @typedef Evas_Map + * + * @brief An opaque handle to map points. + * + * @see evas_map_new() + * @see evas_map_free() + * @see evas_map_dup() + * + * @ingroup Evas_Object_Group_Map + */ +typedef struct _Evas_Map Evas_Map; + +/** + * @typedef Evas + * + * @brief An opaque handle to an Evas canvas. + * + * @see evas_new() + * @see evas_free() + * + * @ingroup Evas_Canvas + */ +typedef struct _Evas Evas; + +/** + * @typedef Evas_Object + * @brief An Evas Object handle. + * @ingroup Evas_Object_Group + */ +typedef struct _Evas_Object Evas_Object; + +typedef void Evas_Performance; /**< @brief Evas Performance handle */ +typedef struct _Evas_Modifier Evas_Modifier; /**< @brief Opaque type containing information on which modifier keys are registered in an Evas canvas */ +typedef struct _Evas_Lock Evas_Lock; /**< @brief Opaque type containing information on which lock keys are registered in an Evas canvas */ +typedef struct _Evas_Smart Evas_Smart; /**< @brief Evas Smart Object handle */ +typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< @brief Generic datatype for engine specific native surface information */ + +/** + * @typedef Evas_Video_Surface + * + * @brief A generic data type for video specific surface information. + * + * @since 1.1 + * + * @see evas_object_image_video_surface_set + * @see evas_object_image_video_surface_get + */ +typedef struct _Evas_Video_Surface Evas_Video_Surface; + +typedef unsigned long long Evas_Modifier_Mask; /**< @brief An Evas modifier mask type */ + +typedef int Evas_Coord; /**< @brief Evas x y coordinates */ +typedef int Evas_Font_Size; /**< @brief Evas Font Sizes */ +typedef int Evas_Angle; /**< @brief Evas angle */ + +struct _Evas_Coord_Rectangle /**< @brief A rectangle in Evas_Coord */ +{ + Evas_Coord x; /**< Top-left x co-ordinate of rectangle */ + Evas_Coord y; /**< Top-left y co-ordinate of rectangle */ + Evas_Coord w; /**< Width of rectangle */ + Evas_Coord h; /**< Height of rectangle */ +}; + +struct _Evas_Point +{ + int x, y; +}; + +struct _Evas_Coord_Point +{ + Evas_Coord x; /**< X co-ordinate */ + Evas_Coord y; /**< Y co-ordinate */ +}; + +struct _Evas_Coord_Size +{ + Evas_Coord w; /**< Width */ + Evas_Coord h; /**< Height */ +}; + +struct _Evas_Coord_Precision_Point +{ + Evas_Coord x, y; + double xsub, ysub; +}; + +struct _Evas_Position +{ + Evas_Point output; + Evas_Coord_Point canvas; /**< Position on the canvas */ +}; + +struct _Evas_Precision_Position +{ + Evas_Point output; + Evas_Coord_Precision_Point canvas; +}; + +/** + * @brief Enumeration for aspect types or policies for scaling size hints, used for evas_object_size_hint_aspect_set(). + */ +typedef enum _Evas_Aspect_Control +{ + EVAS_ASPECT_CONTROL_NONE = 0, /**< Unset scaling preference */ + EVAS_ASPECT_CONTROL_NEITHER = 1, /**< Same effect as unset preference on scaling */ + EVAS_ASPECT_CONTROL_HORIZONTAL = 2, /**< Use all horizontal container space to place an object, using the given aspect */ + EVAS_ASPECT_CONTROL_VERTICAL = 3, /**< Use all vertical container space to place an object, using the given aspect */ + EVAS_ASPECT_CONTROL_BOTH = 4 /**< Use all horizontal @b and vertical container spaces to place an object (never growing it out of those bounds), using the given aspect */ +} Evas_Aspect_Control; /**< Aspect types or policies for scaling size hints, used for evas_object_size_hint_aspect_set() */ + +/** + * @brief Enumeration for object's display modes. + */ +typedef enum _Evas_Display_Mode +{ + EVAS_DISPLAY_MODE_NONE = 0, /**<Default display mode */ + EVAS_DISPLAY_MODE_INHERIT = 1, /**< Object display mode depends on its ancestor display mode */ + EVAS_DISPLAY_MODE_COMPRESS = 2, /**< Give compress display mode hint to object */ + EVAS_DISPLAY_MODE_EXPAND = 3, /**< Give expand display mode hint to object */ + EVAS_DISPLAY_MODE_DONT_CHANGE = 4 /**< Object does not change display mode */ +} Evas_Display_Mode; /**< Object display mode type related with compress and expand or etc mode */ + +typedef struct _Evas_Pixel_Import_Source Evas_Pixel_Import_Source; /**< @brief A source description of pixels for importing pixels */ +typedef struct _Evas_Engine_Info Evas_Engine_Info; /**< @brief A generic Evas Engine information structure */ +typedef struct _Evas_Device Evas_Device; /**< @brief A source device handle - where the event came from */ +typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */ +typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */ +typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */ +typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */ +typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */ +typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< @brief Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */ +typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */ +typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */ +typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< @brief Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */ +typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< @brief Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */ +typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< @brief Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */ +typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< @brief Event structure for #EVAS_CALLBACK_HOLD event callbacks */ + +/** + * @brief Enumeration for load errors. + */ +typedef enum _Evas_Load_Error +{ + EVAS_LOAD_ERROR_NONE = 0, /**< No error on load */ + EVAS_LOAD_ERROR_GENERIC = 1, /**< A non-specific error occurred */ + EVAS_LOAD_ERROR_DOES_NOT_EXIST = 2, /**< File (or file path) does not exist */ + EVAS_LOAD_ERROR_PERMISSION_DENIED = 3, /**< Permission denied to an existing file (or path) */ + EVAS_LOAD_ERROR_RESOURCE_ALLOCATION_FAILED = 4, /**< Allocation of resources failure prevented load */ + EVAS_LOAD_ERROR_CORRUPT_FILE = 5, /**< File corrupt (but is detected as a known format) */ + EVAS_LOAD_ERROR_UNKNOWN_FORMAT = 6 /**< File is not a known format */ +} Evas_Load_Error; /**< Evas image load error codes one can get - see evas_load_error_str() */ + +/** + * @brief Enumeration for allocation errors. + */ +typedef enum _Evas_Alloc_Error +{ + EVAS_ALLOC_ERROR_NONE = 0, /**< No allocation error */ + EVAS_ALLOC_ERROR_FATAL = 1, /**< Allocation failed despite attempts to free up memory */ + EVAS_ALLOC_ERROR_RECOVERED = 2 /**< Allocation succeeded, but extra memory had to be found by freeing up speculative resources */ +} Evas_Alloc_Error; /**< Possible allocation errors returned by evas_alloc_error() */ + +/** + * @brief Enumeration for spread of image fill. + */ +typedef enum _Evas_Fill_Spread +{ + EVAS_TEXTURE_REFLECT = 0, /**< Image fill tiling mode - tiling reflects */ + EVAS_TEXTURE_REPEAT = 1, /**< Tiling repeats */ + EVAS_TEXTURE_RESTRICT = 2, /**< Tiling clamps - range offset ignored */ + EVAS_TEXTURE_RESTRICT_REFLECT = 3, /**< Tiling clamps and any range offset reflects */ + EVAS_TEXTURE_RESTRICT_REPEAT = 4, /**< Tiling clamps and any range offset repeats */ + EVAS_TEXTURE_PAD = 5 /**< Tiling extends with end values */ +} Evas_Fill_Spread; /**< Fill types used for evas_object_image_fill_spread_set() */ + +/** + * @brief Enumeration for aspect types or policies. + */ +typedef enum _Evas_Pixel_Import_Pixel_Format +{ + EVAS_PIXEL_FORMAT_NONE = 0, /**< No pixel format */ + EVAS_PIXEL_FORMAT_ARGB32 = 1, /**< ARGB 32bit pixel format with A in the high byte per 32bit pixel word */ + EVAS_PIXEL_FORMAT_YUV420P_601 = 2 /**< YUV 420 Planar format with CCIR 601 color encoding with contiguous planes in the order Y, U and V */ +} Evas_Pixel_Import_Pixel_Format; /**< Pixel format for import call. See evas_object_image_pixels_import() */ + +struct _Evas_Pixel_Import_Source +{ + Evas_Pixel_Import_Pixel_Format format; /**< Pixel format type i.e. ARGB32, YUV420P_601, and so on */ + int w, h; /**< Width and height of source in pixels */ + void **rows; /**< Array of pointers (size depends on format) pointing to left edge of each scanline */ +}; + +/* Magic version number to know what the native surf struct looks like */ +#define EVAS_NATIVE_SURFACE_VERSION 3 + +/** + * @brief Native surface types that image object supports + * + * @see Evas_Native_Surface + * @see evas_object_image_native_surface_set() + */ +typedef enum _Evas_Native_Surface_Type +{ + EVAS_NATIVE_SURFACE_NONE, /**< No surface type */ + EVAS_NATIVE_SURFACE_X11, /**< X Window system based type. pixmap id or visual of the pixmap */ + EVAS_NATIVE_SURFACE_OPENGL, /**< OpenGL system based type. texture or framebuffer id*/ + EVAS_NATIVE_SURFACE_TIZEN, /**< @internal don't use this type but @see EVAS_NATIVE_SURFACE_TBM */ + EVAS_NATIVE_SURFACE_TBM /**< Tizen system based type. This is used for tizen buffer manager. */ +} Evas_Native_Surface_Type; + +/** + * @brief A generic datatype for engine specific native surface information. + * + * Please fill up Evas_Native_Surface fields that regarded with current surface + * type. If you want to set the native surface type to + * EVAS_NATIVE_SURFACE_X11, you need to set union data with x11.visual or + * x11.pixmap. If you need to set the native surface as + * EVAS_NATIVE_SURFACE_OPENGL, on the other hand, you need to set union data + * with opengl.texture_id or opengl.framebuffer_id and so on. The version field + * should be set with EVAS_NATIVE_SURFACE_VERSION in order to check abi + * break in your application on the different efl library versions. + * + * @warning Native surface types totally depend on the system. Please + * be aware that the types are supported on your system before using + * them. + * @see evas_object_image_native_surface_set() + */ +struct _Evas_Native_Surface +{ + int version; /**< Current Native Surface Version. Use EVAS_NATIVE_SURFACE_VERSION */ + Evas_Native_Surface_Type type; /**< Surface type. @see Evas_Native_Surface_Type */ + union { + struct + { + void *visual; /**< Visual of the pixmap to use (Visual) */ + unsigned long pixmap; /**< Pixmap ID to use (Pixmap) */ + } x11; /**< Set this struct fields if your surface data is X11 based. */ + struct + { + unsigned int texture_id; /**< opengl texture ID to use from glGenTextures() */ + unsigned int framebuffer_id; /**< 0 if this is not an FBO, otherwise FBO ID from glGenFramebuffers() */ + unsigned int internal_format; /**< Same as 'internalFormat' for glTexImage2D() */ + unsigned int format; /**< Same as 'format' for glTexImage2D() */ + unsigned int x, y, w, h; /**< Region inside the texture to use (Image size is assumed as texture size, with 0, 0 being the top-left and co-ordinates working down to the right and bottom being positive) */ + } opengl; /**< Set this struct fields if your surface data is OpenGL based. */ + struct + { + void *buffer; /**< tbm surface */ + int rot; /**< rotation (0, 90, 180, 270) */ + float ratio; /**< width/height ratio of the source image */ + int flip; /**< flip (0:none, 1:horizontal, 2:vertical, 3:both) */ + } tizen; /**< Set this struct fields if your surface data is Tizen based. */ + } data; /**< Choose one union data according to your surface. */ +}; + +/** + * @def EVAS_VIDEO_SURFACE_VERSION + * @brief Definition of the magic version number to know what the video surf struct looks like. + * @since 1.1 + */ +#define EVAS_VIDEO_SURFACE_VERSION 1 + +typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface); +typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b); + +/** + * @brief Struct of Evas Video Surface. + */ +struct _Evas_Video_Surface +{ + int version; + + Evas_Video_Coord_Cb move; /**< Moves the video surface to this position */ + Evas_Video_Coord_Cb resize; /**< Resizes the video surface to that size */ + Evas_Video_Cb show; /**< Shows the video overlay surface */ + Evas_Video_Cb hide; /**< Hides the video overlay surface */ + Evas_Video_Cb update_pixels; /**< Updates the Evas_Object_Image pixels when called */ + + Evas_Object *parent; + void *data; +}; + +#define EVAS_LAYER_MIN -32768 /**< @brief Bottom-most layer number */ +#define EVAS_LAYER_MAX 32767 /**< @brief Top-most layer number */ + +#define EVAS_COLOR_SPACE_ARGB 0 /**< @brief Not used for anything */ +#define EVAS_COLOR_SPACE_AHSV 1 /**< @brief Not used for anything */ +#define EVAS_TEXT_INVALID -1 /**< @brief Not used for anything */ +#define EVAS_TEXT_SPECIAL -2 /**< @brief Not used for anything */ + +#define EVAS_HINT_EXPAND 1.0 /**< @brief Use with evas_object_size_hint_weight_set(), evas_object_size_hint_weight_get(), evas_object_size_hint_expand_set(), evas_object_size_hint_expand_get() */ +#define EVAS_HINT_FILL -1.0 /**< @brief Use with evas_object_size_hint_align_set(), evas_object_size_hint_align_get(), evas_object_size_hint_fill_set(), evas_object_size_hint_fill_get() */ + +/** + * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) + * @ingroup Evas_Object_Group_Size_Hints + */ +#define evas_object_size_hint_fill_set evas_object_size_hint_align_set + +/** + * @brief Convenience macro to make it easier to understand that align is also used for fill properties (as fill is mutually exclusive to align) + * @ingroup Evas_Object_Group_Size_Hints + */ +#define evas_object_size_hint_fill_get evas_object_size_hint_align_get + +/** + * @brief Convenience macro to make it easier to understand that weight is also used for expand properties + * @ingroup Evas_Object_Group_Size_Hints + */ +#define evas_object_size_hint_expand_set evas_object_size_hint_weight_set + +/** + * @brief Convenience macro to make it easier to understand that weight is also used for expand properties + * @ingroup Evas_Object_Group_Size_Hints + */ +#define evas_object_size_hint_expand_get evas_object_size_hint_weight_get + +/** + * @brief Enumeration for modes of object rendering to output. + * @ingroup Evas_Object_Group_Extras + */ +typedef enum _Evas_Render_Op +{ + EVAS_RENDER_BLEND = 0, /**< Default op: d = d*(1-sa) + s */ + EVAS_RENDER_BLEND_REL = 1, /**< d = d*(1 - sa) + s*da */ + EVAS_RENDER_COPY = 2, /**< d = s */ + EVAS_RENDER_COPY_REL = 3, /**< d = s*da */ + EVAS_RENDER_ADD = 4, /* d = d + s */ + EVAS_RENDER_ADD_REL = 5, /**< d = d + s*da */ + EVAS_RENDER_SUB = 6, /**< d = d - s */ + EVAS_RENDER_SUB_REL = 7, /* d = d - s*da */ + EVAS_RENDER_TINT = 8, /**< d = d*s + d*(1 - sa) + s*(1 - da) */ + EVAS_RENDER_TINT_REL = 9, /**< d = d*(1 - sa + s) */ + EVAS_RENDER_MASK = 10, /**< d = d*sa */ + EVAS_RENDER_MUL = 11 /**< d = d*s */ +} Evas_Render_Op; /**< How the object should be rendered to output */ + +/** + * @brief Enumeration for border fill mode. + */ +typedef enum _Evas_Border_Fill_Mode +{ + EVAS_BORDER_FILL_NONE = 0, /**< Image's center region is @b not to be rendered */ + EVAS_BORDER_FILL_DEFAULT = 1, /**< Image's center region is to be @b blended with objects underneath it, if it has transparency. This is the default behavior for image objects */ + EVAS_BORDER_FILL_SOLID = 2 /**< Image's center region is to be made solid, even if it has transparency on it */ +} Evas_Border_Fill_Mode; /**< How an image's center region (the complement to the border region) should be rendered by Evas */ + +/** + * @brief Enumeration for image scale hints. + */ +typedef enum _Evas_Image_Scale_Hint +{ + EVAS_IMAGE_SCALE_HINT_NONE = 0, /**< No scale hint at all */ + EVAS_IMAGE_SCALE_HINT_DYNAMIC = 1, /**< Image is being re-scaled over time, thus turning scaling cache @b off for its data */ + EVAS_IMAGE_SCALE_HINT_STATIC = 2 /**< Image is not being re-scaled over time, thus turning scaling cache @b on for its data */ +} Evas_Image_Scale_Hint; /**< How an image's data is to be treated by Evas, with regard to scaling cache */ + +/** + * @brief Enumeration for animated loop hints. + */ +typedef enum _Evas_Image_Animated_Loop_Hint +{ + EVAS_IMAGE_ANIMATED_HINT_NONE = 0, + EVAS_IMAGE_ANIMATED_HINT_LOOP = 1, /**< Image's animation mode is loop like 1->2->3->1->2->3 */ + EVAS_IMAGE_ANIMATED_HINT_PINGPONG = 2 /**< Image's animation mode is pingpong like 1->2->3->2->1-> ... */ +} Evas_Image_Animated_Loop_Hint; + +/** + * @brief Enumeration for engine rendering modes. + */ +typedef enum _Evas_Engine_Render_Mode +{ + EVAS_RENDER_MODE_BLOCKING = 0, + EVAS_RENDER_MODE_NONBLOCKING = 1, +} Evas_Engine_Render_Mode; + +/** + * @brief Enumeration for image content hints. + */ +typedef enum _Evas_Image_Content_Hint +{ + EVAS_IMAGE_CONTENT_HINT_NONE = 0, /**< No hint at all */ + EVAS_IMAGE_CONTENT_HINT_DYNAMIC = 1, /**< The contents change over time */ + EVAS_IMAGE_CONTENT_HINT_STATIC = 2 /**< The contents do not change over time */ +} Evas_Image_Content_Hint; /**< How an image's data is to be treated by Evas, for optimization */ + +/** + * @brief Enumeration for device class. + */ +typedef enum _Evas_Device_Class +{ + EVAS_DEVICE_CLASS_NONE, /**< Not a device @since 1.8 */ + EVAS_DEVICE_CLASS_SEAT, /**< The user/seat (the user themselves) @since 1.8 */ + EVAS_DEVICE_CLASS_KEYBOARD, /**< Regular keyboard, numberpad or attached buttons @since 1.8 */ + EVAS_DEVICE_CLASS_MOUSE, /**< Mouse, trackball or touchpad relative motion device @since 1.8 */ + EVAS_DEVICE_CLASS_TOUCH, /**< Touchscreen with fingers or stylus @since 1.8 */ + EVAS_DEVICE_CLASS_PEN, /**< Special pen device @since 1.8 */ + EVAS_DEVICE_CLASS_POINTER, /**< Laser pointer, wii-style or "minority report" pointing device @since 1.8 */ + EVAS_DEVICE_CLASS_GAMEPAD /**< Gamepad controller or joystick @since 1.8 */ +} Evas_Device_Class; + +struct _Evas_Engine_Info /** @brief Generic engine information. Generic info is not of much use. */ +{ + int magic; /**< Magic number */ +}; + +struct _Evas_Event_Mouse_Down /** @brief Mouse button press event */ +{ + int button; /**< Mouse button number that went down (1 - 32) */ + + Evas_Point output; /**< The X/Y location of the cursor */ + Evas_Coord_Point canvas; /**< The X/Y location of the cursor */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + Evas_Button_Flags flags; /**< Button flags set during the event */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Mouse_Up /** @brief Mouse button release event */ +{ + int button; /**< Mouse button number that is raised (1 - 32) */ + + Evas_Point output; /**< The X/Y location of the cursor */ + Evas_Coord_Point canvas; /**< The X/Y location of the cursor */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + Evas_Button_Flags flags; /**< Button flags set during the event */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Mouse_In /** @brief Mouse enter event */ +{ + int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */ + + Evas_Point output; /**< The X/Y location of the cursor */ + Evas_Coord_Point canvas; /**< The X/Y location of the cursor */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Mouse_Out /** @brief Mouse leave event */ +{ + int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */ + + Evas_Point output; /**< The X/Y location of the cursor */ + Evas_Coord_Point canvas; /**< The X/Y location of the cursor */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Mouse_Move /** @brief Mouse move event */ +{ + int buttons; /**< Button pressed mask, Bits set to @c 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 and so on) */ + + Evas_Position cur; /**< Current mouse position */ + Evas_Position prev; /**< Previous mouse position */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Mouse_Wheel /** @brief Wheel event */ +{ + int direction; /* 0 = default up/down wheel FIXME: more wheel types */ + int z; /* ...,-2,-1 = down, 1,2,... = up */ + + Evas_Point output; /**< The X/Y location of the cursor */ + Evas_Coord_Point canvas; /**< The X/Y location of the cursor */ + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Multi_Down /** @brief Multi button press event */ +{ + int device; /**< Multi device number that went down (1 or more for extra touches) */ + double radius, radius_x, radius_y; + double pressure, angle; + + Evas_Point output; + Evas_Coord_Precision_Point canvas; + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + Evas_Button_Flags flags; /**< Button flags set during the event */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Multi_Up /** @brief Multi button release event */ +{ + int device; /**< Multi device number that went up (1 or more for extra touches) */ + double radius, radius_x, radius_y; + double pressure, angle; + + Evas_Point output; + Evas_Coord_Precision_Point canvas; + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + Evas_Button_Flags flags; /**< Button flags set during the event */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Multi_Move /** @brief Multi button down event */ +{ + int device; /**< Multi device number that moved (1 or more for extra touches) */ + double radius, radius_x, radius_y; + double pressure, angle; + + Evas_Precision_Position cur; + + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Key_Down /** @brief Key press event */ +{ + char *keyname; /**< Name string of the key pressed */ + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + const char *key; /**< Logical key : (example, shift+1 == exclamation) */ + const char *string; /**< UTF8 string if this keystroke has produced a visible string to be ADDED */ + const char *compose; /**< UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Key_Up /** @brief Key release event */ +{ + char *keyname; /**< Name string of the key released */ + void *data; + Evas_Modifier *modifiers; /**< Modifier keys pressed during the event */ + Evas_Lock *locks; + + const char *key; /**< Logical key : (example, shift+1 == exclamation) */ + const char *string; /**< UTF8 string if this keystroke has produced a visible string to be ADDED */ + const char *compose; /**< UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */ + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +struct _Evas_Event_Hold /** @brief Hold change event */ +{ + int hold; /**< Hold flag */ + void *data; + + unsigned int timestamp; + Evas_Event_Flags event_flags; + Evas_Device *dev; +}; + +/** + * @brief Enumeration for handling mouse pointer. + * + * @remarks In the mode #EVAS_OBJECT_POINTER_MODE_AUTOGRAB, when a mouse button + * is pressed down over an object and held, with the mouse pointer + * being moved outside of it, the pointer still behaves as being bound + * to that object, albeit out of its drawing region. When the button + * is released, the event is fed to the object, that may check if + * the final position is over it or not and do something about it. + * + * @remarks In the mode #EVAS_OBJECT_POINTER_MODE_NOGRAB, the pointer is + * always bound to the object right below it. + * + * @ingroup Evas_Object_Group_Extras + */ +typedef enum _Evas_Object_Pointer_Mode +{ + EVAS_OBJECT_POINTER_MODE_AUTOGRAB, /**< Default, X11-like */ + EVAS_OBJECT_POINTER_MODE_NOGRAB, /**< Pointer always bound to the object right below it */ + EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN /**< Useful on object with "repeat events" enabled, where mouse and touch up and down events ARE NOT repeated to objects and these objects are not auto-grabbed @since 1.2 */ +} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas */ + +/** + * @brief Evas smart objects' "smart callback" function signature + * @since_tizen 2.3 + * @ingroup Evas_Smart_Object_Group + */ +typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info); + +/** + * @brief Evas event callback function signature + * @since_tizen 2.3 + * @ingroup Evas_Canvas_Events + */ +typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info); + +/** + * @brief Evas event callback Post function signature + * @since_tizen 2.3 + * @ingroup Evas_Canvas_Events + */ +typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e); + +/** + * @brief Evas object event callback function signature + * @since_tizen 2.3 + * @ingroup Evas_Object_Group_Events + */ +typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info); + +/** + * @brief Evas Async events put function signature + * @since_tizen 2.3 + * @ingroup Evas_Top_Group + */ +typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Top_Group Top Level Functions + @ingroup Evas + * + * @brief This group provides functions that affect Evas as a whole. + * @{ + */ + +/** + * @brief Initializes Evas. + * + * @details This function initializes Evas and increments a counter of the + * number of calls to it. It returns the new counter value. + * + * @since_tizen 2.3 + * + * @remarks Most EFL users do not use this function directly, because + * they do not access Evas directly by themselves. Instead, they + * use higher level helpers, like @c ecore_evas_init(). + * See http://docs.enlightenment.org/auto/ecore/ + * + * @return The init counter value + * + * @see evas_shutdown() + * + * @ingroup Evas_Top_Group + */ +EAPI int evas_init(void); + +/** + * @brief Shuts down Evas. + * + * @details This function finalizes Evas, decrementing the counter of the + * number of calls to the function evas_init(). This new value for the + * counter is returned. + * + * @since_tizen 2.3 + * + * @remarks If you are the sole user of Evas, you can use evas_init() to + * check if it is being properly shut down by expecting a return value + * of @c 0. + * + * @return The Evas init counter value + * + * @see evas_init() + * + * @ingroup Evas_Top_Group + */ +EAPI int evas_shutdown(void); + +/** + * @brief Gets the allocation errors that have occurred during the execution of the prior function. + * + * @details This function returns any memory allocation errors that occurred during the execution + * and the kind of errors. Valid return values are @c EVAS_ALLOC_ERROR_NONE, + * @c EVAS_ALLOC_ERROR_FATAL, and @c EVAS_ALLOC_ERROR_RECOVERED. + * + * @since_tizen 2.3 + * + * @remarks @c EVAS_ALLOC_ERROR_NONE means that no errors occurred at all and the function + * worked as expected. + * + * @remarks @c EVAS_ALLOC_ERROR_FATAL means the function is completely unable to perform + * its job and exited as cleanly as possible. You should consider this as a + * sign of very low memory and should try and safely recover from the prior function + * failure. You can also try to free up memory elsewhere and try again after memory is freed. + * + * @remarks @c EVAS_ALLOC_ERROR_RECOVERED means that an allocation error occurred, but Evas + * recovered from it by finding memory of its own that it has allocated and + * freeing what it sees as not really usefully allocated memory. What is freed + * may vary. Evas may reduce the resolution of images, free cached images or + * fonts, throw out pre-rendered data, reduce the complexity of change lists, + * and so on. Evas and the program functions as per normal after this, but this + * is a sign of low memory, and it is suggested that your program try and + * identify memory it does not need, and free it. + * + * @remarks The following is an example: + * @code + * extern Evas_Object *object; + * void callback (void *data, Evas *e, Evas_Object *obj, void *event_info); + * + * evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, callback, NULL); + * if (evas_alloc_error() == EVAS_ALLOC_ERROR_FATAL) + * { + * fprintf(stderr, "ERROR: Completely unable to attach callback. Must\n"); + * fprintf(stderr, " destroy object now as it cannot be used.\n"); + * evas_object_del(object); + * object = NULL; + * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n"); + * my_memory_cleanup(); + * } + * if (evas_alloc_error() == EVAS_ALLOC_ERROR_RECOVERED) + * { + * fprintf(stderr, "WARNING: Memory is really low. Cleaning out RAM.\n"); + * my_memory_cleanup(); + * } + * @endcode + * + * @return The allocation error flag + * + * @ingroup Evas_Top_Group + */ +EAPI Evas_Alloc_Error evas_alloc_error(void); + +/** + * @brief Gets the Evas internal asynchronous events read file descriptor. + * + * @details This function returns the read file descriptor of the + * asynchronous events of the canvas. Other mainloops, + * apart from ecore, may make use of it. + * + * @since_tizen 2.3 + * + * @remarks The Evas asynchronous events are meant to be dealt with internally, + * i.e., when building stuff to be glued together into the EFL + * infrastructure - a module, for example. The context which demands + * its use is when calculations need to be done out of the main + * thread, asynchronously, and some action must be performed after + * that. + * + * @remarks An example of the actual use of this API is for image asynchronous + * preload inside Evas. If the canvas is instantiated through + * ecore-evas usage, ecore itself takes care of calling those + * event processing. + * + * @return The asynchronous events read file descriptor of the canvas + * + * @ingroup Evas_Top_Group + */ +EAPI int evas_async_events_fd_get(void) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Triggers the processing of all events waiting on the file + * descriptor returned by evas_async_events_fd_get(). + * + * @details All asynchronous events queued up by evas_async_events_put() are + * processed here. More precisely, the callback functions, informed + * together with other event parameters, when queued, get called (with + * those parameters), in that order. + * + * @since_tizen 2.3 + * + * @return The number of events processed + * + * @ingroup Evas_Top_Group + */ +EAPI int evas_async_events_process(void); + +/** + * @brief Inserts asynchronous events on the canvas. + * + * @details This is the way, for a routine running outside evas' main thread, + * to report an asynchronous event. A callback function is informed, + * whose call is to happen after evas_async_events_process() is + * called. + * + * @since_tizen 2.3 + * + * @param[in] target The target to be affected by the events + * @param[in] type The type of callback function + * @param[in] event_info The information about the event + * @param[in] func The callback function pointer + * @return #EINA_TRUE if the events are inserted successfully, \n + * otherwise #EINA_FALSE on failure + * + * @ingroup Evas_Top_Group + */ +EAPI Eina_Bool evas_async_events_put(const void *target, Evas_Callback_Type type, void *event_info, Evas_Async_Events_Put_Cb func) EINA_ARG_NONNULL(1, 4); + +/** + * @} + */ + +/** + * @defgroup Evas_Canvas Canvas Functions + * @ingroup Evas + * + * @brief This group provides low level Evas canvas functions. Sub-groups + * present more high level ones, though. + * + * @remarks Most of these functions deal with low level Evas actions, like: + * @li creating or destroying raw canvases, not bound to any displaying engine + * @li telling a canvas that it got focused (in a windowing context, for example) + * @li telling a canvas that a region should not be calculated anymore in rendering + * @li telling a canvas to render its contents, immediately + * + * @remarks You mostly use Evas with the @c Ecore_Evas wrapper, which + * deals with all the above mentioned issues automatically. Thus, you + * need this section only if you are building low level stuff. + * + * @remarks The groups present you functions that deal with the canvas + * directly, too, and not yet with its @b objects. They are the + * functions you need to use at a minimum to get a working canvas. + * + * @{ + */ + +/** + * @brief Creates a new empty evas. + * + * @since_tizen 2.3 + * + * @remarks This function should only fail if the memory allocation fails. + * + * @remarks This function is a very low level function. Instead of using it + * directly, consider using the high level functions in + * Ecore_Evas such as @c ecore_evas_new(). See + * http://docs.enlightenment.org/auto/ecore/ + * + * @remarks It is recommended that you call evas_init() before creating new canvas. + * + * @return A new uninitialised Evas canvas on success, \n + * otherwise @c NULL on failure + * + * @pre Note that before you can use evas, you have to: + * @li Set its render method with @ref evas_output_method_set. + * @li Set its viewport size with @ref evas_output_viewport_set. + * @li Set its size of the canvas with @ref evas_output_size_set. + * @li Ensure that the render engine is given the correct settings + * with @ref evas_engine_info_set. + * + * @ingroup Evas_Canvas + */ +EAPI Evas *evas_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * @brief Frees the given evas and any objects created on it. + * + * @since_tizen 2.3 + * + * @remarks Any objects with 'free' callbacks have those callbacks called + * in this function. + * + * @param[in] e The given evas + * + * @ingroup Evas_Canvas + */ +EAPI void evas_free(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Informs evas that it has got focus. + * + * @since_tizen 2.3 + * + * @param[in] e The evas to inform + * @ingroup Evas_Canvas + */ +EAPI void evas_focus_in(Evas *e); + +/** + * @brief Informs the evas that it has lost focus. + * + * @since_tizen 2.3 + * + * @param[in] e The evas to inform + * @ingroup Evas_Canvas + */ +EAPI void evas_focus_out(Evas *e); + +/** + * @brief Gets the focus state of the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The evas to query information + * @return #EINA_TRUE if it is focused, otherwise #EINA_FALSE. + * @ingroup Evas_Canvas + */ +EAPI Eina_Bool evas_focus_state_get(const Evas *e); + +/** + * @brief Pushes the nochange flag up @c 1. + * + * @since_tizen 2.3 + * + * @remarks This tells evas that while the nochange flag is greater than 0, do not + * mark objects as "changed" when making changes. + * + * @param[in] e The evas to changes information + * @ingroup Evas_Canvas + */ +EAPI void evas_nochange_push(Evas *e); + +/** + * @brief Pops the nochange flag down @c 1. + * + * @since_tizen 2.3 + * + * @remarks This tells evas that while the nochange flag is greater than 0, do not + * mark objects as "changed" when making changes. + * + * @param[in] e The evas to change information + * @ingroup Evas_Canvas + */ +EAPI void evas_nochange_pop(Evas *e); + +/** + * @brief Attaches a specific pointer to evas for fetching later. + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to attach the pointer to + * @param[in] data The pointer to attach + * @ingroup Evas_Canvas + */ +EAPI void evas_data_attach_set(Evas *e, void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the pointer attached by evas_data_attach_set(). + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to attach the pointer to + * @return The pointer attached + * @ingroup Evas_Canvas + */ +EAPI void *evas_data_attach_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Adds a damage rectangle. + * + * @details You can use this function to inform evas that a part of the + * canvas has to be repainted. + * + * @since_tizen 2.3 + * + * @remarks All newly created Evas rectangles get the default color values + * of 255 255 255 255 (opaque white). + * + * @param[in] e The given canvas pointer + * @param[in] x The rectangle's left position + * @param[in] y The rectangle's top position + * @param[in] w The rectangle's width + * @param[in] h The rectangle's height + * + * @ingroup Evas_Canvas + */ +EAPI void evas_damage_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Adds an "obscured region" to an Evas canvas. + * + * @since_tizen 2.3 + * + * @remarks You can use this function to inform an Evas canvas that a part + * of it <b>must not</b> be repainted. The region must be + * rectangular and its coordinates inside the canvas viewport are + * passed in the call. After this call, the region specified do not + * participate in any form in Evas' calculations and actions during + * its rendering updates, having its displaying content frozen as it + * is just after this function is executed. + * + * @remarks This is called "obscured region" because the most common use case for + * this rendering (partial) freeze is something else (most probably + * other canvas) being on top of the specified rectangular region, + * thus shading it completely from the user's final scene in a + * display. To avoid unnecessary processing, one should indicate to the + * obscured canvas not to bother about the non-important area. + * + * @remarks The majority of users do not have to worry about this function, as + * they use just one canvas in their applications, with + * nothing inset or on top of it in any form. + * + * @remarks To make this region one that @b has to be repainted again, call the + * function evas_obscured_clear(). + * + * @remarks This is a <b>very low level function</b>, which you may not use. + * + * @remarks This function does @b not flag the canvas as having its state + * changed. If you want to re-render it afterwards expecting new + * contents, you have to add "damage" regions yourself (see + * evas_damage_rectangle_add()). + * + * @param[in] e The given canvas pointer + * @param[in] x The rectangle's top left corner's horizontal coordinate + * @param[in] y The rectangle's top left corner's vertical coordinate + * @param[in] w The rectangle's width + * @param[in] h The rectangle's height + * + * @see evas_obscured_clear() + * @see evas_render_updates() + * + * @ingroup Evas_Canvas + */ +EAPI void evas_obscured_rectangle_add(Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Removes all "obscured regions" from an Evas canvas. + * + * @details This function removes all the rectangles from the obscured regions + * list of the canvas @a e. It takes obscured areas added with + * evas_obscured_rectangle_add() and make them again a regions that @b + * have to be repainted on rendering updates. + * + * @since_tizen 2.3 + * + * @remarks This is a <b>very low level function</b>, which you may not use. + * + * @remarks This function does @b not flag the canvas as having its state + * changed. If you want to re-render it afterwards expecting new + * contents, you have to add "damage" regions yourself (see + * evas_damage_rectangle_add()). + * + * @param[in] e The given canvas pointer + * + * @see evas_obscured_rectangle_add() for an example + * @see evas_render_updates() + * + * @ingroup Evas_Canvas + */ +EAPI void evas_obscured_clear(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Forces immediate renderization of the given Evas canvas. + * + * @details This function forces an immediate renderization update of the given + * canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This is a <b>very low level function</b>, which you may not use. + * You would use it, for example, to grab an Evas' canvas update regions + * and paint them back, using the canvas' pixmap, on a displaying system + * working below Evas. + * + * @remarks Evas is a stateful canvas. If no operations changing its + * state took place since the last rendering action, you do not see any + * changes and this call becomes a no-op. + * + * @param[in] e The given canvas pointer + * @return A newly allocated list of updated rectangles of the canvas (@c Eina_Rectangle structs) \n + * Free this list with evas_render_updates_free(). + * + * @ingroup Evas_Canvas + */ +EAPI Eina_List *evas_render_updates(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Frees the rectangles returned by evas_render_updates(). + * + * @details This function removes the region from the render updates list. + * The region does not get render updated anymore. + * + * @since_tizen 2.3 + * + * @param[in] updates The list of updated rectangles of the canvas + * + * @see evas_render_updates() for an example + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_updates_free(Eina_List *updates); + +/** + * @brief Forces rendering of the given canvas. + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas pointer + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Updates the canvas internal objects but does not trigger immediate rendering. + * + * @details This function updates the canvas internal objects not triggering + * rendering. To force rendering, use evas_render(). + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas pointer + * + * @see evas_render + * + * @ingroup Evas_Canvas + */ +EAPI void evas_norender(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Makes the canvas discard internally cached data used for rendering. + * + * @details This function flushes the arrays of delete, active and render objects. + * The other things it may discard include shared memory segments, + * temporary scratch buffers, and cached data to avoid re-compute of that data. + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas pointer + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_idle_flush(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Makes the canvas discard as much data as possible used by the engine at runtime. + * + * @details This function unloads images, deletes textures and much more, where + * possible. You may also want to call evas_render_idle_flush() immediately + * prior to this to perhaps discard a little more, though evas_render_dump() + * should implicitly delete most of what evas_render_idle_flush() might + * discard too. + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas pointer + * + * @ingroup Evas_Canvas + */ +EAPI void evas_render_dump(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Output_Method Render Engine Functions + * @ingroup Evas_Canvas + * + * @brief This goup provides functions that are used to set the render engine for a given + * function, and then get that engine working. + * + * @remarks The following code snippet shows how they can be used to + * initialise an evas that uses the X11 software engine: + * @code + * Evas *evas; + * Evas_Engine_Info_Software_X11 *einfo; + * extern Display *display; + * extern Window win; + * + * evas_init(); + * + * evas = evas_new(); + * evas_output_method_set(evas, evas_render_method_lookup("software_x11")); + * evas_output_size_set(evas, 640, 480); + * evas_output_viewport_set(evas, 0, 0, 640, 480); + * einfo = (Evas_Engine_Info_Software_X11 *)evas_engine_info_get(evas); + * einfo->info.display = display; + * einfo->info.visual = DefaultVisual(display, DefaultScreen(display)); + * einfo->info.colormap = DefaultColormap(display, DefaultScreen(display)); + * einfo->info.drawable = win; + * einfo->info.depth = DefaultDepth(display, DefaultScreen(display)); + * evas_engine_info_set(evas, (Evas_Engine_Info *)einfo); + * @endcode + * + * @{ + */ + +/** + * @brief Looks up a numeric ID from a string name of a rendering engine. + * + * @details This function looks up a numeric return value for the named engine + * in the string @a name. This is a normal C string, NULL byte + * terminated. The name is case sensitive. If the rendering engine is + * available, a numeric ID for that engine is returned that is not + * @c 0. If the engine is not available, @c 0 is returned, indicating an + * invalid engine. + * + * @since_tizen 2.3 + * + * @remarks You should NEVER rely on the numeric ID of an engine unless it is returned + * by this function. You should NOT write programs written accessing render + * method ID's directly, without first obtaining it from this function. + * + * @remarks It is mandatory that you call evas_init() before + * looking up the render method. + * + * @remarks The following is an example. + * @code + * int engine_id; + * Evas *evas; + * + * evas_init(); + * + * evas = evas_new(); + * if (!evas) + * { + * fprintf(stderr, "ERROR: Canvas creation failed. Fatal error.\n"); + * exit(-1); + * } + * engine_id = evas_render_method_lookup("software_x11"); + * if (!engine_id) + * { + * fprintf(stderr, "ERROR: Requested rendering engine is absent.\n"); + * exit(-1); + * } + * evas_output_method_set(evas, engine_id); + * @endcode + * + * @param[in] name The name string of an engine + * @return A numeric (opaque) ID for the rendering engine + * + * @ingroup Evas_Output_Method + */ +EAPI int evas_render_method_lookup(const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Lists all the rendering engines compiled into the copy of the Evas library. + * + * @since_tizen 2.3 + * + * + * @remarks Calling this returns a handle (pointer) to an Evas linked + * list. Each node in the linked list has the data pointer be a + * (char *) pointer to the name string of the rendering engine + * available. The strings should never be modified, neither should the + * list be modified. This list should be cleaned up as soon as the + * program no longer needs it using evas_render_method_list_free(). If + * no engines are available from Evas, @c NULL is returned. + * + * @remarks The following is an example: + * @code + * Eina_List *engine_list, *l; + * char *engine_name; + * + * engine_list = evas_render_method_list(); + * if (!engine_list) + * { + * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); + * exit(-1); + * } + * printf("Available Evas Engines:\n"); + * EINA_LIST_FOREACH(engine_list, l, engine_name) + * printf("%s\n", engine_name); + * evas_render_method_list_free(engine_list); + * @endcode + * + * @return A linked list whose data members are C strings of engine names + * + * @ingroup Evas_Output_Method + */ +EAPI Eina_List *evas_render_method_list(void) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Frees the list of engine names. + * + * @since_tizen 2.3 + * + * @remarks When this function is called it frees the engine list passed in + * as @a list. The list should only be a list of engines generated by + * calling evas_render_method_list(). If @a list is NULL, nothing happens. + * + * Example: + * @code + * Eina_List *engine_list, *l; + * char *engine_name; + * + * engine_list = evas_render_method_list(); + * if (!engine_list) + * { + * fprintf(stderr, "ERROR: Evas supports no engines! Exit.\n"); + * exit(-1); + * } + * printf("Available Evas Engines:\n"); + * EINA_LIST_FOREACH(engine_list, l, engine_name) + * printf("%s\n", engine_name); + * evas_render_method_list_free(engine_list); + * @endcode + * + * @param[in] list The Eina_List base pointer for the engine list to be freed + * @ingroup Evas_Output_Method + */ +EAPI void evas_render_method_list_free(Eina_List *list); + +/** + * @brief Sets the output engine for the given evas. + * + * @since_tizen 2.3 + * + * @remarks Once the output engine for an evas is set, any attempt to change it + * is ignored. The value for @a render_method can be found using + * @ref evas_render_method_lookup. + * + * @remarks It is mandatory that you call evas_init() before setting the output method. + * + * @param[in] e The given evas + * @param[in] render_method The numeric engine value to use + * + * @ingroup Evas_Output_Method + */ +EAPI void evas_output_method_set(Evas *e, int render_method) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the number of the output engines used for the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The ID number of the output engine being used \n + * @c 0 is returned if there is an error. + * + * @ingroup Evas_Output_Method + */ +EAPI int evas_output_method_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current render engine info struct from the given evas. + * + * @since_tizen 2.3 + * + * @remarks The returned structure is publicly modifiable. The contents are + * valid until either @ref evas_engine_info_set or @ref evas_render + * are called. + * + * @remarks You do not have to free this structure. + * + * @param[in] e The given evas + * @return A pointer to the Engine Info structure \n + * @c NULL is returned if an engine has not yet been assigned. + * + * @ingroup Evas_Output_Method + */ +EAPI Evas_Engine_Info *evas_engine_info_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Applies the engine settings for the given evas from the given @c + * Evas_Engine_Info structure. + * + @ @since_tizen 2.3 + * + * @remarks To get the Evas_Engine_Info structure to use, call @ref + * evas_engine_info_get. Do not try to obtain a pointer to an + * @c Evas_Engine_Info structure in any other way. + * + * @remarks You need to call this function at least once before you can + * create objects on an evas or render that evas. Some engines allow + * their settings to be changed more than once. + * + * @remarks Once called, the @a info pointer should be considered invalid. + * + * @param[in] e The pointer to the Evas canvas + * @param[in] info The pointer to the Engine Info to use + * @return #EINA_TRUE if the engine setting is applied successfully, \n + * otherwise #EINA_FALSE if an error occurred + * @ingroup Evas_Output_Method + */ +EAPI Eina_Bool evas_engine_info_set(Evas *e, Evas_Engine_Info *info) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Output_Size Output and Viewport Resizing Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions that set and retrieve the output and viewport size of an evas. + * + * @{ + */ + +/** + * @brief Sets the output size of the render engine of the given evas. + * + * @since_tizen 2.3 + * + * @remarks The evas renders to a rectangle of the given size once this + * function is called. The output size is independent of the viewport + * size. The viewport is stretched to fill the given rectangle. + * + * @remarks The units used for @a w and @a h depend on the engine used by the evas. + * + * @param[in] e The given evas + * @param[in] w The width in output units, usually pixels + * @param[in] h The height in output units, usually pixels + * + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_size_set(Evas *e, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the output size of the render engine of the given evas. + * + * @since_tizen 2.3 + * + * @remarks The output size is in the output units for the engine. + * + * @remarks If either @a w or @a h is @c NULL, then it is ignored. If @a e is + * invalid, the returned results are undefined. + * + * @param[in] e The given evas + * @param[out] w The pointer to an integer to store the width in + * @param[out] h The pointer to an integer to store the height in + * + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_size_get(const Evas *e, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the output viewport of the given evas in evas units. + * + * @since_tizen 2.3 + * + * @remarks The output viewport is the area of the evas that is visible to the viewer. + * The viewport is stretched to fit the output target of the evas when + * rendering is performed. + * + * @remarks The coordinate values do not have to map 1-to-1 with the output + * target. However, it is generally advised that it is done for ease of use. + * + * @param[in] e The given evas + * @param[in] x The top-left corner x value of the viewport + * @param[in] y The top-left corner y value of the viewport + * @param[in] w The width of the viewport \n + * Must be greater than @c 0. + * @param[in] h The height of the viewport \n + * Must be greater than @c 0. + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_viewport_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the render engine's output viewport co-ordinates in canvas units. + * + * @since_tizen 2.3 + * + * @remarks Calling this function writes the current canvas output viewport + * size and location values into the variables pointed to by @a x, @a y, + * @a w and @a h. On success, the variables have the output + * location and size values written to them in canvas units. Any of @a x, + * @a y, @a w or @a h that are @c NULL is not written to. If @a e + * is invalid, the results are undefined. + * + * @remarks The following is an example. + * @code + * extern Evas *evas; + * Evas_Coord x, y, width, height; + * + * evas_output_viewport_get(evas, &x, &y, &w, &h); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[out] x The pointer to the x variable to be filled in + * @param[out] y The pointer to the y variable to be filled in + * @param[out] w The pointer to the width variable to be filled in + * @param[out] h The pointer to the height variable to be filled in + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_viewport_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the output framespace size of the render engine of the given evas. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks The framespace size is used in the Wayland engines to denote space where + * the output is not drawn. This is mainly used in ecore_evas to draw borders. + * + * @remarks The units used for @a w and @a h depend on the engine used by the evas. + * + * @param[in] e The given evas + * @param[in] x The left coordinate in output units, usually pixels + * @param[in] y The top coordinate in output units, usually pixels + * @param[in] w The width in output units, usually pixels + * @param[in] h The height in output units, usually pixels + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_framespace_set(Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h); + +/** + * @brief Gets the render engine's output framespace co-ordinates in canvas units. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas Canvas + * @param[out] x The pointer to the x variable to be filled in + * @param[out] y The pointer to the y variable to be filled in + * @param[out] w The pointer to the width variable to be filled in + * @param[out] h The pointer to the height variable to be filled in + * @ingroup Evas_Output_Size + */ +EAPI void evas_output_framespace_get(const Evas *e, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h); + +/** + * @} + */ + +/** + * @defgroup Evas_Coord_Mapping_Group Coordinate Mapping Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions that are used to map coordinates from the canvas to the + * screen or the screen to the canvas. + * + * @{ + */ + +/** + * @brief Converts or scales an ouput screen co-ordinate into canvas co-ordinates. + * + * @details This function takes in a horizontal co-ordinate as the @a x + * parameter and converts it into canvas units, accounting for output + * size, viewport size and location, returning it as the function + * return value. If @a e is invalid, the results are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * extern int screen_x; + * Evas_Coord canvas_x; + * + * canvas_x = evas_coord_screen_x_to_world(evas, screen_x); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[in] x The screen or output x co-ordinate + * @return The screen co-ordinate translated to canvas unit co-ordinates + * @ingroup Evas_Coord_Mapping_Group + */ +EAPI Evas_Coord evas_coord_screen_x_to_world(const Evas *e, int x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Converts or scales an ouput screen co-ordinate into canvas co-ordinates. + * + * @details This function takes in a vertical co-ordinate as the @a y parameter + * and converts it into canvas units, accounting for output size, + * viewport size and location, returning it as the function return + * value. If @a e is invalid, the results are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * extern int screen_y; + * Evas_Coord canvas_y; + * + * canvas_y = evas_coord_screen_y_to_world(evas, screen_y); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[in] y The screen or output y co-ordinate + * @return The screen co-ordinate translated to canvas unit co-ordinates + * @ingroup Evas_Coord_Mapping_Group + */ +EAPI Evas_Coord evas_coord_screen_y_to_world(const Evas *e, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Converts or scales a canvas co-ordinate into output screen co-ordinates. + * + * @details This function takes in a horizontal co-ordinate as the @a x + * parameter and converts it into output units, accounting for output + * size, viewport size and location, returning it as the function + * return value. If @a e is invalid, the results are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int screen_x; + * extern Evas_Coord canvas_x; + * + * screen_x = evas_coord_world_x_to_screen(evas, canvas_x); + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @param[in] x The canvas x co-ordinate + * @return The output or screen co-ordinate translated to output co-ordinates + * @ingroup Evas_Coord_Mapping_Group + */ +EAPI int evas_coord_world_x_to_screen(const Evas *e, Evas_Coord x) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Converts or scales a canvas co-ordinate into output screen co-ordinates. + * + * @details This function takes in a vertical co-ordinate as the @a x parameter + * and converts it into output units, accounting for output size, + * viewport size and location, returning it as the function return + * value. If @a e is invalid, the results are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int screen_y; + * extern Evas_Coord canvas_y; + * + * screen_y = evas_coord_world_y_to_screen(evas, canvas_y); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[in] y The canvas y co-ordinate + * @return The output or screen co-ordinate translated to output co-ordinates + * @ingroup Evas_Coord_Mapping_Group + */ +EAPI int evas_coord_world_y_to_screen(const Evas *e, Evas_Coord y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Pointer_Group Pointer (Mouse) Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions that deal with the status of the pointer (mouse cursor). + * + * @{ + */ + +/** + * @brief Gets the current known pointer co-ordinates. + * + * @details This function returns the current known screen or output co-ordinates + * of the mouse pointer and sets the contents of the integers pointed + * to by @a x and @a y to contain these co-ordinates. If @a e is not a + * valid canvas the results of this function are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int mouse_x, mouse_y; + * + * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y); + * printf("Mouse is at screen position %i, %i\n", mouse_x, mouse_y); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[out] x The pointer to an integer to be filled in + * @param[out] y The pointer to an integer to be filled in + * @ingroup Evas_Pointer_Group + */ +EAPI void evas_pointer_output_xy_get(const Evas *e, int *x, int *y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current known pointer co-ordinates. + * + * @details This function returns the current known canvas unit co-ordinates of + * the mouse pointer and sets the contents of the Evas_Coords pointed + * to by @a x and @a y to contain these co-ordinates. If @a e is not a + * valid canvas the results of this function are undefined. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * Evas_Coord mouse_x, mouse_y; + * + * evas_pointer_output_xy_get(evas, &mouse_x, &mouse_y); + * printf("Mouse is at canvas position %f, %f\n", mouse_x, mouse_y); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @param[out] x The pointer to a Evas_Coord to be filled in + * @param[out] y The pointer to a Evas_Coord to be filled in + * @ingroup Evas_Pointer_Group + */ +EAPI void evas_pointer_canvas_xy_get(const Evas *e, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets a bitmask with the mouse buttons currently pressed, set to @c 1. + * + * @since_tizen 2.3 + * + * @remarks This function returns a 32-bit integer with the + * appropriate bits set to @c 1 that correspond to a mouse button being + * depressed. This limits Evas to mouse devices with a maximum of 32 + * buttons, but that is generally in excess of any host system's + * pointing device abilities. + * + * @remarks The least significant bit corresponds to the first mouse button + * (button 1) and the most significant bit corresponds to the last + * mouse button (button 32). + * + * @remarks If @a e is not a valid canvas, the return value is undefined. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int button_mask, i; + * + * button_mask = evas_pointer_button_down_mask_get(evas); + * printf("Buttons currently pressed:\n"); + * for (i = 0; i < 32; i++) + * { + * if ((button_mask & (1 << i)) != 0) printf("Button %i\n", i + 1); + * } + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @return A bitmask of the currently depressed buttons on the canvas + * @ingroup Evas_Pointer_Group + */ +EAPI int evas_pointer_button_down_mask_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the mouse pointer is logically inside the canvas. + * + * @since_tizen 2.3 + * + * @remarks When this function is called it returns a value of either @c 0 or + * @c 1. + * + * @remarks A return value of @c 1 indicates the mouse is logically inside the + * canvas, and @c 0 implies it is logically outside the canvas. + * + * @remarks A canvas begins with the mouse being assumed outside (0). + * + * @remarks If @a e is not a valid canvas, the return value is undefined. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * + * if (evas_pointer_inside_get(evas)) printf("Mouse is in!\n"); + * else printf("Mouse is out!\n"); + * @endcode + * + * @param[in] e The pointer to the Evas Canvas + * @return #EINA_TRUE if the mouse is inside the canvas, + * otherwise #EINA_FALSE + * @ingroup Evas_Pointer_Group + */ +EAPI Eina_Bool evas_pointer_inside_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Canvas_Events Canvas Events + * @ingroup Evas_Canvas + * + * @brief This group provides functions relating to canvas events, which are mainly reports on + * its internal states changing such as an object getting focused, the rendering being updated, + * and so on. + * + * @{ + */ + +/** + * @brief Adds or registers a callback function to a given canvas event. + * + * @details This function adds a function callback to the canvas @a e when the + * event of type @a type occurs on it. The function pointer is @a func. + * + * @since_tizen 2.3 + * + * @remarks In the event of a memory allocation error during the addition of + * the callback to the canvas, evas_alloc_error() should be used to + * determine the nature of the error, if any, and the program should + * sensibly try and recover. + * + * @remarks A callback function must have the ::Evas_Event_Cb prototype + * definition. The first parameter (@a data) in this definition has + * the same value passed to evas_event_callback_add() as the @a data + * parameter, at runtime. The second parameter @a e is the canvas + * pointer on which the event occurred. The third parameter @a + * event_info is a pointer to a data structure that may or may not be + * passed to the callback, depending on the event type that triggered + * the callback. This is so because some events do not carry extra + * context with them, but others do. + * + * @remarks The valid event types @a type to trigger the function are + * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST, + * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT, + * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and + * #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of + * event that triggers the callback to be called. Only the last + * two event types listed here provide useful event information + * data -- a pointer to the recently focused Evas object. For the + * others the @a event_info pointer is going to be @c NULL. + * + * @remarks The canvas flushes its rendering pipeline + * (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb + * routine takes place: it has to redraw that image at a different + * size. Also, the callback on an object being focused comes just + * after you focus it explicitly, on code. + * + * @remarks Be careful not to add the same callback multiple times, if + * that is not what you want, because Evas does not check if a callback + * existed before exactly as the one being registered (and thus, call + * it more than once on the event, in this case). This would make + * sense if you passed different functions and/or callback data, only. + * + * @param[in] e The canvas to attach a callback to + * @param[in] type The type of event that triggers the callback + * @param[in] func The (callback) function to be called when the event is triggered + * @param[in] data The data pointer to be passed to @a func + */ +EAPI void evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Adds or registers a callback function to a given canvas event with a + * non-default priority set. Except for the priority field, it is exactly the + * same as @ref evas_event_callback_add + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to attach a callback to + * @param[in] type The type of event that triggers the callback + * @param[in] priority The priority of the callback, lower values called first + * @param[in] func The (callback) function to be called when the event is triggered + * @param[in] data The data pointer to be passed to @a func + * + * @see evas_event_callback_add + */ +EAPI void evas_event_callback_priority_add(Evas *e, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4); + +/** + * @brief Deletes a callback function from the canvas. + * + * @details This function removes the most recently added callback from the + * canvas @a e which is triggered by the event type @a type and is + * calling the function @a func when triggered. If the removal is + * successful it also returns the data pointer that is passed to + * evas_event_callback_add() when the callback is added to the + * canvas. If not successful @c NULL is returned. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas *e; + * void *my_data; + * void focus_in_callback(void *data, Evas *e, void *event_info); + * + * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback); + * @endcode + * + * @param[in] e The canvas to remove a callback from + * @param[in] type The type of event that is triggering the callback + * @param[in] func The function that is to be called when the event is triggered + * @return The data pointer that is to be passed to the callback + */ +EAPI void *evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Deletes (unregisters) a callback function registered to a given canvas event. + * + * @details This function removes <b>the first</b> added callback from the + * canvas @a e matching the event type @a type, the registered + * function pointer @a func and the callback data pointer @a data. If + * the removal is successful it also returns the data pointer that + * is passed to evas_event_callback_add() (that is the same as + * the parameter) when the callback(s) is (were) added to the + * canvas. If not successful @c NULL is returned. A common use + * would be to remove an exact match of a callback. + * + * @since_tizen 2.3 + * + * @remarks For deleting canvas events callbacks filtering by just + * type and function pointer, use evas_event_callback_del(). + * + * @param[in] e The Canvas to remove an event callback from + * @param[in] type The type of event that triggers the callback + * @param[in] func The function that is to be called when the event is triggered + * @param[in] data The data pointer that is to be passed to the callback + * @return The data pointer that is to be passed to the callback + */ +EAPI void *evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Pushes a callback on the post-event callback stack. + * + * @since_tizen 2.3 + * + * @remarks Evas has a stack of callbacks that get called after all the callbacks for + * an event have triggered (all the objects it triggers on and all the callbacks + * in each object triggered). When all these have been called, the stack is + * unwound from most recently to least recently pushed item and removed from the + * stack calling the callback set for it. + * + * @remarks This is intended for doing reverse logic-like processing, for example - when a + * child object that happens to get the event later is meant to be able to + * "steal" functions from a parent and when this stack is unwound, have its + * function called first, thus being able to set flags, or return @c 0 from the + * post-callback, that stops all other post-callbacks in the current stack from + * being called (thus basically allowing a child to take control, if the event + * callback prepares information ready for taking action, but the post callback + * actually does the action). + * + * @param[in] e The canvas to push the callback on + * @param[in] func The function that to be called when the stack is unwound + * @param[in] data The data pointer to be passed to the callback + */ +EAPI void evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** + * @brief Removes a callback from the post-event callback stack. + * + * @details This removes a callback from the stack added with + * evas_post_event_callback_push(). The first instance of the function in + * the callback stack is removed from being executed when the stack is + * unwound. Further instances may still be run on unwind. + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to push the callback on + * @param[in] func The function that to be called when the stack is unwound + */ +EAPI void evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func); + +/** + * @brief Removes a callback from the post-event callback stack. + * + * @details This removes a callback from the stack added with + * evas_post_event_callback_push(). The first instance of the function and data + * in the callback stack is removed from being executed when the stack is + * unwound. Further instances may still be run on unwind. + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to push the callback on + * @param[in] func The function that to be called when the stack is unwound + * @param[in] data The data pointer to be passed to the callback + */ +EAPI void evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** + * @} + */ + +/** + * @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions + * @ingroup Evas_Canvas_Events + * + * @brief This group provides functions that deal with the freezing of input event processing of + * an Evas canvas. + * + * @remarks There might be scenarios during a graphical user interface + * program's use when the developer wishes the users would not be able + * to deliver input events to this application. It may, for example, + * be the time for it to populate a view or to change some + * layout. Assuming proper behavior with user interaction during this + * exact time would be hard, as things are in a changing state. The + * programmer can then tell the canvas to ignore input events, + * bringing it back to normal behavior when he or she wants. + * + * @remarks Most of the time, the freezing events is used like this: + * @code + * evas_event_freeze(my_evas_canvas); + * function_that_does_work_which_cant_be_interrupted_by_events(); + * evas_event_thaw(my_evas_canvas); + * @endcode + * + * @{ + */ + +/** + * @brief Sets the default set of flags an event begins with. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks Events in evas can have an event_flags member. This starts out with + * an initial value (no flags). This lets you set the default flags that + * an event begins with to be @a flags. + * + * @param[in] e The canvas to set the default event flags of + * @param[in] flags The default flags to use + */ +EAPI void evas_event_default_flags_set(Evas *e, Evas_Event_Flags flags) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the default set of flags an event begins with. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks This gets the default event flags with which the events are produced. + * + * @param[in] e The canvas to get the default event flags from + * @return The default event flags for that canvas + * + * @see evas_event_default_flags_set() + */ +EAPI Evas_Event_Flags evas_event_default_flags_get(const Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Freezes all input events processing. + * + * @since_tizen 2.3 + * + * @remarks This function indicates to Evas that the canvas @a e is to have + * all input event processing frozen until a matching + * evas_event_thaw() function is called on the same canvas. All events + * of this kind during the freeze get @b discarded. Every freeze + * call must be matched by a thaw call in order to completely thaw out + * a canvas (i.e. these calls may be nested). The most common use is + * when you do not want the user to interact with your user interface + * when you are populating a view or changing the layout. + * + * @param[in] e The canvas to freeze input events processing on + */ +EAPI void evas_event_freeze(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Thaws a canvas out after freezing (for input events). + * + * @since_tizen 2.3 + * + * @remarks This thaws out a canvas after a matching evas_event_freeze() + * call. If this call completely thaws out a canvas, i.e., there is no + * other unbalanced call to evas_event_freeze(), events start to + * be processed again, but any "missed" events are @b not be evaluated. + * + * @param[in] e The canvas to thaw out + * + * @see evas_event_freeze() for an example. + */ +EAPI void evas_event_thaw(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the freeze count on input events of a given canvas. + * + * @since_tizen 2.3 + * + * @remarks This returns the number of times the canvas has been told to freeze + * input events. It is possible to call evas_event_freeze() multiple + * times, and these must be matched by evas_event_thaw() calls. This + * call allows the program to discover just how many times things have + * been frozen in case it may want to break out of a deep freeze state + * where the count is high. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * + * while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas); + * @endcode + * + * @param[in] e The canvas to fetch the freeze count from + * @return The freeze count + */ +EAPI int evas_event_freeze_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Re-evaluates the state of objects and call callbacks after thaw of a canvas. + * + * @since_tizen 2.3 + * + * @remarks This is normally called after evas_event_thaw() to re-evaluate mouse + * containment and other states and thus also call callbacks for mouse in and + * out on new objects if the state change demands it. + * + * @param[in] e The canvas to evaluate after a thaw + */ +EAPI void evas_event_thaw_eval(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions + * @ingroup Evas_Canvas_Events + * + * @brief This group provides functions to tell Evas that input events happened and should be processed. + * + * @remarks Most of the time these functions are @b not what you are looking for. + * These functions should only be used if you are not working with ecore evas(or + * another input handling system). If you are not using ecore evas, please + * consider using it, as in most situation it makes life a lot easier. + * + * @remarks As explained in @ref evas_main_intro_not_evas, Evas does not know how to poll + * for input events, so you should do it and then feed such + * events to the canvas to be processed. This is only required if + * operating Evas directly. Modules such as Ecore_Evas do that for you. + * + * @{ + */ + +/** + * @internal + * @since 1.8 + */ +EAPI Evas_Device *evas_device_new(Evas *e); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_free(Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_push(Evas *e, Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_pop(Evas *e); + +/** + * @internal + * @since 1.8 + */ +EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_name_set(Evas_Device *dev, const char *name); + +/** + * @internal + * @since 1.8 + */ +EAPI const char *evas_device_name_get(const Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_description_set(Evas_Device *dev, const char *desc); + +/** + * @internal + * @since 1.8 + */ +EAPI const char *evas_device_description_get(const Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent); + +/** + * @internal + * @since 1.8 + */ +EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas); + +/** + * @internal + * @since 1.8 + */ +EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev); + +/** + * @internal + * @since 1.8 + */ +EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src); + +/** + * @internal + * @since 1.8 + */ +EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev); + +/** + * @internal + * @brief Gets the number of mouse or multi presses currently active. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] e The given canvas pointer + * @return The number of presses, \n + * otherwise @c 0 if none active + * + */ +EAPI int evas_event_down_count_get(const Evas *e) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse down event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function sets some evas properties that is necessary when + * the mouse button is pressed. It prepares information to be treated + * by the callback function. + * + * @param[in] e The given canvas pointer + * @param[in] b The button number + * @param[in] flags The evas button flags + * @param[in] timestamp The timestamp of the mouse down event + * @param[in] data The data for canvas + */ +EAPI void evas_event_feed_mouse_down(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse up event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function sets some evas properties that is necessary when + * the mouse button is released. It prepares information to be treated + * by the callback function. + * + * @param[in] e The given canvas pointer + * @param[in] b The button number + * @param[in] flags The evas button flags + * @param[in] timestamp The timestamp of the mouse up event + * @param[in] data The data for canvas + */ +EAPI void evas_event_feed_mouse_up(Evas *e, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse move event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function sets some evas properties that is necessary when + * the mouse is moved from its last position. It prepares information + * to be treated by the callback function. + * + * @param[in] e The given canvas pointer + * @param[in] x The horizontal position of the mouse pointer + * @param[in] y The vertical position of the mouse pointer + * @param[in] timestamp The timestamp of the mouse up event + * @param[in] data The data for canvas + */ +EAPI void evas_event_feed_mouse_move(Evas *e, int x, int y, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse in event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function sets some evas properties that is necessary when + * the mouse in event happens. It prepares information to be treated + * by the callback function. + * + * @param[in] e The given canvas pointer + * @param[in] timestamp The timestamp of the mouse up event + * @param[in] data The data for canvas + */ +EAPI void evas_event_feed_mouse_in(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse out event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function sets some evas properties that is necessary when + * the mouse out event happens. It prepares information to be treated + * by the callback function. + * + * @param[in] e The given canvas pointer + * @param[in] timestamp The timestamp of the mouse up event + * @param[in] data The data for canvas + */ +EAPI void evas_event_feed_mouse_out(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); +EAPI void evas_event_feed_multi_down(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data); +EAPI void evas_event_feed_multi_up(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data); +EAPI void evas_event_feed_multi_move(Evas *e, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, unsigned int timestamp, const void *data); + +/** + * @internal + * @brief Feeds the mouse cancel event for the given canvas @a e. + * + * @remarks This function calls evas_event_feed_mouse_up() when a + * mouse cancel event happens. + * + * @param e The given canvas pointer + * @param timestamp The timestamp of the mouse up event + * @param data The data for canvas + */ +EAPI void evas_event_feed_mouse_cancel(Evas *e, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the mouse wheel event for the given canvas @a e. + * + * @remarks This function sets some evas properties that is necessary when + * the mouse wheel is scrolled up or down. It prepares information to + * be treated by the callback function. + * + * @param e The given canvas pointer + * @param direction The wheel mouse direction + * @param z The amount of up or down mouse wheel scrolling + * @param timestamp The timestamp of the mouse up event + * @param data The data for canvas + */ +EAPI void evas_event_feed_mouse_wheel(Evas *e, int direction, int z, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the key down event for the given canvas @a e. + * + * @remarks This function sets some evas properties that is necessary when + * a key is pressed. It prepares information to be treated by the + * callback function. + * + * @param e The canvas to thaw out + * @param keyname The name of the key + * @param key The key pressed + * @param string The UTF8 string + * @param compose The compose string + * @param timestamp The timestamp of the mouse up event + * @param data The data for canvas + */ +EAPI void evas_event_feed_key_down(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the key up event feed for the given canvas @a e. + * + * @remarks This function sets some evas properties that is necessary when + * a key is released. It prepares information to be treated by the + * callback function. + * + * @param e The canvas to thaw out + * @param keyname The name of the key + * @param key The key released + * @param string The UTF8 string + * @param compose The compose string + * @param timestamp The timestamp of the mouse up event + * @param data The data for canvas + */ +EAPI void evas_event_feed_key_up(Evas *e, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Feeds the hold event for the given canvas @a e. + * + * @remarks This function makes the object to stop sending events. + * + * @param e The given canvas pointer + * @param hold The hold + * @param timestamp The timestamp of the mouse up event + * @param data The data for canvas + * + */ +EAPI void evas_event_feed_hold(Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Re-feeds the event for the given canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This function re-feeds the event pointed by event_copy. + * + * @remarks This function call evas_event_feed_* functions, so it can + * cause havoc if not used wisely. Please use it responsibly. + * + * @param[in] e The given canvas pointer + * @param[in] event_copy The event to re-feed + * @param[in] event_type The event type + */ +EAPI void evas_event_refeed_event(Evas *e, void *event_copy, Evas_Callback_Type event_type) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Gets a list of Evas objects lying over a given position in a canvas. + * + * @since_tizen 2.3 + * + * @remarks This function traverses all the layers of the given canvas, + * from top to bottom, querying for objects with areas covering the + * given position. It enters the smart objects. + * + * @param[in] eo_e A handle to the canvas + * @param[in] stop The Evas object at which to stop searching + * @param[in] x The horizontal coordinate of the position + * @param[in] y The vertical coordinate of the position + */ +EAPI Eina_List *evas_tree_objects_at_xy_get(Evas *eo_e, Evas_Object *stop, int x, int y) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Image_Group Image Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions that deals with images at canvas level. + * + * @{ + */ + +/** + * @brief Flushes the image cache of the canvas. + * + * @details This function flushes image cache of canvas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas pointer + * + */ +EAPI void evas_image_cache_flush(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Reloads the image cache. + * + * @details This function reloads the image cache of canvas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas pointer + * + */ +EAPI void evas_image_cache_reload(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the image cache. + * + * @details This function sets the image cache of canvas in bytes. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas pointer + * @param[in] size The cache size + */ +EAPI void evas_image_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the image cache + * + * @details This function returns the image cache size of canvas in bytes. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas pointer + * @return The image cache size of canvas in bytes + */ +EAPI int evas_image_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the maximum image size evas can possibly handle. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks This function returns the largest image or surface size that evas can handle + * in pixels, and if there is one, returns #EINA_TRUE. It returns + * #EINA_FALSE if no extra constraint on maximum image size exists. You still + * should check the return values of @a maxw and @a maxh as there may still be + * a limit, just a much higher one. + * + * @param[in] e The given evas pointer + * @param[out] maxw The pointer to hold the return value in pixels of the maximum width + * @param[out] maxh The pointer to hold the return value in pixels of the maximum height + * @return #EINA_TRUE if there is a maximum size that evas can handle, \n + * otherwise #EINA_FALSE if there is no maximum image size constraint + */ +EAPI Eina_Bool evas_image_max_size_get(const Evas *e, int *maxw, int *maxh) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Font_Group Font Functions + * + * @brief This group provides functions that deals with fonts. + * + * @ingroup Evas_Canvas + * + * @{ + */ + +/** + * @brief Changes the font hinting for the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @param[in] hinting The hinting to use \n + * Valid values are #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE. + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the font hinting used by the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas to query + * @return The hinting in use \n + * Valid return values are #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE. + * @ingroup Evas_Font_Group + */ +EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the font hinting is supported by the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas to query + * @param[in] hinting The hinting to use \n + * Valid values are #EVAS_FONT_HINTING_NONE, + * #EVAS_FONT_HINTING_AUTO, and #EVAS_FONT_HINTING_BYTECODE. + * @return #EINA_TRUE if it is supported, \n + * otherwise #EINA_FALSE + * @ingroup Evas_Font_Group + */ +EAPI Eina_Bool evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Forces the given evas and associated engine to flush its font cache. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas to flush font cache + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_cache_flush(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Changes the size of font cache of the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas to flush font cache + * @param[in] size The size in bytes + * + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_cache_set(Evas *e, int size) EINA_ARG_NONNULL(1); + +/** + * @brief Changes the size of font cache of the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas to flush font cache + * @return The size in bytes + * + * @ingroup Evas_Font_Group + */ +EAPI int evas_font_cache_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the list of available font descriptions known or found by this evas. + * + * @since_tizen 2.3 + * + * @remarks The list depends on Evas compile time configuration, such as + * fontconfig support, and the paths provided at runtime as explained + * in @ref Evas_Font_Path_Group. + * + * @param[in] e The evas instance to query + * @return The newly allocated list of strings \n + * Do not change the strings. Be sure to call evas_font_available_list_free() + * after you are done. + * + * @ingroup Evas_Font_Group + */ +EAPI Eina_List *evas_font_available_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Frees the list of font descriptions returned by evas_font_dir_available_list(). + * + * @since_tizen 2.3 + * + * @param[in] e The evas instance that returned such list + * @param[in] available The list returned by evas_font_dir_available_list() + * + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1); + +/** + * @brief Reinitializes Evas by orphaning existing font data until it is unreferenced and + * starts with a fresh font configuration read from any appropriate + * system resources for all newly loaded and created fonts. + * + * @since_tizen 2.3 + * + * @ingroup Evas_Font_Group + */ +EAPI void evas_font_reinit(void); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Font_Path_Group Font Path Functions + * + * @brief This group provides functions that edit the paths being used to load fonts. + * + * @ingroup Evas_Font_Group + * + * @{ + */ + +/** + * @brief Removes all font paths loaded into memory for the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_clear(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Appends a font path to the list of font paths used by the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @param[in] path The new font path + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_append(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Prepends a font path to the list of font paths used by the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @param[in] path The new font path + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_prepend(Evas *e, const char *path) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the list of font paths used by the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The list of font paths used + * @ingroup Evas_Font_Path_Group + */ +EAPI const Eina_List *evas_font_path_list(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Removes all font paths loaded into memory by evas_font_path_app_* APIs for the application. + * @since 1.9 + * + * @since_tizen 2.3 + * + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_global_clear(void); + +/** + * @brief Appends a font path to the list of font paths used by the application. + * @since 1.9 + * + * @since_tizen 2.3 + * + * @param[in] path The new font path + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_global_append(const char *path) EINA_ARG_NONNULL(1); + +/** + * @brief Prepends a font path to the list of font paths used by the application. + * @since 1.9 + * + * @since_tizen 2.3 + * + * @param[in] path The new font path + * @ingroup Evas_Font_Path_Group + */ +EAPI void evas_font_path_global_prepend(const char *path) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the list of font paths used by the application. + * @since 1.9 + * + * @since_tizen 2.3 + * + * @return The list of font paths used + * @ingroup Evas_Font_Path_Group + */ +EAPI const Eina_List *evas_font_path_global_list(void) EINA_WARN_UNUSED_RESULT; + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Group Generic Object Functions + @ingroup Evas + * + * @brief This group provides functions that manipulate generic Evas objects. + * + * @remarks All Evas displaying units are Evas objects. You can handle them all by + * means of the handle ::Evas_Object. Besides Evas treats their + * objects equally, they have @b types, which define their specific + * behavior (and individual API). + * + * @remarks Evas comes with a set of built-in object types: + * - rectangle, + * - line, + * - polygon, + * - text, + * - textblock, and + * - image. + * + * @remarks These functions apply to @b any Evas object, whichever type that + * may have. + * + * @remarks The built-in types which are most used are rectangles, text + * and images. In fact, with these ones one can create 2D interfaces + * of arbitrary complexity and EFL makes it easy. + */ + +/** + * @defgroup Evas_Object_Group_Basic Basic Object Manipulation + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for basic object manipulation. + * + * @remarks Almost every evas object created has some generic function used to + * manipulate it. That is because there are a number of basic actions to be done + * to objects that are irrespective of the object's type like: + * @li Showing/Hiding + * @li Setting(and getting) geometry + * @li Bring up or down a layer + * @li Color management + * @li Handling focus + * @li Clipping + * @li Reference counting + * + * @{ + */ + +/** + * @brief Clips one object to another. + * + * @details This function clips the object @a obj to the area occupied by + * the object @a clip. This means the object @a obj is only + * visible within the area occupied by the clipping object (@a clip). + * + * @since_tizen 2.3 + * + * @remarks The color of the object being clipped is multiplied by the + * color of the clipping one, so the resulting color for the former + * is <code>RESULT = (OBJ * CLIP) / (255 * 255)</code>, per color + * element (red, green, blue and alpha). + * + * @remarks Clipping is recursive, so clipping objects may be clipped by + * others, and their color is in term multiplied. You may @b not + * set up circular clipping lists (i.e. object 1 clips object 2, which + * clips object 1): the behavior of Evas is undefined in this case. + * + * @remarks Objects which do not clip others are visible in the canvas as + * normal; <b>those that clip one or more objects become invisible + * themselves</b>, only affecting what they clip. If an object ceases + * to have other objects being clipped by it, it becomes visible + * again. + * + * @remarks The visibility of an object affects the objects that are clipped by + * it, so if the object clipping others is not shown (as in + * evas_object_show()), the objects clipped by it is not shown + * either. + * + * @remarks If @a obj is being clipped by another object when this function is + * called, it gets implicitly removed from the old clipper's domain + * and is made now to be clipped by its new clipper. + * + * @remarks The following figure illustrates some clipping in Evas: + * + * @image html clipping.png + * @image rtf clipping.png + * @image latex clipping.eps + * + * @remarks At the moment the <b>only objects that can validly be used to + * clip other objects are rectangle objects</b>. All other object + * types are invalid and the result of using them is undefined. The + * clip object @a clip must be a valid object, but can also be @c + * NULL, in which case the effect of this function is the same as + * calling evas_object_clip_unset() on the @a obj object. + * + * @param[in] obj The object to be clipped + * @param[in] clip The object to clip @a obj by + */ +EAPI void evas_object_clip_set(Evas_Object *obj, Evas_Object *clip) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the object clipping @a obj (if any). + * + * @details This function returns the object clipping @a obj. If @a obj is + * not being clipped at all, @c NULL is returned. The object @a obj + * must be a valid ::Evas_Object. + * + * @since_tizen 2.3 + * + * @remarks See also evas_object_clip_set(), evas_object_clip_unset() and + * evas_object_clipees_get(). + * + * @param[in] obj The object to get the clipper from + * @return The object clipping @a obj \n + * If @a obj object is not being clipped, @c NULL is returned. + */ +EAPI Evas_Object *evas_object_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Disables or ceases clipping on a clipped @a obj object. + * + * @details This function disables clipping for the object @a obj, if it is + * already clipped, i.e., its visibility and color get detached from + * the previous clipper. If it is not already clipped, this has no effect. The object + * @a obj must be a valid ::Evas_Object. + * + * @since_tizen 2.3 + * + * @remarks See also evas_object_clip_set() (for an example), + * evas_object_clipees_get() and evas_object_clip_get(). + * + * @param[in] obj The object to cease clipping on + */ +EAPI void evas_object_clip_unset(Evas_Object *obj); + +/** + * @brief Gets a list of objects currently clipped by @a obj. + * + * @details This returns the internal list handle that contains all objects + * clipped by the object @a obj. If none are clipped by it, the call + * returns @c NULL. This list is only valid until the clip list is + * changed and should be fetched again with another call to + * evas_object_clipees_get() if any objects being clipped by this + * object are unclipped, clipped by a new object, deleted or get the + * clipper deleted. These operations invalidate the list + * returned, so it should not be used anymore after that point. Any + * use of the list after this may have undefined results, possibly + * leading to crashes. The object @a obj must be a valid + * ::Evas_Object. + * + * @since_tizen 2.3 + * + * @remarks See also evas_object_clip_set(), evas_object_clip_unset() and + * evas_object_clip_get(). + * + * @remarks The following is an example: + * @code + * extern Evas_Object *obj; + * Evas_Object *clipper; + * + * clipper = evas_object_clip_get(obj); + * if (clipper) + * { + * Eina_List *clippees, *l; + * Evas_Object *obj_tmp; + * + * clippees = evas_object_clipees_get(clipper); + * printf("Clipper clips %i objects\n", eina_list_count(clippees)); + * EINA_LIST_FOREACH(clippees, l, obj_tmp) + * evas_object_show(obj_tmp); + * } + * @endcode + * + * @param[in] obj The object to get a list of clippees from + * @return The list of objects being clipped by @a obj + */ +EAPI const Eina_List *evas_object_clipees_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets or unsets a given object as the currently focused one on its canvas. + * + * @since_tizen 2.3 + * + * @remarks Changing focus only affects where (key) input events go. There can + * be only one object focused at any time. If @a focus is #EINA_TRUE, + * @a obj is set as the currently focused object and it + * receives all keyboard events that are not exclusive key grabs on + * other objects. + * + * @param[in] obj The object to be focused or unfocused + * @param[in] focus #EINA_TRUE to set it as focused, \n + * otherwise #EINA_FALSE to take away the focus from it + * + * @see evas_object_focus_get + * @see evas_focus_get + * @see evas_object_key_grab + * @see evas_object_key_ungrab + */ +EAPI void evas_object_focus_set(Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object has the focus. + * + * @since_tizen 2.3 + * + * @remarks If the passed object is the currently focused one, #EINA_TRUE is + * returned. #EINA_FALSE is returned, otherwise. + * + * @param[in] obj The object to retrieve focus information from + * @return #EINA_TRUE if the object has the focus, \n + * otherwise #EINA_FALSE + * + * @see evas_object_focus_set + * @see evas_focus_get + * @see evas_object_key_grab + * @see evas_object_key_ungrab + */ +EAPI Eina_Bool evas_object_focus_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the layer of its canvas that the given object is part of. + * + * @since_tizen 2.3 + * + * @remarks If you do not use this function, you are dealing with a @b unique + * layer of objects, the default one. Additional layers are handy when + * you do not want a set of objects to interfere with another set with + * regard to @b stacking. Two layers are completely disjoint in that matter. + * + * @remarks This is a low-level function, which you would be using when something + * should be always on top, for example. + * + * @remarks Be careful, it does not make sense to change the layer of the children of + * smart objects. Smart objects have a layer of their own, + * which should contain all their children objects. + * + * @param[in] obj The given Evas object + * @param[in] l The number of the layer to place the object on \n + * This must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX. + * + * @see evas_object_layer_get() + */ +EAPI void evas_object_layer_set(Evas_Object *obj, short l) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the layer of its canvas that the given object is part of. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object to query the layer from + * @return The number of its layer + * + * @see evas_object_layer_set() + */ +EAPI short evas_object_layer_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the name of the given Evas object to the given name. + * + * @since_tizen 2.3 + * + * @remarks There might be occasions where you would like to name your objects. + * + * @param[in] obj The given object + * @param[in] name The given name + */ +EAPI void evas_object_name_set(Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the name of the given Evas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given object + * @return The name of the object, \n + * otherwise @c NULL if no name has been given to it + */ +EAPI const char *evas_object_name_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Increments object reference count to defer its deletion. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks This increments the reference count of an object, which if greater + * than @c 0 defers deletion by evas_object_del() until all + * references are released back (counter back to @c 0). References cannot + * go below @c 0 and unreferencing past that results in the reference + * count being limited to @c 0. References are limited to <c>2^32 - 1</c> + * for an object. Referencing it more than this results in it + * being limited to this value. + * + * @remarks This is a <b>very simple</b> reference counting mechanism. For + * instance, Evas is not ready to check for pending references on a + * canvas deletion, or things like that. This is useful on scenarios + * where, inside a code block, callbacks exist which would possibly + * delete an object that you are operating on afterwards. Then, you would + * evas_object_ref() it on the beginning of the block and + * evas_object_unref() it on the end. It would then be deleted at this + * point, if it should be. + * + * @remarks The following is an example: + * @code + * evas_object_ref(obj); + * + * // action here... + * evas_object_smart_callback_call(obj, SIG_SELECTED, NULL); + * // more action here... + * evas_object_unref(obj); + * @endcode + * + * @param[in] obj The given Evas object to reference + * + * @see evas_object_unref() + * @see evas_object_del() + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_ref(Evas_Object *obj); + +/** + * @brief Decrements object reference count. + * + * @details This decrements the reference count of an object. If the object has + * had evas_object_del() called on it while references were more than + * @c 0, it is deleted at the time this function is called and puts + * the counter back to @c 0. See evas_object_ref() for more information. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object to unreference + * + * @see evas_object_ref() (for an example) + * @see evas_object_del() + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_unref(Evas_Object *obj); + +/** + * @brief Gets the object reference count. + * + * @details This gets the reference count for an object (normally @c 0 until it is + * referenced). Values of @c 1 or greater mean that someone is holding a + * reference to this object that needs to be unreffed before it can be + * deleted. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object to query + * @return The object reference count + * + * @see evas_object_ref() + * @see evas_object_unref() + * @see evas_object_del() + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI int evas_object_ref_get(const Evas_Object *obj); + +/** + * @brief Marks the given Evas object for deletion (when Evas frees its memory). + * + * @details This call marks @a obj for deletion, which takes place + * whenever it has no more references to it (see evas_object_ref() and + * evas_object_unref()). + * + * @since_tizen 2.3 + * + * @remarks At actual deletion time, which may or may not be just after this + * call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks are + * called. If the object currently had the focus, its + * ::EVAS_CALLBACK_FOCUS_OUT callback is also called. + * + * @param[in] obj The given Evas object + * + * @see evas_object_ref() + * @see evas_object_unref() + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_del(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the given Evas object to the given location inside its canvas' viewport. + * + * @since_tizen 2.3 + * + * @remarks Besides being moved, the object's ::EVAS_CALLBACK_MOVE callback is called. + * + * @remarks Naturally, newly created objects are placed at the canvas' origin: <code>0, 0</code>. + * + * @param[in] obj The given Evas object + * @param[in] x The X position to move the object to, in canvas units + * @param[in] y The Y position to move the object to, in canvas units + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Changes the size of the given Evas object. + * + * @since_tizen 2.3 + * + * @remarks Besides being resized, the object's ::EVAS_CALLBACK_RESIZE callback + * is called. + * + * @remarks Newly created objects have zeroed dimensions. Then, you most + * probably want to use evas_object_resize() on them after they are + * created. + * + * @remarks Be aware that resizing an object changes its drawing area, + * but that does imply the object is rescaled. For instance, images + * are filled inside their drawing area using the specifications of + * evas_object_image_fill_set(). Thus to scale the image to match + * exactly your drawing area, you need to change the + * evas_object_image_fill_set() as well. + * + * @remarks This is more evident in images, but text, textblock, lines + * and polygons behave similarly. Check their specific APIs to + * know how to achieve your desired behavior. Consider the following example: + * + * @code + * // rescale image to fill exactly its area without tiling: + * evas_object_resize(img, w, h); + * evas_object_image_fill_set(img, 0, 0, w, h); + * @endcode + * + * @param[in] obj The given Evas object + * @param[in] w The new width of the Evas object + * @param[in] h The new height of the Evas object + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the position and (rectangular) size of the given Evas object. + * + * @since_tizen 2.3 + * + * @remarks The position is relative to the top left corner of + * the canvas' viewport. + * + * @remarks Use @c NULL pointers on the geometry components you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object + * @param[out] x The pointer to an integer in which to store the X coordinate + * of the object + * @param[out] y The pointer to an integer in which to store the Y coordinate + * of the object + * @param[out] w The pointer to an integer in which to store the width of the object + * @param[out] h The pointer to an integer in which to store the height of the object + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_geometry_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Makes the given Evas object visible. + * + * @since_tizen 2.3 + * + * @remarks Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW + * callback are called. + * + * @param[in] obj The given Evas object + * + * @see evas_object_hide() for more on object visibility. + * @see evas_object_visible_get() + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_show(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Makes the given Evas object invisible. + * + * @since_tizen 2.3 + * + * @remarks Hidden objects, besides not being shown at all in your canvas, + * are not checked for changes on the canvas rendering + * process. Furthermore, they do not catch input events. Thus, they + * are much lighter (in processing needs) than an object that is + * invisible due to indirect causes, such as being clipped or out of + * the canvas' viewport. + * + * @remarks Besides becoming hidden, @a obj object's ::EVAS_CALLBACK_SHOW + * callback is called. + * + * @remarks All objects are created in the hidden state. If you want to + * show them, use evas_object_show() after their creation. + * + * @param[in] obj The given Evas object + * + * @see evas_object_show() + * @see evas_object_visible_get() + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_hide(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the given Evas object is visible. + * + * @since_tizen 2.3 + * + * @details This retrieves an object's visibility as the one enforced by + * evas_object_show() and evas_object_hide(). + * + * @remarks The value returned is not, by any means, influenced by + * clippers covering @a obj, it being out of its canvas' viewport or + * stacked below other object. + * + * @param[in] obj The given Evas object + * @return #EINA_TRUE if the object is visible, \n + * otherwise #EINA_FALSE if the object is not visible + * + * @see evas_object_show() + * @see evas_object_hide() (for an example) + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI Eina_Bool evas_object_visible_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the general or main color of the given Evas object. + * + * @since_tizen 2.3 + * + * @remarks These color values are expected to be premultiplied by @a a. + * + * @param[in] obj The given Evas object + * @param[in] r The red component of the given color + * @param[in] g The green component of the given color + * @param[in] b The blue component of the given color + * @param[in] a The alpha component of the given color + * + * @see evas_object_color_get() (for an example) + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the general or main color of the given Evas object. + * + * @since_tizen 2.3 + * + * @remarks Gets the "main" color's RGB component (and alpha channel) + * values, <b>which range from 0 to 255</b>. For the alpha channel, + * which defines the object's transparency level, @c 0 means totally + * transparent, while @c 255 means opaque. These color values are + * premultiplied by the alpha value. + * + * @remarks Usually you use this attribute for text and rectangle objects, + * where the "main" color is their unique one. If set for objects + * which themselves have colors, like the images one, those colors get + * modulated by this one. + * + * @remarks All newly created Evas rectangles get the default color + * values of <code>255 255 255 255</code> (opaque white). + * + * @remarks Use @c NULL pointers on the components you are not interested + * in: they are ignored by the function. + * + * @param[in] obj The given Evas object to retrieve color from + * @param[out] r The pointer to an integer in which to store the red component + * of the color + * @param[out] g The pointer to an integer in which to store the green + * component of the color + * @param[out] b The pointer to an integer in which to store the blue component + * of the color + * @param[out] a The pointer to an integer in which to store the alpha + * component of the color + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas canvas that the given object lives on. + * + * @details This function is most useful at code contexts where you need to + * operate on the canvas but have only the object pointer. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @return A pointer to the canvas where the object is on + * + * @ingroup Evas_Object_Group_Basic + */ +EAPI Evas *evas_object_evas_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the type of the given Evas object. + * + * @since_tizen 2.3 + * + * @remarks For Evas' built-in types, the return strings are one of: + * - <c>"rectangle"</c>, + * - <c>"line"</c>, + * - <c>"polygon"</c>, + * - <c>"text"</c>, + * - <c>"textblock"</c> and + * - <c>"image"</c>. + * + * @internal + * @remarks For Evas smart objects (see @ref Evas_Smart_Group), the name of the + * smart class itself is returned on this call. For the built-in smart + * objects, these names are: + * - <c>"EvasObjectSmartClipped"</c>, for the clipped smart object + * - <c>"Evas_Object_Box"</c>, for the box object and + * - <c>"Evas_Object_Table"</c>, for the table object. + * @endinternal + * + * @param[in] obj The given object + * @return The type of the object + */ +EAPI const char *evas_object_type_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Raises @a obj to the top of its layer. + * + * @since_tizen 2.3 + * + * @remarks @a obj is, then, the highest one in the layer it belongs + * to. Objects on other layers do not get touched. + * + * @param[in] obj The object to raise + * + * @see evas_object_stack_above() + * @see evas_object_stack_below() + * @see evas_object_lower() + */ +EAPI void evas_object_raise(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Lowers @a obj to the bottom of its layer. + * + * @since_tizen 2.3 + * + * @remarks @a obj is, then, the lowest one in the layer it belongs + * to. Objects on other layers do not get touched. + * + * @param[in] obj The object to lower + * + * @see evas_object_stack_above() + * @see evas_object_stack_below() + * @see evas_object_raise() + */ +EAPI void evas_object_lower(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Stacks @a obj immediately above @a above. + * + * @since_tizen 2.3 + * + * @remarks Objects, in a given canvas, are stacked in the order they get added + * to it. This means that, if they overlap, the highest ones + * cover the lowest ones, in that order. This function is a way to + * change the stacking order for the objects. + * + * @remarks This function is intended to be used with <b>objects belonging to + * the same layer</b> in a given canvas, otherwise it fails (and + * accomplish nothing). + * + * @remarks If you have smart objects on your canvas and @a obj is a member of + * one of them, then @a above must also be a member of the same + * smart object. + * + * @remarks Similarly, if @a obj is not a member of a smart object, @a above + * must not be either. + * + * @param[in] obj The object to stack + * @param[in] above The object above which to stack + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_stack_below() + */ +EAPI void evas_object_stack_above(Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Stacks @a obj immediately below @a below. + * + * @since_tizen 2.3 + * + * @remarks Objects, in a given canvas, are stacked in the order they get added + * to it. This means that, if they overlap, the highest ones + * cover the lowest ones, in that order. This function is a way to + * change the stacking order for the objects. + * + * @remarks This function is intended to be used with <b>objects belonging to + * the same layer</b> in a given canvas, otherwise it fails (and + * accomplish nothing). + * + * @remarks If you have smart objects on your canvas and @a obj is a member of + * one of them, then @a below must also be a member of the same + * smart object. + * + * @remarks Similarly, if @a obj is not a member of a smart object, @a below + * must not be either. + * + * @param[in] obj The object to stack + * @param[in] below The object below which to stack + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_stack_below() + */ +EAPI void evas_object_stack_below(Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the Evas object stacked right above @a obj. + * + * @since_tizen 2.3 + * + * @remarks This function traverses layers in its search, if there are + * objects on layers above the one @a obj is placed at. + * + * @param[in] obj An #Evas_Object + * @return The #Evas_Object directly above @a obj, if any, \n + * otherwise @c NULL if none + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_below_get() + * + */ +EAPI Evas_Object *evas_object_above_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas object stacked right below @a obj. + * + * @details This function traverses layers in its search, if there are + * objects on layers below the one @a obj is placed at. + * + * @since_tizen 2.3 + * + * @param[in] obj An #Evas_Object + * @return The #Evas_Object directly below @a obj, if any, \n + * otherwise @c NULL if none + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_below_get() + */ +EAPI Evas_Object *evas_object_below_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Group_Events Object Events + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for object events. + * + * @remarks Objects generate events when they are moved, resized, when their + * visibility change, when they are deleted and so on. These methods + * allow you to be notified about and to handle such events. + * + * @remarks Objects also generate events on input (keyboard and mouse), if they + * accept them (are visible, focused, and so on). + * + * @remarks For each of those events, Evas provides a way for one to register + * callback functions to be issued just after they happen. + * + * @remarks The following figure illustrates some Evas (event) callbacks: + * + * @image html evas-callbacks.png + * @image rtf evas-callbacks.png + * @image latex evas-callbacks.eps + * + * @remarks These events have their values in the #Evas_Callback_Type + * enumeration, which also has the happening on the canvas level (see + * @ref Evas_Canvas_Events ). + * + * @{ + */ + +/** + * @brief Adds or registers a callback function to a given Evas object event. + * + * @details This function adds a function callback to an object when the event + * + * @since_tizen 2.3 of type @a type occurs on object @a obj. The function is @a func. + * + * + * @remarks In the event of a memory allocation error during addition of the + * callback to the object, evas_alloc_error() should be used to + * determine the nature of the error, if any, and the program should + * sensibly try and recover. + * + * @remarks A callback function must have the #Evas_Object_Event_Cb prototype + * definition. The first parameter (@a data) in this definition + * has the same value passed to evas_object_event_callback_add() as + * the @a data parameter, at runtime. The second parameter @a e is the + * canvas pointer on which the event occurred. The third parameter is + * a pointer to the object on which event occurred. Finally, the + * fourth parameter @a event_info is a pointer to a data structure + * that may or may not be passed to the callback, depending on the + * event type that triggered the callback. This is so because some + * events do not carry extra context with them, but others do. + * + * @remarks The valid event type @a type to trigger the function are + * #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT, + * #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP, + * #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL, + * #EVAS_CALLBACK_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP, + * #EVAS_CALLBACK_MULTI_MOVE, #EVAS_CALLBACK_FREE, + * #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP, + * #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT, + * #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE, + * #EVAS_CALLBACK_RESIZE, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL, + * #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS, + * #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED. + * + * @remarks This determines the kind of event that triggers the callback. + * The event types are explained below along with their associated @a event_info pointers: + * + * @remarks - #EVAS_CALLBACK_MOUSE_IN: @a event_info is a pointer to an + * #Evas_Event_Mouse_In struct\n\n + * This event is triggered when the mouse pointer enters the area + * (not shaded by other objects) of the object @a obj. This may + * occur by the mouse pointer being moved or by the object being shown, + * raised, moved, resized, or other objects being moved out of the + * way, hidden or lowered, whatever may cause the mouse pointer to + * get on top of @a obj, having been on top of another object + * previously. + * + * - #EVAS_CALLBACK_MOUSE_OUT: @a event_info is a pointer to an + * #Evas_Event_Mouse_Out struct\n\n + * This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, + * but it occurs when the mouse pointer exits an object's area. Note + * that no mouse out events are reported if the mouse pointer is + * implicitly grabbed to an object (mouse buttons are down, having + * been pressed while the pointer is over that object). In these + * cases, mouse out events are reported once all buttons are + * released, if the mouse pointer has left the object's area. The + * indirect ways of taking off the mouse pointer from an object, + * like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here, + * naturally. + * + * - #EVAS_CALLBACK_MOUSE_DOWN: @a event_info is a pointer to an + * #Evas_Event_Mouse_Down struct\n\n + * This event is triggered by a mouse button being pressed while the + * mouse pointer is over an object. If the pointer mode for Evas is + * #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this + * object to <b>passively grab the mouse</b> until all mouse buttons + * have been released: all future mouse events are reported to + * only this object until no buttons are down. That includes mouse + * move events, mouse in and mouse out events, and further button + * presses. When all buttons are released, event propagation + * occurs as normal (see #Evas_Object_Pointer_Mode). + * + * - #EVAS_CALLBACK_MOUSE_UP: @a event_info is a pointer to an + * #Evas_Event_Mouse_Up struct\n\n + * This event is triggered by a mouse button being released while + * the mouse pointer is over an object's area (or when passively + * grabbed to an object). + * + * - #EVAS_CALLBACK_MOUSE_MOVE: @a event_info is a pointer to an + * #Evas_Event_Mouse_Move struct\n\n + * This event is triggered by the mouse pointer being moved while + * over an object's area (or while passively grabbed to an object). + * + * - #EVAS_CALLBACK_MOUSE_WHEEL: @a event_info is a pointer to an + * #Evas_Event_Mouse_Wheel struct\n\n + * This event is triggered by the mouse wheel being rolled while the + * mouse pointer is over an object (or passively grabbed to an object). + * + * - #EVAS_CALLBACK_MULTI_DOWN: @a event_info is a pointer to an + * #Evas_Event_Multi_Down struct + * + * - #EVAS_CALLBACK_MULTI_UP: @a event_info is a pointer to an + * #Evas_Event_Multi_Up struct + * + * - #EVAS_CALLBACK_MULTI_MOVE: @a event_info is a pointer to an + * #Evas_Event_Multi_Move struct + * + * - #EVAS_CALLBACK_FREE: @a event_info is @c NULL \n\n + * This event is triggered just before Evas is about to free all + * memory used by an object and remove all references to it. This is + * useful for programs to use if they attached data to an object and + * want to free it when the object is deleted. The object is still + * valid when this callback is called, but after it returns, there + * is no guarantee on the object's validity. + * + * - #EVAS_CALLBACK_KEY_DOWN: @a event_info is a pointer to an + * #Evas_Event_Key_Down struct\n\n + * This callback is called when a key is pressed and the focus is on + * the object, or a key has been grabbed to a particular object + * which wants to intercept the key press regardless of what object + * has the focus. + * + * - #EVAS_CALLBACK_KEY_UP: @a event_info is a pointer to an + * #Evas_Event_Key_Up struct \n\n + * This callback is called when a key is released and the focus is + * on the object, or a key has been grabbed to a particular object + * which wants to intercept the key release regardless of what + * object has the focus. + * + * - #EVAS_CALLBACK_FOCUS_IN: @a event_info is @c NULL \n\n + * This event is called when an object gains the focus. When it is + * called the object has already gained the focus. + * + * - #EVAS_CALLBACK_FOCUS_OUT: @a event_info is @c NULL \n\n + * This event is triggered when an object loses the focus. When it + * is called the object has already lost the focus. + * + * - #EVAS_CALLBACK_SHOW: @a event_info is @c NULL \n\n + * This event is triggered by the object being shown by + * evas_object_show(). + * + * - #EVAS_CALLBACK_HIDE: @a event_info is @c NULL \n\n + * This event is triggered by an object being hidden by + * evas_object_hide(). + * + * - #EVAS_CALLBACK_MOVE: @a event_info is @c NULL \n\n + * This event is triggered by an object being + * moved. evas_object_move() can trigger this, as can any + * object-specific manipulations that would mean the object's origin + * could move. + * + * - #EVAS_CALLBACK_RESIZE: @a event_info is @c NULL \n\n + * This event is triggered by an object being resized. Resizes can + * be triggered by evas_object_resize() or by any object-specific + * calls that may cause the object to resize. + * + * - #EVAS_CALLBACK_RESTACK: @a event_info is @c NULL \n\n + * This event is triggered by an object being re-stacked. Stacking + * changes can be triggered by + * evas_object_stack_below()/evas_object_stack_above() and others. + * + * - #EVAS_CALLBACK_DEL: @a event_info is @c NULL. + * + * - #EVAS_CALLBACK_HOLD: @a event_info is a pointer to an + * #Evas_Event_Hold struct + * + * - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @a event_info is @c NULL. + * + * - #EVAS_CALLBACK_IMAGE_PRELOADED: @a event_info is @c NULL. + * + * - #EVAS_CALLBACK_IMAGE_UNLOADED: @a event_info is @c NULL. + * + * @remarks Be careful not to add the same callback multiple times, if + * that is not what you want, because Evas does not check if a callback + * existed before exactly as the one being registered (and thus, call + * it more than once on the event, in this case). This would make + * sense if you passed different functions and/or callback data, only. + * + * @param[in] obj The object to attach a callback to + * @param[in] type The type of event that triggers the callback + * @param[in] func The function to be called when the event is triggered + * @param[in] data The data pointer to be passed to @a func + */ +EAPI void evas_object_event_callback_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Adds or registers a callback function to a given Evas object event with a + * non-default priority set. Except for the priority field, it is exactly the + * same as @ref evas_object_event_callback_add. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The object to attach a callback to + * @param[in] type The type of event that triggers the callback + * @param[in] priority The priority of the callback \n + * Lower values are called first. + * @param[in] func The function to be called when the event is triggered + * @param[in] data The data pointer to be passed to @a func + * + * @see evas_object_event_callback_add + */ +EAPI void evas_object_event_callback_priority_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4); + +/** + * @brief Deletes a callback function from an object. + * + * @details This function removes the most recently added callback from the + * object @a obj which is triggered by the event type @a type and is + * calling the function @a func when triggered. If the removal is + * successful it also returns the data pointer that is passed to + * evas_object_event_callback_add() when the callback is added to the + * object. If not successful @c NULL is returned. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas_Object *object; + * void *my_data; + * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); + * + * my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback); + * @endcode + * + * @param[in] obj The object to remove a callback from + * @param[in] type The type of event triggering the callback + * @param[in] func The function to be called when the event is triggered + * @return The data pointer to be passed to the callback + */ +EAPI void *evas_object_event_callback_del(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Deletes or unregisters a callback function registered to a given Evas object event. + * + * @details This function removes the most recently added callback from the + * object @a obj, which is triggered by the event type @a type and is + * calling the function @a func with data @a data, when triggered. If + * the removal is successful it also returns the data pointer that + * is passed to evas_object_event_callback_add() (that is the + * same as the parameter) when the callback is added to the + * object. In case of errors, @c NULL is returned. + * + * @since_tizen 2.3 + * + * @remarks For deletion of Evas object events callbacks filtering by + * just type and function pointer, use evas_object_event_callback_del(). + * + * @remarks The following is an example: + * @code + * extern Evas_Object *object; + * void *my_data; + * void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); + * + * my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data); + * @endcode + * + * @param[in] obj The object to remove a callback from + * @param[in] type The type of event triggering the callback + * @param[in] func The function to be called when the event is triggered + * @param[in] data The data pointer to be passed to the callback + * @return The data pointer to be passed to the callback + */ +EAPI void *evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * @brief Sets whether an Evas object is to pass (ignore) events. + * + * @since_tizen 2.3 + * + * @remarks If @a pass is #EINA_TRUE, it makes events on @a obj to be @b + * ignored. They instead are triggered on the @b next lower object that + * is not set to pass events. See evas_object_below_get(). + * + * @remarks If @a pass is #EINA_FALSE, events are processed on that + * object as normal. + * + * + * @param[in] obj The Evas object to operate on + * @param[in] pass Set #EINA_TRUE for @a obj to pass events, \n + * otherwise #EINA_FALSE not to pass events + * + * @see evas_object_pass_events_get() for an example + * @see evas_object_repeat_events_set() + * @see evas_object_propagate_events_set() + * @see evas_object_freeze_events_set() + */ +EAPI void evas_object_pass_events_set(Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object is set to pass (ignore) events. + * + * @since_tizen 2.3 + * + * @param[in] obj The Evas object to get information from + * @return #EINA_TRUE if @a obj is set to pass events, \n + * otherwise #EINA_FALSE if it is not set to pass events + * + * @see evas_object_pass_events_set() + * @see evas_object_repeat_events_get() + * @see evas_object_propagate_events_get() + * @see evas_object_freeze_events_get() + */ +EAPI Eina_Bool evas_object_pass_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether an Evas object is to repeat events. + * + * @since_tizen 2.3 + * + * @remarks If @a repeat is #EINA_TRUE, it makes events on @a obj to also + * be repeated for the @b next lower object in the objects' stack. See + * evas_object_below_get(). + * + * @remarks If @a repeat is #EINA_FALSE, events occurring on @a obj are + * processed only on it. + * + * @param[in] obj The Evas object to operate on + * @param[in] repeat Set #EINA_TRUE for @a obj to repeat events, \n + * otherwise set #EINA_FALSE + * + * @see evas_object_repeat_events_get() + * @see evas_object_pass_events_set() + * @see evas_object_propagate_events_set() + * @see evas_object_freeze_events_set() + */ +EAPI void evas_object_repeat_events_set(Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object is set to repeat events. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object pointer + * @return #EINA_TRUE if @a obj is set to repeat events, + * otherwise #EINA_FALSE if it is not set to repeat events + * + * @see evas_object_repeat_events_set() for an example + * @see evas_object_pass_events_get() + * @see evas_object_propagate_events_get() + * @see evas_object_freeze_events_get() + */ +EAPI Eina_Bool evas_object_repeat_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether events on a smart object's member should get propagated + * up to its parent. + * + * @details This function has @b no effect if @a obj is not a member of a smart object. + * + * @since_tizen 2.3 + * + * @remarks If @a prop is #EINA_TRUE, events occurring on this object is + * propagated on to the smart object of which @a obj is a member. If + * @a prop is #EINA_FALSE, events occurring on this object is @b + * not propagated on to the smart object of which @a obj is a + * member. The default value is #EINA_TRUE. + * + * @param[in] obj The smart object's child to operate on + * @param[in] prop Set #EINA_TRUE to propagate events, \n + * otherwise #EINA_FALSE to not propagate events + * + * @see evas_object_propagate_events_get() + * @see evas_object_repeat_events_set() + * @see evas_object_pass_events_set() + * @see evas_object_freeze_events_set() + */ +EAPI void evas_object_propagate_events_set(Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an Evas object is set to propagate events. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object pointer + * @return #EINA_TRUE if @a obj is set to propagate events, \n + * otherwise #EINA_FALSE it is not set to propagate events + * + * @see evas_object_propagate_events_set() + * @see evas_object_repeat_events_get() + * @see evas_object_pass_events_get() + * @see evas_object_freeze_events_get() + */ +EAPI Eina_Bool evas_object_propagate_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether an Evas object is to freeze (discard) events. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks If @a freeze is #EINA_TRUE, it makes events on @a obj to be @b + * discarded. Unlike evas_object_pass_events_set(), events are not + * passed to @b next lower object. This API can be used for blocking + * events while @a obj is on transiting. + * + * @remarks If @a freeze is #EINA_FALSE, events are processed on that + * object as normal. + * + * @param[in] obj The Evas object to operate on + * @param[in] freeze Set #EINA_TRUE for @a obj to freeze events, \n + * otherwise #EINA_FALSE not to freeze events + * + * @see evas_object_freeze_events_get() + * @see evas_object_pass_events_set() + * @see evas_object_repeat_events_set() + * @see evas_object_propagate_events_set() + */ +EAPI void evas_object_freeze_events_set(Evas_Object *obj, Eina_Bool freeze) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object is set to freeze (discard) events. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The Evas object to get information from + * @return #EINA_TRUE if @a obj is set to freeze events, \n + * otherwise #EINA_FALSE if it is not set to freeze events + * + * @see evas_object_freeze_events_set() + * @see evas_object_pass_events_get() + * @see evas_object_repeat_events_get() + * @see evas_object_propagate_events_get() + */ +EAPI Eina_Bool evas_object_freeze_events_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspective, 3D...) + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for UV mapping. + * + * Evas allows different transformations to be applied to all kinds of + * objects. These are applied by means of UV mapping. + * + * With UV mapping, one maps points in the source object to a 3D space + * positioning at target. This allows rotation, perspective, scale and + * lots of other effects, depending on the map that is used. + * + * Each map point may carry a multiplier color. If properly + * calculated, these can do shading effects on the object, producing + * 3D effects. + * + * As usual, Evas provides both raw and easy to use methods. The + * raw methods allow developers to create their maps somewhere else, + * possibly loading them from some file format. The easy to use methods + * calculate the points given some high-level parameters such as + * rotation angle, ambient light, and so on. + * + * @remarks Applying mapping reduces performance, so use with + * care. The impact on performance depends on the engine in + * use. The software is quite optimized, but not as fast as OpenGL. + * + * @section sec-map-points Map points + * @subsection subsec-rotation Rotation + * + * A map consists of a set of points, currently only four are supported. Each + * of these points contains a set of canvas coordinates @c x and @c y that + * can be used to alter the geometry of the mapped object, and a @c z + * coordinate that indicates the depth of that point. This last coordinate + * does not normally affect the map, but it is used by several of the utility + * functions to calculate the right position of the point given other + * parameters. + * + * The coordinates for each point are set with evas_map_point_coord_set(). + * The following image shows a map set to match the geometry of an existing object. + * + * @image html map-set-map-points-1.png + * @image rtf map-set-map-points-1.png + * @image latex map-set-map-points-1.eps + * + * This is a common practice, so there are a few functions that help make it easier. + * + * evas_map_util_points_populate_from_geometry() sets the coordinates of each + * point in the given map to match the rectangle defined by the function parameters. + * + * evas_map_util_points_populate_from_object() and + * evas_map_util_points_populate_from_object_full() both take an object and + * set the map points to match its geometry. The difference between the two + * is that the first function sets the @c z value of all points to @c 0, while + * the latter receives the value to set in said coordinate as a parameter. + * + * The following lines of code all produce the same result as in the image above. + * @code + * evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0); + * // Assuming o is our original object + * evas_object_move(o, 100, 100); + * evas_object_resize(o, 200, 200); + * evas_map_util_points_populate_from_object(m, o); + * evas_map_util_points_populate_from_object_full(m, o, 0); + * @endcode + * + * Several effects can be applied to an object by simply setting each point + * of the map to the right coordinates. For example, a simulated perspective + * could be achieve as follows. + * + * @image html map-set-map-points-2.png + * @image rtf map-set-map-points-2.png + * @image latex map-set-map-points-2.eps + * + * As said before, the @c z coordinate is unused here so when setting points + * by hand, its value is of no importance. + * + * @image html map-set-map-points-3.png + * @image rtf map-set-map-points-3.png + * @image latex map-set-map-points-3.eps + * + * In all three cases above, setting the map to be used by the object is the same. + * @code + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * @endcode + * + * Doing things this way, however, is a lot of work that can be avoided by + * using the provided utility functions, as described in the next section. + * + * @section map-utils Utility functions + * + * Utility functions take an already set up map and alter it to produce a + * specific effect. For example, to rotate an object around its own center + * you would need to take the rotation angle, the coordinates of each corner + * of the object and do all the math to get the new set of coordinates that + * need to be set in the map. + * + * Or you can use this code: + * @code + * evas_object_geometry_get(o, &x, &y, &w, &h); + * m = evas_map_new(4); + * evas_map_util_points_populate_from_object(m, o); + * evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2)); + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * evas_map_free(m); + * @endcode + * + * which rotates the object around its center point in a 45 degree angle + * in the clockwise direction, taking it from this + * + * @image html map-rotation-2d-1.png + * @image rtf map-rotation-2d-1.png + * @image latex map-rotation-2d-1.eps + * + * to this + * + * @image html map-rotation-2d-2.png + * @image rtf map-rotation-2d-2.png + * @image latex map-rotation-2d-2.eps + * + * Objects may be rotated around any other point just by setting the last two + * parameters of the evas_map_util_rotate() function to the right values. A + * circle of roughly the diameter of the object overlaid on each image shows + * where the center of rotation is set for each example. + * + * For example, this code + * @code + * evas_object_geometry_get(o, &x, &y, &w, &h); + * m = evas_map_new(4); + * evas_map_util_points_populate_from_object(m, o); + * evas_map_util_rotate(m, 45, x + w - 20, y + h - 20); + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * evas_map_free(m); + * @endcode + * + * produces something like + * + * @image html map-rotation-2d-3.png + * @image rtf map-rotation-2d-3.png + * @image latex map-rotation-2d-3.eps + * + * And the following + * @code + * evas_output_size_get(evas, &w, &h); + * m = evas_map_new(4); + * evas_map_util_points_populate_from_object(m, o); + * evas_map_util_rotate(m, 45, w, h); + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * evas_map_free(m); + * @endcode + * + * rotates the object around the center of the window + * + * @image html map-rotation-2d-4.png + * @image rtf map-rotation-2d-4.png + * @image latex map-rotation-2d-4.eps + * + * @subsection subsec-3d 3D Maps + * + * Maps can also be used to achieve the effect of 3-dimensionality. When doing + * this, the @c z coordinate of each point counts, with higher values meaning + * the point is further into the screen, and smaller values (negative, usually) + * meaning the point is closer towards the user. + * + * Thinking in 3D also introduces the concept of back-face of an object. An + * object is said to be facing the user when all its points are placed in a + * clockwise fashion. The next image shows this, with each point showing each + * corner of the object with which it is identified within the map. + * + * @image html map-point-order-face.png + * @image rtf map-point-order-face.png + * @image latex map-point-order-face.eps + * + * Rotating this map around the @c Y axis would leave the order of the points + * in a counter-clockwise fashion, as seen in the following image. + * + * @image html map-point-order-back.png + * @image rtf map-point-order-back.png + * @image latex map-point-order-back.eps + * + * This way we can say that we are looking at the back face of the object. + * This has stronger implications later when we talk about lighting. + * + * To know if a map is facing towards the user or not it is enough to use + * the evas_map_util_clockwise_get() function, but this is normally done + * after all the other operations are applied on the map. + * + * @subsection subsec-3d-rot 3D rotation and perspective + * + * Much like evas_map_util_rotate(), there is the function + * evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation + * to an object. As in its 2D counterpart, the rotation can be applied around + * any point in the canvas, this time with a @c z coordinate too. The rotation + * can also be around any of the 3 axis. + * + * Starting from this simple setup + * + * @image html map-3d-basic-1.png + * @image rtf map-3d-basic-1.png + * @image latex map-3d-basic-1.eps + * + * and setting maps so that the blue square to rotate on all axis around a + * sphere that uses the object as its center, and the red square to rotate + * around the @c Y axis, we get the following. A simple overlay over the image + * shows the original geometry of each object and the axis around which they + * are being rotated, with the @c Z one not appearing due to being orthogonal + * to the screen. + * + * @image html map-3d-basic-2.png + * @image rtf map-3d-basic-2.png + * @image latex map-3d-basic-2.eps + * + * which does not look very real. This can be helped by adding perspective + * to the transformation, which can be simply done by calling + * evas_map_util_3d_perspective() on the map after its position has been set. + * The result in this case, making the vanishing point the center of each + * object: + * + * @image html map-3d-basic-3.png + * @image rtf map-3d-basic-3.png + * @image latex map-3d-basic-3.eps + * + * @section sec-color Color and lighting + * + * Each point in a map can be set to a color, which is multiplied with + * the objects own color and linearly interpolated in between adjacent points. + * This is done with evas_map_point_color_set() for each point of the map, + * or evas_map_util_points_color_set() to set every point to the same color. + * + * When using 3D effects, colors can be used to improve the looks of them by + * simulating a light source. The evas_map_util_3d_lighting() function makes + * this task easier by taking the coordinates of the light source and its + * color, along with the color of the ambient light. Evas then sets the color + * of each point based on the distance to the light source, the angle with + * which the object is facing the light and the ambient light. Here, the + * orientation of each point as explained before, becomes more important. + * If the map is defined counter-clockwise, the object faces away + * from the user and thus become obscured, since no light would be reflecting + * from it. + * + * @image html map-light.png + * @image rtf map-light.png + * @image latex map-light.eps + * @note Object facing the light source + * + * @image html map-light2.png + * @image rtf map-light2.png + * @image latex map-light2.eps + * @note Same object facing away from the user + * + * @section Image mapping + * + * @image html map-uv-mapping-1.png + * @image rtf map-uv-mapping-1.png + * @image latex map-uv-mapping-1.eps + * + * Images need some special handling when mapped. Evas can easily take care + * of objects and do almost anything with them, but it is completely oblivious + * to the content of images, so each point in the map needs to be told to what + * pixel in the source image it belongs. Failing to do may sometimes result + * in the expected behavior, or it may look like a partial work. + * + * The next image illustrates one possibility of a map being set to an image + * object, without setting the right UV mapping for each point. The objects + * themselves are mapped properly to their new geometry, but the image content + * may not be displayed correctly within the mapped object. + * + * @image html map-uv-mapping-2.png + * @image rtf map-uv-mapping-2.png + * @image latex map-uv-mapping-2.eps + * + * Once Evas knows how to handle the source image within the map, it + * transforms it as needed. This is done with evas_map_point_image_uv_set(), + * which tells the map to which pixel in image it maps. + * + * To match our example images to the maps above all we need is the size of + * each image, which can always be found with evas_object_image_size_get(). + * + * @code + * evas_map_point_image_uv_set(m, 0, 0, 0); + * evas_map_point_image_uv_set(m, 1, 150, 0); + * evas_map_point_image_uv_set(m, 2, 150, 200); + * evas_map_point_image_uv_set(m, 3, 0, 200); + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * + * evas_map_point_image_uv_set(m, 0, 0, 0); + * evas_map_point_image_uv_set(m, 1, 120, 0); + * evas_map_point_image_uv_set(m, 2, 120, 160); + * evas_map_point_image_uv_set(m, 3, 0, 160); + * evas_object_map_set(o2, m); + * evas_object_map_enable_set(o2, EINA_TRUE); + * @endcode + * + * @image html map-uv-mapping-3.png + * @image rtf map-uv-mapping-3.png + * @image latex map-uv-mapping-3.eps + * + * Maps can also be set to use part of an image only, or even map them inverted, + * and when combined with evas_object_image_source_set() it can be used to achieve + * more interesting results. + * + * @code + * evas_object_image_size_get(evas_object_image_source_get(o), &w, &h); + * evas_map_point_image_uv_set(m, 0, 0, h); + * evas_map_point_image_uv_set(m, 1, w, h); + * evas_map_point_image_uv_set(m, 2, w, h / 3); + * evas_map_point_image_uv_set(m, 3, 0, h / 3); + * evas_object_map_set(o, m); + * evas_object_map_enable_set(o, EINA_TRUE); + * @endcode + * + * @image html map-uv-mapping-4.png + * @image rtf map-uv-mapping-4.png + * @image latex map-uv-mapping-4.eps + * + * @{ + */ + +/** + * @brief Enables or disables the map that is set. + * + * @details This function enables or disables the use of map for the object @a obj. + * When enabled, the object geometry is saved, and the new geometry + * changes (position and size) to reflect the map geometry set. + * + * @since_tizen 2.3 + * + * @remarks If the object does not have a map set (with evas_object_map_set()), the + * initial geometry is undefined. It is advised to always set a map + * to the object first, and then call this function to enable its use. + * + * @param[in] obj The object to enable the map on + * @param[in] enabled Set #EINA_TRUE to enable the map, \n + * otherwise #EINA_FALSE to not enable the map + */ +EAPI void evas_object_map_enable_set(Evas_Object *obj, Eina_Bool enabled); + +/** + * @brief Checks whether the map is enabled. + * + * @details This function returns the currently enabled state of the map on the object indicated. + * The default map enable state is off. You can enable and disable it with + * evas_object_map_enable_set(). + * + * @since_tizen 2.3 + * + * @param[in] obj The object to get the map enabled state from + * @return #EINA_TRUE of the map is enabled, \n + * otherwise #EINA_FALSE of the map is not enabled + */ +EAPI Eina_Bool evas_object_map_enable_get(const Evas_Object *obj); + +/** + * @brief Sets current object transformation map. + * + * @details This function sets the map on a given object. It is copied from the @a map pointer, + * so there is no need to keep the @a map object if you do not need it anymore. + * + * @since_tizen 2.3 + * + * @remarks A map is a set of 4 points which have canvas @c x, @c y coordinates per point, + * with an optional @c z point value as a hint for perspective correction, if it + * is available. As well each point has @c u and @c v coordinates. These are like + * "texture coordinates" in OpenGL in that they define a point in the source + * image that is mapped to that map vertex or point. The @c u corresponds to the @c x + * coordinate of this mapped point and @c v, the @c y coordinate. Note that these + * coordinates describe a bounding region to sample. If you have a 200x100 + * source image and want to display it at 200x100 with proper pixel + * precision, then do the following: + * + * @code + * Evas_Map *m = evas_map_new(4); + * evas_map_point_coord_set(m, 0, 0, 0, 0); + * evas_map_point_coord_set(m, 1, 200, 0, 0); + * evas_map_point_coord_set(m, 2, 200, 100, 0); + * evas_map_point_coord_set(m, 3, 0, 100, 0); + * evas_map_point_image_uv_set(m, 0, 0, 0); + * evas_map_point_image_uv_set(m, 1, 200, 0); + * evas_map_point_image_uv_set(m, 2, 200, 100); + * evas_map_point_image_uv_set(m, 3, 0, 100); + * evas_object_map_set(obj, m); + * evas_map_free(m); + * @endcode + * + * @remarks Note that the map points a uv coordinates that match the image geometry. If + * the @a map parameter is @c NULL, the stored map is freed and geometry + * prior to enabling/setting a map is restored. + * + * @param[in] obj The object to change transformation map + * @param[in] map The new map to use + * + * @see evas_map_new() + */ +EAPI void evas_object_map_set(Evas_Object *obj, const Evas_Map *map); + +/** + * @brief Gets the current object transformation map. + * + * @details This function returns the current internal map set on the indicated object. It is + * intended for read-only access and is only valid as long as the object is + * not deleted or the map on the object is not changed. If you wish to modify + * the map and set it back do the following: + * + * @since_tizen 2.3 + * + * @code + * const Evas_Map *m = evas_object_map_get(obj); + * Evas_Map *m2 = evas_map_dup(m); + * evas_map_util_rotate(m2, 30.0, 0, 0); + * evas_object_map_set(obj, m2); + * evas_map_free(m2); + * @endcode + * + * @param[in] obj The object to query transformation map + * @return The map reference to the map in use \n + * This is an internal data structure, so do not modify it. + * + * @see evas_object_map_set() + */ +EAPI const Evas_Map *evas_object_map_get(const Evas_Object *obj); + +/** + * @brief Populates source and destination map points to exactly match the object. + * + * @since_tizen 2.3 + * + * @remarks You initialize the map of an object to match its original + * position and size, then transform these with evas_map_util_* + * functions, such as evas_map_util_rotate() or + * evas_map_util_3d_rotate(). The original set is done by this + * function, avoiding code duplication all around. + * + * @param[in] m The map to change all 4 points (must be of size 4) + * @param[in] obj The object to use unmapped geometry to populate map coordinates + * @param[in] z The point Z coordinate hint (pre-perspective transform) \n + * This value is used for all four points. + * + * @see evas_map_util_points_populate_from_object() + * @see evas_map_point_coord_set() + * @see evas_map_point_image_uv_set() + */ +EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z); + +/** + * @brief Populates the source and destination map points to exactly match the object. + * + * @since_tizen 2.3 + * + * @remarks You initialize map of an object to match its original + * position and size, then transform these with evas_map_util_* + * functions, such as evas_map_util_rotate() or + * evas_map_util_3d_rotate(). The original set is done by this + * function, avoiding code duplication all around. + * + * @remarks The Z point coordinate is assumed as @c 0 (zero). + * + * @param[in] m The map to change all 4 points (must be of size 4) + * @param[in] obj The object to use unmapped geometry to populate map coordinates + * + * @see evas_map_util_points_populate_from_object_full() + * @see evas_map_util_points_populate_from_geometry() + * @see evas_map_point_coord_set() + * @see evas_map_point_image_uv_set() + */ +EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj); + +/** + * @brief Populates the source and destination map points to match the given geometry. + * + * @since_tizen 2.3 + * + * @remarks Similar to evas_map_util_points_populate_from_object_full(), this + * call takes raw values instead of querying object's unmapped + * geometry. The given width is used to calculate destination + * points (evas_map_point_coord_set()) and set the image uv + * (evas_map_point_image_uv_set()). + * + * @param[in] m The map to change all 4 points (must be of size 4) + * @param[in] x The X coordinate + * @param[in] y The Y coordinate + * @param[in] w The width to use to calculate second and third points + * @param[in] h The height to use to calculate third and fourth points + * @param[in] z The Z coordinate hint (pre-perspective transform) \n + * This value is used for all four points. + * + * @see evas_map_util_points_populate_from_object() + * @see evas_map_point_coord_set() + * @see evas_map_point_image_uv_set() + */ +EAPI void evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z); + +/** + * @brief Sets the given color for all the points. + * + * @details This function is useful to reuse maps after they had 3D lightning or + * any other colorization applied before. + * + * @since_tizen 2.3 + * + * @param[in] m The map to change the color of + * @param[in] r The red color (0 - 255) + * @param[in] g The green color (0 - 255) + * @param[in] b The blue color (0 - 255) + * @param[in] a The alpha color (0 - 255) + * + * @see evas_map_point_color_set() + */ +EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a); + +/** + * @brief Changes the map to apply the given rotation. + * + * @details This function rotates the indicated map's coordinates around the center coordinate + * given by @a cx and @a cy as the rotation center. The points have their + * X and Y coordinates rotated clockwise by @a degrees degrees (@c 360.0 is a + * full rotation). Negative values for degrees rotate counter-clockwise + * by that amount. All coordinates are canvas global coordinates. + * + * @since_tizen 2.3 + * + * @param[in] m The map to change + * @param[in] degrees The amount of degrees from @c 0.0 to @c 360.0 to rotate + * @param[in] cx The rotation's center horizontal position + * @param[in] cy The rotation's center vertical position + * + * @see evas_map_point_coord_set() + * @see evas_map_util_zoom() + */ +EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy); + +/** + * @brief Changes the map to apply the given zooming. + * + * @since_tizen 2.3 + * + * @remarks Like evas_map_util_rotate(), this zooms the points of the map from a center + * point. That center is defined by @a cx and @a cy. The @a zoomx and @a zoomy + * parameters specify how much to zoom in the X and Y direction respectively. + * A value of @c 1.0 means "don't zoom", @c 2.0 means "double the size", @c 0.5 is + * "half the size", and so on. All coordinates are canvas global coordinates. + * + * @param[in] m The map to change + * @param[in] zoomx The horizontal zoom to use + * @param[in] zoomy The vertical zoom to use + * @param[in] cx The zooming center horizontal position + * @param[in] cy The zooming center vertical position + * + * @see evas_map_point_coord_set() + * @see evas_map_util_rotate() + */ +EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy); + +/** + * @brief Rotates the map around 3 axes in 3D. + * + * @details This function rotates not just around the "Z" axis as in evas_map_util_rotate() + * (which is a convenience call for those only wanting 2D). This rotates + * around the X, Y and Z axes. The Z axis points "into" the screen with low + * values at the screen and higher values further away. The X axis runs from + * left to right on the screen and the Y axis from top to bottom. Like with + * evas_map_util_rotate() you provide a center point to rotate around (in 3D). + * + * @since_tizen 2.3 + * + * @param[in] m The map to change + * @param[in] dx The amount of degrees from @c 0.0 to @c 360.0 to rotate around X axis + * @param[in] dy The amount of degrees from @c 0.0 to @c 360.0 to rotate around Y axis + * @param[in] dz The amount of degrees from @c 0.0 to @c 360.0 to rotate around Z axis + * @param[in] cx The rotation's center horizontal position + * @param[in] cy The rotation's center vertical position + * @param[in] cz The rotation's center vertical position + */ +EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz); + +/** + * @brief Rotates the map in 3D using a unit quaternion. + * + * @details This function rotates in 3D using a unit quaternion. Like with + * evas_map_util_3d_rotate() you provide a center point + * to rotate around (in 3D). + * @since 1.8 + * + * @since_tizen 2.3 + * + * @remarks Rotations can be done using a unit quaternion. Thus, this + * function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1). + * If this is not the case the behavior is undefined. + * + * @param[in] m The map to change + * @param[in] qx The x component of the imaginary part of the quaternion + * @param[in] qy The y component of the imaginary part of the quaternion + * @param[in] qz The z component of the imaginary part of the quaternion + * @param[in] qw The w component of the real part of the quaternion + * @param[in] cx The rotation's center x + * @param[in] cy The rotation's center y + * @param[in] cz The rotation's center z + * + */ +EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz); + +/** + * @brief Performs lighting calculations on the given map. + * + * @details This function is used to apply lighting calculations (from a single light source) + * to a given map. The R, G and B values of each vertex is modified to + * reflect the lighting based on the lixth point coordinates, the light + * color and the ambient color, and at what angle the map is facing the + * light source. A surface should have its points declared in a + * clockwise fashion if the face is "facing" towards you (as opposed to + * away from you) as faces have a "logical" side for lighting. + * + * @since_tizen 2.3 + * + * @image html map-light3.png + * @image rtf map-light3.png + * @image latex map-light3.eps + * @remarks Grey object, no lighting used + * + * @image html map-light4.png + * @image rtf map-light4.png + * @image latex map-light4.eps + * @remarks Lights out! Every color set to @c 0 + * + * @image html map-light5.png + * @image rtf map-light5.png + * @image latex map-light5.eps + * @remarks Ambient light to full black, red light coming from close at the + * bottom-left vertex. + * + * @image html map-light6.png + * @image rtf map-light6.png + * @image latex map-light6.eps + * @remarks Same light as before, but not the light is set to 0 and ambient light + * is cyan. + * + * @image html map-light7.png + * @image rtf map-light7.png + * @image latex map-light7.eps + * @remarks Both lights are on. + * + * @image html map-light8.png + * @image rtf map-light8.png + * @image latex map-light8.eps + * @remarks Both lights again, but this time both are the same color. + * + * @param[in] m The map to change + * @param[in] lx The X coordinate in space of light point + * @param[in] ly The Y coordinate in space of light point + * @param[in] lz The Z coordinate in space of light point + * @param[in] lr The light red value (0 - 255) + * @param[in] lg The light green value (0 - 255) + * @param[in] lb The light blue value (0 - 255) + * @param[in] ar The ambient color red value (0 - 255) + * @param[in] ag The ambient color green value (0 - 255) + * @param[in] ab The ambient color blue value (0 - 255) + */ +EAPI void evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab); + +/** + * @brief Applies a perspective transform to the map. + * + * @details This function applies a given perspective (3D) to the map coordinates. X, Y and Z + * values are used. The px and py points specify the "infinite distance" point + * in the 3D conversion (where all lines converge to, like when artists draw + * 3D by hand). The @a z0 value specifies the z value at which there is a 1:1 + * mapping between spatial coordinates and screen coordinates. Any points + * on this z value do not have their X and Y values modified in the transform. + * Those further away (Z value higher) shrink into the distance, and + * those less than this value expand and become bigger. The @a foc value + * determines the "focal length" of the camera. This is in reality the distance + * between the camera lens plane itself (at or closer than this rendering + * results are undefined) and the "z0" z value. This allows for some "depth" + * control and @a foc must be greater than @c 0. + * + * @since_tizen 2.3 + * + * @param[in] m The map to change + * @param[in] px The perspective distance X coordinate + * @param[in] py The perspective distance Y coordinate + * @param[in] z0 The "0" z plane value + * @param[in] foc The focal distance + */ +EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc); + +/** + * @brief Gets the clockwise state of a map. + * + * @details This function determines if the output points (X and Y. Z is not used) are + * clockwise or counter-clockwise. This can be used for "back-face culling". This + * is where you hide objects that "face away" from you, in this case, the objects + * that are not clockwise. + * + * @since_tizen 2.3 + * + * @param[in] m The map to query + * @return #EINA_TRUE if the output points are clockwise, + * otherwise #EINA_FALSE if the output points are not clockwise + */ +EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m); + +/** + * @brief Creates a map of transformation points to be later used with an Evas object. + * + * @details This function creates a set of points (currently only 4 is supported and no other + * number for @a count works). That is empty and ready to be modified + * with evas_map calls. + * + * @since_tizen 2.3 + * + * @param[in] count The number of points in the map + * @return The newly allocated map, \n + * otherwise @c NULL on errors + * + * @see evas_map_free() + * @see evas_map_dup() + * @see evas_map_point_coord_set() + * @see evas_map_point_image_uv_set() + * @see evas_map_util_points_populate_from_object_full() + * @see evas_map_util_points_populate_from_object() + * + * @see evas_object_map_set() + */ +EAPI Evas_Map *evas_map_new(int count); + +/** + * @brief Sets the smoothing for map rendering. + * + * @details This function sets smoothing for map rendering. If the object is a type that has + * its own smoothing settings, then both the smooth settings for this object + * and the map must be turned off. By default, smooth maps are enabled. + * + * @since_tizen 2.3 + * + * @param[in] m The map to modify \n + * This must not be @c NULL. + * @param[in] enabled Set #EINA_TRUE to enable smooth map rendering, \n + * otherwise set #EINA_FALSE not to enable smooth map rendering + */ +EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled); + +/** + * Checks whether the smoothing for map rendering is enabled. + * + * @details This gets smoothing for map rendering. + * + * @since_tizen 2.3 + * + * @param[in] m The map for which to get the smoothing status \n + * This must not be @c NULL. + * @return #EINA_TRUE if smoothing for map rendering is enabled, \n + * otherwise #EINA_FALSE if smoothing for map rendering is not enabled + */ +EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m); + +/** + * @brief Sets the alpha flag for map rendering. + * + * @details This function sets alpha flag for map rendering. If the object is a type that has + * its own alpha settings, then this takes precedence. Only image objects + * have this currently. Setting this off stops alpha blending of the map area, and is + * useful if you know the object and/or all sub-objects is 100% solid. + * + * @since_tizen 2.3 + * + * @param[in] m The map to modify \n + * This must not be @c NULL. + * @param[in] enabled Set #EINA_TRUE to enable alpha map rendering, \n + * otheriwse set #EINA_FALSE to disable alpha map rendering + */ +EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled); + +/** + * @brief Gets the alpha flag for map rendering. + * + * @details This gets the alpha flag for map rendering. + * + * @since_tizen 2.3 + * + * @param[in] m The map to get the alpha from \n + * This must not be @c NULL. + * @return The alpha flag + */ +EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m); + +/** + * @brief Copies a previously allocated map. + * + * @details This makes a duplicate of the @a m object and returns it. + * + * @since_tizen 2.3 + * + * @param[in] m The map to copy \n + * This must not be @c NULL. + * @return The newly allocated map with the same count and contents as @a m + */ +EAPI Evas_Map *evas_map_dup(const Evas_Map *m); + +/** + * @brief Frees a previously allocated map. + * + * @details This function frees a given map @a m and all memory associated with it. You must NOT + * free a map returned by evas_object_map_get() as this is internal. + * + * @since_tizen 2.3 + * + * @param[in] m The map to free + */ +EAPI void evas_map_free(Evas_Map *m); + +/** + * @brief Gets a maps size. + * + * @since_tizen 2.3 + * + * @remarks This function returns the number of points in a map. It should be at least be @c 4. + * + * @param[in] m The map to get the size + * @return The number of points in a map, \n + * otherwise @c -1 on error + */ +EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST; + +/** + * @brief Changes the map point's coordinate. + * + * @details This function sets the fixed point's coordinate in the map. Note that points + * describe the outline of a quadrangle and are ordered either clockwise + * or counter-clockwise. It is suggested to keep your quadrangles concave and + * non-complex, though these polygon modes may work, they may not render + * a desired set of output. The quadrangle uses points @c 0 and @c 1 , @c 1 and @c 2, + * @c 2 and @c 3, and @c 3 and @c 0 to describe the edges of the quadrangle. + * + * @since_tizen 2.3 + * + * @remarks The X, Y, and Z coordinates are in canvas units. Z is optional and may + * or may not be honored in drawing. Z is a hint and does not affect the + * X and Y rendered coordinates. It may be used for calculating fills with + * perspective correct rendering. + * + * @remarks Remember all coordinates are canvas global ones like with move and resize in evas. + * + * @param[in] m The map to change point \n + * This must not be @c NULL. + * @param[in] idx The index of point to change \n + * This must be smaller than map size. + * @param[in] x The X coordinate + * @param[in] y The Y coordinate + * @param[in] z The Z coordinate hint (pre-perspective transform) + * + * @see evas_map_util_rotate() + * @see evas_map_util_zoom() + * @see evas_map_util_points_populate_from_object_full() + * @see evas_map_util_points_populate_from_object() + */ +EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z); + +/** + * @brief Gets the map point's coordinate. + * + * @details This function returns the coordinates of the given point in the map. + * + * @since_tizen 2.3 + * + * @param[in] m The map to query point + * @param[in] idx The index of point to query \n + * This must be smaller than the map size. + * @param[out] x The X coordinate + * @param[out] y The Y coordinate + * @param[out] z The Z coordinate + */ +EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z); + +/** + * @brief Changes the map point's U and V texture source point. + * + * @details This sets the U and V coordinates for the point. This determines which + * coordinate in the source image is mapped to the given point, much like + * OpenGL and textures. Note that these points do select the pixel, but + * are double floating point values to allow for accuracy and sub-pixel selection. + * + * @since_tizen 2.3 + * + * @param[in] m The map to change the point of + * @param[in] idx The index of point to change \n + * This must be smaller than map size. + * @param[in] u The X coordinate within the image or texture source + * @param[in] v The Y coordinate within the image or texture source + * + * @see evas_map_point_coord_set() + * @see evas_object_map_set() + * @see evas_map_util_points_populate_from_object_full() + * @see evas_map_util_points_populate_from_object() + */ +EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v); + +/** + * @brief Gets the map point's U and V texture source points. + * + * @details This function returns the texture points set by evas_map_point_image_uv_set(). + * + * @since_tizen 2.3 + * + * @param[in] m The map to query point + * @param[in] idx The index of point to query \n + * This must be smaller than map size. + * @param[out] u The X coordinate within the image or texture source + * @param[out] v The Y coordinate within the image or texture source + */ +EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v); + +/** + * @brief Sets the color of a vertex in the map. + * + * @details This sets the color of the vertex in the map. Colors are linearly + * interpolated between vertex points through the map. Color multiplies + * the "texture" pixels (like GL_MODULATE in OpenGL). The default color of + * a vertex in a map is white solid (255, 255, 255, 255) which means it + * has no affect on modifying the texture pixels. + * + * @since_tizen 2.3 + * + * @param[in] m The map to change the color of + * @param[in] idx The index of point to change \n + * This must be smaller than the map size. + * @param[in] r The red color (0 - 255) + * @param[in] g The green color (0 - 255) + * @param[in] b The blue color (0 - 255) + * @param[in] a The alpha color (0 - 255) + * + * @see evas_map_util_points_color_set() + * @see evas_map_point_coord_set() + * @see evas_object_map_set() + */ +EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a); + +/** + * @brief Gets the color set on a vertex in the map. + * + * @details This function gets the color set by evas_map_point_color_set() on the given vertex + * of the map. + * + * @since_tizen 2.3 + * + * @param[in] m The map to get the color of the vertex from + * @param[in] idx The index of point get \n + * This must be smaller than the map size. + * @param[out] r The pointer to red color + * @param[out] g The pointer to green color + * @param[out] b The pointer to blue color + * @param[out] a The pointer to alpha color (0 - 255) + * + * @see evas_map_point_coord_set() + * @see evas_object_map_set() + */ +EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Group_Size_Hints Size Hints + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for size hints. + * + * Objects may carry hints, so that another object that acts as a + * manager (see @ref Evas_Smart_Object_Group) may know how to properly + * position and resize its subordinate objects. The Size Hints provide + * a common interface that is recommended as the protocol for such + * information. + * + * For example, box objects use alignment hints to align its + * lines or columns inside its container, padding hints to set the + * padding between each individual child, and so on. + * + * @{ + */ + +/** + * @brief Gets the hints for an object's minimum size. + * + * @since_tizen 2.3 + * + * @remarks These are hints on the minimim sizes @a obj should have. This is + * not a size enforcement in any way. It is just a hint that should be + * used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object to query hints from + * @param[out] w The pointer to an integer in which to store the minimum width + * @param[out] h The pointer to an integer in which to store the minimum height + * + * @see evas_object_size_hint_min_set() for an example + */ +EAPI void evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's minimum size. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Values like @c 0 are treated as unset hint components, when queried + * by managers. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] w The integer to use as the minimum width hint + * @param[in] h The integer to use as the minimum height hint + * + * @see evas_object_size_hint_min_get() + */ +EAPI void evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for an object's maximum size. + * + * @since_tizen 2.3 + * + * @remarks These are hints on the maximum sizes @a obj should have. This is + * not a size enforcement in any way. It is just a hint that should be + * used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object to query hints from + * @param[out] w The pointer to an integer in which to store the maximum width + * @param[out] h The pointer to an integer in which to store the maximum height + * @see evas_object_size_hint_max_set() + */ +EAPI void evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's maximum size. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Values like @c -1 are treated as unset hint components, when queried + * by managers. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] w The integer to use as the maximum width hint + * @param[in] h The integer to use as the maximum height hint + * @see evas_object_size_hint_max_get() + */ +EAPI void evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for an object's display mode. + * + * @since_tizen 2.3 + * + * @remarks These are hints on the display mode @a obj. This is + * not a size enforcement in any way. It is just a hint that can be + * used whenever appropriate. This mode can be used with object's display + * mode like compress or expand. + * + * @param[in] obj The given Evas object to query hints from + * @return The display mode hints + * + * @see evas_object_size_hint_display_mode_set() + */ +EAPI Evas_Display_Mode evas_object_size_hint_display_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's display mode. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * can be used whenever appropriate. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] dispmode The display mode hint + * + * @see evas_object_size_hint_display_mode_get() + */ +EAPI void evas_object_size_hint_display_mode_set(Evas_Object *obj, Evas_Display_Mode dispmode) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Gets the hints for an object's optimum size. + * + * @since_tizen 2.3 + * + * @remarks These are hints on the optimum sizes @a obj should have. This is + * not a size enforcement in any way. It is just a hint that should be + * used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object to query hints from + * @param[out] w The pointer to an integer in which to store the requested width + * @param[out] h The pointer to an integer in which to store the requested height + * + * @see evas_object_size_hint_request_set() + */ +EAPI void evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Sets the hints for an object's optimum size. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Values like @c 0 are treated as unset hint components, when queried + * by managers. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] w The integer to use as the preferred width hint + * @param[in] h The integer to use as the preferred height hint + * + * @see evas_object_size_hint_request_get() + */ +EAPI void evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for an object's aspect ratio. + * + * @since_tizen 2.3 + * + * @remarks The different aspect ratio policies are documented in the + * #Evas_Aspect_Control type. A container respecting these size hints + * would @b resize its children accordingly to those policies. + * + * @remarks For any policy, if any of the given aspect ratio terms are @c 0, + * the object's container should ignore the aspect and scale @a obj to + * occupy the whole available area. If they are both positive + * integers, that proportion is respected, under each scaling policy. + * + * @remarks These images illustrate some of the #Evas_Aspect_Control policies: + * + * @image html any-policy.png + * @image rtf any-policy.png + * @image latex any-policy.eps + * + * @image html aspect-control-none-neither.png + * @image rtf aspect-control-none-neither.png + * @image latex aspect-control-none-neither.eps + * + * @image html aspect-control-both.png + * @image rtf aspect-control-both.png + * @image latex aspect-control-both.eps + * + * @image html aspect-control-horizontal.png + * @image rtf aspect-control-horizontal.png + * @image latex aspect-control-horizontal.eps + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object to query hints from + * @param[out] aspect The policy or type of aspect ratio applied to @a obj that is returned + * @param[out] w The pointer to an integer in which to store the aspect's width + * ratio term + * @param[out] h The pointer to an integer in which to store the aspect's + * height ratio term + * + * @see evas_object_size_hint_aspect_set() + */ +EAPI void evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's aspect ratio. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that should + * be used whenever appropriate. + * + * @remarks If any of the given aspect ratio terms are @c 0, + * the object's container ignores the aspect and scale @a obj to + * occupy the whole available area, for any given policy. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] aspect The policy or type of aspect ratio to apply to @a obj + * @param[in] w The integer to use as aspect width ratio term + * @param[in] h The integer to use as aspect height ratio term + * + * @see evas_object_size_hint_aspect_get() for more information. + */ +EAPI void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for the object's alignment. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * @remarks If @c obj is invalid, then the hint components are set with @c 0.5 + * + * @param[in] obj The given Evas object to query hints from + * @param[out] x The pointer to a double in which to store the horizontal alignment hint + * @param[out] y The pointer to a double in which to store the vertical alignment hint + * + * @see evas_object_size_hint_align_set() for more information + */ +EAPI void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's alignment. + * + * @since_tizen 2.3 + * + * @remarks These are hints on how to align an object <b>inside the boundaries + * of a container/manager</b>. Accepted values are in the @c 0.0 to @c + * 1.0 range, with the special value #EVAS_HINT_FILL used to specify + * "justify" or "fill" by some users. In this case, maximum size hints + * should be enforced with higher priority, if they are set. Also, any + * padding hint set on objects should add up to the alignment space on + * the final scene composition. + * + * @remarks See documentation of possible users: in Evas, they are the @ref + * Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart objects. + * + * @remarks For the horizontal component, @c 0.0 means to the left, @c 1.0 + * means to the right. Analogously, for the vertical component, @c 0.0 + * to the top, @c 1.0 means to the bottom. + * + * @remarks See the following figure: + * + * @image html alignment-hints.png + * @image rtf alignment-hints.png + * @image latex alignment-hints.eps + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks The default alignment hint values are @c 0.5, for both axis. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] x The horizontal alignment hint as double value ranging from @c 0.0 to @c 1.0 or with the + * special value #EVAS_HINT_FILL + * @param[in] y The vertical alignment hint as double value ranging from @c 0.0 to @c 1.0 or with the + * special value #EVAS_HINT_FILL + * + * @see evas_object_size_hint_align_get() + * @see evas_object_size_hint_max_set() + * @see evas_object_size_hint_padding_set() + */ +EAPI void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for an object's weight. + * + * @since_tizen 2.3 + * + * @remarks Accepted values are @c 0 or positive values. Some users might use + * this hint as a boolean, but some might consider it as a @b + * proportion. See documentation of possible users, which in Evas are + * the @ref Evas_Object_Box "box" and @ref Evas_Object_Table "table" + * smart objects. + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * @remarks If @c obj is invalid, then the hint components are set with @c 0.0 + * + * @param[in] obj The given Evas object to query hints from + * @param[out] x The pointer to a double in which to store the horizontal weight + * @param[out] y The pointer to a double in which to store the vertical weight + * + * @see evas_object_size_hint_weight_set() for an example + */ +EAPI void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's weight. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks This is a hint on how a container object should @b resize a given + * child within its area. Containers may adhere to the simpler logic + * of just expanding the child object's dimensions to fit its own (see + * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of + * taking each child's weight hint as real @b weights to how much of + * its size to allocate for them in each axis. A container is supposed + * to, after @b normalizing the weights of its children (with weight + * hints), distribute the space it has to layout them by those factors + * -- most weighted children get larger in this process than the least ones. + * + * @remarks Default weight hint values are @c 0.0, for both axis. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] x The non-negative double value to use as horizontal weight hint + * @param[in] y The non-negative double value to use as vertical weight hint + * + * @see evas_object_size_hint_weight_get() for more information + */ +EAPI void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the hints for an object's padding space. + * + * @since_tizen 2.3 + * + * @remarks Padding is extra space that an object takes on each of its delimiting + * rectangle sides, in canvas units. This space is rendered + * transparent, naturally, as in the following figure: + * + * @image html padding-hints.png + * @image rtf padding-hints.png + * @image latex padding-hints.eps + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @remarks Use @c NULL pointers on the hint components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas object to query hints from + * @param[out] l The pointer to an integer in which to store left padding + * @param[out] r The pointer to an integer in which to store right padding + * @param[out] t The pointer to an integer in which to store top padding + * @param[out] b The pointer to an integer in which to store bottom padding + * + * @see evas_object_size_hint_padding_set() + */ +EAPI void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the hints for an object's padding space. + * + * @since_tizen 2.3 + * + * @remarks This is not a size enforcement in any way. It is just a hint that + * should be used whenever appropriate. + * + * @param[in] obj The given Evas object to query hints from + * @param[in] l The integer to specify left padding + * @param[in] r The integer to specify right padding + * @param[in] t The integer to specify top padding + * @param[in] b The integer to specify bottom padding + * + * @see evas_object_size_hint_padding_get() for more information + */ +EAPI void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Group_Extras Extra Object Manipulation + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for extra object manipulation. + * + * Miscellaneous functions that also apply to any object, but are less + * used or not implemented by all objects. + * + * @{ + */ + +/** + * @brief Sets an attached data pointer to an object with a given string key. + * + * @since_tizen 2.3 + * + * @remarks This attaches the pointer @a data to the object @a obj, given the + * access string @a key. This pointer stays "hooked" to the object + * until a new pointer with the same string key is attached with + * evas_object_data_set() or it is deleted with + * evas_object_data_del(). On deletion of the object @a obj, the + * pointers is not accessible from the object anymore. + * + * @remarks You can find the pointer attached under a string key using + * evas_object_data_get(). It is the job of the calling application to + * free any data pointed to by @a data when it is no longer required. + * + * @remarks If @a data is @c NULL, the old value stored at @a key is + * removed but no new value is stored. This is synonymous with + * calling evas_object_data_del() with @a obj and @a key. + * + * @remarks This function is very handy when you have data associated + * specifically to an Evas object, being of use only when dealing with + * it. You do not have the burden to a pointer to it elsewhere, + * using this family of functions. + * + * @remarks The following is an example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = malloc(500); + * evas_object_data_set(obj, "name_of_data", my_data); + * printf("The data that is attached is %p\n", evas_object_data_get(obj, "name_of_data")); + * @endcode + * + * @param[in] obj The object to attach the data pointer to + * @param[in] key The string key for the data to access it + * @param[in] data The pointer to the data to be attached + * + */ +EAPI void evas_object_data_set(Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets an attached data pointer on an Evas object by its given + * string key. + * + * @details This function returns the data pointer attached to the object + * @a obj, stored using the string key @a key. If the object is valid + * and a data pointer is stored under the given key, that pointer + * is returned. If this is not the case, @c NULL is + * returned, signifying an invalid object or a non-existent key. It is + * possible that a @c NULL pointer is stored given that key, but this + * situation is not probable and thus can be considered an error as + * well. @c NULL pointers are never stored as this is the return value + * if an error occurs. + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = evas_object_data_get(obj, "name_of_my_data"); + * if (my_data) printf("Data stored is %p\n", my_data); + * else printf("No data is stored on the object\n"); + * @endcode + * + * @param[in] obj The object to which the data is attached + * @param[in] key The string key the data is stored under + * @return The data pointer stored, + * otherwise @c NULL if none are stored + */ +EAPI void *evas_object_data_get(const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Deletes an attached data pointer from an object. + * + * @since_tizen 2.3 + * + * @remarks This removes the stored data pointer from @a obj stored under + * @a key and return this same pointer, if actually there is data + * there, or @c NULL, if nothing is stored under that key. + * + * @remarks The following is an example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = evas_object_data_del(obj, "name_of_my_data"); + * @endcode + * + * @param[in] obj The object to delete the data pointer from + * @param[in] key The string key the data is stored under + * @return The original data pointer stored at @a key on @a obj + */ +EAPI void *evas_object_data_del(Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the pointer behavior. + * + * @since_tizen 2.3 + * + * @remarks This function has direct effect on event callbacks related to mouse. + * + * @remarks If @a setting is @c EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse + * is down at this object, events are restricted to it as source, + * mouse moves, for example, are emitted even if outside this + * object area. + * + * @remarks If @a setting is @c EVAS_OBJECT_POINTER_MODE_NOGRAB, then events are + * emitted just when inside this object area. + * + * @remarks The default value is @c EVAS_OBJECT_POINTER_MODE_AUTOGRAB. + * + * @param[in] obj The pointer for which behavior is set + * @param[in] setting The desired behavior + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_pointer_mode_set(Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1); + +/** + * @brief Gets how the pointer behaves. + * + * @since_tizen 2.3 + * + * @param[in] obj The pointer + * @return The pointer behavior + * @ingroup Evas_Object_Group_Extras + */ +EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether the given Evas object is to be drawn anti-aliased. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @param[in] antialias Set #EINA_TRUE for the object to be anti-aliased, \n + * otherwise #EINA_FALSE for it not to be anti-aliased + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_anti_alias_set(Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the given Evas object is to be drawn anti-aliased. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @return #EINA_TRUE if the object is to be anti-aliased, + * otherwise #EINA_FALSE if it is not to be anti-aliased + * @ingroup Evas_Object_Group_Extras + */ +EAPI Eina_Bool evas_object_anti_alias_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the scaling factor for an Evas object. \n + * Does not affect all objects. + * + * @since_tizen 2.3 + * + * @remarks This multiplies the object's dimension by the given factor, thus + * altering its geometry (width and height). This is useful when you want + * scalable UI elements, possibly at run time. + * + * @remarks Only text and textblock objects have scaling change + * handlers. Other objects do not change visually on this call. + * + * @param[in] obj The given Evas object + * @param[in] scale The scaling factor \n + * <c>1.0</c> means no scaling, default size. + * + * @see evas_object_scale_get() + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_scale_set(Evas_Object *obj, double scale) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the scaling factor for the given Evas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @return The scaling factor + * + * @ingroup Evas_Object_Group_Extras + * + * @see evas_object_scale_set() + */ +EAPI double evas_object_scale_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the render_op to be used for rendering the Evas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @param[in] op An Evas_Render_Op value + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current value of the operation used for rendering the Evas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas object + * @return An enumerated value in Evas_Render_Op + * @ingroup Evas_Object_Group_Extras + */ +EAPI Evas_Render_Op evas_object_render_op_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether to use precise (usually expensive) point collision + * detection for a given Evas object. + * + * @since_tizen 2.3 + * + * @remarks Use this function to make Evas treat objects' transparent areas as + * @b not belonging to it with regard to mouse pointer events. By + * default, all of the object's boundary rectangle is taken into + * account for them. + * + * @remarks By using precise point collision detection you are + * making Evas more resource intensive. + * + * @param[in] obj The given object + * @param[in] precise Set #EINA_TRUE to use precise point collision detection, \n + * otherwise set #EINA_FALSE to not use it \n + * The default value is #EINA_FALSE. + * + * @see evas_object_precise_is_inside_get() + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object is set to use precise point collision detection. + * + * @since_tizen 2.3 + * + * @param[in] obj The given object + * @return #EINA_TRUE if @a obj is set to use precise point collision detection, \n + * otherwise #EINA_FALSE if it is not set to use \n + * The default value is #EINA_FALSE. + * + * @see evas_object_precise_is_inside_set() for an example + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets a hint flag on the given Evas object that it is used as a "static clipper". + * + * @since_tizen 2.3 + * + * @remarks This is a hint to Evas that this object is used as a big static + * clipper and should not be moved with children and otherwise + * considered specially. The default value for new objects is #EINA_FALSE. + * + * @param[in] obj The given object + * @param[in] is_static_clip Set #EINA_TRUE if it is to be used as a static clipper, \n + * otherwise set #EINA_FALSE + * + * @see evas_object_static_clip_get() + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI void evas_object_static_clip_set(Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the "static clipper" hint flag for a given Evas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given object + * @return #EINA_TRUE if it is set as a static clipper, \n + * otheriwse #EINA_FALSE + * + * @see evas_object_static_clip_set() for more details + * + * @ingroup Evas_Object_Group_Extras + */ +EAPI Eina_Bool evas_object_static_clip_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Object_Group_Find Finding Objects + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for finding objects. + * Functions that allows finding objects by their position, name or + * other properties. + * + * @{ + */ + +/** + * @brief Gets the object that currently has focus. + * + * @since_tizen 2.3 + * + * @remarks Evas can have (at most) one of its objects focused at a time. + * Focused objects are the ones having <b>key events</b> delivered + * to, which the programmer can act upon by means of + * evas_object_event_callback_add() usage. + * + * @remarks Mostly you would not be dealing directly with Evas focused + * objects. Instead, you would be using a higher level library for + * that (like a toolkit, as Elementary) to handle focus and who is + * receiving input for them. + * + * @remarks This call returns the object that currently has focus on the canvas + * @a e or @c NULL, if none. + * + * @param[in] e The Evas canvas to query for focused object + * @return The object that has focus, \n + * otherwise @c NULL if there is no object that has focus + * + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_object_key_grab + * @see evas_object_key_ungrab + * @ingroup Evas_Object_Group_Find + */ +EAPI Evas_Object *evas_focus_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the object on the given evas with the given name. + * + * @since_tizen 2.3 + * + * @remarks This looks for the evas object given a name by evas_object_name_set(). If + * the name is not unique canvas-wide, then which one of the many objects + * with that name is returned is undefined. So only use this if you can ensure + * the object name is unique. + * + * @param[in] e The given evas + * @param[in] name The given name + * @return The Evas object with the given name, \n + * otherwise @c NULL on failure + * + * @ingroup Evas_Object_Group_Find + */ +EAPI Evas_Object *evas_object_name_find(const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the object from children of the given object with the given name. + * + * @details This function looks for the evas object, which has its name set using evas_object_name_set(), but + * it ONLY looks at the children of the object @a obj, and only recurse + * into those children if @a recurse is greater than @c 0. If the name is not + * unique within immediate children (or the whole child tree) then it is not + * defined which child object is returned. If @a recurse is set to @c -1 then + * it recurses without limit. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The parent (smart) object whose children to search + * @param[in] name The given name + * @param[in] recurse Set to the number of child levels to recurse \n + * (0 == do not recurse, \n + * 1 == only look at the children of @a obj or their immediate children and no further etc.). + * @return The Evas object with the given name, \n + * otherwise @c NULL on failure + * + * @ingroup Evas_Object_Group_Find + */ +EAPI Evas_Object *evas_object_name_child_find(const Evas_Object *obj, const char *name, int recurse) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas object stacked at the top of a given position in a canvas. + * + * @details This function traverses all the layers of the given canvas, + * from top to bottom, querying for objects with areas covering the + * given position. The user can remove from the query + * objects which are hidden and/or which are set to pass events. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A handle to the canvas + * @param[in] x The horizontal coordinate of the position + * @param[in] y The vertical coordinate of the position + * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n + * otherwise set #EINA_FALSE to not include the objects + * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n + * otherwise set #EINA_FALSE to not include hidden objects + * @return The Evas object that is over all other objects at the given position + */ +EAPI Evas_Object *evas_object_top_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas object stacked at the top at the position of the + * mouse cursor, over a given canvas. + * + * @details This function traverses all the layers of the given canvas, + * from top to bottom, querying for objects with areas covering the + * mouse pointer's position, over @a e. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A handle to the canvas + * @return The Evas object that is over all other objects at the mouse pointer's position + */ +EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas object stacked at the top of a given rectangular + * region in a canvas. + * + * @details This function traverses all the layers of the given canvas, + * from top to bottom, querying for objects with areas overlapping + * with the given rectangular region inside @a e. The user can remove + * from the query objects which are hidden and/or which are set to + * pass events. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A handle to the canvas + * @param[in] x The top left corner's horizontal coordinate for the + * rectangular region + * @param[in] y The top left corner's vertical coordinate for the + * rectangular region + * @param[in] w The width of the rectangular region + * @param[in] h The height of the rectangular region + * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n + * otherwise #EINA_FALSE to not include the objects + * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n + * otherwise #EINA_FALSE to not include the hidden objects + * @return The Evas object that is over all other objects at the given rectangular region + */ +EAPI Evas_Object *evas_object_top_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets a list of Evas objects lying over a given position in a canvas. + * + * @details This function traverses all the layers of the given canvas, + * from top to bottom, querying for objects with areas covering the + * given position. The user can remove from query + * objects which are hidden and/or which are set to pass events. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A handle to the canvas + * @param[in] x The horizontal coordinate of the position + * @param[in] y The vertical coordinate of the position + * @param[in] include_pass_events_objects Set #EINA_TRUE to include objects which pass events in this calculation, \n + * otherwise set #EINA_FALSE to not include the objects + * @param[in] include_hidden_objects Set #EINA_TRUE to include hidden objects in this calculation, \n + * otherwise set #EINA_FALSE to not include the hidden objects + * @return The list of Evas objects that are over the given position in @a e + */ +EAPI Eina_List *evas_objects_at_xy_get(const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +EAPI Eina_List *evas_objects_in_rectangle_get(const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the lowest (stacked) Evas object on the canvas @a e. + * + * @details This function takes all populated layers in the canvas into + * account, getting the lowest object for the lowest layer, naturally. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A valid canvas pointer + * @return A pointer to the lowest object on it, if any, \n + * otherwise @c NULL if the pointer is not obtained + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_below_get() + * @see evas_object_above_get() + */ +EAPI Evas_Object *evas_object_bottom_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the highest (stacked) Evas object on the canvas @a e. + * + * @details This function takes all populated layers in the canvas into + * account, getting the highest object for the highest layer, naturally. + * + * @since_tizen 2.3 + * + * @remarks This function @b skips objects parented by smart + * objects, acting only on the ones at the "top level", with regard to + * object parenting. + * + * @param[in] e A valid canvas pointer + * @return A pointer to the highest object on it, if any, \n + * otherwise @c NULL if the pointer is not obtained + * + * @see evas_object_layer_get() + * @see evas_object_layer_set() + * @see evas_object_below_get() + * @see evas_object_above_get() + */ +EAPI Evas_Object *evas_object_top_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Object_Group_Interceptors Object Method Interceptors + * @ingroup Evas_Object_Group + * + * @brief This group provides functions for method interceptors. + * + * Evas provides a way to intercept method calls. The interceptor + * callback may opt to completely deny the call, or may check and + * change the parameters before continuing. The continuation of an + * intercepted call is done by calling the intercepted call again, + * from inside the interceptor callback. + * + * @{ + */ + +typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj); +typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj); +typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y); +typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h); +typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj); +typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj); +typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above); +typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above); +typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l); +typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a); +typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip); +typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj); + +/** + * @brief Sets the callback function that intercepts a show event of an object. + * + * @details This function sets a callback function to intercepts a show event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given function to be the callback function + * @param[in] data The data passed to the callback function + * + * @see evas_object_intercept_show_callback_del(). + * + */ +EAPI void evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Unsets the callback function that intercepts a show event of a object. + * + * @details This function sets a callback function to intercept a show event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given callback function + * + * @see evas_object_intercept_show_callback_add(). + * + */ +EAPI void *evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the callback function that intercepts a hide event of a object. + * + * @details This function sets a callback function to intercepts a hide event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given function to be the callback function + * @param[in] data The data passed to the callback function + * + * @see evas_object_intercept_hide_callback_del(). + * + */ +EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Unsets the callback function that intercepts a hide event of a object. + * + * @details This function sets a callback function to intercepts a hide event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given callback function + * + * @see evas_object_intercept_hide_callback_add(). + * + */ +EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the callback function that intercepts a move event of a object. + * + * @details This function sets a callback function to intercepts a move event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given function to be the callback function + * @param[in] data The data passed to the callback function + * + * @see evas_object_intercept_move_callback_del(). + * + */ +EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Unsets the callback function that intercepts a move event of a object. + * + * @details This function sets a callback function to intercept a move event + * of a canvas object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object pointer + * @param[in] func The given callback function + * + * @see evas_object_intercept_move_callback_add(). + * + */ +EAPI void *evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2); + +EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2); +EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); +EAPI void *evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Specific Specific Object Functions + * @ingroup Evas_Object_Group + * + * @brief This group provides functions that work on specific objects. + * + */ + +/** + * @defgroup Evas_Object_Rectangle Rectangle Object Functions + * @ingroup Evas_Object_Specific + * + * @brief Function to create evas rectangle objects. + * + * There is only one function to deal with rectangle objects, this may make this + * function seem useless given there are no functions to manipulate the created + * rectangle, however the rectangle is actually very useful and should be + * manipulated using the generic @ref Evas_Object_Group "evas object functions". + * + * The evas rectangle serves a number of key functions when working on evas + * programs: + * @li Background + * @li Debugging + * @li Clipper + * + * @section Background + * + * One extremely common requirement of evas programs is to have a solid color + * background. This can be accomplished with the following very simple code: + * @code + * Evas_Object *bg = evas_object_rectangle_add(evas_canvas); + * //Here we set the rectangles red, green, blue and opacity levels + * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background + * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas + * evas_object_show(bg); + * @endcode + * + * This however has issues if the @c evas_canvas is resized. However most + * windows are created using ecore evas and that has a solution to using the + * rectangle as a background: + * @code + * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee)); + * //Here we set the rectangles red, green, blue and opacity levels + * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background + * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas + * evas_object_show(bg); + * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE); + * @endcode + * So this gives us a white background to our window that is resized + * together with it. + * + * @section Debugging + * + * Debugging is a major part of any programmers task and when debugging visual + * issues with evas programs the rectangle is an extremely useful tool. The + * rectangle's simplicity means that it is easier to pinpoint issues with it than + * with more complex objects. Therefore a common technique to use when writing + * an evas program and not getting the desired visual result is to replace the + * misbehaving object for a solid color rectangle and seeing how it interacts + * with the other elements, this often allows us to notice clipping, parenting + * or positioning issues. Once the issues have been identified and corrected the + * rectangle can be replaced for the original part and in all likelihood any + * remaining issues are specific to that object's type. + * + * @section clipping Clipping + * + * Clipping serves two main functions: + * @li Limiting visibility (i.e. hiding portions of an object). + * @li Applying a layer of color to an object. + * + * @subsection hiding Limiting visibility + * + * It is often necessary to show only parts of an object, while it may be + * possible to create an object that corresponds only to the part that must be + * shown (and it is not always possible), it is usually easier to use a clipper. A + * clipper is a rectangle that defines what is visible and what is not. The way + * to do this is to create a solid white rectangle (which is the default, no need + * to call evas_object_color_set()) and give it a position and size of what + * should be visible. The following code exemplifies showing the center half of + * @c my_evas_object: + * @code + * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas); + * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4); + * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2); + * evas_object_clip_set(my_evas_object, clipper); + * evas_object_show(clipper); + * @endcode + * + * @subsection color Layer of color + * + * In the @ref clipping section we used a solid white clipper, which produced no + * change in the color of the clipped object, it just hid what is outside the + * clippers area. It is however sometimes desirable to change the color of an + * object, this can be accomplished using a clipper that has a non-white color. + * Clippers with color work by multiplying the colors of clipped object. The + * following code shows how to remove all the red from an object: + * @code + * Evas_Object *clipper = evas_object_rectangle_add(evas); + * evas_object_move(clipper, my_evas_object_x, my_evas_object_y); + * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height); + * evas_object_color_set(clipper, 0, 255, 255, 255); + * evas_object_clip_set(obj, clipper); + * evas_object_show(clipper); + * @endcode + * + * @remarks We do not guarantee any proper results if you create a Rectangle + * object without setting the evas engine. + * + * @{ + */ + +/** + * @brief Adds a rectangle to the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The new rectangle object + */ +EAPI Evas_Object *evas_object_rectangle_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Image Image Object Functions + * @ingroup Evas_Object_Specific + * + * @brief This group provides functions for image objects. + * + * The functions used to create and manipulate image objects + * are grouped together. They are available to whichever occasion one needs + * complex imagery on a GUI that could not be achieved by the other + * Evas' primitive object types, or to make image manipulations. + * + * Evas supports whichever image file types it is compiled with + * support to (its image loaders) -- check your software packager for + * that information and see + * evas_object_image_extension_can_load_get(). + * + * @section Evas_Object_Image_Basics Image object basics + * + * The most common use of image objects -- to display an image on the + * canvas -- is achieved by a common function triplet: + * @code + * img = evas_object_image_add(canvas); + * evas_object_image_file_set(img, "path/to/img", NULL); + * evas_object_image_fill_set(img, 0, 0, w, h); + * @endcode + * The first function, naturally, is creating the image object. Then, + * one must set a source file on it, so that it knows where to fetch + * image data from. Next, one must set <b>how to fill the image + * object's area</b> with the given pixel data. One could use just a + * sub-region of the original image or even have it tiled repeatedly + * on the image object. For the common case of having the whole source + * image to be displayed on the image object, stretched to the + * destination's size, there is also a function helper, to be used + * instead of evas_object_image_fill_set(): + * @code + * evas_object_image_filled_set(img, EINA_TRUE); + * @endcode + * See those functions' documentation for more details. + * + * @section Evas_Object_Image_Scale Scale and resizing + * + * Resizing of image objects scales their respective source images + * to their areas, if they are set to "fill" the object's area + * (evas_object_image_filled_set()). If you want any control on + * the aspect ratio of an image for different sizes, you have to + * take care of that yourself. There are functions to make images to + * get loaded scaled (up or down) in memory, already, if you are + * going to use them at pre-determined sizes and want to save + * computations. + * + * Evas has even a scale cache, which takes care of caching scaled + * versions of images with most usage/hits. Finally, you can + * have images being rescaled @b smoothly by Evas (more + * computationally expensive) or not. + * + * @section Evas_Object_Image_Performance Performance hints + * + * When dealing with image objects, there are some tricks to boost the + * performance of your application, if it does intense image loading + * and/or manipulations, as in animations on a UI. + * + * @subsection Evas_Object_Image_Load Load hints + * + * In image viewer applications, for example, the user is looking + * at a given image, at full size, and desires that the navigation + * to the adjacent images on his/her album be fluid and fast. Thus, + * while displaying a given image, the program can be on the + * background loading the next and previous images already, so that + * displaying them on the sequence is just a matter of repainting the + * screen (and not decoding image data). + * + * Evas addresses this issue with <b>image pre-loading</b>. The code + * for the situation above would be something like the following: + * @code + * prev = evas_object_image_filled_add(canvas); + * evas_object_image_file_set(prev, "/path/to/prev", NULL); + * evas_object_image_preload(prev, EINA_TRUE); + * + * next = evas_object_image_filled_add(canvas); + * evas_object_image_file_set(next, "/path/to/next", NULL); + * evas_object_image_preload(next, EINA_TRUE); + * @endcode + * + * If you are loading images which are too big, consider setting + * its loading size to something smaller, in case you do not expose + * them in real size. It may speed up the loading considerably: + * @code + * //To load a scaled down version of the image in memory, if that is + * //the size you are displaying anyway + * evas_object_image_load_scale_down_set(img, zoom); + * + * //optional: if you know you are going to show a sub-set of the image's + * //pixels, you can avoid loading the complementary data + * evas_object_image_load_region_set(img, x, y, w, h); + * @endcode + * Refer to Elementary's Photocam widget for a high level (smart) + * object which does lots of loading speed-ups for you. + * + * @subsection Evas_Object_Image_Animation Animation hints + * + * If you want to animate image objects on a UI (what you would get by + * concomitant usage of other libraries, like Ecore and Edje), there + * are also some tips on how to boost the performance of your + * application. If the animation involves resizing of an image (thus, + * re-scaling), you would better turn off smooth scaling on it @b during + * the animation, turning it back on afterwards, for less + * computations. Also, in this case you would better flag the image object + * in question not to cache scaled versions of it: + * @code + * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_DYNAMIC); + * + * // Resizing takes place in between + * + * evas_object_image_scale_hint_set(wd->img, EVAS_IMAGE_SCALE_HINT_STATIC); + * @endcode + * + * Finally, movement of opaque images through the canvas is less + * expensive than of translucid ones, because of blending + * computations. + * + * @section Evas_Object_Image_Borders Borders + * + * Evas provides facilities for one to specify an image's region to be + * treated specially -- as "borders". This makes those regions to be + * treated specially on resizing scales, by keeping their aspect. This + * makes setting frames around other objects on UIs easy. + * See the following figures for a visual explanation:\n + * + * @image html image-borders.png + * @htmlonly + * <a href="image-borders.png">Full-size</a> + * @endhtmlonly + * @image rtf image-borders.png + * @image latex image-borders.eps "image borders" width=\textwidth + * + * @image html border-effect.png + * @htmlonly + * <a href="border-effect.png">Full-size</a> + * @endhtmlonly + * @image rtf border-effect.png + * @image latex border-effect.eps "border effect" width=\textwidth + * + * @section Evas_Object_Image_Manipulation Manipulating pixels + * + * Evas image objects can be used to manipulate raw pixels in many + * ways. The meaning of the data in the pixel arrays depends on + * the image's color space, be warned (see next section). You can set + * your own data as an image's pixel data, fetch an image's pixel data + * for saving or altering, convert images between different color spaces + * and even advanced operations like setting a native surface as image + * objects' data. + * + * @section Evas_Object_Image_Color_Spaces Color spaces + * + * Image objects may return or accept "image data" in multiple + * formats. This is based on the color space of an object. Here is a + * rundown on formats: + * + * - #EVAS_COLORSPACE_ARGB8888: + * This pixel format is a linear block of pixels, starting at the + * top-left row by row until the bottom right of the image or pixel + * region. All pixels are 32-bit unsigned int with the high-byte + * being alpha and the low byte being blue in the format ARGB. Alpha + * may or may not be used by evas depending on the alpha flag of the + * image, but if not used, should be set to 0xff anyway. + * \n\n + * This colorspace uses premultiplied alpha. That means that R, G + * and B cannot exceed A in value. The conversion from + * non-premultiplied colorspace is: + * \n\n + * R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255; + * \n\n + * So 50% transparent blue is: 0x80000080. This is not + * "dark" - just 50% transparent. Values are 0 == black, 255 == + * solid or full red, green or blue. + * . + * - #EVAS_COLORSPACE_YCBCR422P601_PL: + * This is a pointer-list indirected set of YUV (YCbCr) pixel + * data. This means that the data returned or set is not actual + * pixel data, but pointers TO lines of pixel data. The list of + * pointers are first be N rows of pointers to the Y plane - + * pointing to the first pixel at the start of each row in the Y + * plane. N is the height of the image data in pixels. Each pixel in + * the Y, U and V planes is 1 byte exactly, packed. The next N / 2 + * pointers points to rows in the U plane, and the next N / 2 + * pointers points to the V plane rows. U and V planes are half + * the horizontal and vertical resolution of the Y plane. + * \n\n + * Row order is top to bottom and row pixels are stored left to + * right. + * \n\n + * There is a limitation that these images MUST be a multiple of 2 + * pixels in size horizontally or vertically. This is due to the U + * and V planes being half resolution. Also note that this assumes + * the itu601 YUV colorspace specification. This is defined for + * standard television and mpeg streams. HDTV may use the itu709 + * specification. + * \n\n + * Values are @c 0 to @c 255, indicating full or no signal in that plane + * respectively. + * . + * - #EVAS_COLORSPACE_YCBCR422P709_PL: + * Not implemented yet. + * . + * - #EVAS_COLORSPACE_RGB565_A5P: + * In the process of being implemented in one engine only. This may + * change. + * \n\n + * This is a pointer to image data for 16-bit half-word pixel data + * in 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), + * with the high-byte containing red and the low byte containing + * blue, per pixel. This data is packed row by row from the top-left + * to the bottom right. + * \n\n + * If the image has an alpha channel enabled there is an extra + * alpha plane after the color pixel plane. If not, then this data + * does not exist and should not be accessed in any way. This plane + * is a set of pixels with 1 byte per pixel defining the alpha + * values of all pixels in the image from the top-left to the bottom + * right of the image, row by row. Even though the values of the + * alpha pixels can be @c 0 to @c 255, only values @c 0 through to @c 32 are + * used, @c 32 being solid and 0 being transparent. + * \n\n + * RGB values can be @c 0 to @c 31 for red and blue and @c 0 to @c 63 for green, + * with @c 0 being black and @c 31 or @c 63 being full red, green or blue + * respectively. This colorspace is also pre-multiplied like + * EVAS_COLORSPACE_ARGB8888 so: + * \n\n + * R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32; + * . + * - #EVAS_COLORSPACE_GRY8: + * The image is just an alpha mask (8 bits per pixel). This is used + * for alpha masking. + * + * @remarks We do not guarantee any proper results if you create an Image object + * without setting the evas engine. + * + * @{ + */ + +/** + * @brief Callback of Evas Object Image Pixels + * @see evas_object_image_pixels_get_callback_set + */ +typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o); + +/** + * @brief Creates a new image object on the given Evas @a e canvas. + * + * @since_tizen 2.3 + * + * @remarks If you intend to @b display an image somehow in a GUI, + * besides binding it to a real image file or source (with + * evas_object_image_file_set(), for example), you have to tell + * this image object how to fill its space with the pixels it can get + * from the source. See evas_object_image_filled_add(), for a helper + * on the common case of scaling up an image source to the whole area + * of the image object. + * + * @remarks The following is an example: + * @code + * img = evas_object_image_add(canvas); + * evas_object_image_file_set(img, "/path/to/img", NULL); + * @endcode + * + * @param[in] e The given canvas + * @return The created image object handle + * + * @see evas_object_image_fill_set() + */ +EAPI Evas_Object *evas_object_image_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Creates a new image object that @b automatically scales its bound + * image to the object's area, on both axis. + * + * @since_tizen 2.3 + * + * @remarks This is a helper function around evas_object_image_add() and + * evas_object_image_filled_set(). It has the same effect of applying + * those functions in sequence, which is a very common use case. + * + * @remarks Whenever this object gets resized, the bound image is + * rescaled, too. + * + * @param[in] e The given canvas + * @return The created image object handle + * + * @see evas_object_image_add() + * @see evas_object_image_filled_set() + * @see evas_object_image_fill_set() + */ +EAPI Evas_Object *evas_object_image_filled_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Sets the data for an image from memory to be loaded. + * + * @details This function is the same as evas_object_image_file_set() but the file to be loaded + * may exist at an address in memory (the data for the file, not the filename + * itself). The @a data at the address is copied and stored for future use, so + * no @a data needs to be kept after this call is made. It is managed and + * freed for you when no longer needed. The @a size is limited to 2 gigabytes + * in size, and must be greater than @c 0. A @c NULL @a data pointer is also + * invalid. Set the filename to @c NULL to reset to empty state and have the + * image file data freed from memory using evas_object_image_file_set(). + * + * @since_tizen 2.3 + * + * @remarks The @a format is optional (pass @c NULL if you do not need/use it). It is + * used to help Evas guess better which loader to use for the data. It may + * simply be the "extension" of the file as it would normally be on disk + * such as "jpg", "png", and "gif". + * + * @param[in] obj The given image object + * @param[in] data The image file data address + * @param[in] size The size of the image file data in bytes + * @param[in] format The format of the file (optional), \n + * otherwise set @c NULL + * @param[in] key The image key in file, \n + * otherwise set @c NULL + */ +EAPI void evas_object_image_memfile_set(Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the source file from where an image object must fetch the real + * image data (it may be an Eet file, besides pure image ones). + * + * @since_tizen 2.3 + * + * @remarks If the file supports multiple data stored in it (as Eet files do), + * you can specify the key to be used as the index of the image in + * this file. + * + * @remarks The following is an example: + * @code + * img = evas_object_image_add(canvas); + * evas_object_image_file_set(img, "/path/to/img", NULL); + * err = evas_object_image_load_error_get(img); + * if (err != EVAS_LOAD_ERROR_NONE) + * { + * fprintf(stderr, "could not load image '%s'. error string is \"%s\"\n", + * valid_path, evas_load_error_str(err)); + * } + * else + * { + * evas_object_image_fill_set(img, 0, 0, w, h); + * evas_object_resize(img, w, h); + * evas_object_show(img); + * } + * @endcode + * + * @param[in] obj The given image object + * @param[in] file The image file path + * @param[in] key The image key in @a file (if its an Eet one), \n + * otherwise set @c NULL + */ +EAPI void evas_object_image_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the source file from where an image object is to fetch the + * real image data (it may be an Eet file, besides pure image ones). + * + * @since_tizen 2.3 + * + * @remarks You must @b not modify the strings on the returned pointers. + * + * @remarks Use @c NULL pointers on the file components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given image object + * @param[out] file The location to store the image file path + * @param[out] key The location to store the image key (if @a file is an Eet one) + */ +EAPI void evas_object_image_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the dimensions for an image object's border, a region which @b + * is not scaled together with its center ever. + * + * @since_tizen 2.3 + * + * @remarks When Evas is rendering, an image source may be scaled to fit the + * size of its image object. This function sets an area from the + * borders of the image inwards which is @b not to be scaled. This + * function is useful for making frames and for widget theming, where, + * for example, buttons may be of varying sizes, but their border size + * must remain constant. + * + * @remarks The units used for @a l, @a r, @a t and @a b are canvas units. + * + * @remarks The border region itself @b may be scaled by the + * evas_object_image_border_scale_set() function. + * + * @remarks By default, image objects have no borders set, i. e. @c l, @c + * r, @c t and @c b start as @c 0. + * + * @remarks See the following figures for visual explanation:\n + * + * @image html image-borders.png + * @htmlonly + * <a href="image-borders.png">Full-size</a> + * @endhtmlonly + * @image latex image-borders.eps "image borders" width=\textwidth + * + * @image html border-effect.png + * @htmlonly + * <a href="border-effect.png">Full-size</a> + * @endhtmlonly + * @image rtf border-effect.png + * @image latex border-effect.eps "border effect" width=\textwidth + * + * @param[in] obj The given image object + * @param[in] l The border's left width + * @param[in] r The border's right width + * @param[in] t The border's top width + * @param[in] b The border's bottom width + * + * @see evas_object_image_border_get() + * @see evas_object_image_border_center_fill_set() + */ +EAPI void evas_object_image_border_set(Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the dimensions for an image object's border, a region + * which @b is not scaled together with its center ever. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the border components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given image object + * @param[out] l The location to store the border's left width in + * @param[out] r The location to store the border's right width in + * @param[out] t The location to store the border's top width in + * @param[out] b The location to store the border's bottom width in + * + * @see evas_object_image_border_set() for more details. + */ +EAPI void evas_object_image_border_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1); + +/** + * @brief Sets @b how the center part of the given image object (not the + * borders) should be drawn when Evas is rendering it. + * + * @details This function sets how the center part of the image object's source + * image is to be drawn, which must be one of the values in + * #Evas_Border_Fill_Mode. By center we mean the complementary part of + * that defined by evas_object_image_border_set(). This one is very + * useful for making frames and decorations. You would most probably + * also be using a filled image (as in evas_object_image_filled_set()) + * to use as a frame. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] fill The fill mode of the center region of @a obj (a value in + * #Evas_Border_Fill_Mode) + * + * @see evas_object_image_border_center_fill_get() + */ +EAPI void evas_object_image_border_center_fill_set(Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1); + +/** + * @brief Gets @b how the center part of the given image object (not the + * borders) is to be drawn when Evas is rendering it. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return fill The fill mode of the center region of @a obj (a value in + * #Evas_Border_Fill_Mode) + * + * @see evas_object_image_fill_set() + */ +EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether the image object's fill property should track the + * object's size. + * + * @since_tizen 2.3 + * + * @remarks If @a setting is #EINA_TRUE, then every evas_object_resize() + * @b automatically triggers a call to evas_object_image_fill_set() + * with the that new size (and @c 0, @c 0 as source image's origin), + * so the bound image fills the whole object's area. + * + * @param[in] obj The given image object + * @param[in] setting Set #EINA_TRUE to make the fill property follow object size, \n + * otherwise set #EINA_FALSE + * + * @see evas_object_image_filled_add() + * @see evas_object_image_fill_get() + */ +EAPI void evas_object_image_filled_set(Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the image object's fill property should track the + * object's size. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return #EINA_TRUE if it is tracking, \n + * otherwise #EINA_FALSE if it is not tracking (and + * evas_object_fill_set() must be called manually) + * + * @see evas_object_image_filled_set() for more information + */ +EAPI Eina_Bool evas_object_image_filled_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the scaling factor (multiplier) for the borders of an image object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] scale The scale factor (default is @c 1.0 - i.e. no scaling) + * + * @see evas_object_image_border_set() + * @see evas_object_image_border_scale_get() + */ +EAPI void evas_object_image_border_scale_set(Evas_Object *obj, double scale); + +/** + * @brief Gets the scaling factor (multiplier) for the borders of an image object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return The scale factor set for its borders + * + * @see evas_object_image_border_set() + * @see evas_object_image_border_scale_set() + */ +EAPI double evas_object_image_border_scale_get(const Evas_Object *obj); + +/** + * @brief Sets how to fill an image object's drawing rectangle given the + * (real) image bound to it. + * + * @since_tizen 2.3 + * + * @remarks Note that if @a w or @a h are smaller than the dimensions of + * @a obj, the displayed image is @b tiled around the object's + * area. To have only one copy of the bound image drawn, @a x and @a y + * must be @c 0 and @a w and @a h need to be the exact width and height + * of the image object itself, respectively. + * + * @remarks See the following image to better understand the effects of this + * call. On this diagram, both image object and original image source + * have @c a x @c a dimensions and the image itself is a circle, with + * empty space around it: + * + * @image html image-fill.png + * @image rtf image-fill.png + * @image latex image-fill.eps + * + * @remarks The default values for the fill parameters are @a x = 0, + * @a y = 0, @a w = 0 and @a h = 0. Thus, if you are not using the + * evas_object_image_filled_add() helper and want your image + * displayed, you have to set valid values with this function on + * your object. + * + * @remarks evas_object_image_filled_set() is a helper function which + * @b overrides the values set here automatically, for you, in a + * given way. + * + * @param[in] obj The given image object to operate on + * @param[in] x The x coordinate (from the top left corner of the bound + * image) to start drawing from + * @param[in] y The y coordinate (from the top left corner of the bound + * image) to start drawing from + * @param[in] w The width the bound image is displayed at + * @param[in] h The height the bound image is displayed at + */ +EAPI void evas_object_image_fill_set(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets how an image object is to fill its drawing rectangle, + * given the (real) image bound to it. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the fill components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given image object + * @param[out] x The location to store the x coordinate (from the top left + * corner of the bound image) to start drawing from + * @param[out] y The location to store the y coordinate (from the top left + * corner of the bound image) to start drawing from + * @param[out] w The location to store the width the bound image is to be + * displayed at + * @param[out] h The location to store the height the bound image is to be + * displayed at + * + * See @ref evas_object_image_fill_set() for more details. + */ +EAPI void evas_object_image_fill_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the tiling mode for the given evas image object's fill. + * + * @since_tizen 2.3 + * + * @param[in] obj The given evas image object + * @param[in] spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT, + * EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD. + */ +EAPI void evas_object_image_fill_spread_set(Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the spread (tiling mode) for the given image object's fill. + * + * @since_tizen 2.3 + * + * @param[in] obj The given evas image object + * @return The current spread mode of the image object + */ +EAPI Evas_Fill_Spread evas_object_image_fill_spread_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the size of the given image object. + * + * @details This function scales down or crops the image so that it is + * treated as if it were at the given size. If the size given is + * smaller than the image, it is cropped. If the size given is + * larger, then the image is treated as if it were in the upper + * left hand corner of a larger image that is otherwise transparent. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] w The new width of the image + * @param[in] h The new height of the image + */ +EAPI void evas_object_image_size_set(Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the size of the given image object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[out] w The location to store the width of the image in, or @c NULL + * @param[out] h The location to store the height of the image in, or @c NULL + * + * See @ref evas_object_image_size_set() for more details. + */ +EAPI void evas_object_image_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the row stride of the given image object. + * + * @since_tizen 2.3 + * + * @remarks The row stride is the number of bytes between the start of a row + * and the start of the next row for image data. + * + * @param[in] obj The given image object + * @return The stride of the image (<b>in bytes</b>) + */ +EAPI int evas_object_image_stride_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets a number representing any error that occurred during the + * last loading of the given image object's source image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return A value giving the last error that occurred \n + * It should be a #Evas_Load_Error value. #EVAS_LOAD_ERROR_NONE + * is returned if there is no error. + */ +EAPI Evas_Load_Error evas_object_image_load_error_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the raw image data of the given image object. + * + * @since_tizen 2.3 + * + * @remarks Note that the raw data must be of the same size (see + * evas_object_image_size_set(), which has to be called @b before this + * one) and colorspace (see evas_object_image_colorspace_set()) of the + * image. If data is @c NULL, the current image data is + * freed. Naturally, if one does not set an image object's data + * manually, it still has one, allocated by Evas. + * + * @param[in] obj The given image object + * @param[in] data The raw data, or @c NULL + * + * @see evas_object_image_data_get() + */ +EAPI void evas_object_image_data_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Gets a pointer to the raw image data of the given image object. + * + * @details This function returns a pointer to an image object's internal pixel + * buffer, for reading only or read/write. If you request it for + * writing, the image is marked as dirty so that it gets redrawn at + * the next update. + * + * @since_tizen 2.3 + * + * @remarks Each time you call this function on an image object, its data + * buffer has an internal reference counter + * incremented. Decrement it back by using + * evas_object_image_data_set(). This is specially important for the + * directfb Evas engine. + * + * @remarks This is best suited for when you want to modify an existing image, + * without changing its dimensions. + * + * @remarks The contents' format returned by it depend on the color + * space of the given image object. + * + * @remarks You may want to use evas_object_image_data_update_add() to + * inform data changes, if you did any. + * + * @param[in] obj The given image object + * @param[in] for_writing Set #EINA_TRUE to set retrieved data as modifiable, \n + * otherwise #EINA_FALSE to not set it as modifiable + * @return The raw image data + * + * @see evas_object_image_data_set() + */ +EAPI void *evas_object_image_data_get(const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Converts the raw image data of the given image object to the + * specified colorspace. + * + * @since_tizen 2.3 + * + * @remarks Note that this function does not modify the raw image data. If the + * requested colorspace is the same as the image colorspace nothing is + * done and @c NULL is returned. You should use + * evas_object_image_colorspace_get() to check the current image + * colorspace. + * + * + * @param[in] obj The given image object + * @param[in] to_cspace The colorspace to which the image raw data is converted + * + * @see @ref evas_object_image_colorspace_get + */ +EAPI void *evas_object_image_data_convert(Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Replaces the raw image data of the given image object. + * + * @details This function lets the application replace an image object's + * internal pixel buffer with an user-allocated one. For best results, + * you should generally first call evas_object_image_size_set() with + * the width and height for the new buffer. + * + * @since_tizen 2.3 + * + * @remarks This call is best suited for when you are using image data with + * different dimensions than the existing image data, if any. If you + * only need to modify the existing image in some fashion, then using + * evas_object_image_data_get() is probably what you are after. + * + * @remarks Note that the caller is responsible for freeing the buffer when + * finished with it, as user-set image data is not automatically + * freed when the image object is deleted. + * + * @param[in] obj The given image object + * @param[in] data The raw data to replace + * + * @see evas_object_image_data_get() + */ +EAPI void evas_object_image_data_copy_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Marks a sub-region of the given image object to be redrawn. + * + * @details This function schedules a particular rectangular region of an image + * object to be updated (redrawn) at the next rendering cycle. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] x The X-offset of the region to be updated + * @param[in] y The Y-offset of the region to be updated + * @param[in] w The width of the region to be updated + * @param[in] h The height of the region to be updated + */ +EAPI void evas_object_image_data_update_add(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Enables or disables alpha channel usage on the given image object. + * + * @details This function sets a flag on an image object indicating whether or + * not to use alpha channel data. A value of #EINA_TRUE makes it use + * alpha channel data, and #EINA_FALSE makes it ignore that + * data. Note that this has nothing to do with an object's color as + * manipulated by evas_object_color_set(). + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] has_alpha Set #EINA_TRUE to use alpha channel () data, \n + * otherwise set #EINA_FALSE to not use it + * + * @see evas_object_image_alpha_get() + */ +EAPI void evas_object_image_alpha_set(Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether alpha channel data is being used on the given + * image object. + * + * @details This function returns #EINA_TRUE if the image object's alpha + * channel is being used, or #EINA_FALSE otherwise. + * + * @since_tizen 2.3 + * + * @remarks See @ref evas_object_image_alpha_set() for more details. + * + * @param[in] obj The given image object + * @return #EINA_TRUE if the alpha channel data is being used, \n + * otherwise #EINA_FALSE if the alpha channel data is not being used + * + */ +EAPI Eina_Bool evas_object_image_alpha_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether to use high-quality image scaling algorithm on the + * given image object. + * + * @since_tizen 2.3 + * + * @remarks When enabled, a higher quality image scaling algorithm is used when + * scaling images to sizes other than the source image's original + * one. This gives better results but is more computationally expensive. + * + * @remarks Image objects get created originally with smooth scaling @b on. + * + * @param[in] obj The given image object + * @param[in] smooth_scale Set #EINA_TRUE to use smooth scale, \n + * otherwise set #EINA_FALSE to not use it + * + * @see evas_object_image_smooth_scale_get() + */ +EAPI void evas_object_image_smooth_scale_set(Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the given image object is using high-quality + * image scaling algorithm. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return #EINA_TRUE if smooth scale is being used, \n + * otherwise #EINA_FALSE if smooth scale is not being used + * + * @see evas_object_image_smooth_scale_set() + */ +EAPI Eina_Bool evas_object_image_smooth_scale_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Preloads an image object's image data in the background. + * + * @details This function requests the preload of the data image in the + * background. The work is queued before being processed (because + * there might be other pending requests of this type). + * + * @since_tizen 2.3 + * + * @remarks Whenever the image data gets loaded, Evas calls + * #EVAS_CALLBACK_IMAGE_PRELOADED registered callbacks on @a obj (that + * may be immediately, if the data is already preloaded before). + * + * @remarks Use #EINA_TRUE for @a cancel on scenarios where you do not need + * the image data preloaded anymore. + * + * @remarks Any evas_object_show() call after evas_object_image_preload() + * makes the latter to be @b cancelled, with the loading process + * now taking place @b synchronously (and, thus, blocking the return + * of the former until the image is loaded). It is highly advisable, + * then, that the user preload an image with it being @b hidden, just + * to be shown on the #EVAS_CALLBACK_IMAGE_PRELOADED event's callback. + * + * @param[in] obj The given image object + * @param[in] cancel Set #EINA_FALSE to add to the preloading work queue, \n + * otherwise set #EINA_TRUE to remove it (if it is issued before) + */ +EAPI void evas_object_image_preload(Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1); + +/** + * @brief Reloads an image object's image data. + * + * @details This function reloads the image data bound to image object @a obj. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + */ +EAPI void evas_object_image_reload(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Saves the given image object's contents to an (image) file. + * + * @since_tizen 2.3 + * + * @remarks The extension suffix on @a file determines which <b>saver + * module</b> Evas is to use when saving, thus the final file's + * format. If the file supports multiple data stored in it (Eet ones), + * you can specify the key to be used as the index of the image in it. + * + * @remarks You can specify some flags when saving the image. Currently + * acceptable flags are @c quality and @c compress. Eg.: @c + * "quality=100 compress=9" + * + * @param[in] obj The given image object + * @param[in] file The filename to be used to save the image (extension obligatory) + * @param[in] key The image key in the file (if an Eet one), \n + * otherwise @c NULL + * @param[in] flags String containing the flags to be used (@c NULL for none) + * @return #EINA_TRUE if the contents are saved successfully, \n + * otherwise #EINA_FALSE if it fails + */ +EAPI Eina_Bool evas_object_image_save(const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Imports pixels from given source to a given canvas image object. + * + * @details This function imports pixels from a given source to a given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas object + * @param[in] pixels The pixel's source to be imported + * @return #EINA_TRUE if success, otherwise #EINA_FALSE. + */ +EAPI Eina_Bool evas_object_image_pixels_import(Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the callback function to get pixels from a canvas' image. + * + * @details This sets a function to be the callback function that gets + * pixels from an image of the canvas. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @param[in] func The callback function + * @param[in] data The data pointer to be passed to @a func + * + */ +EAPI void evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pixels_Get_Cb func, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets whether the given image object is dirty and needs to request its pixels. + * + * @details This function only works properly if a callback for getting pixels has been set. + * + * @since_tizen 2.3 + * + * @remarks Use this function if you really know what you are doing. + * + * @param[in] obj The given image object + * @param[in] dirty Set #EINA_TRUE to mark the image object as dirty, \n + * otherwise set #EINA_FALSE to mark the image object as not dirty + * + * @see evas_object_image_pixels_get_callback_set() + */ +EAPI void evas_object_image_pixels_dirty_set(Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the given image object is dirty (needs to be redrawn). + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @return #EINA_TRUE if the image is dirty, \n + * otherwise #EINA_FALSE if the image is not dirty + */ +EAPI Eina_Bool evas_object_image_pixels_dirty_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the DPI resolution of an image object's source image. + * + * @details This function sets the DPI resolution of a given loaded canvas + * image. This is useful for the SVG image loader. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @param[in] dpi The new DPI resolution + * + * @see evas_object_image_load_dpi_get() + */ +EAPI void evas_object_image_load_dpi_set(Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the DPI resolution of a loaded image object in the canvas. + * + * @details This function returns the DPI resolution of the given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @return The DPI resolution of the given canvas image + * + * @see evas_object_image_load_dpi_set() for more details + */ +EAPI double evas_object_image_load_dpi_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the load size of a given image object's source image. + * + * @details This function sets a new geometry size for the given canvas image. + * The image will be loaded into memory as if it was the set size instead of + * the original size. + * + * @since_tizen 2.3 + * + * @remarks The size of a given image object's source image will be less than or + * equal to the size of @p w and @p h. + * + * @param[in] obj The given canvas object + * @param[in] w The new width of the image's load size + * @param[in] h The new height of the image's load size + * + * @see evas_object_image_load_size_get() + */ +EAPI void evas_object_image_load_size_set(Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the load size of a given image object's source image. + * + * @details This function gets the geometry size set manually for the given canvas image. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the size components that you are not + * interested in: they are ignored by the function. + * @p w and @p h will be set with the image's loading size only if + * the image's load size is set manually: if evas_object_image_load_size_set() + * has not been called, @p w and @p h will be set with 0. + * + * @param[in] obj The given image object + * @param[out] w The new width of the image's load size that is returned + * @param[out] h The new height of the image's load size that is returned + * + * @see evas_object_image_load_size_set() for more details + */ +EAPI void evas_object_image_load_size_get(const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the scale down factor of a given image object's source image, + * when loading it. + * + * @details This function sets the scale down factor of a given canvas + * image. This is useful for the SVG image loader. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @param[in] scale_down The scale down factor + * + * @see evas_object_image_load_scale_down_get() + */ +EAPI void evas_object_image_load_scale_down_set(Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the scale down factor of a given image object's source image, + * when loading it. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @return The scale down factor + * + * @see evas_object_image_load_scale_down_set() for more details + */ +EAPI int evas_object_image_load_scale_down_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets a selective region of the source image to load for the given image object. + * + * @details This function is useful when you are not showing all of an image's + * area on its image object. + * + * @since_tizen 2.3 + * + * @remarks The image loader for the image format in question has to + * support selective region loading in order to this function to take effect. + * + * @param[in] obj The given image object pointer + * @param[in] x The X-offset of the region to be loaded + * @param[in] y The Y-offset of the region to be loaded + * @param[in] w The width of the region to be loaded + * @param[in] h The height of the region to be loaded + * + * @see evas_object_image_load_region_get() + */ +EAPI void evas_object_image_load_region_set(Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the coordinates of a given image object's selective + * (source image) load region. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the coordinates that you are not interested + * in: they are ignored by the function. + * + * @param[in] obj The given image object pointer + * @param[out] x The X-offset of the region to be loaded + * @param[out] y The Y-offset of the region to be loaded + * @param[out] w The width of the region to be loaded + * @param[out] h The height of the region to be loaded + * + * @see evas_object_image_load_region_get() + */ +EAPI void evas_object_image_load_region_get(const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets whether the orientation information in the image file should be honored. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @param[in] enable Set #EINA_TRUE to honor the orientation information, \n + * otherwise #EINA_FALSE to not honor the orientation information + */ +EAPI void evas_object_image_load_orientation_set(Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the orientation information in the image file should be honored. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @return #EINA_TRUE if the orientation information is honored, \n + * otherwise #EINA_FALSE if it is not honored + */ +EAPI Eina_Bool evas_object_image_load_orientation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the colorspace of a given image of the canvas. + * + * @details This function sets the colorspace of given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @param[in] cspace The new color space + * + */ +EAPI void evas_object_image_colorspace_set(Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the colorspace of a given image of the canvas. + * + * @details This function returns the colorspace of given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @return The colorspace of the image + * + */ +EAPI Evas_Colorspace evas_object_image_colorspace_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the support state of a given image. + * + * @details This function returns the state of the region support of given image + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @return The region support state + */ +EAPI Eina_Bool evas_object_image_region_support_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the native surface of a given image of the canvas. + * + * @details This function sets a native surface of a given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @param[in] surf The new native surface + * + */ +EAPI void evas_object_image_native_surface_set(Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the native surface of a given image of the canvas. + * + * @details This function returns the native surface of a given canvas image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @return The native surface of the given canvas image + * + */ +EAPI Evas_Native_Surface *evas_object_image_native_surface_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the video surface linked to a given image of the canvas. + * + * @details This function links a video surface to a given canvas image. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @param[in] surf The new video surface + * + */ +EAPI void evas_object_image_video_surface_set(Evas_Object *obj, Evas_Video_Surface *surf) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the video surface linked to a given image of the canvas. + * + * @details This function returns the video surface linked to a given canvas image. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @return The video surface of the given canvas image + * + */ +EAPI const Evas_Video_Surface *evas_object_image_video_surface_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the scale hint of a given image of the canvas. + * + * @details This function sets the scale hint value of the given image object + * in the canvas, which affects how Evas is to cache scaled + * versions of its original source image. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @param[in] hint The scale hint \n + * A #Evas_Image_Scale_Hint value. + * + * @see evas_object_image_scale_hint_get() + */ +EAPI void evas_object_image_scale_hint_set(Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the scale hint of a given image of the canvas. + * + * @details This function returns the scale hint value of the given image + * object of the canvas. + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object pointer + * @return The scale hint value set on @a obj \n + * A #Evas_Image_Scale_Hint value. + * + * @see evas_object_image_scale_hint_set() for more details. + */ +EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the content hint setting of a given image object of the canvas. + * + * @details This function sets the content hint value of the given image of the + * canvas. For example, if you are on the GL engine and your driver + * implementation supports it, setting this hint to + * #EVAS_IMAGE_CONTENT_HINT_DYNAMIC makes it need @b zero copies + * at texture upload time, which is an "expensive" operation. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @param[in] hint The content hint value \n + * Valid values are defined in #Evas_Image_Content_Hint. + * + * @see evas_object_image_content_hint_get() + */ +EAPI void evas_object_image_content_hint_set(Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the content hint setting of a given image object of the canvas. + * + * @details This function returns the content hint value of the given image of + * the canvas. + * + * @since_tizen 2.3 + * + * @param[in] obj The given canvas pointer + * @return The content hint value set on it \n + * Valid values are define in #Evas_Image_Content_Hint. \n + * #EVAS_IMAGE_CONTENT_HINT_NONE means an error. + * + * @see evas_object_image_content_hint_set() + */ +EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Enables an image to be used as an alpha mask. + * + * @details This function sets flags, and discard any excess image data not used as an + * alpha mask. + * + * @since_tizen 2.3 + * + * @remarks Note that there is little point in using a image as alpha mask unless it has an + * alpha channel. + * + * @param[in] obj The object to use as an alpha mask + * @param[in] ismask Set #EINA_TRUE to use image as alphamask, + * otherwise #EINA_FALSE to not use image as alphamask + */ +EAPI void evas_object_image_alpha_mask_set(Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the source object on an image object to used as a @b proxy. + * + * @since_tizen 2.3 + * + * @remarks If an image object is set to behave as a @b proxy, it mirrors + * the rendering contents of a given @b source object in its drawing + * region, without affecting that source in any way. The source must + * be another valid Evas object. Other effects may be applied to the + * proxy, such as a map (see evas_object_map_set()) to create a + * reflection of the original object (for example). + * + * @remarks Any existing source object on @a obj is removed after this + * call. Setting @a src to @c NULL clears the proxy object (not in + * "proxy state" anymore). + * + * @remarks You cannot set a proxy as another proxy's source. + * + * @param[in] obj The proxy (image) object + * @param[in] src The source object to use for the proxy + * @return #EINA_TRUE if the source object is set successfully, \n + * otherwise #EINA_FALSE on error + * + * @see evas_object_image_source_get() + * @see evas_object_image_source_unset() + */ +EAPI Eina_Bool evas_object_image_source_set(Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current source object of an image object. + * + * @since_tizen 2.3 + * + * @param[in] obj The Image object + * @return The source object (if any), \n + * otherwise @c NULL if not in "proxy mode" or on errors + * + * @see evas_object_image_source_set() for more details + */ +EAPI Evas_Object *evas_object_image_source_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Clears the source object on a proxy image object. + * + * @details This function is equivalent to calling evas_object_image_source_set() with a + * @c NULL source. + * + * @since_tizen 2.3 + * + * @param[in] obj The Image object to clear source of + * @return #EINA_TRUE if the source object is cleared successfully, \n + * otherwise #EINA_FALSE on error + */ +EAPI Eina_Bool evas_object_image_source_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the source object to be visible. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @remarks If @a visible is set to #EINA_FALSE, the source object of the proxy (@a obj) + * is invisible. + * + * @remarks This function works differently to evas_object_show() and evas_object_hide(). + * Once the source object is hidden by evas_object_hide() then the proxy object is + * hidden as well. Actually in this case both objects are excluded from the + * Evas internal update circle. + * + * @remarks Using this method, you can toggle the visibility of a proxy's source + * object keeping the proxy visibility untouched. + * + * @param[in] obj The proxy (image) object + * @param[in] visible Set #EINA_TRUE to show the source object, \n + * otherwise set #EINA_FALSE to not show it + * + * @see evas_object_image_source_visible_get() + * @see evas_object_image_source_set() + * @see evas_object_show() + * @see evas_object_hide() + */ +EAPI void evas_object_image_source_visible_set(Evas_Object *obj, Eina_Bool visible) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the state of the source object visibility. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The proxy (image) object + * @return #EINA_TRUE if source object is visible, \n + * otherwise #EINA_FALSE + * + * @see evas_object_image_source_visible_set() + * @see evas_object_image_source_set() + * @see evas_object_show() + * @see evas_object_hide() + */ +EAPI Eina_Bool evas_object_image_source_visible_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Clips the proxy object with the source object's clipper. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The proxy (image) object + * @param[in] source_clip Set #EINA_TRUE if @a obj must be clipped by the source clipper, \n + * otherwise set #EINA_FALSE + * + * @see evas_object_clip_set() + * @see evas_object_image_source_set() + */ +EAPI void evas_object_image_source_clip_set(Evas_Object *obj, Eina_Bool source_clip) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether an object is clipped by source object's clipper. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The proxy (image) object + * @return #EINA_TRUE if source clip is enabled, + * otherwise #EINA_FALSE if source clip is not enabled + * + * @see evas_object_clip_set() + * @see evas_object_image_source_set() + * @see evas_object_image_source_clip_set() + */ +EAPI Eina_Bool evas_object_image_source_clip_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether a file extension is supported by @ref Evas_Object_Image. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks If file is a Eina_Stringshare, use @ref evas_object_image_extension_can_load_fast_get directly. + * + * @remarks This function is threadsafe. + * + * @param[in] file The file to check + * @return #EINA_TRUE if the file extension is supported, \n + * otherwise #EINA_FALSE if it is not supported + */ +EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file); + +/** + * @brief Checks whether a file extension is supported by @ref Evas_Object_Image. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks This function is threadsafe. + * @param[in] file The file to check \n + * It should be Eina_Stringshare. + * @return #EINA_TRUE if the file extension is supported, \n + * otherwise #EINA_FALSE if it is not supported + */ +EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file); + +/** + * @brief Checks whether an image object can be animated (have multiple frames). + * + * @details This function returns if the image file of an image object is capable of animation + * such as an animated gif file might. This is only useful to be called once + * the image object file has been set. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks The following is an example: + * @code + * extern Evas_Object *obj; + * + * if (evas_object_image_animated_get(obj)) + * { + * int frame_count; + * int loop_count; + * Evas_Image_Animated_Loop_Hint loop_type; + * double duration; + * + * frame_count = evas_object_image_animated_frame_count_get(obj); + * printf("This image has %d frames\n",frame_count); + * + * duration = evas_object_image_animated_frame_duration_get(obj,1,0); + * printf("Frame 1's duration is %f. You had better set object's frame to 2 after this duration using timer\n"); + * + * loop_count = evas_object_image_animated_loop_count_get(obj); + * printf("loop count is %d. You had better run loop %d times\n",loop_count,loop_count); + * + * loop_type = evas_object_image_animated_loop_type_get(obj); + * if (loop_type == EVAS_IMAGE_ANIMATED_HINT_LOOP) + * printf("You had better set frame like 1->2->3->1->2->3...\n"); + * else if (loop_type == EVAS_IMAGE_ANIMATED_HINT_PINGPONG) + * printf("You had better set frame like 1->2->3->2->1->2...\n"); + * else + * printf("Unknown loop type\n"); + * + * evas_object_image_animated_frame_set(obj,1); + * printf("You set image object's frame to 1. You can see frame 1\n"); + * } + * @endcode + * + * @param[in] obj The Image object + * @return #EINA_TRUE if @a obj supports animation, \n + * otherwise #EINA_FALSE if it does not support animation + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI Eina_Bool evas_object_image_animated_get(const Evas_Object *obj); + +/** + * @brief Gets the total number of frames of the image object. + * + * @details This returns the total number of frames the image object supports (if animated). + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The Image object + * @return The number of frames + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI int evas_object_image_animated_frame_count_get(const Evas_Object *obj); + +/** + * @brief Gets the kind of looping the image object does. + * + * @details This function returns the kind of looping the image object wants to do. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks If it returns @c EVAS_IMAGE_ANIMATED_HINT_LOOP, you should display frames in a sequence like: + * 1->2->3->1->2->3->1... + * If it returns @c EVAS_IMAGE_ANIMATED_HINT_PINGPONG, it is better to + * display frames in a sequence like: 1->2->3->2->1->2->3->1... + * The default type is EVAS_IMAGE_ANIMATED_HINT_LOOP. + * + * @param[in] obj The Image object + * @return The Loop type of the image object + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI Evas_Image_Animated_Loop_Hint evas_object_image_animated_loop_type_get(const Evas_Object *obj); + +/** + * @brief Gets the number of times the animation of the object loops. + * + * @details This function returns loop count of image. The loop count is the number of times + * the animation plays fully from first to last frame until the animation + * should stop (at the final frame). + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks If @c 0 is returned, then looping should happen indefinitely (no limit to + * the number of times it loops). + * + * @param[in] obj The Image object + * @return The number of loop of an animated image object + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI int evas_object_image_animated_loop_count_get(const Evas_Object *obj); + +/** + * @brief Gets the duration of a sequence of frames. + * + * @details This function returns the total duration that the specified sequence of frames should + * take in seconds. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks If you set start_frame to 1 and frame_num 0, you get frame 1's duration. + * If you set start_frame to 1 and frame_num 1, you get frame 1's duration + + * frame2's duration. + * + * @param[in] obj The Image object + * @param[in] start_frame The first frame + * @param[in] fram_num The number of frames in the sequence + * @return The duraction of a sequence of frames. + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI double evas_object_image_animated_frame_duration_get(const Evas_Object *obj, int start_frame, int fram_num); + +/** + * @brief Sets the frame to the current frame of an image object. + * + * @details This function sets the image object's current frame to frame_num + * with 1 being the first frame. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given image object + * @param[in] frame_num The index of current frame + * + * @see evas_object_image_animated_get() + * @see evas_object_image_animated_frame_count_get() + * @see evas_object_image_animated_loop_type_get() + * @see evas_object_image_animated_loop_count_get() + * @see evas_object_image_animated_frame_duration_get() + * @see evas_object_image_animated_frame_set() + */ +EAPI void evas_object_image_animated_frame_set(Evas_Object *obj, int frame_num); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Text Text Object Functions + * @ingroup Evas_Object_Specific + * + * @brief This group provides functions that operate on single line, single style text objects. + * + * For multiline and multiple style text, see @ref Evas_Object_Textblock. + * + * @remarks We do not guarantee any proper results if you create a Text object + * without setting the evas engine. + * + * @{ + */ + +/* Definition for basic styles (4 bits allocated use 0->10 now, 5 left) */ +#define EVAS_TEXT_STYLE_MASK_BASIC 0xf + +/** + * @brief Definition for text style type creation macro. Use style types on the 's' + * arguments, being 'x' your style variable. + */ +#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \ + do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0) + +#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4) + +/** + * @brief Definition for text style type creation macro. This one imposes shadow + * directions on the style type variable -- use the @c + * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* values on 's', incrementally. + */ +#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \ + do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0) + +/** + * Types of styles to be applied on text objects. + * The @c EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with + * others imposing shadow, to change shadow's direction + */ +typedef enum _Evas_Text_Style_Type +{ + EVAS_TEXT_STYLE_PLAIN, /**< Plain, standard text */ + EVAS_TEXT_STYLE_SHADOW, /**< Text with shadow underneath */ + EVAS_TEXT_STYLE_OUTLINE, /**< Text with an outline */ + EVAS_TEXT_STYLE_SOFT_OUTLINE, /**< Text with a soft outline */ + EVAS_TEXT_STYLE_GLOW, /**< Text with a glow effect */ + EVAS_TEXT_STYLE_OUTLINE_SHADOW, /**< Text with both outline and shadow effects */ + EVAS_TEXT_STYLE_FAR_SHADOW, /**< Text with (far) shadow underneath */ + EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW, /**< Text with outline and soft shadow effects combined */ + EVAS_TEXT_STYLE_SOFT_SHADOW, /**< Text with (soft) shadow underneath */ + EVAS_TEXT_STYLE_FAR_SOFT_SHADOW, /**< Text with (far soft) shadow underneath */ + // TIZEN ONLY (20131106) : Font effect for tizen. + EVAS_TEXT_STYLE_TIZEN_GLOW_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_HOME_SCREEN_ICON */ + EVAS_TEXT_STYLE_TIZEN_SOFT_GLOW_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_DYNAMIC_BOX_IMPORT_IMAGE */ + EVAS_TEXT_STYLE_TIZEN_SHADOW, /** Tizen::Graphics::Effect::EFFECT_FOR_TEXT_ON_DYNAMIC_BOX_IMAGE */ + ////////////////////////////// + + /* OR these to modify shadow direction (3 bits needed) */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< Shadow growing to bottom right */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< Shadow growing to the bottom */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< Shadow growing to bottom left */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< Shadow growing to the left */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< Shadow growing to top left */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< Shadow growing to the top */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< Shadow growing to top right */ + EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< Shadow growing to the right */ +} Evas_Text_Style_Type; + +/** + * @brief Creates a new text object on the provided canvas. + * + * @since_tizen 2.3 + * + * @remarks Text objects are for simple, single line text elements. If you want + * more elaborated text blocks, see @ref Evas_Object_Textblock. + * + * @param[in] e The canvas to create the text object on + * @return A pointer to a new text object on success, \n + * otherwise @c NULL on error + * + * @see evas_object_text_font_source_set() + * @see evas_object_text_font_set() + * @see evas_object_text_text_set() + */ +EAPI Evas_Object *evas_object_text_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Sets the font (source) file to be used on a given text object. + * + * @details This function allows the font file to be explicitly set for a given + * text object, overriding system lookup, which first occurs in + * the given file's contents. + * + * @since_tizen 2.3 + * + * @param[in] obj The text object to set font for + * @param[in] font The font file's path + * + * @see evas_object_text_font_get() + */ +EAPI void evas_object_text_font_source_set(Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the font file's path which is being used on a given text object. + * + * @since_tizen 2.3 + * + * @param[in] obj The text object to set the font for + * @return The font file's path + * + * @see evas_object_text_font_get() for more details + */ +EAPI const char *evas_object_text_font_source_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the font family and size on a given text object. + * + * @details This function allows the font name and size of a text object to be + * set. The @a font string has to follow fontconfig's convention on + * naming fonts, as it is the underlying library used to query system + * fonts by Evas (see the @c fc-list command's output, on your system, + * to get an idea). + * + * @since_tizen 2.3 + * + * @param[in] obj The text object to set font for + * @param[in] font The font (family) name + * @param[in] size The font size, in points + * + * @see evas_object_text_font_get() + * @see evas_object_text_font_source_set() + */ +EAPI void evas_object_text_font_set(Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the font family and size in use on a given text object. + * + * @details This function allows the font name and size of a text object to be + * queried. Be aware that the font name string is still owned by Evas + * and should @b not have free() called on it by the caller of the + * function. + * + * @since_tizen 2.3 + * + * @param[in] obj The evas text object to query for font information + * @param[out] font A pointer to the location to store the font name in + * @param[out] size A pointer to the location to store the font size in + * + * @see evas_object_text_font_set() + */ +EAPI void evas_object_text_font_get(const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the text string to be displayed by the given text object. + * + * @since_tizen 2.3 + * + * @param[in] obj The text object to set text string on + * @param[in] text The text string to display on it + * + * @see evas_object_text_text_get() + */ +EAPI void evas_object_text_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the text string currently being displayed by the given text object. + * + * @since_tizen 2.3 + * + * @remarks Do not free() the return value. + * + * @param[in] obj The given text object + * @return The text string currently being displayed on it + * + * @see evas_object_text_text_set() + */ +EAPI const char *evas_object_text_text_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the BiDi delimiters used in the textblock. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks BiDi delimiters are use for in-paragraph separation of bidi segments. This + * is useful for example in recipients fields of e-mail clients where bidi + * oddities can occur when mixing RTL and LTR. + * + * @param[in] obj The given text object + * @param[in] delim A null terminated string of delimiters, for example ",|" + */ +EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim); + +/** + * @brief Gets the BiDi delimiters used in the textblock. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks BiDi delimiters are use for in-paragraph separation of bidi segments. This + * is useful for example in recipients fields of e-mail clients where bidi + * oddities can occur when mixing RTL and LTR. + * + * @param[in] obj The given text object + * @return A null terminated string of delimiters, for example, ",|", \n + * otherwise @c NULL if empty + */ +EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj); + +/** + * @brief Sets the ellipsis that should be used for the text object. + * + * @details This is a value between @c 0.0 and @c 1.0 indicating the position of the text + * to be shown. @c 0.0 means the start is shown and the end trimmed, @c 1.0 + * means the beginning is trimmed and the end is shown, and any value + * in between causes ellipsis to be added in both the end of the text and the + * requested part to be shown. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @remarks @c -1.0 means ellipsis is turned off. + * + * @param[in] obj The given text object + * @param[in] ellipsis The ellipsis + */ +EAPI void evas_object_text_ellipsis_set(Evas_Object *obj, double ellipsis); + +/** + * @brief Gets the ellipsis currently set on the text object. + * @since 1.8 + * + * @since_tizen 2.3 + * + * @param[in] obj The given text object + * @return The ellipsis set on the text object + * @see evas_object_text_ellipsis_set() + */ +EAPI double evas_object_text_ellipsis_get(const Evas_Object *obj); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_ascent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_descent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_max_ascent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_max_descent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_vert_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI Evas_Coord evas_object_text_inset_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the position and dimension information of a character within a text @c Evas_Object. + * + * @details This function is used to obtain the X, Y, width and height of a the character + * located at @a pos within the @c Evas_Object @a obj. @a obj must be a text object + * as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx, + * @a cy, @a cw, @a ch) may be @c NULL in which case no value is assigned to that + * parameter. + * + * @since_tizen 2.3 + * + * @param[in] obj The text object to retrieve position information for + * @param[in] pos The character position to request co-ordinates for + * @param[out] cx A pointer to an @c Evas_Coord to store the X value in (can be @c NULL) + * @param[out] cy A pointer to an @c Evas_Coord to store the Y value in (can be @c NULL) + * @param[out] cw A pointer to an @c Evas_Coord to store the Width value in (can be @c NULL) + * @param[out] ch A pointer to an @c Evas_Coord to store the Height value in (can be @c NULL) + * @return #EINA_FALSE if the information is obtained successfully, + * otherwise #EINA_TRUE on error + */ +EAPI Eina_Bool evas_object_text_char_pos_get(const Evas_Object *obj, int pos, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI int evas_object_text_char_coords_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the logical position of the last char in the text up to the given position. \n + * This is NOT the position of the last char because of the possibility of RTL in the text. + * + * @since_tizen 2.3 + * + * @param[in] obj The text object + * @param[in] x The X co-ordinate + * @param[in] y The Y co-ordinate + * @return The logical The positoin of the last char in the text up to the given position + */ +EAPI int evas_object_text_last_up_to_pos(const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the style on use on the given text object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given text object to set style on + * @return The style type in use + * + * @see evas_object_text_style_set() for more details. + */ +EAPI Evas_Text_Style_Type evas_object_text_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the style to apply on the given text object. + * + * @since_tizen 2.3 + * + * @remarks Valid text object styles are defined in #Evas_Text_Style_Type. + * Some of those values are combinations of more than one style, + * and some account for the direction of the rendering of shadow effects. + * + * @remarks You can use the helper macros #EVAS_TEXT_STYLE_BASIC_SET and + * #EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET to assemble a style value. + * + * @remarks The following figure illustrates the text styles: + * + * @image html text-styles.png + * @image rtf text-styles.png + * @image latex text-styles.eps + * + * @param[in] obj The given text object to set style on + * @param[in] type The style type + * + * @see evas_object_text_style_get() + * @see evas_object_text_shadow_color_set() + * @see evas_object_text_outline_color_set() + * @see evas_object_text_glow_color_set() + * @see evas_object_text_glow2_color_set() + */ +EAPI void evas_object_text_style_set(Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the shadow color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Shadow effects, which are fading colors decorating the text + * underneath it, are just shown if the object is set to one of + * the following styles: + * - #EVAS_TEXT_STYLE_SHADOW + * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW + * - #EVAS_TEXT_STYLE_FAR_SHADOW + * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW + * - #EVAS_TEXT_STYLE_SOFT_SHADOW + * - #EVAS_TEXT_STYLE_FAR_SOFT_SHADOW + * + * @remarks You can also change the direction where the shadow grows to, with + * evas_object_text_style_set(). + * + * @param[in] obj The given Evas text object + * @param[in] r The red component of the given color + * @param[in] g The green component of the given color + * @param[in] b The blue component of the given color + * @param[in] a The alpha component of the given color + * + * @see evas_object_text_shadow_color_get() + */ +EAPI void evas_object_text_shadow_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the shadow color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the color components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas text object + * @param[out] r The pointer to variable to hold the red component of the given color + * @param[out] g The pointer to variable to hold the green component of the given color + * @param[out] b The pointer to variable to hold the blue component of the given color + * @param[out] a The pointer to variable to hold the alpha component of the given color + * + * @see evas_object_text_shadow_color_set() for more details. + */ +EAPI void evas_object_text_shadow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the glow color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Glow effects, which are glowing colors decorating the text's + * surroundings, are shown if the object is set to the + * #EVAS_TEXT_STYLE_GLOW style. + * + * @remarks Glow effects are placed from a short distance of the text + * itself, but no touching it. For glowing effects right on the + * borders of the glyphs, see 'glow 2' effects + * (evas_object_text_glow2_color_set()). + * + * @param[in] obj The given Evas text object + * @param[in] r The red component of the given color + * @param[in] g The green component of the given color + * @param[in] b The blue component of the given color + * @param[in] a The alpha component of the given color + * + * @see evas_object_text_glow_color_get() + */ +EAPI void evas_object_text_glow_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the glow color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the color components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas text object. + * @param[out] r The pointer to variable to hold the red component of the given color + * @param[out] g The pointer to variable to hold the green component of the given color + * @param[out] b The pointer to variable to hold the blue component of the given color + * @param[out] a The pointer to variable to hold the alpha component of the given color + * + * @see evas_object_text_glow_color_set() for more details. + */ +EAPI void evas_object_text_glow_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the 'glow 2' color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks 'Glow 2' effects, which are glowing colors decorating the text's + * (immediate) surroundings, are shown if the object is set + * to the #EVAS_TEXT_STYLE_GLOW style. See also + * evas_object_text_glow_color_set(). + * + * @param[in] obj The given Evas text object + * @param[in] r The red component of the given color + * @param[in] g The green component of the given color + * @param[in] b The blue component of the given color + * @param[in] a The alpha component of the given color + * + * @see evas_object_text_glow2_color_get() + */ +EAPI void evas_object_text_glow2_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the 'glow 2' color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the color components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas text object + * @param[out] r The pointer to variable to hold the red component of the given color + * @param[out] g The pointer to variable to hold the green component of the given color + * @param[out] b The pointer to variable to hold the blue component of the given color + * @param[out] a The pointer to variable to hold the alpha component of the given color + * + * @see evas_object_text_glow2_color_set() for more details. + */ +EAPI void evas_object_text_glow2_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the outline color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Outline effects (colored lines around text glyphs) are just + * shown if the object is set to one of the following styles: + * - #EVAS_TEXT_STYLE_OUTLINE + * - #EVAS_TEXT_STYLE_SOFT_OUTLINE + * - #EVAS_TEXT_STYLE_OUTLINE_SHADOW + * - #EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW + * + * @param[in] obj The given Evas text object + * @param[in] r The red component of the given color + * @param[in] g The green component of the given color + * @param[in] b The blue component of the given color + * @param[in] a The alpha component of the given color + * + * @see evas_object_text_outline_color_get() + */ +EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the outline color for the given text object. + * + * @since_tizen 2.3 + * + * @remarks Use @c NULL pointers on the color components that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The given Evas text object + * @param[out] r The pointer to the variable to hold the red component of the given color + * @param[out] g The pointer to the variable to hold the green component of the given color + * @param[out] b The pointer to the variable to hold the blue component of the given color + * @param[out] a The pointer to the variable to hold the alpha component of the given color + * + * @see evas_object_text_outline_color_set() for more details. + */ +EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the text style pad of a text object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given text object + * @param[out] l The left pad (or @c NULL) + * @param[out] r The right pad (or @c NULL) + * @param[out] t The top pad (or @c NULL) + * @param[out] b The bottom pad (or @c NULL) + * + */ +EAPI void evas_object_text_style_pad_get(const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the direction of the text currently being displayed in the text object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given evas text object + * @return The direction of the text + */ +EAPI Evas_BiDi_Direction evas_object_text_direction_get(const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Sets an Evas filter program on this Text Object. + * @since 1.9. Backported for Tizen (1.7.99). + * + * @since_tizen 2.3 + * + * @remarks If the program fails to compile (syntax error, invalid buffer name, etc...), + * the standard text effects are applied instead (SHADOW, etc...). + * + * @remarks EXPERIMENTAL FEATURE. This is an unstable API, please use this only for testing purposes. + * + * @param[in] obj The given evas text object + * @param[in] arg The program code, as defined by the "Evas filters script language". + * Pass @c NULL to remove the former program and + * switch back to the standard text effects. + * + * @internal + * @see @ref evasfiltersref "Evas filters reference" + * @endinternal + */ +EAPI void evas_object_text_filter_program_set(Evas_Object *obj, const char *arg); + +/** + * @brief Binds an object to use as a mask or texture with Evas Filters. This + * automatically creates a new RGBA buffer containing the source object's + * pixels (as it is rendered). + * @since 1.9. Backported for Tizen (1.7.99). + * + * @since_tizen 2.3 + * + * @remarks EXPERIMENTAL FEATURE. This is an unstable API, please use this only for testing purposes. + * + * @param[in] obj The given evas object + * @param[in] name The object name as used in the program code + * @param[in] source The evas object to use through proxy rendering + * + * @see evas_obj_text_filter_program_set + * @internal + * @see @ref evasfiltersref "Evas filters reference" + * @endinternal + */ +EAPI void evas_object_text_filter_source_set(Evas_Object *obj, const char *name, Evas_Object *source); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Textblock Textblock Object Functions + * @ingroup Evas_Object_Specific + * + * @brief This group provides functions used to create and manipulate textblock objects. + * + * Unlike @ref Evas_Object_Text, these handle complex text, doing multiple + * styles and multiline text based on HTML-like tags. Of these extra + * features are heavier on memory and processing cost. + * + * @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial + * + * This part explains about the textblock object's API and proper usage. + * The main user of the textblock object is the edje entry object in Edje. So + * that is a good place to learn from, but this document is more than + * enough. If it is not, please contact the developer to update it. + * + * @subsection textblock_intro Introduction + * The textblock object is, as implied, an object that can show big chunks of + * text. Textblock supports many features including: Text formatting, automatic + * and manual text alignment, embedding items (for example icons) and more. + * Textblock has three important parts: the text paragraphs, the format nodes, + * and the cursors. + * + * You can use markup to format text, for example: "<font_size=50>Big!</font_size>". + * You can also put more than one style directive in one tag: + * "<font_size=50 color=#F00>Big and Red!</font_size>". + * Please notice that we used "</font_size>" although the format also included + * color. This is because the first format determines the matching closing tag's + * name. You can also use anonymous tags, like: "<font_size=30>Big</>" which + * just pop any type of format, but it is advised to use the named alternatives + * instead. + * + * @subsection textblock_cursors Textblock Object Cursors + * A textblock cursor is the data type that represents + * a position in a textblock. Each cursor contains information about the + * paragraph it points to, the position in that paragraph, and the object itself. + * Cursors register to textblock objects upon creation. This means that once + * you created a cursor, it belongs to a specific object and you cannot, for example, + * copy a cursor "into" a cursor of a different object. Registered cursors + * also have the added benefit of updating automatically upon textblock changes, + * this means that if you have a cursor pointing to a specific character, it + * still points to it even after you change the whole object completely (as long + * as the char is not deleted). This is not possible without updating, because + * as mentioned, each cursor holds a character position. There are many + * functions that handle cursors. See the evas_textblock_cursor* + * functions. For creation and deletion of cursors, see: + * @see evas_object_textblock_cursor_new() + * @see evas_textblock_cursor_free() + * @remarks Cursors are generally the correct way to handle text in the textblock object, + * and there are enough functions to do everything you need with them + * (no need to get big chunks of text and processing them yourself). + * + * @subsection textblock_paragraphs Textblock Object Paragraphs + * The textblock object is made out of text split to paragraphs (delimited + * by the paragraph separation character). Each paragraph has many (or none) + * format nodes associated with it which are responsible for the formatting + * of that paragraph. + * + * @subsection textblock_format_nodes Textblock Object Format Nodes + * As explained in @ref textblock_paragraphs each one of the format nodes + * is associated with a paragraph. + * There are two types of format nodes: visible and invisible. + * Visible: Formats that a cursor can point to, that is, the formats that + * occupy space. For example: newlines, tabs, items and so on. Some visible items + * are made of two parts. In this case, only the opening tag is visible. + * A closing tag (i.e a \</tag\> tag) should NEVER be visible. + * Invisible: Formats that do not occupy space. For example: bold and underline. + * Being able to access format nodes is very important for some uses. For + * example, edje uses the "<a>" format to create links in the text (and pop + * popups above them when clicked). For the textblock object a is just a + * formatting instruction (how to color the text), but edje utilizes the access + * to the format nodes to make it do more. + * For more information, see all the evas_textblock_node_format_* functions. + * The translation of "<tag>" tags to actual format is done according to the + * tags defined in the style, see @ref evas_textblock_style_set + * + * @subsection textblock_special_formats Special Formats + * Textblock supports various format directives that can be used in markup. In + * addition to the mentioned format directives, textblock allows creating + * additional format directives using "tags" that can be set in the style. See + * @ref evas_textblock_style_set . + * + * Textblock supports the following formats: + * @li font - Font description in fontconfig like format. Example: "Sans:style=Italic:lang=hi". or "Serif:style=Bold". + * @li font_weight - Overrides the weight defined in "font". Example: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack". + * @li font_style - Overrides the style defined in "font". Example: "font_style=Italic" is the same as "font=:style=Italic". Supported styles: "normal", "oblique", and "italic". + * @li font_width - Overrides the width defined in "font". E.g: "font_width=Condensed" is the same as "font=:style=Condensed". Supported widths: "normal", "ultracondensed", "extracondensed", "condensed", "semicondensed", "semiexpanded", "expanded", "extraexpanded", and "ultraexpanded". + * @li lang - Overrides the language defined in "font". Example: "lang=he" is the same as "font=:lang=he". + * @li font_fallbacks - A comma delimited list of fonts to try if finding the main font fails. + * @li font_size - The font size in points. + * @li font_source - The source of the font. Example: An eet file. + * @li color - Text color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li underline_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li underline2_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li outline_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li shadow_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li glow_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li glow2_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li strikethrough_color - Color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li align - Either "auto" (meaning according to text direction), "left", "right", "center", "middle", a value between @c 0.0 and @c 1.0, or a value between 0% to 100%. + * @li valign - Either "top", "bottom", "middle", "center", "baseline", "base", a value between @c 0.0 and @c 1.0, or a value between 0% to 100%. + * @li wrap - "word", "char", "mixed", or "none". + * @li left_margin - Either "reset", or a pixel value indicating the margin. + * @li right_margin - Either "reset", or a pixel value indicating the margin. + * @li underline - "on", "off", "single", or "double". + * @li strikethrough - "on" or "off" + * @li backing_color - Background color in one of the following formats: "#RRGGBB", "#RRGGBBAA", "#RGB", and "#RGBA". + * @li backing - Enable or disable background color. Example: "on" or "off" + * @li style - Either "off", "none", "plain", "shadow", "outline", "soft_outline", "outline_shadow", "outline_soft_shadow", "glow", "far_shadow", "soft_shadow", or "far_soft_shadow". + * @li tabstops - Pixel value for tab width. + * @li linesize - Force a line size in pixels. + * @li linerelsize - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size. + * @li linegap - Force a line gap in pixels. + * @li linerelgap - Either a floating point value or a percentage indicating the wanted size of the line relative to the calculated size. + * @li item - Creates an empty space that should be filled by an upper layer. Use "size", "abssize", or "relsize". To define the items size, and an optional: vsize=full/ascent to define the item's position in the line. + * @li linefill - Either a float value or percentage indicating how much to fill the line. + * @li ellipsis - Value between @c 0.0-@c 1.0 to indicate the type of ellipsis, or @c -1.0 to indicate that ellipsis is not wanted. + * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off. + * + * @remarks There is no guarantee of any proper results if you create a Textblock + * object without setting the evas engine. + * + * @todo put here some usage examples + * + * @{ + */ + +typedef struct _Evas_Textblock_Style Evas_Textblock_Style; /**< @brief handle for Evas Textblock Style */ +typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor; /**< @brief handle for Evas Textblock Cursor */ +/** + * @typedef Evas_Object_Textblock_Node_Format + * @brief The structure type containing a format node. + */ +typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format; +typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle; + +struct _Evas_Textblock_Rectangle +{ + Evas_Coord x, y, w, h; +}; + +typedef enum _Evas_Textblock_Text_Type +{ + EVAS_TEXTBLOCK_TEXT_RAW, + EVAS_TEXTBLOCK_TEXT_PLAIN, + EVAS_TEXTBLOCK_TEXT_MARKUP +} Evas_Textblock_Text_Type; + +typedef enum _Evas_Textblock_Cursor_Type +{ + EVAS_TEXTBLOCK_CURSOR_UNDER, + EVAS_TEXTBLOCK_CURSOR_BEFORE +} Evas_Textblock_Cursor_Type; + +/** + * @brief Adds a textblock to the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The new textblock object + */ +EAPI Evas_Object *evas_object_textblock_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the unescaped version of escape. + * + * @since_tizen 2.3 + * + * @param[in] escape The string to be escaped + * @return The unescaped version of escape + */ +EAPI const char *evas_textblock_escape_string_get(const char *escape) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the escaped version of the string. + * + * @since_tizen 2.3 + * + * @param[in] string The string to escape + * @param[out] len_ret The len of the part of the string that is used + * @return The escaped string + */ +EAPI const char *evas_textblock_string_escape_get(const char *string, int *len_ret) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the unescaped version of the string between start and end. + * + * @since_tizen 2.3 + * + * @param[in] escape_start The start of the string + * @param[in] escape_end The end of the string + * @return The unescaped version of the range + */ +EAPI const char *evas_textblock_escape_string_range_get(const char *escape_start, const char *escape_end) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the plain version of the markup. + * + * @details This function works as if you set the markup to a textblock and then retrieve the plain + * version of the text. That is: <br> and <\n> is replaced with \n, &...; with + * the actual char and so on. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The textblock object to work with \n + * If @c NULL, it tries the default. + * @param[in] text The markup text \n + * If @c NULL, it returns @c NULL. + * @return An allocated plain text version of the markup + */ +EAPI char *evas_textblock_text_markup_to_utf8(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * @brief Gets the markup version of the plain text. + * + * @details This function replaces \\n -\> \<br/\> \\t -\> \<tab/\> and so on. + * This is generally needed before you pass plain text to be set in a textblock. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The textblock object to work with \n + * If @c NULL, it just does the default behaviour, i.e with no extra object information. + * @param[in] text The markup text \n + * If @c NULL, it returns @c NULL. + * @return An allocated plain text version of the markup + */ +EAPI char *evas_textblock_text_utf8_to_markup(const Evas_Object *obj, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * @brief Creates a new textblock style. + * + * @since_tizen 2.3 + * + * @return The new textblock style + */ +EAPI Evas_Textblock_Style *evas_textblock_style_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC; + +/** + * @brief Destroys a textblock style. + * + * @since_tizen 2.3 + * + * @param[in] ts The textblock style to free + */ +EAPI void evas_textblock_style_free(Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the style @a ts to the style passed as text by text. + * @details This function expects a string consisting of many (or none) tag='format' pairs. + * + * @since_tizen 2.3 + * + * @param[in] ts The style to set + * @param[in] text The text to parse \n + * This should be NOT NULL. + */ +EAPI void evas_textblock_style_set(Evas_Textblock_Style *ts, const char *text) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the text of the style @a ts. + * + * @since_tizen 2.3 + * + * @param[in] ts The style to get the text + * @return The text of the style, \n + * otherwise @c NULL on error + */ +EAPI const char *evas_textblock_style_get(const Evas_Textblock_Style *ts) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the object style to @a ts. + * + * @since_tizen 2.3 + * + * @param[in] obj The Evas object to set the style to + * @param[in] ts The style to set + */ +EAPI void evas_object_textblock_style_set(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the style of an object. + * + * @since_tizen 2.3 + * + * @param[in] obj The object to get the style from + * @return The style of the object + */ +EAPI const Evas_Textblock_Style *evas_object_textblock_style_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Pushes @a ts to the top of the user style stack. + * + * FIXME: API is solid but currently only supports 1 style in the stack. + * + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks The user style overrides the corresponding elements of the regular style. + * This is the proper way to do theme overrides in code. + * @param[in] obj The Evas object to set the style to + * @param[in] ts The style to set + * @see evas_object_textblock_style_set + */ +EAPI void evas_object_textblock_style_user_push(Evas_Object *obj, Evas_Textblock_Style *ts) EINA_ARG_NONNULL(1); + +/** + * @brief Deletes the style from the top of the user style stack. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The object to get the style from + * @see evas_object_textblock_style_get + */ +EAPI void evas_object_textblock_style_user_pop(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets (does not remove) the style at the top of the user style stack. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] obj The object to get the style from + * @return The style of the object + * @see evas_object_textblock_style_get + */ +EAPI const Evas_Textblock_Style *evas_object_textblock_style_user_peek(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the "replacement character" to use for the given textblock object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given textblock object + * @param[in] ch The charset name + */ +EAPI void evas_object_textblock_replace_char_set(Evas_Object *obj, const char *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the "replacement character" for given textblock object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given textblock object + * @return The replacement character, \n + * otherwise @c NULL if no replacement character is in use + */ +EAPI const char *evas_object_textblock_replace_char_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the vertical alignment of text within the textblock object as a whole. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Normally alignment is @c 0.0 (top of object). Values given should be + * between @c 0.0 and @c 1.0 , where @c 1.0 is bottom of object, @c 0.5 is + * vertically centered, and so on. + * + * @param[in] obj The given textblock object + * @param[in] align A value between @c 0.0 and @c 1.0 + */ +EAPI void evas_object_textblock_valign_set(Evas_Object *obj, double align); + +/** + * @brief Gets the vertical alignment of a textblock. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj The given textblock object + * @return The alignment set for the object + */ +EAPI double evas_object_textblock_valign_get(const Evas_Object *obj); + +/** + * @brief Sets the BiDi delimiters used in the textblock. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks BiDi delimiters are uses for in-paragraph separation of bidi segments. This + * is useful, for example, in recipients fields of e-mail clients where bidi + * oddities can occur when mixing RTL and LTR. + * + * @param[in] obj The given textblock object + * @param[in] delim A null terminated string of delimiters, for example ",|" + */ +EAPI void evas_object_textblock_bidi_delimiters_set(Evas_Object *obj, const char *delim); + +/** + * @brief Gets the BiDi delimiters used in the textblock. + * + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks BiDi delimiters are used for in-paragraph separation of bidi segments. This + * is useful, for example, in recipients fields of e-mail clients where bidi + * oddities can occur when mixing RTL and LTR. + * + * @param[in] obj The given textblock object + * @return A null terminated string of delimiters, for example ",|", \n + * otherwise @c NULL if it is empty + */ +EAPI const char *evas_object_textblock_bidi_delimiters_get(const Evas_Object *obj); + +/** + * @brief Sets the newline mode. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks When @c true, newline character behaves as a paragraph separator. + * + * @param[in] obj The given textblock object + * @param[in] mode Set #EINA_TRUE for legacy mode, \n + * otherwise set #EINA_FALSE + */ +EAPI void evas_object_textblock_legacy_newline_set(Evas_Object *obj, Eina_Bool mode) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the newline mode. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks When true, newline character behaves as a paragraph separator. + * + * @param[in] obj The given textblock object + * @return #EINA_TRUE if it is in legacy mode, \n + * otherwise #EINA_FALSE + + */ +EAPI Eina_Bool evas_object_textblock_legacy_newline_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the textblock's text to the markup text. + * + * @since_tizen 2.3 + * + * @remarks This assumes that the text does not include the unicode object replacement char (0xFFFC). + * + * @param[in] obj The textblock object + * @param[in] text The markup text to use + */ +EAPI void evas_object_textblock_text_markup_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1); + +/** + * @brief Prepends markup to the cursor @a cur. + * + * @since_tizen 2.3 + * + * @remarks This assumes that the text does not include the unicode object replacement char (0xFFFC). + * + * @param[in] cur The cursor to prepend to + * @param[in] text The markup text to prepend + */ +EAPI void evas_object_textblock_text_markup_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the markup of the object. + * + * @since_tizen 2.3 + * + * @param[in] obj The Evas object + * @return The markup text of the object + */ +EAPI const char *evas_object_textblock_text_markup_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the object's main cursor. + * + * @since_tizen 2.3 + * + * @param[in] obj The object + * @return @a obj's main cursor + */ +EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Creates a new cursor, associates it to the obj and inits it to point + * to the start of the textblock. + * + * @since_tizen 2.3 + * + * @remarks Association to the object means the cursor is updated when the object changes. + * + * @remarks If you need speed and you know what you are doing, it is slightly faster to + * just allocate the cursor yourself and not associate it. + * + * @param[in] obj The object to associate to + * @return The new cursor + */ +EAPI Evas_Textblock_Cursor *evas_object_textblock_cursor_new(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Frees the cursor and unassociates it from the object. + * + * @since_tizen 2.3 + * + * @remarks Do not use it to free the unassociated cursors. + * + * @param[in] cur The cursor to free + */ +EAPI void evas_textblock_cursor_free(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the cursor to the start of the first text node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + */ +EAPI void evas_textblock_cursor_paragraph_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the cursor to the end of the last text node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to set + */ +EAPI void evas_textblock_cursor_paragraph_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Advances to the start of the next text node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + * @return #EINA_TRUE if the cursor advances a paragraph, \n + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool evas_textblock_cursor_paragraph_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Goes to the end of the previous text node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + * @return #EINA_TRUE if the cursor goes to the end of the previous paragraph, \n + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool evas_textblock_cursor_paragraph_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the the list format node corresponding to @a anchor. + * + * @since_tizen 2.3 + * + * @param[in] obj The evas object \n + * This must not be @c NULL. + * @param[in] anchor The anchor name to get + * @return The list format node corresponding to the anchor, \n + * otherwise @c NULL if there is no list format node + */ +EAPI const Eina_List *evas_textblock_node_format_list_get(const Evas_Object *obj, const char *anchor) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the first format node. + * + * @since_tizen 2.3 + * + * @param[in] obj The evas object \n + * This must not be @c NULL. + * @return The first format node, \n + * otherwise @c NULL if there is no first format node + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_first_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the last format node. + * + * @since_tizen 2.3 + * + * @param[in] obj The evas textblock \n + * This must not be @c NULL. + * @return The last format node, \n + * otherwise @c NULL if there is no last format node + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_last_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the next format node (after n). + * + * @since_tizen 2.3 + * + * @param[in] n The current format node \n + * This must not be @c NULL. + * @return The next format node, \n + * otherwise @c NULL if there is no next format node + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_next_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the previous format node (after n). + * + * @since_tizen 2.3 + * + * @param[in] n The current format node \n + * This is must not be @c NULL. + * @return The previous format node, \n + * otherwise @c NULL if there is no previous format node + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_node_format_prev_get(const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1); + +/** + * @brief Removes a format node and its match. \n + * That is it removes a \<tag\> \</tag\> pair. + * + * @since_tizen 2.3 + * + * @remarks Assumes that the node is the first part of \<tag\>. + * This does not work if @a n is a closing tag. + * + * @param[in] obj The Evas object of the textblock \n + * This must not be @c NULL. + * @param[in] n The current format node \n + * This must not be @c NULL. + */ +EAPI void evas_textblock_node_format_remove_pair(Evas_Object *obj, Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the cursor to point to the place where format points to. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + * @param[in] n The format node to update according + * @deprecated Duplicate of evas_textblock_cursor_at_format_set + */ +EAPI void evas_textblock_cursor_set_at_format(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *n) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the format node at the position pointed by @a cur. + * + * @since_tizen 2.3 + * + * @param[in] cur The position to look at + * @return The format node, \n + * otherwise @c NULL if it is not found + * @see evas_textblock_cursor_format_is_visible_get() + */ +EAPI const Evas_Object_Textblock_Node_Format *evas_textblock_cursor_format_get(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the text format representation of the format node. + * + * @since_tizen 2.3 + * + * @param[in] fnode The format node + * @return The textual format of the format node + */ +EAPI const char *evas_textblock_node_format_text_get(const Evas_Object_Textblock_Node_Format *fnode) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the cursor to point to the position of @a fmt. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + * @param[in] fmt The format to update according to + */ +EAPI void evas_textblock_cursor_at_format_set(Evas_Textblock_Cursor *cur, const Evas_Object_Textblock_Node_Format *fmt) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Checks whether the current cursor position is a visible format. + * + * @since_tizen 2.3 + * + * @remarks This way is more efficient than evas_textblock_cursor_format_get() to check for the existence + * of a visible format. + * + * @param[in] cur The cursor to look at + * @return #EINA_TRUE if the cursor points to a visible format, \n + * otherwise #EINA_FALSE if the cursor does not point to a visible format + * @see evas_textblock_cursor_format_get() + */ +EAPI Eina_Bool evas_textblock_cursor_format_is_visible_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Advances the cursor to the next format node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to be updated + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_format_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Advances the cursor to the previous format node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to update + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_format_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the cursor points to a format. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to check + * @return #EINA_TRUE if the cursor points to a format, \n + * otherwise #EINA_FALSE if the cursor does not point to a format + */ +EAPI Eina_Bool evas_textblock_cursor_is_format(const Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Advances the cursor 1 cluster forward. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to advance + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_cluster_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Advances the cursor 1 cluster backward. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to advance + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_cluster_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Advances the cursor 1 char forward. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to advance + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_char_next(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Advances the cursor 1 char backward. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to advance + * @return #EINA_TRUE if the cursor is advanced successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_char_prev(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the start of the word under the cursor. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + * @return #EINA_TRUE if the cursor is moved successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_word_start(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the end of the word under the cursor. + * @since 1.2 + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + * @return #EINA_TRUE if the cursor is moved successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the first char in the node the cursor is pointing on. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + */ +EAPI void evas_textblock_cursor_paragraph_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the last char in a text node. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + */ +EAPI void evas_textblock_cursor_paragraph_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the start of the current line. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + */ +EAPI void evas_textblock_cursor_line_char_first(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the end of the current line. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to move + */ +EAPI void evas_textblock_cursor_line_char_last(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current cursor position. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor + * @return The cursor position, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_pos_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets the cursor position. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to be set + * @param[in] pos The position to set + */ +EAPI void evas_textblock_cursor_pos_set(Evas_Textblock_Cursor *cur, int pos) EINA_ARG_NONNULL(1); + +/** + * @brief Moves the cursor to the start of the line passed. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor + * @param[in] line The line number + * @return #EINA_TRUE if the cursor is moved successfully, \n + * otherwise #EINA_FALSE on error + */ +EAPI Eina_Bool evas_textblock_cursor_line_set(Evas_Textblock_Cursor *cur, int line) EINA_ARG_NONNULL(1); + +/** + * @brief Compares two cursors. + * + * @since_tizen 2.3 + * + * @param[in] cur1 The first cursor + * @param[in] cur2 The second cursor + * @return @c -1 if cur1 < cur2, @c 0 if cur1 == cur2, \n + * otherwise @c 1 + */ +EAPI int evas_textblock_cursor_compare(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Makes @a cur_dest point to the same point as @a cur. + * + * @since_tizen 2.3 + * + * @remarks This does not work if they do not point to the same object. + * + * @param[in] cur The source cursor + * @param[in] cur_dest The destination cursor + */ +EAPI void evas_textblock_cursor_copy(const Evas_Textblock_Cursor *cur, Evas_Textblock_Cursor *cur_dest) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds text to the current cursor position and sets the cursor to *before* + * the start of the text just added. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to the position to add text at + * @param[in] text The text to add + * @return The length of the text added + * @see evas_textblock_cursor_text_prepend() + */ +EAPI int evas_textblock_cursor_text_append(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds text to the current cursor position and sets the cursor to *after* + * the start of the text just added. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to the position to add text at + * @param[in] text The text to add + * @return The length of the text added + * @see evas_textblock_cursor_text_append() + */ +EAPI int evas_textblock_cursor_text_prepend(Evas_Textblock_Cursor *cur, const char *text) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds format to the current cursor position. + * @details If the format being added is a visible format, + add it *before* the cursor position, otherwise, add it after. + * This behavior is because visible formats are like characters and invisible + * should be stacked in a way that the last one is added last. + * + * @since_tizen 2.3 + * + * @remarks This function works with native formats, that means that style defined + * tags like <br> won't work here. For those kind of things use markup prepend. + * + * @param[in] cur the cursor to where to add format at. + * @param[in] format the format to add. + * @return Returns true if a visible format was added, false otherwise. + * @see evas_textblock_cursor_format_prepend() + */ +EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds the format to the current cursor position. + * @details If the format being added is a visible format, + * add it *before* the cursor position, otherwise, add it after. + * This behavior is because visible formats are like characters and invisible + * should be stacked in a way that the last one is added last. + * If the format is visible the cursor is advanced after it. + * + * @since_tizen 2.3 + * + * @remarks This function works with native formats, that means that style defined + * tags like <br> does not work here. For those, use markup prepend. + * + * @param[in] cur The cursor to where to add format at + * @param[in] format The format to add + * @return #EINA_TRUE if the visible format is added, \n + * otherwise #EINA_FALSE if the visible format is not added + * @see evas_textblock_cursor_format_prepend() + */ +EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Deletes the character at the location of the cursor. + * @details If there is a format pointing to this position, delete it as well. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor pointing to the current location + */ +EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1); + +/** + * @brief Deletes the range between @a cur1 and @a cur2. + * + * @since_tizen 2.3 + * + * @param[in] cur1 Starting point of the range + * @param[in] cur2 Ending point of the range + */ +EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the text of the paragraph @a cur points to. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor pointing to the paragraph + * @return The text in markup, \n + * otherwise @c NULL on error + */ +EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the length of the paragraph. + * + * @since_tizen 2.3 + * + * @remarks This is cheaper that the eina_unicode_strlen(). + * + * @param[in] cur The position of the paragraph + * @return The length of the paragraph on success, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the currently visible range. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] start The start of the range + * @param[in] end The end of the range + * @return #EINA_TRUE if the range is obtained successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_visible_range_get(Evas_Textblock_Cursor *start, Evas_Textblock_Cursor *end) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the format nodes in the range between @a cur1 and @a cur2. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] cur1 The start of the range + * @param[in] cur2 The end of the range + * @return The format nodes in the range \n + * You have to free it. + */ +EAPI Eina_List *evas_textblock_cursor_range_formats_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the text in the range between @a cur1 and @a cur2. + * + * @since_tizen 2.3 + * + * @param[in] cur1 The start of the range + * @param[in] cur2 The end of the range + * @param[in] format The format in which to return the text \n + * Markup - in textblock markup. Plain - UTF8. + * @return The text in the range + * @see elm_entry_markup_to_utf8() + */ +EAPI char *evas_textblock_cursor_range_text_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2, Evas_Textblock_Text_Type format) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @internal + * // TIZEN_ONLY(20131218) + * // Add evas_textblock_cursor_range_text_valid_markup_get API. + * @brief Gets the text and markup tags in the range between @a cur1 and @a cur2. + * + * @param cur1 The start of the range + * @param cur2 The end of the range + * @return The text in the range and the markup tags that affect the text + * @see elm_entry_markup_to_utf8() + */ +EAPI char *evas_textblock_cursor_range_text_valid_markup_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); +/****************************************************/ +/************* TIZEN ONLY END *********************/ +/****************************************************/ + +/** + * @brief Gets the content of the cursor. + * + * @since_tizen 2.3 + * + * @remarks Frees the returned string pointer when done if it is not @c NULL. + * + * @param[in] cur The cursor + * @return The text in the range, terminated by a null byte (may be utf8) + */ +EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the geometry of two cursors ("split cursor"), if logical cursor is + * between LTR/RTL text, also considering paragraph direction. + * + * @since_tizen 2.3 + * + * @remarks The upper cursor is shown for the text of the same direction as paragraph, + * lower cursor - for the opposite. + * + * @remarks The split cursor geometry is valid only in '|' cursor mode. + * In this case #EINA_TRUE is returned and @a cx2, @a cy2, @a cw2, @a ch2 are set, + * otherwise it behaves like cursor_geometry_get. + * + * @param[in] cur The cursor + * @param[out] cx The x coordinate of the cursor (or upper cursor) + * @param[out] cy The y coordinate of the cursor (or upper cursor) + * @param[out] cw The width of the cursor (or upper cursor) + * @param[out] ch The height of the cursor (or upper cursor) + * @param[out] cx2 The x coordinate of the lower cursor + * @param[out] cy2 The y coordinate of the lower cursor + * @param[out] cw2 The width of the lower cursor + * @param[out] ch2 The height of the lower cursor + * @param[in] ctype The type of the cursor + * @return #EINA_TRUE if split cursor, + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool evas_textblock_cursor_geometry_bidi_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_Coord *cx2, Evas_Coord *cy2, Evas_Coord *cw2, Evas_Coord *ch2, Evas_Textblock_Cursor_Type ctype); + +/** + * @brief Gets the geometry of the cursor. + * + * @since_tizen 2.3 + * + * @remarks It depends on the type of cursor requested. + * This should be used instead of char_geometry_get because there are weird + * special cases with BiDi text. + * + * @remarks In '_' cursor mode (i.e a line below the char) it is the same as char_geometry_get, + * except for the case of the last char of a line which depends on the + * paragraph direction. + * + * @remarks In '|' cursor mode (i.e a line between two chars) it is very variable. + * For example, consider the following visual string: + * "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw + * a '|' between the c and the C. + * + * @param[in] cur The cursor + * @param[out] cx The x coordinate of the cursor + * @param[out] cy The y coordinate of the cursor + * @param[out] cw The width of the cursor + * @param[out] ch The height of the cursor + * @param[in] dir The direction of the cursor \n + * This can be @c NULL. + * @param[in] ctype The type of the cursor + * @return The line number of the char on success, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_BiDi_Direction *dir, Evas_Textblock_Cursor_Type ctype) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the geometry of the char at @a cur. + * + * @since_tizen 2.3 + * + * @param[in] cur The position of the char + * @param[out] cx The x coordinate of the char + * @param[out] cy The y coordinate of the char + * @param[out] cw The width of the char + * @param[out] ch The height of the char + * @return The line number of the char, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_char_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the geometry of the pen at @a cur. + * + * @since_tizen 2.3 + * + * @param[in] cur The position of the char + * @param[out] cpen_x The pen_x of the char + * @param[out] cy The y of the char + * @param[out] cadv The adv of the char + * @param[out] ch The h of the char + * @return The line number of the char, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cpen_x, Evas_Coord *cy, Evas_Coord *cadv, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the geometry of the line at @a cur. + * + * @since_tizen 2.3 + * + * @param[in] cur The position of the line + * @param[out] cx The x coordinate of the line + * @param[out] cy The y coordinate of the line + * @param[out] cw The width of the line + * @param[out] ch The height of the line + * @return The line number of the line, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_line_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Sets the position of the cursor at a proper cluster according to the X and Y coordinates. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to set + * @param[in] x The x coordinate to set + * @param[in] y The y coordinate to set + * @return #EINA_TRUE if the position of the cursor is set successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_cluster_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the position of the cursor according to the X and Y coordinates. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to set + * @param[in] x The x coordinate to set + * @param[in] y The y coordinate to set + * @return #EINA_TRUE if the position of the cursor is set successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the cursor position according to the y coordinate. + * + * @since_tizen 2.3 + * + * @param[in] cur The cur to be set + * @param[in] y The y coordinate to set + * @return The line number found, \n + * otherwise @c -1 on error + */ +EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the geometry of a range. + * + * @since_tizen 2.3 + * + * @param[in] cur1 The start of the range + * @param[in] cur2 The end of the range + * @return A list of rectangles representing the geometry of the range + */ +EAPI Eina_List *evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Get the simple geometry of a range. + * The simple geometry is the geomtry in which rectangles in middle + * lines of range are merged into one big rectangle. + * + * @since_tizen 2.3 + * + * @param cur1 one side of the range. + * @param cur2 other side of the range. + * @return an iterator of rectangles representing the geometry of the range. + */ +EAPI Eina_Iterator *evas_textblock_cursor_range_simple_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + + +EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether the cursor points to the end of the line. + * + * @since_tizen 2.3 + * + * @param[in] cur The cursor to check + * @return #EINA_TRUE if the cursor points to the end of the line, \n + * otherwise #EINA_FALSE + */ +EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the geometry of a line number. + * + * @since_tizen 2.3 + * + * @param[in] obj The object + * @param[in] line The line number + * @param[out] cx The x coordinate of the line + * @param[out] cy The y coordinate of the line + * @param[out] cw The w coordinate of the line + * @param[out] ch The h coordinate of the line + * @return #EINA_TRUE if the geometry of the line is obtained successfully, + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_textblock_line_number_geometry_get(const Evas_Object *obj, int line, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); + +/** + * @brief Clears the textblock object. + * + * @since_tizen 2.3 + * + * @remarks Does *NOT* free the Evas object itself. + * + * @param[in] obj The object to clear + */ +EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the formatted width and height. + * + * @since_tizen 2.3 + * + * @remarks This calculates the actual size after restricting + * the textblock to the current size of the object. + * The main difference between this and @ref evas_object_textblock_size_native_get + * is that the "native" function does not take wrapping into account. + * It just calculates the real width of the object if it is placed on an + * infinite canvas, while this function gives the size after wrapping + * according to the size restrictions of the object. + * + * @remarks For example, a textblock containing the text: "You shall not pass!" + * with no margins or padding and assuming a monospace font and a size of + * 7x10 char widths (for simplicity) has a native size of 19x1 + * and a formatted size of 5x4. + * + * + * @param[in] obj The Evas object + * @param[out] w The width of the object + * @param[out] h The height of the object + * @see evas_object_textblock_size_native_get + */ +EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the native width and height. + * + * @since_tizen 2.3 + * + * @remarks This calculates the actual size without taking into account + * the current size of the object. + * The main difference between this and @ref evas_object_textblock_size_formatted_get + * is that the "native" function does not take wrapping into account. + * It just calculates the real width of the object if it is placed on an + * infinite canvas, while the "formatted" function gives the size after + * wrapping text according to the size restrictions of the object. + * + * @remarks For example, a textblock containing the text: "You shall not pass!" + * with no margins or padding and assuming a monospace font and a size of + * 7x10 char widths (for simplicity) has a native size of 19x1 + * and a formatted size of 5x4. + * + * @param[in] obj The Evas object of the textblock + * @param[out] w The width returned + * @param[out] h The height returned + */ +EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1); + +/** + * @internal + */ +EAPI void evas_object_textblock_style_insets_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1); + +/** + * @} + */ + + +/** + * @internal + * @defgroup Evas_Object_Textgrid Textgrid Object Functions + * @ingroup Evas_Object_Specific + * + * @todo put here some usage examples + * + * @since 1.7 + * + * @{ + */ + +/** + * @typedef Evas_Textgrid_Palette + * + * @brief Enumeration for the palette to use for the foreground and background colors. + * + * @since 1.7 + */ +typedef enum +{ + EVAS_TEXTGRID_PALETTE_NONE, /**< No palette is used */ + EVAS_TEXTGRID_PALETTE_STANDARD, /**< Standard palette (around 16 colors) */ + EVAS_TEXTGRID_PALETTE_EXTENDED, /**< Extended palette (at max 256 colors) */ + EVAS_TEXTGRID_PALETTE_LAST /**< Ignore this */ +} Evas_Textgrid_Palette; + +/** + * @typedef Evas_Textgrid_Font_Style + * + * @brief Enumeration for the style to give to each character of the grid. + * + * @since 1.7 + */ +typedef enum +{ + EVAS_TEXTGRID_FONT_STYLE_NORMAL = (1 << 0), /**< Normal style */ + EVAS_TEXTGRID_FONT_STYLE_BOLD = (1 << 1), /**< Bold style */ + EVAS_TEXTGRID_FONT_STYLE_ITALIC = (1 << 2) /**< Oblique style */ +} Evas_Textgrid_Font_Style; + +/** + * @typedef Evas_Textgrid_Cell + * + * @brief The structure type containing the values that describe each cell. + * + * @since 1.7 + */ +typedef struct _Evas_Textgrid_Cell Evas_Textgrid_Cell; + +/** + * @internal + * @struct _Evas_Textgrid_Cell + * + * @brief The structure type containing the values that describe each cell. + * + * @since 1.7 + */ +struct _Evas_Textgrid_Cell +{ + Eina_Unicode codepoint; /**< The UNICODE value of the character */ + unsigned char fg; /**< The index of the palette for the foreground color */ + unsigned char bg; /**< The index of the palette for the background color */ + unsigned short bold : 1; /**< The character is bold */ + unsigned short italic : 1; /**< The character is oblique */ + unsigned short underline : 1; /**< The character is underlined */ + unsigned short strikethrough : 1; /**< The character is struck through */ + unsigned short fg_extended : 1; /**< The extended palette is used for the foreground color */ + unsigned short bg_extended : 1; /**< The extended palette is used for the background color */ + unsigned short double_width : 1; /**< The codepoint is merged with the following cell to the right visually (cells must be in pairs with 2nd cell being a duplicate in all ways except codepoint is 0) */ +}; + +/** + * @brief Adds a textgrid to the given Evas. + * + * @details This function adds a new textgrid object to the Evas @a e and returns the object. + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The new textgrid object + * + */ +EAPI Evas_Object *evas_object_textgrid_add(Evas *e); + +/** + * @brief Sets the size of the textgrid object. + * + * @details This function sets the number of lines @a h and the number + * of columns @a w to the textgrid object @a obj. If + * @a w or @a h are less or equal than @c 0, this + * function does nothing. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object + * @param[in] w The number of columns (width in cells) of the grid + * @param[in] h The number of rows (height in cells) of the grid + */ +EAPI void evas_object_textgrid_size_set(Evas_Object *obj, int w, int h); + +/** + * @brief Gets the size of the textgrid object. + * + * @details This function retrieves the number of lines in the buffer @a + * h and the number of columns in the buffer @a w of + * the textgrid object @a obj. @a w or @a h can be + * @c NULL. On error, their value is @c 0. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object + * @param[out] w The number of columns of the grid + * @param[out] h The number of rows of the grid + */ +EAPI void evas_object_textgrid_size_get(const Evas_Object *obj, int *w, int *h); + +/** + * @brief Sets the font (source) file to be used on a given textgrid object. + * + * @details This function allows the font file @a font_source to be explicitly + * set for the textgrid object @a obj, overriding system lookup, which + * first occurs in the given file's contents. If @a font_source is + * @c NULL or is an empty string, or the same @a font_source has already + * been set, or on error, this function does nothing. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to set font for + * @param[in] font_source The font file's path + * + * @see evas_object_textgrid_font_get() + * @see evas_object_textgrid_font_set() + * @see evas_object_textgrid_font_source_get() + */ +EAPI void evas_object_textgrid_font_source_set(Evas_Object *obj, const char *font_source); + +/** + * @brief Gets the font file's path which is being used on a given textgrid object. + * + * @details This function returns the font source path of the textgrid object + * @a obj. If the font source path has not been set, or on error, + * @c NULL is returned. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to set font for + * @return The font file's path + * + * @see evas_object_textgrid_font_get() + * @see evas_object_textgrid_font_set() + * @see evas_object_textgrid_font_source_set() + */ +EAPI const char *evas_object_textgrid_font_source_get(const Evas_Object *obj); + +/** + * @brief Sets the font family and size on a given textgrid object. + * + * @details This function allows the font name @a font_name and size + * @a font_size of the textgrid object @a obj to be set. The @a font_name + * string has to follow fontconfig's convention on naming fonts, as + * it is the underlying library used to query system fonts by Evas (see + * the @c fc-list command's output, on your system, to get an + * idea). It also has to be a monospace font. If @a font_name is + * @c NULL, or if it is an empty string, or if @a font_size is less or + * equal than @c 0, or on error, this function does nothing. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to set font for + * @param[in] font_name The font (family) name + * @param[in] font_size The font size, in points + * + * @see evas_object_textgrid_font_get() + * @see evas_object_textgrid_font_source_set() + * @see evas_object_textgrid_font_source_get() + */ +EAPI void evas_object_textgrid_font_set(Evas_Object *obj, const char *font_name, Evas_Font_Size font_size); + +/** + * @brief Gets the font family and size in use on a given textgrid object. + * + * @details This function allows the font name and size of a textgrid object + * @a obj to be queried and stored respectively in the buffers + * @a font_name and @a font_size. Be aware that the font name string is + * still owned by Evas and should @b not have free() called on it by + * the caller of the function. On error, the font name is the empty + * string and the font size is @c 0. @a font_name and @a font_source can + * be @c NULL. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[out] font_name A pointer to the location to store the font name in + * @param[out] font_size A pointer to the location to store the font size in + * + * @see evas_object_textgrid_font_set() + * @see evas_object_textgrid_font_source_set() + * @see evas_object_textgrid_font_source_get() + */ +EAPI void evas_object_textgrid_font_get(const Evas_Object *obj, const char **font_name, Evas_Font_Size *font_size); + +/** + * @brief Gets the size of a cell of the given textgrid object in pixels. + * + * @details This functions retrieves the width and height, in pixels, of a cell + * of the textgrid object @a obj and store them respectively in the + * buffers @a width and @a height. Their value depends on the + * monospace font used for the textgrid object, as well as the + * style. @a width and @a height can be @c NULL. On error, they are + * set to @c 0. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[out] w A pointer to the location to store the width in pixels of a cell + * @param[out] h A pointer to the location to store the height in pixels of a cell + * + * @see evas_object_textgrid_font_set() + * @see evas_object_textgrid_supported_font_styles_set() + */ +EAPI void evas_object_textgrid_cell_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h); + +/** + * @brief Sets the color to the given palette at the given index of the given textgrid object. + * + * @details This function sets the color for the palette of type @a pal at the + * index @a idx of the textgrid object @a obj. The ARGB components are + * given by @a r, @a g, @a b and @a a. This color can be used when + * setting the #Evas_Textgrid_Cell structure. The components must set + * a pre-multiplied color. If pal is #EVAS_TEXTGRID_PALETTE_NONE or + * #EVAS_TEXTGRID_PALETTE_LAST, or if @a idx is not between @c 0 and @c 255, + * or on error, this function does nothing. The color components are + * clamped between @c 0 and @c 255. If @a idx is greater than the latest set + * color, the colors between this last index and @a idx - 1 are set to + * black (0, 0, 0, 0). + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[in] pal The type of the palette to set the color + * @param[in] idx The index of the paletter to which the color is stored + * @param[in] r The red component of the color + * @param[in] g The green component of the color + * @param[in] b The blue component of the color + * @param[in] a The alpha component of the color + * + * @see evas_object_textgrid_palette_get() + */ +EAPI void evas_object_textgrid_palette_set(Evas_Object *obj, Evas_Textgrid_Palette pal, int idx, int r, int g, int b, int a); + +/** + * @brief Gets the color to the given palette at the given index of the given textgrid object. + * + * @details This function retrieves the color for the palette of type @a pal at the + * index @a idx of the textgrid object @a obj. The ARGB components are + * stored in the buffers @a r, @a g, @a b and @a a. If @a idx is not + * between @c 0 and the index of the latest set color, or if @a pal is + * #EVAS_TEXTGRID_PALETTE_NONE or #EVAS_TEXTGRID_PALETTE_LAST, the + * values of the components are @c 0. @a r, @a g, @a b and @a a can be + * @c NULL. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[in] pal The type of the palette to set the color + * @param[in] idx The index of the paletter to which the color is stored + * @param[out] r A pointer to the red component of the color + * @param[out] g A pointer to the green component of the color + * @param[out] b A pointer to the blue component of the color + * @param[out] a A pointer to the alpha component of the color + * + * @see evas_object_textgrid_palette_set() + */ +EAPI void evas_object_textgrid_palette_get(const Evas_Object *obj, Evas_Textgrid_Palette pal, int idx, int *r, int *g, int *b, int *a); + +EAPI void evas_object_textgrid_supported_font_styles_set(Evas_Object *obj, Evas_Textgrid_Font_Style styles); +EAPI Evas_Textgrid_Font_Style evas_object_textgrid_supported_font_styles_get(const Evas_Object *obj); + +/** + * @brief Sets the string at the given row of the given textgrid object. + * + * @details This function returns cells to the textgrid taken by + * evas_object_textgrid_cellrow_get(). The row pointer @a row should be the + * same row pointer returned by evas_object_textgrid_cellrow_get() for the + * same row @a y. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[in] y The row index of the grid + * @param[in] row The string as a sequence of #Evas_Textgrid_Cell + * + * @see evas_object_textgrid_cellrow_get() + * @see evas_object_textgrid_size_set() + * @see evas_object_textgrid_update_add() + */ +EAPI void evas_object_textgrid_cellrow_set(Evas_Object *obj, int y, const Evas_Textgrid_Cell *row); + +/** + * @brief Gets the string at the given row of the given textgrid object. + * + * @details This function returns a pointer to the first cell of the line @a y + * of the textgrid object @a obj. If @a y is not between @c 0 and the + * number of lines of the grid - 1, or on error, this function return @c NULL. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj The textgrid object to query for font information + * @param[in] y The row index of the grid + * @return A pointer to the first cell of the given row + * + * @see evas_object_textgrid_cellrow_set() + * @see evas_object_textgrid_size_set() + * @see evas_object_textgrid_update_add() + */ +EAPI Evas_Textgrid_Cell *evas_object_textgrid_cellrow_get(const Evas_Object *obj, int y); + +/** + * @brief Indicates to evas that part of a textgrid region (cells) has been updated. + * + * @since 1.7 + * + * @since_tizen 2.3 + * + * @remarks This function declares to evas that a region of cells is updated by + * code and needs refreshing. An application should modify cells like this + * as an example: + * + * @code + * Evas_Textgrid_Cell *cells; + * int i; + * + * cells = evas_object_textgrid_cellrow_get(obj, row); + * for (i = 0; i < width; i++) cells[i].codepoint = 'E'; + * evas_object_textgrid_cellrow_set(obj, row, cells); + * evas_object_textgrid_update_add(obj, 0, row, width, 1); + * @endcode + * + * @param[in] obj The textgrid object + * @param[in] x The rect region of cells top-left x (column) + * @param[in] y The rect region of cells top-left y (row) + * @param[in] w The rect region size in number of cells (columns) + * @param[in] h The rect region size in number of cells (rows) + * + * @see evas_object_textgrid_cellrow_set() + * @see evas_object_textgrid_cellrow_get() + * @see evas_object_textgrid_size_set() + */ +EAPI void evas_object_textgrid_update_add(Evas_Object *obj, int x, int y, int w, int h); + +/** + * @} + */ + +/** + * @defgroup Evas_Line_Group Line Object Functions + * @ingroup Evas_Object_Specific + * + * @brief This group provides functions to deal with evas line objects. + * + * @remarks We do not guarantee any proper results if you create a Line object + * without setting the evas engine. + * + * @{ + */ + +/** + * @brief Adds a new evas line object to the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return The new evas line object + */ +EAPI Evas_Object *evas_object_line_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Sets the coordinates of the end points of the given evas line object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given evas line object + * @param[in] x1 The X coordinate of the first point + * @param[in] y1 The Y coordinate of the first point + * @param[in] x2 The X coordinate of the second point + * @param[in] y2 The Y coordinate of the second point + */ +EAPI void evas_object_line_xy_set(Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2); + +/** + * @brief Gets the coordinates of the end points of the given evas line object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given line object + * @param[out] x1 The pointer to an integer in which to store the X coordinate of the + * first end point + * @param[out] y1 The pointer to an integer in which to store the Y coordinate of the + * first end point + * @param[out] x2 The pointer to an integer in which to store the X coordinate of the + * second end point + * @param[out] y2 The pointer to an integer in which to store the Y coordinate of the + * second end point + */ +EAPI void evas_object_line_xy_get(const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Polygon Polygon Object Functions + * @ingroup Evas_Object_Specific + * + * @brief This group provides functions that operate on evas polygon objects. + * + * Hint: as evas does not provide ellipse, smooth paths or circle, one + * can calculate points and convert these to a polygon. + * + * @remarks We do not guarantee any proper results if you create a Polygon + * object without setting the evas engine. + * + * @{ + */ + +/** + * @brief Adds a new evas polygon object to the given evas. + * + * @since_tizen 2.3 + * + * @param[in] e The given evas + * @return A new evas polygon object + */ +EAPI Evas_Object *evas_object_polygon_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Adds the given point to the given evas polygon object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given evas polygon object + * @param[in] x The X coordinate of the given point + * @param[in] y The Y coordinate of the given point + * @ingroup Evas_Polygon_Group + */ +EAPI void evas_object_polygon_point_add(Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1); + +/** + * @brief Removes all of the points from the given evas polygon object. + * + * @since_tizen 2.3 + * + * @param[in] obj The given polygon object + */ +EAPI void evas_object_polygon_points_clear(Evas_Object *obj) EINA_ARG_NONNULL(1); +/** + * @} + */ + +/** + * @internal + * @since 1.2 + * + * Need description + * @ingroup Evas_Object_Group + */ +EAPI void evas_object_is_frame_object_set(Evas_Object *obj, Eina_Bool is_frame); + +/** + * @internal + * @since 1.2 + * + * Need description + * @ingroup Evas_Object_Group + */ +EAPI Eina_Bool evas_object_is_frame_object_get(Evas_Object *obj); + +/** + * @internal + * @defgroup Evas_Smart_Group Smart Functions + @ingroup Evas + * + * This group provides functions that deal with #Evas_Smart structs, creating definition + * (classes) of objects that have customized behavior for methods + * like evas_object_move(), evas_object_resize(), + * evas_object_clip_set() and others. + * + * These objects accept the generic methods defined in @ref + * Evas_Object_Group and the extensions defined in @ref + * Evas_Smart_Object_Group. There are a couple of existent smart + * objects in Evas itself (see @ref Evas_Object_Box, @ref + * Evas_Object_Table and @ref Evas_Smart_Object_Clipped). + * + * @{ + */ + +/** + * @def EVAS_SMART_CLASS_VERSION + * + * The version you have to put into the version field in the + * #Evas_Smart_Class struct. Used to safeguard from binaries with old + * smart object intefaces running with newer ones. + */ +#define EVAS_SMART_CLASS_VERSION 4 + +/** + * @internal + * @struct _Evas_Smart_Class + * + * @brief The structure type containing a smart object's @b base class definition. + */ +struct _Evas_Smart_Class +{ + const char *name; /**< The name string of the class */ + int version; + void (*add)(Evas_Object *o); /**< Code to be run when adding object to a canvas */ + void (*del)(Evas_Object *o); /**< Code to be run when removing object from a canvas */ + void (*move)(Evas_Object *o, Evas_Coord x, Evas_Coord y); /**< Code to be run when moving object on a canvas. @a x and @a y are new coordinates you apply to the object. Use evas_object_geometry_get() if you need the old values, during this call. After that, the old values are lost */ + void (*resize)(Evas_Object *o, Evas_Coord w, Evas_Coord h); /**< Code to be run when resizing object on a canvas. @a w and @a h are new dimensions you apply to the object. Use evas_object_geometry_get() if you need the old values, during this call. After that, the old values are lost */ + void (*show)(Evas_Object *o); /**< Code to be run when showing object on a canvas */ + void (*hide)(Evas_Object *o); /**< Code to be run when hiding object on a canvas */ + void (*color_set)(Evas_Object *o, int r, int g, int b, int a); /**< Code to be run when setting color of object on a canvas. @a r, @a g, @a b and @a y are new color components one applied to the object. Use evas_object_color_get() if you need the old values, during this call. After that, the old values are lost */ + void (*clip_set)(Evas_Object *o, Evas_Object *clip); /**< Code to be run when setting clipper of object on a canvas. @a clip is a new clipper you apply to the object. Use evas_object_clip_get() if you need the old one, during this call. After that, the old (object pointer) value is lost */ + void (*clip_unset)(Evas_Object *o); /**< Code to be run when unsetting clipper of object on a canvas. If you need the pointer to a previous set clipper, during this call, use evas_object_clip_get(). After that, the old (object pointer) value is lost */ + void (*calculate)(Evas_Object *o); /**< Code to be run when object has rendering updates on a canvas */ + void (*member_add)(Evas_Object *o, Evas_Object *child); /**< Code to be run when a child member is added to object */ + void (*member_del)(Evas_Object *o, Evas_Object *child); /**< Code to be run when a child member is removed from object */ + + const Evas_Smart_Class *parent; /**< This class inherits from this parent */ + const Evas_Smart_Cb_Description *callbacks; /**< Callbacks at this level, @c NULL terminated */ + const Evas_Smart_Interface **interfaces; /**< #Evas_Smart_Interface pointers array, @c NULL terminated. These are the interfaces supported at this level for an object (parents may have others) @since 1.7 */ + const void *data; +}; + +/** + * @internal + * @struct _Evas_Smart_Interface + * + * @brief The structure type containing a smart object's @b base interface definition + * @since 1.7 + * + * @remarks Every Evas interface must have a name field, pointing to a global, + * constant string variable. This string pointer is the only way + * of retrieving back a given interface from a smart object. Two + * function pointers must be defined, too, which is called at + * object creation and deletion times. + * + * + * @ingroup Evas_Smart_Group + */ +struct _Evas_Smart_Interface +{ + const char *name; /**< Name of the given interface */ + unsigned private_size; /**< Size, in bytes, of the interface's private data blob. This is allocated and freed automatically for you. Get it with evas_object_smart_interface_data_get() */ + Eina_Bool (*add)(Evas_Object *obj); /**< Function to be called at object creation time. This takes place @b before the object's smart @c add() function */ + void (*del)(Evas_Object *obj); /**< Function to be called at object deletion time. This takes place @b after the object's smart @c del() function */ +}; + +/** + * @internal + * @struct _Evas_Smart_Cb_Description + * + * @brief The structure type that describes a callback issued by a smart object + * (evas_object_smart_callback_call()), as defined in its smart object + * class. This is particularly useful to explain to end users and + * their code (i.e., introspection) what the parameter @a event_info + * points to. + */ +struct _Evas_Smart_Cb_Description +{ + const char *name; /**< callback name ("changed", for example) */ + + /** + * @brief Hint on the type of @a event_info parameter's contents on + * a #Evas_Smart_Cb callback. + * + * @remarks The type string uses the pattern similar to + * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures, + * but extended to optionally include variable names within + * brackets preceding types. Example: + * + * @li Structure with two integers: + * @c "(ii)" + * + * @li Structure called 'x' with two integers named 'a' and 'b': + * @c "[x]([a]i[b]i)" + * + * @li Array of integers: + * @c "ai" + * + * @li Array called 'x' of struct with two integers: + * @c "[x]a(ii)" + * + * @remarks This type string is used as a hint and is @b not validated + * or enforced in any way. Implementors should make the best + * use of it to help bindings, documentation and other users + * of introspection features. + */ + const char *type; +}; + +/** + * @def EVAS_SMART_CLASS_INIT_NULL + * @brief Definition for initializing to zero a whole Evas_Smart_Class structure. + * + * @see EVAS_SMART_CLASS_INIT_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS + */ +#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL} + +/** + * @def EVAS_SMART_CLASS_INIT_VERSION + * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set version. + * + * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to + * latest EVAS_SMART_CLASS_VERSION. + * + * @see EVAS_SMART_CLASS_INIT_NULL + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS + */ +#define EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL} + +/** + * @def EVAS_SMART_CLASS_INIT_NAME_VERSION + * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name + * and version. + * + * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to + * latest EVAS_SMART_CLASS_VERSION and name to the specified value. + * + * @remarks It keeps a reference to name field as a "const char *", that is, + * name must be available while the structure is used (hint: static or global!) + * and is not modified. + * + * @see EVAS_SMART_CLASS_INIT_NULL + * @see EVAS_SMART_CLASS_INIT_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS + */ +#define EVAS_SMART_CLASS_INIT_NAME_VERSION(name) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL} + +/** + * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT + * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name, + * version and parent class. + * + * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to + * latest EVAS_SMART_CLASS_VERSION, name to the specified value and + * parent class. + * + * @remarks It keeps a reference to name field as a "const char *", that is, + * name must be available while the structure is used (hint: static or global!) + * and is not modified. Similarly, parent reference is kept. + * + * @see EVAS_SMART_CLASS_INIT_NULL + * @see EVAS_SMART_CLASS_INIT_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS + */ +#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL} + +/** + * @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS + * @brief Definition for initializing to zero a whole Evas_Smart_Class structure and set name, + * version, parent class and callbacks definition. + * + * @remarks Similar to EVAS_SMART_CLASS_INIT_NULL, but sets version field to + * latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent + * class and callbacks at this level. + * + * @remarks It keeps a reference to name field as a "const char *", that is, + * name must be available while the structure is used (hint: static or global!) + * and is not modified. Similarly, parent and callbacks reference + * is kept. + * + * @see EVAS_SMART_CLASS_INIT_NULL + * @see EVAS_SMART_CLASS_INIT_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT + */ +#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL} + +/** + * @def EVAS_SMART_SUBCLASS_NEW + * + * @brief Convenience macro to subclass a given Evas smart class. + * + * @details This macro saves some typing when writing a smart class derived + * from another one. In order to work, the user @b must provide some + * functions adhering to the following guidelines: + * - @<prefix@>_smart_set_user(): The @b internal @c _smart_set + * function (defined by this macro) calls this one, provided by + * the user, after inheriting everything from the parent, which + * should <b>take care of setting the right member functions for + * the class</b>, both overrides and extensions, if any. + * - If this new class should be subclassable as well, a @b public + * @c _smart_set() function is desirable to fill in the class used as + * parent by the children. It is up to the user to provide this + * interface, which most likely calls @<prefix@>_smart_set() to + * get the job done. + * + * After the macro's usage, the following are defined for use: + * - @<prefix@>_parent_sc: A pointer to the @b parent smart + * class. When calling parent functions from overloaded ones, use + * this global variable. + * - @<prefix@>_smart_class_new(): This function returns the + * #Evas_Smart needed to create smart objects with this class, + * which should be passed to evas_object_smart_add(). + * + * @remarks @a smart_name has to be a pointer to a globally available + * string. The smart class created here just has a pointer set + * to that, and all object instances depend on it for smart class + * name lookup. + * + * @param smart_name The name used for the smart class \n + * For example, @c "Evas_Object_Box". + * @param prefix Prefix used for all variables and functions defined + * and referenced by this macro + * @param api_type Type of the structure used as API for the smart class \n + * Either #Evas_Smart_Class or something derived from it. + * @param parent_type Type of the parent class API + * @param parent_func Function that gets the parent class \n + * For example, evas_object_box_smart_class_get(). + * @param cb_desc Array of callback descriptions for this smart class + */ +#define EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc) \ + static const parent_type * prefix##_parent_sc = NULL; \ + static void prefix##_smart_set_user(api_type * api); \ + static void prefix##_smart_set(api_type * api) \ + { \ + Evas_Smart_Class *sc; \ + if (!(sc = (Evas_Smart_Class *)api)) \ + return; \ + if (!prefix##_parent_sc) \ + prefix##_parent_sc = parent_func(); \ + evas_smart_class_inherit(sc, prefix##_parent_sc); \ + prefix##_smart_set_user(api); \ + } \ + static Evas_Smart *prefix##_smart_class_new(void) \ + { \ + static Evas_Smart *smart = NULL; \ + static api_type api; \ + if (!smart) \ + { \ + Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \ + memset(&api, 0, sizeof(api_type)); \ + sc->version = EVAS_SMART_CLASS_VERSION; \ + sc->name = smart_name; \ + sc->callbacks = cb_desc; \ + prefix##_smart_set(&api); \ + smart = evas_smart_class_new(sc); \ + } \ + return smart; \ + } + +/** + * @def EVAS_SMART_SUBCLASS_IFACE_NEW + * + * @brief Convenience macro to subclass a given Evas smart class. This is the + * same as #EVAS_SMART_SUBCLASS_NEW, but <b>declares smart + * interfaces</b> besides the smart callbacks. + * + * @details This macro saves some typing when writing a smart class derived + * from another one. In order to work, the user @b must provide some + * functions adhering to the following guidelines: + * - @<prefix@>_smart_set_user(): The @b internal @c _smart_set + * function (defined by this macro) calls this one, provided by + * the user, after inheriting everything from the parent, which + * should <b>take care of setting the right member functions for + * the class</b>, both overrides and extensions, if any. + * - If this new class should be subclassable as well, a @b public + * @c _smart_set() function is desirable to fill in the class used as + * parent by the children. It is up to the user to provide this + * interface, which most likely calls @<prefix@>_smart_set() to + * get the job done. + * + * After the macro's usage, the following is defined for use: + * - @<prefix@>_parent_sc: A pointer to the @b parent smart + * class. When calling parent functions from overloaded ones, use + * this global variable. + * - @<prefix@>_smart_class_new(): This function returns the + * #Evas_Smart needed to create smart objects with this class, + * which should be passed to evas_object_smart_add(). + * + * @since 1.7 + * + * @remarks @a smart_name has to be a pointer to a globally available + * string. The smart class created here just has a pointer set + * to that, and all object instances depend on it for smart class + * name lookup. + * + * @param smart_name The name used for the smart class \n + * For example, @c "Evas_Object_Box". + * @param prefix Prefix used for all variables and functions defined + * and referenced by this macro + * @param api_type Type of the structure used as API for the smart class + * Either #Evas_Smart_Class or something + * derived from it. + * @param parent_type Type of the parent class API + * @param parent_func Function that gets the parent class \n + * For example, evas_object_box_smart_class_get(). + * @param cb_desc Array of smart callback descriptions for this smart class + * @param ifaces Array of Evas smart interfaces for this smart class + */ +#define EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name, \ + prefix, \ + api_type, \ + parent_type, \ + parent_func, \ + cb_desc, \ + ifaces) \ + static const parent_type * prefix##_parent_sc = NULL; \ + static void prefix##_smart_set_user(api_type * api); \ + static void prefix##_smart_set(api_type * api) \ + { \ + Evas_Smart_Class *sc; \ + if (!(sc = (Evas_Smart_Class *)api)) \ + return; \ + if (!prefix##_parent_sc) \ + prefix##_parent_sc = parent_func(); \ + evas_smart_class_inherit(sc, prefix##_parent_sc); \ + prefix##_smart_set_user(api); \ + } \ + static Evas_Smart *prefix##_smart_class_new(void) \ + { \ + static Evas_Smart *smart = NULL; \ + static api_type api; \ + if (!smart) \ + { \ + Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \ + memset(&api, 0, sizeof(api_type)); \ + sc->version = EVAS_SMART_CLASS_VERSION; \ + sc->name = smart_name; \ + sc->callbacks = cb_desc; \ + sc->interfaces = ifaces; \ + prefix##_smart_set(&api); \ + smart = evas_smart_class_new(sc); \ + } \ + return smart; \ + } + +/** + * @def EVAS_SMART_DATA_ALLOC + * + * @brief Convenience macro to allocate smart data only if needed. + * + * @remarks When writing a subclassable smart object, the @c .add() function + * needs to check if the smart private data is already allocated + * by some child object or not. This macro makes it easier to do it. + * + * @remarks This is an idiom used when one calls the parent's @c .add() + * after the specialized code. Naturally, the parent's base smart data + * has to be contemplated as the specialized one's first member, for + * things to work. + * + * @param o The Evas object passed to the @c .add() function + * @param priv_type The type of the data to allocate + */ +#define EVAS_SMART_DATA_ALLOC(o, priv_type) \ + priv_type * priv; \ + priv = evas_object_smart_data_get(o); \ + if (!priv) { \ + priv = (priv_type *)calloc(1, sizeof(priv_type)); \ + if (!priv) return; \ + evas_object_smart_data_set(o, priv); \ + } + +/** + * @brief Frees an #Evas_Smart struct. + * + * @since_tizen 2.3 + * + * @remarks If this smart handle is created using evas_smart_class_new(), + * the associated #Evas_Smart_Class is not freed. + * + * @remarks If you are using the #EVAS_SMART_SUBCLASS_NEW schema to create your + * smart object, note that an #Evas_Smart handle is shared amongst all + * instances of the given smart class, through a static variable. + * Evas internally counts references on #Evas_Smart handles and free them + * when they are not referenced any more. Thus, this function is mostly of no use + * for Evas users. + * + * @param[in] s The #Evas_Smart struct to free + */ +EAPI void evas_smart_free(Evas_Smart *s) EINA_ARG_NONNULL(1); + +/** + * @brief Creates a new #Evas_Smart from a given #Evas_Smart_Class struct. + * + * @since_tizen 2.3 + * + * @remarks #Evas_Smart handles are necessary to create new @b instances of + * smart objects belonging to the class described by @a sc. That + * handle contains, besides the smart class interface definition, + * all its smart callbacks infrastructure set, too. + * + * @remarks If you are willing to subclass a given smart class to + * construct yours, consider using the #EVAS_SMART_SUBCLASS_NEW macro, + * which makes use of this function automatically for you. + * + * @param[in] sc The smart class definition + * @return A new #Evas_Smart pointer + */ +EAPI Evas_Smart *evas_smart_class_new(const Evas_Smart_Class *sc) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the #Evas_Smart_Class handle of an #Evas_Smart struct. + * + * @since_tizen 2.3 + * + * @param[in] s A valid #Evas_Smart pointer + * @return The #Evas_Smart_Class + */ +EAPI const Evas_Smart_Class *evas_smart_class_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the data pointer set on an #Evas_Smart struct. + * + * @since_tizen 2.3 + * + * @remarks This data pointer is set as the data field in the #Evas_Smart_Class + * passed in to evas_smart_class_new(). + * + * @param[in] s A valid #Evas_Smart handle + */ +EAPI void *evas_smart_data_get(const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the smart callbacks known by this #Evas_Smart handle's smart + * class hierarchy. + * + * @details This function is likely different from + * evas_object_smart_callbacks_descriptions_get() as it contains + * the callbacks of @b all this class hierarchy sorted, while the + * direct smart class member refers only to that specific class and + * should not include the parent's. + * + * @since_tizen 2.3 + * + * @remarks If no callbacks are known, this function returns @c NULL. + * + * @remarks The array elements and thus their contents are @b references to + * original values given to evas_smart_class_new() as + * Evas_Smart_Class::callbacks. + * + * @remarks The array is sorted by Evas_Smart_Cb_Description::name. The last + * array element is a @c NULL pointer and is not accounted for in @a + * count. Loop iterations can check any of these size indicators. + * + * @remarks Objects may provide per-instance callbacks. Use + * evas_object_smart_callbacks_descriptions_get() to get those + * as well. + * + * @param[in] s A valid #Evas_Smart handle. + * @param[out] count The number of elements in the returned array + * @return The array with callback descriptions known by this smart + * class, with its size returned in @a count parameter \n + * It should not be modified in any way. If no callbacks are + * known, @c NULL is returned. The array is sorted by event + * names and elements refer to the original values given to + * evas_smart_class_new()'s Evas_Smart_Class::callbacks + * (pointer to them). + * + * @see evas_object_smart_callbacks_descriptions_get() + */ +EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(const Evas_Smart *s, unsigned int *count) EINA_ARG_NONNULL(1, 1); + +/** + * @brief Finds a callback description for the callback named @a name. + * + * @since_tizen 2.3 + * + * @param[in] s The #Evas_Smart where to search for class registered smart + * event callbacks + * @param[in] name The name of the desired callback, which must @b not be @c + * NULL. The search has a special case for @a name being the + * same pointer as registered with #Evas_Smart_Cb_Description. + * You can use it to avoid excessive use of strcmp(). + * @return A reference to the description if found, \n + * otherwise @c NULL if no description is found + * + * @see evas_smart_callbacks_descriptions_get() + */ +EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2); + +/** + * brief Sets one class to inherit from the other. + * + * @since_tizen 2.3 + * everything after sizeof(Evas_Smart_Class) present in @a parent_sc, + * using @a parent_sc_size as reference. + * + * @remarks This is recommended instead of a single memcpy() since it takes + * care to not modify @a sc name, version, callbacks and possible + * other members. + * + * @param[in] sc The child class + * @param[in] parent_sc The parent class, provides attributes + * @param[in] parent_sc_size The size of parent_sc structure \n + * The child should be at least this size. \n + * Everything after @c Evas_Smart_Class size is copied + * using regular memcpy(). + */ +EAPI Eina_Bool evas_smart_class_inherit_full(Evas_Smart_Class *sc, const Evas_Smart_Class *parent_sc, unsigned int parent_sc_size) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets the number of users of the smart instance. + * + * @details This function tells you how many more uses of the smart instance are in + * existence. This should be used before freeing or clearing any of the + * Evas_Smart_Class that is used to create the smart instance. The smart + * instance refers to data in the Evas_Smart_Class used to create it and + * thus you cannot remove the original data until all users of it are gone. + * When the usage count goes to @c 0, you can evas_smart_free() the smart + * instance @a s and remove from memory any of the Evas_Smart_Class that + * is used to create the smart instance, if you desire. Removing it from + * memory without doing this causes problems (crashes, undefined + * behavior, and so on). So either never remove the original + * Evas_Smart_Class data from memory (have it be a constant structure and + * data), or use this API call and be very careful. + * + * @since_tizen 2.3 + * + * @param[in] s The Evas_Smart to get the usage count of + * @return The number of uses of the smart instance + */ +EAPI int evas_smart_usage_get(const Evas_Smart *s); + +/** + * @def evas_smart_class_inherit + * @brief Easy to use version of evas_smart_class_inherit_full(). + * + * @remarks This version uses sizeof(parent_sc), copying everything. + * + * @param sc The child class \n + * It has methods copied from @a parent_sc. + * @param parent_sc The parent class \n + * It provides contents to be copied. + * @return @c 1 if everything is copied successfully, \n + * otherwise @c 0 on failure + * @ingroup Evas_Smart_Group + */ +#define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc)) + +/** + * @} + */ + +/** + * @defgroup Evas_Smart_Object_Group Smart Object Functions + @ingroup Evas_Object_Group + * + * @brief This group provides functions dealing with Evas smart objects (instances). + * + * Smart objects are groupings of primitive Evas objects that behave + * as a cohesive group. For instance, a file manager icon may be a + * smart object composed of an image object, a text label, and two + * rectangles that appear behind the image and text when the icon is + * selected. As a smart object, the normal Evas object API could be + * used on the icon object. + * + * Besides that, generally smart objects implement a <b>specific + * API</b>, so that users interact with its own custom features. The + * API takes the form of explicit exported functions one may call and + * <b>smart callbacks</b>. + * + * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks + * + * Smart objects can elect events (smart events, from now on) occurring + * inside of them to be reported back to their users via callback + * functions (smart callbacks). This way, you can extend Evas' own + * object events. They are defined by an <b>event string</b>, which + * identifies them uniquely. There is also a function prototype + * definition for the callback functions: Evas_Smart_Cb. + * + * When defining an #Evas_Smart_Class, smart object implementors are + * strongly encouraged to properly set the Evas_Smart_Class::callbacks + * callbacks description array, so that the users of the smart object + * can have introspection on its events API <b>at run time</b>. + * + * @internal + * @see @ref Evas_Smart_Group for class definitions. + * @endinternal + * + * @{ + */ + +/** + * @brief Instantiates a new smart object described by @a s. + * + * @details This is the function that you should use when defining the public + * function @b adding an instance of the new smart object to a given + * canvas. + * @internal + * It takes care of setting all of its internals to work + * as they should, if the user set things properly, like + * #EVAS_SMART_SUBCLASS_NEW, for example. + * @endinternal + * + * @since_tizen 2.3 + * + * @param[in] e The canvas on which to add the object + * @param[in] s The #Evas_Smart describing the smart object + * @return A new #Evas_Object handle + */ +EAPI Evas_Object *evas_object_smart_add(Evas *e, Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_MALLOC; + +/** + * @brief Sets an Evas object as a member of a given smart object. + * + * @since_tizen 2.3 + * + * @remarks Members are automatically stacked and layered together with the + * smart object. The various stacking functions operate on + * members relative to the other members instead of the entire canvas, + * since they now live on an exclusive layer (see + * evas_object_stack_above(), for more details). + * + * @remarks Any @a smart_obj object's specific implementation of the @c + * member_add() smart function takes place too, naturally. + * + * @param[in] obj The member object + * @param[in] smart_obj The smart object + * + * @see evas_object_smart_member_del() + * @see evas_object_smart_members_get() + */ +EAPI void evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes a member object from a given smart object. + * + * @details This function removes a member object from a smart object, if it is added + * to any. The object is still on the canvas, but no longer + * associated with whichever smart object it is associated with. + * + * @since_tizen 2.3 + * + * @param[in] obj The member object + * + * @see evas_object_smart_member_add() for more details + * @see evas_object_smart_members_get() + */ +EAPI void evas_object_smart_member_del(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the list of the member objects of a given Evas smart object. + * @since 1.7 + * + * @since_tizen 2.3 + * + * @remarks The returned list should be freed with @c eina_list_free() when you + * no longer need it. + * + * @param[in] obj The smart object to get members from + * @return The list of the member objects of @a obj, \n + * otherwise @c NULL when a non-smart object is passed + * + * @see evas_object_smart_member_add() + * @see evas_object_smart_member_del() + */ +EAPI Eina_List *evas_object_smart_members_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the parent smart object of a given Evas object, if it has one. + * + * @since_tizen 2.3 + * + * @param[in] obj The Evas object to get the parent smart object from + * @return The parent smart object of @a obj \n + * otherwise @c NULL if @a obj is not a smart member of any Evas object + */ +EAPI Evas_Object *evas_object_smart_parent_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether a given smart object or any of its smart object + * parents is of a given smart class. + * + * @since_tizen 2.3 + * + * @remarks If @a obj is not a smart object, this call fails + * immediately. Otherwise, make sure evas_smart_class_inherit() or its + * sibling functions were used correctly when creating the smart + * object's class, so it has a valid @b parent smart class pointer set. + * + * @remarks The checks use smart classes names and <b>string + * comparison</b>. There is a version of this same check using + * <b>pointer comparison</b>, since a smart class' name is a single + * string in Evas. + * + * @param[in] obj An Evas smart object to check the type of + * @param[in] type The @b name (type) of the smart class to check for + * @return #EINA_TRUE if @a obj or any of its parents is of type @a type, \n + * otherwise #EINA_FALSE + * + * @see evas_object_smart_type_check_ptr() + * @internal + * @see #EVAS_SMART_SUBCLASS_NEW + * @endinternal + */ +EAPI Eina_Bool evas_object_smart_type_check(const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @internal + * @brief Checks whether a given smart object or any of its smart object + * parents is of a given smart class, <b>using pointer comparison</b>. + * + * @since_tizen 2.3 + * + * @param[in] obj An Evas smart object to check the type of + * @param[in] type The type (name string) to check for \n + * Must be the name. + * @return #EINA_TRUE if @a obj or any of its parents is of type @a type, \n + * otherwise #EINA_FALSE + * + * @see evas_object_smart_type_check() for more details + * + * @ingroup Evas_Smart_Object_Group + */ +EAPI Eina_Bool evas_object_smart_type_check_ptr(const Evas_Object *obj, const char *type) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @internal + * @brief Gets the #Evas_Smart from which @a obj smart object is created. + * + * @since_tizen 2.3 + * + * @param[in] obj A smart object + * @return The #Evas_Smart handle, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Smart *evas_object_smart_smart_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the user data stored on a given smart object. + * + * @since_tizen 2.3 + * + * @param[in] obj The smart object's handle + * @return A pointer to data stored using evas_object_smart_data_set(), \n + * otherwise @c NULL if none has been set + * + * @see evas_object_smart_data_set() + */ +EAPI void *evas_object_smart_data_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets a pointer to the user data for a given smart object. + * + * @since_tizen 2.3 + * + * @remarks This data is stored @b independently of the one set by + * evas_object_data_set(), naturally. + * + * @param[in] obj The smart object's handle + * @param[in] data A pointer to user data + * + * @see evas_object_smart_data_get() + */ +EAPI void evas_object_smart_data_set(Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Adds or registers a callback function to the smart event specified by + * @a event on the smart object @a obj. + * + * @since_tizen 2.3 + * + * @remarks Smart callbacks look very similar to Evas callbacks, but are + * implemented as smart object's custom ones. + * + * @remarks This function adds a function callback to an smart object when the + * event named @a event occurs in it. The function is @a func. + * + * @remarks In the event of a memory allocation error during addition of the + * callback to the object, evas_alloc_error() should be used to + * determine the nature of the error, if any, and the program should + * sensibly try and recover. + * + * @remarks A smart callback function must have the ::Evas_Smart_Cb prototype + * definition. The first parameter (@a data) in this definition + * has the same value passed to evas_object_smart_callback_add() as + * the @a data parameter, at runtime. The second parameter @a obj is a + * handle to the object on which the event occurred. The third + * parameter, @a event_info, is a pointer to data which is totally + * dependent on the smart object's implementation and semantic for the + * given event. + * + * @remarks There is an infrastructure for introspection on smart objects' + * events (see evas_smart_callbacks_descriptions_get()), but no + * internal smart objects on Evas implement them yet. + * + * @remarks The event's name strings are implemented by each smart object. + * Please refer the documentation of a smart object which you are + * insterested in. + * + * @param[in] obj A smart object + * @param[in] event The event's name string + * @param[in] func The callback function + * @param[in] data The user data to be passed to the callback function + * + * @see @ref Evas_Smart_Object_Group_Callbacks for more details. + * + * @see evas_object_smart_callback_del() + */ +EAPI void evas_object_smart_callback_add(Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @internal + * @brief Adds or registers a callback function to the smart event specified by + * @a event on the smart object @a obj. + * + * @details Except for the priority field, it is exactly the same as @ref evas_object_smart_callback_add. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] obj A smart object + * @param[in] event The event's name string + * @param[in] priority The priority of the callback \n + * Lower values are called first. + * @param[in] func The callback function + * @param[in] data The user data to be passed to the callback function + * + * @see evas_object_smart_callback_add + */ +EAPI void evas_object_smart_callback_priority_add(Evas_Object *obj, const char *event, Evas_Callback_Priority priority, Evas_Smart_Cb func, const void *data); + +/** + * @brief Deletes or unregisters a callback function from the smart event + * specified by @a event on the smart object @a obj. + * + * @details This function removes <b>the first</b> added smart callback on the + * object @a obj matching the event name @a event and the registered + * function pointer @a func. If the removal is successful it also + * returns the data pointer that is passed to + * evas_object_smart_callback_add() (that is the same as the + * parameter) when the callback(s) is(are) added to the canvas. + * + * @since_tizen 2.3 + * + * @param[in] obj A smart object + * @param[in] event The event's name string + * @param[in] func The callback function + * @return The data pointer, \n + * otherwise @c NULL if it is not successful + * + * @see evas_object_smart_callback_add() for more details. + */ +EAPI void *evas_object_smart_callback_del(Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Deletes or unregisters a callback function from the smart event + * specified by @a event on the smart object @a obj. + * + * @details This function removes <b>the first</b> added smart callback on the + * object @a obj matching the event name @a event, the registered + * function pointer @a func and the callback data pointer @a data. If + * the removal is successful, it also returns the data pointer that + * is passed to evas_object_smart_callback_add() (that is the same + * as the parameter) when the callback(s) is(are) added to the canvas. + * If not successful @c NULL is returned. A common use would be to + * remove an exact match of a callback + * @since 1.2 + * + * @since_tizen 2.3 + * + * @remarks To delete all smart event callbacks which match @a type and @a func, + * use evas_object_smart_callback_del(). + * + * @param[in] obj A smart object + * @param[in] event The event's name string + * @param[in] func The callback function + * @param[in] data The data pointer that is passed to the callback + * @return The data pointer + * + * @see evas_object_smart_callback_add() for more details. + */ +EAPI void *evas_object_smart_callback_del_full(Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Calls a given smart callback on the smart object @a obj. + * + * @details This function should be called @b internally, from the smart object's own + * code, when some specific event has occurred and the implementor + * wants to listen to the object's events API (see @ref + * Evas_Smart_Object_Group_Callbacks). The documentation for the smart + * object should include a list of possible events and what type of @a + * event_info to expect for each of them. Also, when defining an + * #Evas_Smart_Class, smart object implementors are strongly + * encouraged to properly set the Evas_Smart_Class::callbacks + * callbacks description array, so that the users of the smart object + * can have introspection on its events API <b>at run time</b>. + * + * @since_tizen 2.3 + * + * @param[in] obj The smart object + * @param[in] event The event's name string + * @param[in] event_info The pointer to an event specific struct or information to + * pass to the callback functions registered on this smart event + */ +EAPI void evas_object_smart_callback_call(Evas_Object *obj, const char *event, void *event_info) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets an smart object @b instance's smart callbacks descriptions. + * + * @since_tizen 2.3 + * + * @remarks These descriptions are hints to be used by introspection and are + * not enforced in any way. + * + * @remarks It is not checked if instance callbacks descriptions have the + * same name as respective possibly registered in the smart object + * @b class. Both are kept in different arrays and users of + * evas_object_smart_callbacks_descriptions_get() should handle this + * case as they wish. + * + * @remarks Because @a descriptions must be @c NULL terminated, and + * because a @c NULL name makes little sense, too, + * Evas_Smart_Cb_Description::name must @b not be @c NULL. + * + * @remarks While instance callbacks descriptions are possible, they are + * @b not recommended. Use @b class callbacks descriptions + * instead as they make it easier for you to use smart objects + * and use less memory, as descriptions and arrays are + * shared among all instances. + * + * @param[in] obj A smart object + * @param[in] descriptions @c NULL terminated array with #Evas_Smart_Cb_Description descriptions \n + * Array elements are not modified at run time, but references to + * them and their contents are made, so this array should be kept + * alive during the whole object's lifetime. + * @return #EINA_TRUE if the descriptions are set successfully, + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1); + +/** + * @brief Gets a smart object's smart callback descriptions (both + * instance and class ones). + * + * @details This function searches for registered callback descriptions for both + * instance and class of the given smart object. These arrays are + * sorted by Evas_Smart_Cb_Description::name and also @c NULL + * terminated, so both @a class_count and @a instance_count can be + * ignored, if the caller wishes so. The terminator @c NULL is not + * counted in these values. + * + * @since_tizen 2.3 + * + * @remarks If just class descriptions are of interest, try + * evas_smart_callbacks_descriptions_get() instead. + * + * @remarks Use @c NULL pointers on the descriptions or counters that you are not + * interested in: they are ignored by the function. + * + * @param[in] obj The smart object to get callback descriptions from + * @param[in] class_descriptions The class callbacks descriptions array, if any, that is returned \n + * If no descriptions are known, @c NULL is returned. + * @param[in] class_count The number of class callbacks descriptions, that is returned + * @param[in] instance_descriptions The instance callbacks descriptions array, if any, that is returned \n + * If no descriptions are known, @c NULL is returned. + * @param[in] instance_count The number of instance callbacks descriptions, that is returned + * + * @see evas_smart_callbacks_descriptions_get() + */ +EAPI void evas_object_smart_callbacks_descriptions_get(const Evas_Object *obj, const Evas_Smart_Cb_Description ***class_descriptions, unsigned int *class_count, const Evas_Smart_Cb_Description ***instance_descriptions, unsigned int *instance_count) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Finds the callback description for callback called @a name. + * + * @since_tizen 2.3 + * + * @param[in] obj The smart object + * @param[in] name The name of desired callback, \n + * This must @b not be @c NULL. The search has a special case + * for @a name being the same pointer as registered with + * Evas_Smart_Cb_Description; you can use it to avoid excessive + * use of strcmp(). + * @param[in] class_description The pointer to return class description or @c NULL, if not found \n + * If parameter is @c NULL, no search is done on class descriptions. + * @param[in] instance_description The pointer to return instance description or @c NULL if not found \n + * If parameter is @c NULL, no search is done on instance descriptions. + * @return The reference to description if found, \n + * otherwise @c NULL if not found + */ +EAPI void evas_object_smart_callback_description_find(const Evas_Object *obj, const char *name, const Evas_Smart_Cb_Description **class_description, const Evas_Smart_Cb_Description **instance_description) EINA_ARG_NONNULL(1, 2); + +/** + * @internal + * @brief Gets an Evas smart object's interface, by name string pointer. + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj An Evas smart object. + * @param[in] name The name string of the desired interface \n + * This must be the same pointer used at the interface's declaration, + * when creating the smart object @a obj. + * @return The interface's handle pointer, \n + * otherwise @c NULL if not found + */ +EAPI const void *evas_object_smart_interface_get(const Evas_Object *obj, const char *name); + +/** + * @internal + * @brief Gets an Evas smart object interface's <b>private data</b>. + * @since 1.7 + * + * @since_tizen 2.3 + * + * @param[in] obj An Evas smart object + * @param[in] iface The given object's interface handle + * @return The object interface's private data blob pointer, \n + * otherwise @c NULL if not found + */ +EAPI void *evas_object_smart_interface_data_get(const Evas_Object *obj, const Evas_Smart_Interface *iface); + +/** + * @brief Marks smart object as changed, dirty. + * + * @details This function flags the given object as needing recalculation, + * forcefully. As an effect, on the next rendering cycle its @b + * calculate() (see #Evas_Smart_Class) smart function is called. + * + * @since_tizen 2.3 + * + * @param[in] obj The given Evas smart object + * + * @see evas_object_smart_need_recalculate_set(). + * @see evas_object_smart_calculate(). + */ +EAPI void evas_object_smart_changed(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Sets or unsets the flag signalling that a given smart object needs to + * get recalculated. + * + * @since_tizen 2.3 + * + * @remarks If this flag is set, then the @c calculate() smart function of @a + * obj is called, if one is provided, during rendering phase of + * Evas (see evas_render()), after which this flag is + * automatically unset. + * + * @remarks If that smart function is not provided for the given object, this + * flag is left unchanged. + * + * @remarks Just setting this flag does not make the canvas' whole scene + * dirty, by itself, and evas_render() has no effect. To + * force that, use evas_object_smart_changed(), that also + * automatically calls this function, with + * #EINA_TRUE as parameter. + * + * @param[in] obj The smart object + * @param[in] value Set #EINA_TRUE to recalculate the smart object, \n + * otherwise set #EINA_FALSE to not recalculate the smart object + * + * @see evas_object_smart_need_recalculate_get() + * @see evas_object_smart_calculate() + * @see evas_smart_objects_calculate() + */ +EAPI void evas_object_smart_need_recalculate_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Gets the value of the flag signalling that a given smart object needs to + * get recalculated. + * + * @since_tizen 2.3 + * + * @remarks This flag is unset during the rendering phase, when the + * @c calculate() smart function is called, if one is provided. + * If it is not provided, then the flag is left unchanged + * after the rendering phase. + * + * @param[in] obj The smart object + * @return #EINA_TRUE if flag is set to recalculate, \n + * otherwise #EINA_FALSE if flag is not set to recalculate + * + * @see evas_object_smart_need_recalculate_set() + */ +EAPI Eina_Bool evas_object_smart_need_recalculate_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Calls the @b calculate() smart function immediately on a given smart object. + * + * @details This function forces immediate calculations (see #Evas_Smart_Class) + * needed for rendering of this object and, besides, unset the + * flag on it telling it needs recalculation for the next rendering phase. + * + * @since_tizen 2.3 + * + * @param[in] obj The smart object's handle + * + * @see evas_object_smart_need_recalculate_set() + */ +EAPI void evas_object_smart_calculate(Evas_Object *obj) EINA_ARG_NONNULL(1); + +/** + * @brief Calls user-provided @c calculate() smart functions and unset the + * flag signalling that the object needs to get recalculated to @b all + * smart objects in the canvas. + * + * @since_tizen 2.3 + * + * @param[in] e The canvas to calculate all smart objects in + * + * @see evas_object_smart_need_recalculate_set() + */ +EAPI void evas_smart_objects_calculate(Evas *e); + +/** + * @brief Gets the internal counter that counts the number of smart calculations. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Whenever evas performs smart object calculations on the whole canvas + * it increments a counter by @c 1. This is the smart object calculate counter + * that this function returns the value of. It starts at the value of @c 0 and + * increases (and eventually wrap around to negative values and so on) by + * @c 1 every time objects are calculated. You can use this counter to ensure + * that you do not re-do calculations within the same calculation generation or run + * if the calculations maybe cause self-feeding effects. + * + * @param[in] e The canvas to get the calculate counter from + * @return The number of smart calculations + */ +EAPI int evas_smart_objects_calculate_count_get(const Evas *e); + +/** + * @internal + * @brief Moves all children objects of a given smart object relative to a + * given offset. + * + * @details This function makes each of @a obj object's children to move, from where + * they before, with those delta values (offsets) on both directions. + * + * @since_tizen 2.3 + * + * @remarks This is most useful on custom smart @c move() functions. + * + * @remarks Clipped smart objects already make use of this function on + * their @c move() smart function definition. + * + * @param[in] obj The smart object + * @param[in] dx The horizontal offset (delta) + * @param[in] dy The vertical offset (delta) + */ +EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Smart_Object_Clipped Clipped Smart Object + * @ingroup Evas_Smart_Object_Group + * + * @brief This group provides functions for clipped smart objects. + * + * Clipped smart object is a base to construct other smart objects + * based on the concept of having an internal clipper that is applied + * to all children objects. This clipper controls the visibility, + * clipping and color of sibling objects (remember that the clipping + * is recursive, and clipper color modulates the color of its + * clippees). By default, this base also moves children relatively + * to the parent, and delete them when parent is deleted. In other + * words, it is the base for simple object grouping. + * + * @see evas_object_smart_clipped_smart_set() + * + * @{ + */ + +/** + * @brief The strcuture type that every subclass should provide this at the beginning of their own + * data set with evas_object_smart_data_set(). + */ +typedef struct _Evas_Object_Smart_Clipped_Data Evas_Object_Smart_Clipped_Data; +struct _Evas_Object_Smart_Clipped_Data +{ + Evas_Object *clipper; + Evas *evas; +}; + +/** + * @brief Gets the clipper object for the given clipped smart object. + * + * @since_tizen 2.3 + * + * @remarks Use this function if you want to change any of this clipper's + * properties, like colors. + * + * @param[in] obj The clipped smart object to retrieve associated clipper from + * @return The clipper object + * + * @see evas_object_smart_clipped_smart_add() + */ +EAPI Evas_Object *evas_object_smart_clipped_clipper_get(Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Sets a given smart class' callbacks so it implements the <b>clipped smart + * object</b>'s interface. + * + * @since_tizen 2.3 + * + * @remarks This call assigns all the required methods of the @a sc + * #Evas_Smart_Class instance to the implementations set for clipped + * smart objects. If one wants to "subclass" it, call this function + * and then override desired values. If one wants to call any original + * method, save it somewhere. + * + * @remarks The following is an example: + * + * @code + * static Evas_Smart_Class parent_sc = EVAS_SMART_CLASS_INIT_NULL; + * + * static void my_class_smart_add(Evas_Object *o) + * { + * parent_sc.add(o); + * evas_object_color_set(evas_object_smart_clipped_clipper_get(o), + * 255, 0, 0, 255); + * } + * + * Evas_Smart_Class *my_class_new(void) + * { + * static Evas_Smart_Class sc = EVAS_SMART_CLASS_INIT_NAME_VERSION("MyClass"); + * if (!parent_sc.name) + * { + * evas_object_smart_clipped_smart_set(&sc); + * parent_sc = sc; + * sc.add = my_class_smart_add; + * } + * return ≻ + * } + * @endcode + * + * @remarks The default behavior for each of #Evas_Smart_Class functions on a + * clipped smart object are: + * - @c add: creates a hidden clipper with "infinite" size, to clip any incoming members; + * - @c del: delete all children objects; + * - @c move: move all objects relative relatively; + * - @c resize: <b>not defined</b>; + * - @c show: if there are children objects, show clipper; + * - @c hide: hides clipper; + * - @c color_set: set the color of clipper; + * - @c clip_set: set clipper of clipper; + * - @c clip_unset: unset the clipper of clipper; + * + * @remarks There are other means of assigning parent smart classes to + * child ones, like the #EVAS_SMART_SUBCLASS_NEW macro or the + * evas_smart_class_inherit_full() function. + * + * @param[in] sc The smart class handle to operate on + */ +EAPI void evas_object_smart_clipped_smart_set(Evas_Smart_Class *sc) EINA_ARG_NONNULL(1); + +/** + * @internal + * @brief Gets a pointer to the <b>clipped smart object's</b> class, to use + * for proper inheritance. + * + * @since_tizen 2.3 + * + * @see #Evas_Smart_Object_Clipped for more information on this smart class. + */ +EAPI const Evas_Smart_Class *evas_object_smart_clipped_class_get(void) EINA_CONST; + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Box Box Smart Object + * @ingroup Evas_Smart_Object_Group + * + * @brief This group provides functions for bos smart objects. + * + * A box is a convenience smart object that packs children inside it + * in @b sequence, using a layouting function specified by the + * user. There are a couple of pre-made layouting functions <b>built-in + * in Evas</b>, all of them using children size hints to define their + * size and alignment inside their cell space. + * + * @see @ref Evas_Object_Group_Size_Hints + * + * @{ + */ + +/** + * @typedef Evas_Object_Box_Api + * + * @brief The structure type containing the smart class extension, providing extra box object requirements. + */ +typedef struct _Evas_Object_Box_Api Evas_Object_Box_Api; + +/** + * @typedef Evas_Object_Box_Data + * + * @brief The structure type containing the smart object instance data, providing box object requirements. + */ +typedef struct _Evas_Object_Box_Data Evas_Object_Box_Data; + +/** + * @typedef Evas_Object_Box_Option + * + * @brief The structure type containing the base structure for a box option. + * Box options are a way of extending box items properties, which are taken into account + * for layouting decisions. The box layouting functions provided by + * Evas only relies on objects' canonical size hints to layout + * them, so the basic box option has @b no (custom) property set. + * + * Users creating their own layouts, but not depending on extra child + * items' properties, would be fine just using + * evas_object_box_layout_set(). But if one desires a layout depending + * on extra child properties, he or she has to @b subclass the box smart + * object. Thus, by using evas_object_box_smart_class_get() and + * evas_object_box_smart_set(), the @c option_new() and @c + * option_free() smart class functions should be properly + * redefined or extended. + * + * Object properties are bound to an integer identifier and must have + * a name string. Their values are open to any data. See the API on + * option properties for more details. + */ +typedef struct _Evas_Object_Box_Option Evas_Object_Box_Option; + +/** + * @typedef Evas_Object_Box_Layout + * + * @brief Called for the function signature for an Evas box object layouting routine. + * @a o is the box object in question, @a priv is the box's internal data + * and, @a user_data is any custom data you could have set to + * a given box layouting function, with evas_object_box_layout_set(). + */ +typedef void (*Evas_Object_Box_Layout)(Evas_Object *o, Evas_Object_Box_Data *priv, void *user_data); + +/** + * @def EVAS_OBJECT_BOX_API_VERSION + * + * @brief Definition of the current version for Evas box object smart class, a value which goes + * to _Evas_Object_Box_Api::version. + */ +#define EVAS_OBJECT_BOX_API_VERSION 1 + +/** + * @struct _Evas_Object_Box_Api + * + * @brief The structure type that should be used by any smart class inheriting from + * the box's one, to provide custom box behavior which could not be + * achieved only by providing a layout function, with evas_object_box_layout_set(). + * + * @extends Evas_Smart_Class + */ +struct _Evas_Object_Box_Api +{ + Evas_Smart_Class base; /**< Base smart class struct, need for all smart objects */ + int version; /**< Version of this smart class definition */ + Evas_Object_Box_Option *(*append)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to append child elements in boxes */ + Evas_Object_Box_Option *(*prepend)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to prepend child elements in boxes */ + Evas_Object_Box_Option *(*insert_before)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, const Evas_Object * reference); /**< Smart function to insert a child element before another in boxes */ + Evas_Object_Box_Option *(*insert_after)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, const Evas_Object * reference); /**< Smart function to insert a child element after another in boxes */ + Evas_Object_Box_Option *(*insert_at)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child, unsigned int pos); /**< Smart function to insert a child element at a given position on boxes */ + Evas_Object *(*remove)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to remove a child element from boxes */ + Evas_Object *(*remove_at)(Evas_Object * o, Evas_Object_Box_Data * priv, unsigned int pos); /**< Smart function to remove a child element from boxes, by its position */ + Eina_Bool (*property_set)(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to set a custom property on a box child */ + Eina_Bool (*property_get)(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args); /**< Smart function to retrieve a custom property from a box child */ + const char *(*property_name_get)(const Evas_Object * o, int property); /**< Smart function to get the name of a custom property of box children */ + int (*property_id_get)(const Evas_Object *o, const char *name); /**< Smart function to get the numerical ID of a custom property of box children */ + Evas_Object_Box_Option *(*option_new)(Evas_Object * o, Evas_Object_Box_Data * priv, Evas_Object * child); /**< Smart function to create a new box option struct */ + void (*option_free)(Evas_Object *o, Evas_Object_Box_Data *priv, Evas_Object_Box_Option *opt); /**< Smart function to delete a box option struct */ +}; + +/** + * @def EVAS_OBJECT_BOX_API_INIT + * + * @brief Definition for initializing for a whole #Evas_Object_Box_Api structure, with + * @c NULL values on its specific fields. + * + * @param smart_class_init The initializer to use for the "base" field + * (#Evas_Smart_Class) + * + * @see EVAS_SMART_CLASS_INIT_NULL + * @see EVAS_SMART_CLASS_INIT_VERSION + * @see EVAS_SMART_CLASS_INIT_NAME_VERSION + * @see EVAS_OBJECT_BOX_API_INIT_NULL + * @see EVAS_OBJECT_BOX_API_INIT_VERSION + * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION + */ +#define EVAS_OBJECT_BOX_API_INIT(smart_class_init) {smart_class_init, EVAS_OBJECT_BOX_API_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL} + +/** + * @def EVAS_OBJECT_BOX_API_INIT_NULL + * + * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure. + * + * @see EVAS_OBJECT_BOX_API_INIT_VERSION + * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION + * @see EVAS_OBJECT_BOX_API_INIT + */ +#define EVAS_OBJECT_BOX_API_INIT_NULL EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NULL) + +/** + * @def EVAS_OBJECT_BOX_API_INIT_VERSION + * + * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure and + * set a specific version on it. + * + * @remarks This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it sets + * the version field of #Evas_Smart_Class (base field) to the latest + * EVAS_SMART_CLASS_VERSION. + * + * @see EVAS_OBJECT_BOX_API_INIT_NULL + * @see EVAS_OBJECT_BOX_API_INIT_NAME_VERSION + * @see EVAS_OBJECT_BOX_API_INIT + */ +#define EVAS_OBJECT_BOX_API_INIT_VERSION EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_VERSION) + +/** + * @def EVAS_OBJECT_BOX_API_INIT_NAME_VERSION + * + * @brief Definition for initializing to zero out a whole #Evas_Object_Box_Api structure and + * set its name and version. + * + * @remarks This is similar to #EVAS_OBJECT_BOX_API_INIT_NULL, but it also + * sets the version field of #Evas_Smart_Class (base field) to the + * latest EVAS_SMART_CLASS_VERSION and name it to the specific value. + * + * @remarks It keeps a reference to the name field as a <c>"const char *"</c>, + * i.e., the name must be available while the structure is + * used (hint: static or global variable) and must not be modified. + * + * @see EVAS_OBJECT_BOX_API_INIT_NULL + * @see EVAS_OBJECT_BOX_API_INIT_VERSION + * @see EVAS_OBJECT_BOX_API_INIT + */ +#define EVAS_OBJECT_BOX_API_INIT_NAME_VERSION(name) EVAS_OBJECT_BOX_API_INIT(EVAS_SMART_CLASS_INIT_NAME_VERSION(name)) + +/** + * @struct _Evas_Object_Box_Data + * + * @brief The structure type that augments clipped smart object's instance data, + * providing extra members required by generic box implementation. If + * a subclass inherits from #Evas_Object_Box_Api, then it may augment + * #Evas_Object_Box_Data to fit its own needs. + * + * @extends Evas_Object_Smart_Clipped_Data + */ +struct _Evas_Object_Box_Data +{ + Evas_Object_Smart_Clipped_Data base; + const Evas_Object_Box_Api *api; + struct + { + double h, v; + } align; + struct + { + Evas_Coord h, v; + } pad; + Eina_List *children; + struct + { + Evas_Object_Box_Layout cb; + void *data; + void (*free_data)(void *data); + } layout; + Eina_Bool layouting : 1; + Eina_Bool children_changed : 1; +}; + +/** + * @brief Evas_Object_Box_Option struct fields + */ +struct _Evas_Object_Box_Option +{ + Evas_Object *obj; /**< Pointer to the box child object, itself */ + Eina_Bool max_reached : 1; + Eina_Bool min_reached : 1; + Evas_Coord alloc_size; +}; + +/** + * @brief Sets the default box @a api struct (Evas_Object_Box_Api) + * with the default values. This may be used to extend that API. + * + * @param api The box API struct to set back, most probably with + * overridden fields (on class extensions scenarios) + */ +EAPI void evas_object_box_smart_set(Evas_Object_Box_Api *api) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the Evas box smart class, for inheritance purposes. + * + * @remarks The returned value is @b not to be modified, just use it as your + * parent class. + * @return The (canonical) Evas box smart class + */ +EAPI const Evas_Object_Box_Api *evas_object_box_smart_class_get(void) EINA_CONST; + +/** + * @brief Sets a new layouting function to a given box object. + * + * @since_tizen 2.3 + * + * @remarks A box layout function affects how a box object displays child + * elements within its area. The list of pre-defined box layouts + * available in Evas is: + * - evas_object_box_layout_horizontal() + * - evas_object_box_layout_vertical() + * - evas_object_box_layout_homogeneous_horizontal() + * - evas_object_box_layout_homogeneous_vertical() + * - evas_object_box_layout_homogeneous_max_size_horizontal() + * - evas_object_box_layout_homogeneous_max_size_vertical() + * - evas_object_box_layout_flow_horizontal() + * - evas_object_box_layout_flow_vertical() + * - evas_object_box_layout_stack() + * See each of their documentation texts for details on them. + * + * @remarks A box layouting function is triggered by the @c + * 'calculate' smart callback of the box's smart class. + * + * @param[in] o The box object to operate on + * @param[in] cb The new layout function to set on @a o + * @param[in] data The data pointer to be passed to @a cb + * @param[in] free_data The function to free @a data, if need be + */ +EAPI void evas_object_box_layout_set(Evas_Object *o, Evas_Object_Box_Layout cb, const void *data, void (*free_data)(void *data)) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds a new box object on the provided canvas. + * + * @since_tizen 2.3 + * + * @remarks After instantiation, if a box object has not its layout function + * set, via evas_object_box_layout_set(), it has it by default + * set to evas_object_box_layout_horizontal(). The remaining + * properties of the box must be set/retrieved via + * <c>evas_object_box_{h,v}_{align,padding}_{get,set)()</c>. + * + * @param[in] evas The canvas to create the box object on + * @return A pointer to a new box object, \n + * otherwise @c NULL on error + */ +EAPI Evas_Object *evas_object_box_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Adds a new box as a @b child of a given smart object. + * + * @since_tizen 2.3 + * + * @remarks This function is a helper function that has the same effect of putting a new + * box object into @a parent by use of evas_object_smart_member_add(). + * + * @param[in] parent The parent smart object to put the new box in + * @return A pointer to a new box object, \n + * otherwise @c NULL on error + * + * @see evas_object_box_add() + */ +EAPI Evas_Object *evas_object_box_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Layout function which sets the box @a o to a (basic) horizontal box. + * + * In this layout, the box object's overall behavior is controlled by + * its padding/alignment properties, which are set by the + * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of + * functions. The size hints of the elements in the box -- set by the + * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions + * -- also control the way this function works. + * + * @par Box's properties: + * @c align_h controls the horizontal alignment of the child objects + * relative to the containing box. When set to @c 0.0, children are + * aligned to the left. A value of @c 1.0 makes them aligned to the + * right border. Values in between align them proportionally. Note + * that if the size required by the children, which is given by their + * widths and the @c padding_h property of the box, is bigger than the + * their container's width, the children are displayed out of the + * box's bounds. A negative value of @c align_h makes the box to + * @b justify its children. The padding between them, in this case, is + * corrected so that the leftmost one touches the left border and the + * rightmost one touches the right border (even if they must + * overlap). The @c align_v and @c padding_v properties of the box + * @b do not contribute to its behaviour when this layout is chosen. + * + * @par Child element's properties: + * @c align_x does @b not influence the box's behavior. @c padding_l + * and @c padding_r sum up to the container's horizontal padding + * between elements. The child's @c padding_t, @c padding_b and + * @c align_y properties apply for padding or alignment relative to the + * overall height of the box. Finally, there is the @c weight_x + * property, which, if set to a non-zero value, tells the container + * that the child width is @b not pre-defined. If the container can not + * accommodate all its children, it sets the widths of the ones + * <b>with weights</b> to sizes as small as they can all fit into + * it. If the size required by the children is less than the + * available, the box increases its childrens' (which have weights) + * widths as to fit the remaining space. The @c weight_x property, + * besides telling the element is resizable, gives a @b weight for the + * resizing process. The parent box tries to distribute (or take + * off) widths accordingly to the @b normalized list of weights: most + * weighted children remain or get larger in this process than the least + * ones. @c weight_y does not influence the layout. + * + * If you desire that, besides having weights, child elements must be + * resized bounded to a minimum or maximum size, those size hints must + * be set, by the <c>evas_object_size_hint_{min,max}_set()</c> + * functions. + * + * @since_tizen 2.3 + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a (basic) vertical box. + * + * @details This Layout function behaves analogously to + * evas_object_box_layout_horizontal(). The description of its + * behaviour can be derived from that function's documentation. + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + * + * @since_tizen 2.3 + * + */ +EAPI void evas_object_box_layout_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a @b homogeneous vertical box. + * + * @details This Layout function behaves analogously to + * evas_object_box_layout_homogeneous_horizontal(). The description + * of its behaviour can be derived from that function's documentation. + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + * + * @since_tizen 2.3 + * + */ +EAPI void evas_object_box_layout_homogeneous_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a @b homogeneous horizontal box. + * + * In a homogeneous horizontal box, its width is divided @b equally + * between the contained objects. The box's overall behavior is + * controlled by its padding or alignment properties, which are set by + * the <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of + * functions. The size hints the elements in the box -- set by the + * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions + * -- also control the way this function works. + * + * @par Box's properties: + * @c align_h has no influence on the box for this layout. + * @c padding_h tells the box to draw empty spaces of that size, in + * pixels, between the (equal) child objects' cells. The @c align_v + * and @c padding_v properties of the box do not contribute to its + * behaviour when this layout is chosen. + * + * @par Child element's properties: + * @c padding_l and @c padding_r sum up to the required width of the + * child element. The @c align_x property tells the relative position + * of this overall child width in its allocated cell (@c 0.0 to + * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to + * @c align_x makes the box try to resize this child element to the exact + * width of its cell (respecting the minimum and maximum size hints on + * the child's width and accounting for its horizontal padding + * hints). The child's @c padding_t, @c padding_b and @c align_y + * properties apply for padding or alignment relative to the overall + * height of the box. A value of @c -1.0 to @c align_y makes the box + * try to resize this child element to the exact height of its parent + * (respecting the maximum size hint on the child's height). + * + * @since_tizen 2.3 + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_homogeneous_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a <b>maximum size, homogeneous</b> horizontal box + * + * In a maximum size, homogeneous horizontal box, besides having cells + * of <b>equal size</b> reserved for the child objects, this size is + * defined by the size of the @b largest child in the box (in + * width). The box's overall behavior is controlled by its properties, + * which are set by the + * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of + * functions. The size hints of the elements in the box -- set by the + * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions + * -- also control the way this function works. + * + * @par Box's properties: + * @c padding_h tells the box to draw empty spaces of that size, in + * pixels, between the child objects' cells. @c align_h controls the + * horizontal alignment of the child objects, relative to the + * containing box. When set to @c 0.0, children are aligned to the + * left. A value of @c 1.0 lets them aligned to the right + * border. Values in between align them proportionally. A negative + * value of @c align_h makes the box to @b justify its children + * cells. The padding between them, in this case, is corrected so that + * the leftmost one touches the left border and the rightmost one + * touches the right border (even if they must overlap). The + * @c align_v and @c padding_v properties of the box do not contribute to + * its behaviour when this layout is chosen. + * + * @par Child element's properties: + * @c padding_l and @c padding_r sum up to the required width of the + * child element. The @c align_x property tells the relative position + * of this overall child width in its allocated cell (@c 0.0 to + * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to + * @c align_x makes the box try to resize this child element to the exact + * width of its cell (respecting the minimum and maximum size hints on + * the child's width and accounting for its horizontal padding + * hints). The child's @c padding_t, @c padding_b and @c align_y + * properties apply for padding/alignment relative to the overall + * height of the box. A value of @c -1.0 to @c align_y makes the box + * try to resize this child element to the exact height of its parent + * (respecting the max hint on the child's height). + * + * @since_tizen 2.3 + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_homogeneous_max_size_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a <b>maximum size, homogeneous</b> vertical box. + * + * @since_tizen 2.3 + * + * @remarks This function behaves analogously to + * evas_object_box_layout_homogeneous_max_size_horizontal(). The + * description of its behaviour can be derived from that function's + * documentation. + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_homogeneous_max_size_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a @b flow horizontal box. + * + * In a flow horizontal box, the box's child elements are placed in + * @b rows (think of text as an analogy). A row has as much elements as + * can fit into the box's width. The box's overall behavior is + * controlled by its properties, which are set by the + * <c>evas_object_box_{h,v}_{align,padding}_set()</c> family of + * functions. The size hints of the elements in the box -- set by the + * <c>evas_object_size_hint_{align,padding,weight}_set()</c> functions + * -- also control the way this function works. + * + * @par Box's properties: + * @c padding_h tells the box to draw empty spaces of that size, in + * pixels, between the child objects' cells. @c align_h dictates the + * horizontal alignment of the rows (@c 0.0 to left align them, @c 1.0 + * to right align). A value of @c -1.0 to @c align_h lets the rows + * @b justified horizontally. @c align_v controls the vertical alignment + * of the entire set of rows (@c 0.0 to top, @c 1.0 to bottom). A + * value of @c -1.0 to @c align_v makes the box to @b justify the rows + * vertically. The padding between them, in this case, is corrected so + * that the first row touches the top border and the last one touches + * the bottom border (even if they must overlap). @c padding_v has no + * influence on the layout. + * + * @par Child element's properties: + * @c padding_l and @c padding_r sum up to the required width of the + * child element. The @c align_x property has no influence on the + * layout. The child's @c padding_t and @c padding_b sum up to the + * required height of the child element and is the only means (besides + * row justifying) of setting space between rows. Note, however, that + * @c align_y dictates positioning relative to the <b>largest + * height</b> required by a child object in the actual row. + * + * @since_tizen 2.3 + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_flow_horizontal(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a @b flow vertical box. + * + * @details This function behaves analogously to + * evas_object_box_layout_flow_horizontal(). The description of its + * behaviour can be derived from that function's documentation. + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + * + * @since_tizen 2.3 + * + */ +EAPI void evas_object_box_layout_flow_vertical(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the box @a o to a @b stacking box. + * + * In a stacking box, all children are given the same size -- the + * box's own size -- and they are stacked one above the other, so + * that the first object in @a o's internal list of child elements + * are the bottommost in the stack. + * + * @par Box's properties: + * No box properties are used. + * + * @par Child element's properties: + * @c padding_l and @c padding_r sum up to the required width of the + * child element. The @c align_x property tells the relative position + * of this overall child width in its allocated cell (@c 0.0 to + * extreme left, @c 1.0 to extreme right). A value of @c -1.0 to @c + * align_x makes the box try to resize this child element to the exact + * width of its cell (respecting the min and max hints on the child's + * width and accounting for its horizontal padding properties). The + * same applies to the vertical axis. + * + * @since_tizen 2.3 + * + * @param[in] o The box object in question + * @param[in] priv The smart data of the @a o + * @param[in] data The data pointer passed on evas_object_box_layout_set(), if any + */ +EAPI void evas_object_box_layout_stack(Evas_Object *o, Evas_Object_Box_Data *priv, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets the alignment of the whole bounding box of contents, for a + * given box object. + * + * @details This influences how a box object is to align its bounding box + * of contents within its own area. The values @b must be in the range + * @c 0.0 - @c 1.0, or undefined behavior is expected. For horizontal + * alignment, @c 0.0 means to the left, with @c 1.0 meaning to the + * right. For vertical alignment, @c 0.0 means to the top, with @c 1.0 + * meaning to the bottom. + * + * @since_tizen 2.3 + * + * @remarks The default values for both alignments is @c 0.5. + * + * @param[in] o The given box object to set alignment from + * @param[in] horizontal The horizontal alignment, in pixels + * @param[in] vertical The vertical alignment, in pixels + * + * @see evas_object_box_align_get() + */ +EAPI void evas_object_box_align_set(Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the alignment of the whole bounding box of contents, for a + * given box object. + * + * @since_tizen 2.3 + * + * @param[in] o The given box object to get alignment from + * @param[out] horizontal The pointer to a variable where to store the + * horizontal alignment + * @param[out] vertical The pointer to a variable where to store the vertical alignment + * + * @see evas_object_box_align_set() for more information + */ +EAPI void evas_object_box_align_get(const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the (space) padding between cells set for a given box object. + * + * @since_tizen 2.3 + * + * @remarks The default values for both padding components is @c 0. + * + * @param[in] o The given box object to set padding from + * @param[in] horizontal The horizontal padding, in pixels + * @param[in] vertical The vertical padding, in pixels + * + * @see evas_object_box_padding_get() + */ +EAPI void evas_object_box_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the (space) padding between cells set for a given box object. + * + * @since_tizen 2.3 + * + * @param[in] o The given box object to get padding from + * @param[out] horizontal The pointer to a variable where to store the + * horizontal padding + * @param[out] vertical The pointer to a variable where to store the vertical padding + * + * @see evas_object_box_padding_set() + */ +EAPI void evas_object_box_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Appends a new @a child object to the given box object @a o. + * + * @since_tizen 2.3 + * + * @remarks On success, the @c "child,added" smart event takes place. + * + * @remarks The actual placing of the item relative to the area of @a o + * depends on the layout set to it. For example, on horizontal layouts + * an item in the end of the box's list of children appear on its right. + * + * @remarks This call triggers the box's _Evas_Object_Box_Api::append + * smart function. + * + * @param[in] o The given box object + * @param[in] child A child Evas object to be made a member of @a o + * @return A box option bound to the recently added box item, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Object_Box_Option *evas_object_box_append(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Prepends a new @a child object to the given box object @a o. + * + * @since_tizen 2.3 + * + * @remarks On success, the @c "child,added" smart event takes place. + * + * @remarks The actual placing of the item relative to the area of @a o + * depends on the layout set to it. For example, on horizontal layouts + * an item in the beginning of the box's list of children appear + * on its left. + * + * @remarks This call triggers the box's + * _Evas_Object_Box_Api::prepend smart function. + * + * @param[in] o The given box object + * @param[in] child A child Evas object to be made a member of @a o + * @return A box option bound to the recently added box item, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Object_Box_Option *evas_object_box_prepend(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Inserts a new @a child object <b>before another existing one</b>, in + * a given box object @a o. + * + * @since_tizen 2.3 + * + * @remarks On success, the @c "child,added" smart event takes place. + * + * @remarks This function fails if @a reference is not a member of @a o. + * + * @remarks The actual placing of the item relative to the area of @a o + * depends on the layout set to it. + * + * @remarks This call triggers the box's + * _Evas_Object_Box_Api::insert_before smart function. + * + * @param[in] o The given box object + * @param[in] child A child Evas object to be made a member of @a o + * @param[in] reference The child object to place this new one before + * @return A box option bound to the recently added box item, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Object_Box_Option *evas_object_box_insert_before(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Inserts a new @a child object <b>after another existing one</b>, in + * a given box object @a o. + * + * @since_tizen 2.3 + * + * @remarks On success, the @c "child,added" smart event takes place. + * + * @remarks This function fails if @a reference is not a member of @a o. + * + * @remarks The actual placing of the item relative to the area of @a o + * depends on the layout set to it. + * + * @remarks This call triggers the box's + * _Evas_Object_Box_Api::insert_after smart function. + * + * @param[in] o The given box object + * @param[in] child A child Evas object to be made a member of @a o + * @param[in] reference The child object to place this new one after + * @return A box option bound to the recently added box item, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Object_Box_Option *evas_object_box_insert_after(Evas_Object *o, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Inserts a new @a child object <b>at a given position</b>, in a given + * box object @a o. + * + * @since_tizen 2.3 + * + * @remarks On success, the @c "child,added" smart event takes place. + * + * @remarks This function fails if the given position is invalid, + * given the internal list of elements of @a o. + * + * @remarks The actual placing of the item relative to the area of @a o + * depends on the layout set to it. + * + * @remarks This call triggers the box's + * _Evas_Object_Box_Api::insert_at smart function. + * + * @param[in] o The given box object + * @param[in] child A child Evas object to be made a member of @a o + * @param[in] pos The numeric position (starting from @c 0) to place the + * new child object at + * @return A box option bound to the recently added box item, \n + * otherwise @c NULL on errors + */ +EAPI Evas_Object_Box_Option *evas_object_box_insert_at(Evas_Object *o, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes a given object from a box object, unparenting it again. + * + * @since_tizen 2.3 + * + * @remarks On removal, you get an unparented object again, just as it is + * before you inserted it in the box. The + * _Evas_Object_Box_Api::option_free box smart callback is called + * automatically for you and, also, the @c "child,removed" smart event + * takes place. + * + * @remarks This call triggers the box's _Evas_Object_Box_Api::remove + * smart function. + * + * @param[in] o The box object to remove a child object from + * @param[in] child The handle to the child object to be removed + * @return #EINA_TRUE if the object is removed from the box object successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_remove(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes an object, <b>bound to a given position</b> in a box object, + * unparenting it again. + * + * @since_tizen 2.3 + * + * @remarks On removal, you get an unparented object again, just as it is + * before you inserted it in the box. The @c option_free() box smart + * callback is called automatically for you and, also, the + * @c "child,removed" smart event takes place. + * + * @remarks This function fails if the given position is invalid, + * given the internal list of elements of @a o. + * + * @remarks This call triggers the box's + * _Evas_Object_Box_Api::remove_at smart function. + * + * @param[in] o The box object to remove a child object from + * @param[in] pos The numeric position (starting from @c 0) of the child + * object to be removed + * @return #EINA_TRUE if the object is removed successfully, + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_remove_at(Evas_Object *o, unsigned int pos) EINA_ARG_NONNULL(1); + +/** + * @brief Removes @b all child objects from a box object, unparenting them again. + * + * @since_tizen 2.3 + * + * @remarks This has the same effect of calling evas_object_box_remove() on + * each of @a o's child objects, in sequence. If, and only if, all + * those calls succeed, so does this one. + * + * @param[in] o The box object to remove a child object from + * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n + * otherwise set #EINA_FALSE to not delete the children + * @return #EINA_TRUE if the child objects are removed successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_remove_all(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); + +/** + * @brief Gets an iterator to walk the list of children of a given box object. + * + * @since_tizen 2.3 + * + * @remarks Do @b not remove or delete objects while walking the list. + * + * @param[in] o The box to retrieve an items iterator from + * @return An iterator on @a o's child objects, \n + * otherwise @c NULL on errors + */ +EAPI Eina_Iterator *evas_object_box_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets an accessor (a structure providing random items access) to the + * list of children of a given box object. + * + * @since_tizen 2.3 + * + * @remarks Do not remove or delete objects while walking the list. + * + * @param[in] o The box to retrieve an items iterator from + * @return An accessor on @a o's child objects, \n + * otherwise @c NULL on errors + */ +EAPI Eina_Accessor *evas_object_box_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the list of children objects in a given box object. + * + * @since_tizen 2.3 + * + * @remarks The returned list should be freed with @c eina_list_free() when you + * no longer need it. + * + * @remarks This is a duplicate of the list kept by the box internally. + * It is up to the user to destroy it when it no longer needs it. + * It is possible to remove objects from the box when walking + * this list, but these removals are not reflected on it. + * + * @param[in] o The box to retrieve an items list from + * @return A list of @a o's child objects, \n + * otherwise @c NULL on errors or if it has no child objects + */ +EAPI Eina_List *evas_object_box_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the name of the property of the child elements of the box @a o + * which have @a id as identifier. + * + * @since_tizen 2.3 + * + * @remarks This call does not do anything for a canonical Evas box. Only + * users which have @b subclassed it, setting custom box items options + * (see #Evas_Object_Box_Option) on it, would benefit from this + * function. They would have to implement it and set it to be the + * _Evas_Object_Box_Api::property_name_get smart class function of the + * box, which is originally set to @c NULL. + * + * @param[in] o The box to search child options from + * @param[in] property The numerical identifier of the option being searched, + * for its name + * @return The name of the given property, \n + * otherwise @c NULL on errors + */ +EAPI const char *evas_object_box_option_property_name_get(const Evas_Object *o, int property) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets the numerical identifier of the property of the child elements + * of the box @a o which have @a name as name string. + * + * @since_tizen 2.3 + * + * @remarks This call does not do anything for a canonical Evas box. Only + * users which have @b subclassed it, setting custom box items options + * (see #Evas_Object_Box_Option) on it, would benefit from this + * function. They would have to implement it and set it to be the + * _Evas_Object_Box_Api::property_id_get smart class function of the + * box, which is originally set to @c NULL. + * + * @param[in] o The box to search child options from + * @param[in] name The name string of the option being searched, for its ID + * @return The numerical ID of the given property, \n + * otherwise @c -1 on errors + */ +EAPI int evas_object_box_option_property_id_get(const Evas_Object *o, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets a property value (by its given numerical identifier), on a + * given box child element + * + * @since_tizen 2.3 + * + * @remarks This call does not do anything for a canonical Evas box. Only + * users which have @b subclassed it, setting custom box items options + * (see #Evas_Object_Box_Option) on it, would benefit from this + * function. They would have to implement it and set it to be the + * _Evas_Object_Box_Api::property_set smart class function of the box, + * which is originally set to @c NULL. + * + * @remarks This function internally creates a variable argument + * list, with the values passed after @a property, and call + * evas_object_box_option_property_vset() with this list and the same + * previous arguments. + * + * @param[in] o The box parenting the child element + * @param[in] opt The box option structure bound to the child box element + * to set a property on + * @param[in] property The numerical ID of the given property + * @param[in] ... (List of) actual value(s) to be set for this property \n + * It (they) @b must be of the same type the user has + * defined for it (them). + * @return #EINA_TRUE if the property value is set successfully, + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_option_property_set(Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Sets a property value (by its given numerical identifier), on a + * given box child element -- by a variable argument list + * + * @since_tizen 2.3 + * + * @remarks This is a variable argument list variant of the + * evas_object_box_option_property_set(). See its documentation for + * more details. + * + * @param[in] o The box parenting the child element + * @param[in] opt The box option structure bound to the child box element + * to set a property on + * @param[in] property The numerical ID of the given property + * @param[in] args The variable argument list implementing the value to + * be set for this property. It @b must be of the same type the user has + * defined for it. + * @return #EINA_TRUE if teh property value is set successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_option_property_vset(Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets a property's value (by its given numerical identifier), on a + * given box child element. + * + * @since_tizen 2.3 + * + * @remarks This call does not do anything for a canonical Evas box. Only + * users which have @b subclassed it, getting custom box items options + * (see #Evas_Object_Box_Option) on it, would benefit from this + * function. They would have to implement it and get it to be the + * _Evas_Object_Box_Api::property_get smart class function of the + * box, which is originally get to @c NULL. + * + * @remarks This function internally creates a variable argument + * list, with the values passed after @a property, and call + * evas_object_box_option_property_vget() with this list and the same + * previous arguments. + * + * @param[in] o The box parenting the child element + * @param[in] opt The box option structure bound to the child box element + * to get a property from + * @param[in] property The numerical ID of the given property + * @param[in] ... (List of) pointer(s) where to store the value(s) set for this property, \n + * It (they) @b must point to variable(s) of the same type the user + * has defined for it (them). + * @return #EINA_TRUE if the property values are obtained successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_option_property_get(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, ...) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Gets a property's value (by its given numerical identifier), on a + * given box child element -- by a variable argument list + * + * @since_tizen 2.3 + * + * @remarks This is a variable argument list variant of the + * evas_object_box_option_property_get(). See its documentation for + * more details. + * + * @param[in] o The box parenting the child element + * @param[in] opt The box option structure bound to the child box element + * to get a property from + * @param[in] property The numerical ID of the given property + * @param[in] args The variable argument list with pointers to where to + * store the values of this property \n + * They @b must point to variables + * of the same type the user has defined for them. + * @return #EINA_TRUE if the property values are obtained successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_box_option_property_vget(const Evas_Object *o, Evas_Object_Box_Option *opt, int property, va_list args) EINA_ARG_NONNULL(1, 2); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Table Table Smart Object. + * @ingroup Evas_Smart_Object_Group + * + * @brief This group provides functions for table smart objects. + * + * @remarks Convenience smart object that packs children using a tabular + * layout using children size hints to define their size and + * alignment inside their cell space. + * + * @see @ref Evas_Object_Group_Size_Hints + * + * @{ + */ + +/** + * @brief Creates a new table. + * + * @since_tizen 2.3 + * + * @param[in] evas The canvas in which table are added + * @return The new table object + */ +EAPI Evas_Object *evas_object_table_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Creates a table that is child of a given element @a parent. + * + * @since_tizen 2.3 + * + * @param[in] parent The parent element + * @return The new table object + * + * @see evas_object_table_add() + */ +EAPI Evas_Object *evas_object_table_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Sets how this table should layout children. + * + * @todo consider aspect hint and respect it. + * + * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE + * If table does not use homogeneous mode then columns and rows + * are calculated based on hints of individual cells. This operation + * mode is more flexible, but more complex and heavy to calculate as + * well. @b Weight properties are handled as a boolean expand. Negative + * alignment is considered as @c 0.5. This is the default. + * + * @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight. + * + * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE + * When homogeneous is relative to table, the own table size is divided + * equally among children, filling the whole table area. That is, if + * table has @c WIDTH and @c COLUMNS, each cell gets <tt>WIDTH / + * COLUMNS</tt> pixels. If children have minimum size that is larger + * than this amount (including padding), then it overflows and is + * aligned respecting the alignment hint, possible overlapping sibling + * cells. @b Weight hint is used as a boolean, if greater than zero it + * makes the child expand in that axis, taking as much space as + * possible (bounded to maximum size hint). Negative alignment is + * considered as @c 0.5. + * + * @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM + * When homogeneous is relative to item, it means the greatest minimum + * cell size is used. That is, if no element is set to expand, + * the table has its contents to a minimum size, the bounding + * box of all these children is aligned relatively to the table + * object using evas_object_table_align_get(). If the table area is + * too small to hold this minimum bounding box, then the objects + * keep their size and the bounding box overflows the box area, + * still respecting the alignment. @b Weight hint is used as a + * boolean, if greater than zero it makes that cell expand in that + * axis, toggling the <b>expand mode</b>, which makes the table behave + * much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the + * bounding box overflows and items do not overlap siblings. If + * no minimum size is provided at all then the table fallsback to + * expand mode as well. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @param[in] homogeneous The homogeneous mode + */ +EAPI void evas_object_table_homogeneous_set(Evas_Object *o, Evas_Object_Table_Homogeneous_Mode homogeneous) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current layout homogeneous mode. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @return The homogeneous mode + + * @see evas_object_table_homogeneous_set() + */ +EAPI Evas_Object_Table_Homogeneous_Mode evas_object_table_homogeneous_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Sets padding between cells. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @param[in] horizontal The horizontal padding to set + * @param[in] vertical The vertical padding to set + * + */ +EAPI void evas_object_table_padding_set(Evas_Object *o, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Gets padding between cells. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @param[out] horizontal The horizontal padding that is obtained + * @param[out] vertical The vertical padding that is obtained + */ +EAPI void evas_object_table_padding_get(const Evas_Object *o, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the alignment of the whole bounding box of contents. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @param[in] horizontal The horizontal alignment to set + * @param[in] vertical The vertical alignment to set + */ +EAPI void evas_object_table_align_set(Evas_Object *o, double horizontal, double vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the alignment of the whole bounding box of contents. + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @param[out] horizontal The horizontal alignment that is obtained + * @param[out] vertical The vertical alignment that is obtained + */ +EAPI void evas_object_table_align_get(const Evas_Object *o, double *horizontal, double *vertical) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the mirrored mode of the table. + * @since 1.1 + * + * @since_tizen 2.3 + * + * remarks In mirrored mode the table items go from right to left instead of left to right. + * That is, 1,1 is top right, not top left. + * + * @param[in] o The table object + * @param[in] mirrored The mirrored mode to set + */ +EAPI void evas_object_table_mirrored_set(Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the mirrored mode of the table. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The table object + * @return #EINA_TRUE if it is a mirrored table, \n + * otherwise #EINA_FALSE if it is not a mirrored table + * @see evas_object_table_mirrored_set() + */ +EAPI Eina_Bool evas_object_table_mirrored_get(const Evas_Object *o) EINA_ARG_NONNULL(1); + +/** + * @brief Gets packing location of a child of table. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The given table object + * @param[in] child The child object to add + * @param[out] col The pointer to store relative-horizontal position to place child + * @param[out] row The pointer to store relative-vertical position to place child + * @param[out] colspan The pointer to store how many relative-horizontal position to use for this child + * @param[out] rowspan The pointer to store how many relative-vertical position to use for this child + * + * @return #EINA_TRUE if the packing location is obtained successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_table_pack_get(const Evas_Object *o, Evas_Object *child, unsigned short *col, unsigned short *row, unsigned short *colspan, unsigned short *rowspan); + +/** + * @brief Adds a new child to a table object or set its current packing. + * + * @since_tizen 2.3 + * + * @param[in] o The given table object + * @param[in] child The child object to add + * @param[in] col The relative-horizontal position to place the child + * @param[in] row The relative-vertical position to place the child + * @param[in] colspan The number of relative-horizontal position to use for this child + * @param[in] rowspan The number of relative-vertical position to use for this child + * @return #EINA_TRUE if the new child is added successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_table_pack(Evas_Object *o, Evas_Object *child, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes child from table. + * + * @since_tizen 2.3 + * + * @remarks Removing a child immediately calls a walk over children in order + * to recalculate the numbers of columns and rows. If you plan to remove + * all children, use evas_object_table_clear() instead. + * + * @param[in] o The given table object + * @param[in] child The child object to remove + * @return #EINA_TRUE if the child is removed successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_table_unpack(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes all child objects from a table object. + * + * @since_tizen 2.3 + * + * @remarks This is a faster way to remove the child objects. + * + * @param[in] o The given table object + * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n + * otherwise set #EINA_FALSE to not delete the removed children + */ +EAPI void evas_object_table_clear(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the number of columns and rows this table takes. + * + * @since_tizen 2.3 + * + * @remarks The columns and rows are virtual entities, one can specify a table + * with a single object that takes 4 columns and 5 rows. The only + * difference for a single cell table is that paddings are + * accounted proportionally. + * + * @param[in] o The table object + * @param[out] cols The number of columns + * @param[out] rows The number of rows + */ +EAPI void evas_object_table_col_row_size_get(const Evas_Object *o, int *cols, int *rows) EINA_ARG_NONNULL(1); + +/** + * @brief Gets an iterator to walk through the list of children for the table. + * + * @since_tizen 2.3 + * + * @remarks Do not remove or delete objects while walking the list. + * + * @param[in] o The table object + * @return An iterator to walk through the children of the object, \n + * otherwise @c NULL in case of errors + */ +EAPI Eina_Iterator *evas_object_table_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets an accessor to get random access to the list of children for the table. + * + * @since_tizen 2.3 + * + * @remarks Do not remove or delete objects while walking the list. + * + * @param[in] o The table object + * @return An accessor on @a o's child objects, \n + * otherwise @c NULL in case of errors + */ +EAPI Eina_Accessor *evas_object_table_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the list of children for the table. + * + * @since_tizen 2.3 + * + * @remarks This is a duplicate of the list kept by the table internally. + * It is up to the user to destroy it when it no longer needs it. + * It is possible to remove objects from the table when walking this + * list, but these removals are not reflected on it. + * + * @param[in] o The table object + * @return The list of the children, \n + * otherwise @c NULL in case of errors + */ +EAPI Eina_List *evas_object_table_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the child of the table at the given coordinates. + * + * @since_tizen 2.3 + * + * @remarks This does not take into account col or row spanning. + * + * @param[in] o The table object + * @param[in] col The number of columns + * @param[in] row The number of rows + * @return A child of the table object + */ +EAPI Evas_Object *evas_object_table_child_get(const Evas_Object *o, unsigned short col, unsigned short row) EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Object_Grid Grid Smart Object. + * @ingroup Evas_Smart_Object_Group + * + * @brief This group provides functions for grid smart objects. + * @since 1.1 + * + * @remarks Convenience smart object that packs children under a regular grid + * layout, using their virtual grid location and size to determine + * children's positions inside the grid object's area. + * + * @{ + */ + +/** + * @brief Creates a new grid. + * + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks It is set to a virtual size of 1x1 by default and add children with + * evas_object_grid_pack(). + * + * @param[in] evas The given evas + * @return The new grid object + */ +EAPI Evas_Object *evas_object_grid_add(Evas *evas) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Creates a grid that is child of a given element @a parent. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] parent The parent element + * @return The new grid object + * + * @see evas_object_grid_add() + */ +EAPI Evas_Object *evas_object_grid_add_to(Evas_Object *parent) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Sets the virtual resolution for the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The grid object to modify + * @param[in] w The virtual horizontal size (resolution) in integer units + * @param[in] h The virtual vertical size (resolution) in integer units + */ +EAPI void evas_object_grid_size_set(Evas_Object *o, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the current virtual resolution. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The grid object to query + * @param[out] w A pointer to an integer to store the virtual width + * @param[out] h A pointer to an integer to store the virtual height + * @see evas_object_grid_size_set() + */ +EAPI void evas_object_grid_size_get(const Evas_Object *o, int *w, int *h) EINA_ARG_NONNULL(1); + +/** + * @brief Sets the mirrored mode of the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks In mirrored mode the grid items go from right to left + * instead of left to right. That is, 0,0 is top right, not to left. + * + * @param[in] o The grid object + * @param[in] mirrored The mirrored mode to set + */ +EAPI void evas_object_grid_mirrored_set(Evas_Object *o, Eina_Bool mirrored) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the mirrored mode of the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The grid object + * @return #EINA_TRUE if it is a mirrored grid, \n + * otherwise #EINA_FALSE if it is not a mirrored grid + * + * @see evas_object_grid_mirrored_set() + */ +EAPI Eina_Bool evas_object_grid_mirrored_get(const Evas_Object *o) EINA_ARG_NONNULL(1); + +/** + * @brief Adds a new child to a grid object. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @param[in] o The given grid object + * @param[in] child The child object to add + * @param[in] x The virtual x coordinate of the child + * @param[in] y The virtual y coordinate of the child + * @param[in] w The virtual width of the child + * @param[in] h The virtual height of the child + * @return #EINA_TRUE if the child is added successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_grid_pack(Evas_Object *o, Evas_Object *child, int x, int y, int w, int h) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes child from grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Removing a child immediately calls a walk over children in order + * to recalculate numbers of columns and rows. If you plan to remove + * all children, use evas_object_grid_clear() instead. + * + * @param[in] o The given grid object + * @param[in] child The child object to remove + * @return #EINA_TRUE if the child is removed successfully, \n + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_grid_unpack(Evas_Object *o, Evas_Object *child) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes all child objects from a grid object. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks This is a faster way to remove all child objects. + * + * @param[in] o The given grid object + * @param[in] clear Set #EINA_TRUE to delete the just removed children, \n + * otherwise set #EINA_FALSE to not delete them + */ +EAPI void evas_object_grid_clear(Evas_Object *o, Eina_Bool clear) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the pack options for a grid child. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Gets the pack x, y, width and height in virtual coordinates set by + * evas_object_grid_pack(). + * + * @param[in] o The grid object + * @param[in] child The grid child to query for coordinates + * @param[out] x The pointer to where the x coordinate to be returned + * @param[out] y The pointer to where the y coordinate to be returned + * @param[out] w The pointer to where the width to be returned + * @param[out] h The pointer to where the height to be returned + * @return #EINA_TRUE if the pack options are obtained successfully, + * otherwise #EINA_FALSE on failure + */ +EAPI Eina_Bool evas_object_grid_pack_get(const Evas_Object *o, Evas_Object *child, int *x, int *y, int *w, int *h); + +/** + * @brief Gets an iterator to walk the list of children for the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Do not remove or delete objects while walking the list. + * + * @param[in] o The grid object + * @return An iterator to walk through the children of the object, \n + * otherwise @c NULL in case of errors + */ +EAPI Eina_Iterator *evas_object_grid_iterator_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets an accessor to get random access to the list of children for the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks Do not remove or delete objects while walking the list. + * + * @param[in] o The grid object + * @return An accessor to get random access to the list of children for the grid, \n + * otherwise @c NULL in case of errors + */ +EAPI Eina_Accessor *evas_object_grid_accessor_new(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @brief Gets the list of children for the grid. + * @since 1.1 + * + * @since_tizen 2.3 + * + * @remarks This is a duplicate of the list kept by the grid internally. + * It is up to the user to destroy it when it no longer needs it. + * It is possible to remove objects from the grid when walking this + * list, but these removals are not reflected on it. + * + * @param[in] o The grid object + * @return The list of children for the grid + */ +EAPI Eina_List *evas_object_grid_children_get(const Evas_Object *o) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Cserve Shared Image Cache Server + * @ingroup Evas + * + * @brief This group provides functions for shared image cache server + * + * Evas has an (optional) module which provides client-server + * infrastructure to <b>share bitmaps across multiple processes</b>, + * saving data and processing power. + * + * Be warned that it @b does not work when <b>threaded image + * preloading</b> is enabled for Evas, though. + * + * @{ + */ +typedef struct _Evas_Cserve_Stats Evas_Cserve_Stats; +typedef struct _Evas_Cserve_Image_Cache Evas_Cserve_Image_Cache; +typedef struct _Evas_Cserve_Image Evas_Cserve_Image; +typedef struct _Evas_Cserve_Config Evas_Cserve_Config; + +/** + * @brief The structure type containing the statistics about the server that shares cached bitmaps. + */ +struct _Evas_Cserve_Stats +{ + int saved_memory; /**< The current amount of saved memory, in bytes */ + int wasted_memory; /**< The current amount of wasted memory, in bytes */ + int saved_memory_peak; /**< The peak amount of saved memory, in bytes */ + int wasted_memory_peak; /**< The peak amount of wasted memory, in bytes */ + double saved_time_image_header_load; /**< The time, in seconds, saved in header loads by sharing cached loads instead */ + double saved_time_image_data_load; /**< The time, in seconds, saved in data loads by sharing cached loads instead */ +}; + +/** + * @brief The structure type containing a handle of a cache of images shared by a server. + */ +struct _Evas_Cserve_Image_Cache +{ + struct + { + int mem_total; + int count; + } active, cached; + Eina_List *images; +}; + +/** + * @brief The structure type containing a handle to an image shared by a server. + */ +struct _Evas_Cserve_Image +{ + const char *file, *key; + int w, h; + time_t file_mod_time; + time_t file_checked_time; + time_t cached_time; + int refcount; + int data_refcount; + int memory_footprint; + double head_load_time; + double data_load_time; + Eina_Bool alpha : 1; + Eina_Bool data_loaded : 1; + Eina_Bool active : 1; + Eina_Bool dead : 1; + Eina_Bool useless : 1; +}; + +/** + * @brief The structure type containing the configuration that controls the server that shares cached bitmaps. + */ +struct _Evas_Cserve_Config +{ + int cache_max_usage; + int cache_item_timeout; + int cache_item_timeout_check; +}; + +/** + * @brief Checks whether the system shares bitmaps using the server. + * + * @since_tizen 2.3 + * + * @return #EINA_TRUE if the system shares bitmaps using the server, \n + * otherwise #EINA_FALSE if the system does not share bitmaps + */ +EAPI Eina_Bool evas_cserve_want_get(void) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Checks whether the system is connected to the server used to share bitmaps. + * + * @since_tizen 2.3 + * + * @return #EINA_TRUE if the system is connected to the server, \n + * otherwise #EINA_FALSE if it is not connected + */ +EAPI Eina_Bool evas_cserve_connected_get(void) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Gets the statistics from a running bitmap sharing server. + * + * @since_tizen 2.3 + * + * @param[in] stats The pointer to the structure to fill the statistics about the + * bitmap cache server + * @return #EINA_TRUE if @a stats is filled with data, \n + * otherwise #EINA_FALSE when @a stats is untouched + */ +EAPI Eina_Bool evas_cserve_stats_get(Evas_Cserve_Stats *stats) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Completely discards or cleans a given images cache, thus re-setting it. + * + * @since_tizen 2.3 + * + * @param[in] cache A handle to the given images cache + */ +EAPI void evas_cserve_image_cache_contents_clean(Evas_Cserve_Image_Cache *cache); + +/** + * @brief Gets the current configuration of the Evas image caching server. + * + * @since_tizen 2.3 + * + * @remarks The fields of @a config are altered to reflect the current + * configuration's values. + * + * @param[in] config The current image caching server's configuration + * + * @return #EINA_TRUE if @a config is filled with data, \n + * otherwise #EINA_FALSE when @a config is untouched + * + * @see evas_cserve_config_set() + */ +EAPI Eina_Bool evas_cserve_config_get(Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Sets the configurations of the Evas image caching server. + * + * @since_tizen 2.3 + * + * @param[in] config A bitmap cache configuration handle with fields set + * to desired configuration values + * @return #EINA_TRUE if @a config is applied successfully, + * otherwise #EINA_FALSE + * + * @see evas_cserve_config_get() + */ +EAPI Eina_Bool evas_cserve_config_set(const Evas_Cserve_Config *config) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Forces the system to disconnect from the bitmap caching server. + * + * @since_tizen 2.3 + */ +EAPI void evas_cserve_disconnect(void); + +/** + * @} + */ + +/** + * @defgroup Evas_Utils General Utilities + * @ingroup Evas + * @brief This group provides general utilities functions. + * @remarks Some functions that are handy but are not specific to canvas or objects. + * + * @{ + */ + +/** + * @brief Converts the given Evas image load error code into a string + * describing it in English. + * + * @since_tizen 2.3 + * + * @remarks Mostly evas_object_image_file_set() would be the function setting + * that error value afterwards, but also evas_object_image_load(), + * evas_object_image_save(), evas_object_image_data_get(), + * evas_object_image_data_convert(), evas_object_image_pixels_import() + * and evas_object_image_is_inside(). This function is meant to be + * used in conjunction with evas_object_image_load_error_get(), as in: + * + * @remarks The following is an example code: + * @skip img1 = + * @until ecore_main_loop_begin( + * + * @remarks Here, @c valid_path is the path to a valid image and @c + * bogus_path is a path to a file which does not exist. The two outputs + * of evas_load_error_str() would be (if no other errors occur): + * <code>"No error on load"</code> and <code>"File (or file path) does + * not exist"</code>, respectively. + * + * + * @param[in] error The error code \n + * A value in #Evas_Load_Error. + * @return A valid string \n + * If the given @a error is not supported, <code>"Unknown error"</code> is returned. + */ +EAPI const char *evas_load_error_str(Evas_Load_Error error); + +/* Evas utility routines for color space conversions */ +/* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */ +/* rgb color space has r,g,b in the range 0 to 255 */ + +/** + * @brief Converts a given color from HSV to RGB format. + * + * @details This function converts a given color in HSV color format to RGB + * color format. + * + * @since_tizen 2.3 + * + * @param[in] h The Hue component of the color + * @param[in] s The Saturation component of the color + * @param[in] v The Value component of the color + * @param[out] r The Red component of the color + * @param[out] g The Green component of the color + * @param[out] b The Blue component of the color + **/ +EAPI void evas_color_hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b); + +/** + * @brief Converts a given color from RGB to HSV format. + * + * @details This function converts a given color in RGB color format to HSV + * color format. + * + * @since_tizen 2.3 + * + * @param[in] r The Red component of the color + * @param[in] g The Green component of the color + * @param[in] b The Blue component of the color + * @param[out] h The Hue component of the color + * @param[out] s The Saturation component of the color + * @param[out] v The Value component of the color + **/ +EAPI void evas_color_rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v); + +/* argb color space has a,r,g,b in the range 0 to 255 */ + +/** + * @brief Pre-multiplies a rgb triplet by an alpha factor. + * @details This function pre-multiplies a given rgb triplet by an alpha + * factor. Alpha factor is used to define transparency. + * + * @since_tizen 2.3 + * + * @param[in] a The alpha factor + * @param[out] r The Red component of the color + * @param[out] g The Green component of the color + * @param[out] b The Blue component of the color + **/ +EAPI void evas_color_argb_premul(int a, int *r, int *g, int *b); + +/** + * @brief Undoes pre-multiplication of a rgb triplet by an alpha factor. + * + * @details This function undoes pre-multiplication a given rbg triplet by an + * alpha factor. Alpha factor is used to define transparency. + * + * @since_tizen 2.3 + * + * @param[in] a The alpha factor + * @param[out] r The Red component of the color + * @param[out] g The Green component of the color + * @param[out] b The Blue component of the color + * + * @see evas_color_argb_premul(). + **/ +EAPI void evas_color_argb_unpremul(int a, int *r, int *g, int *b); + +/** + * @brief Pre-multiplies data by an alpha factor. + * @details This function pre-multiplies a given data by an alpha + * factor. Alpha factor is used to define transparency. + * + * @since_tizen 2.3 + * + * @param[in] data The data value + * @param[in] len The length value + **/ +EAPI void evas_data_argb_premul(unsigned int *data, unsigned int len); + +/** + * @brief Undoes pre-multiplication data by an alpha factor. + * + * @details This function undoes the pre-multiplication of a given data by an alpha + * factor. Alpha factor is used to define transparency. + * + * @since_tizen 2.3 + * + * @param[in] data The data value + * @param[in] len The length value + **/ +EAPI void evas_data_argb_unpremul(unsigned int *data, unsigned int len); + +/** + * @internal + * @remarks Tizen only feature + * @remarks TIZEN_ONLY(20140822): Added evas_bidi_direction_hint_set, get APIs and applied to textblock, text. + * @brief Set BiDi direction hint to the given evas canvas. + * + * @details Evas has a BiDi direction hint value which affect to textblock, text object. + * If a text that has only neutral BiDi direction is set to textblock or text, + * the BiDi direction hint will be used to decide alignment of paragraphs. + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas canvas + * @param[in] dir The BiDi direction hint + **/ +EAPI void evas_bidi_direction_hint_set(Evas *e, Evas_BiDi_Direction dir); + +/** + * @internal + * @remarks Tizen only feature + * @remarks TIZEN_ONLY(20140822): Added evas_bidi_direction_hint_set, get APIs and applied to textblock, text. + * @brief Get BiDi direction hint of the given evas canvas. + * + * @details Evas has a BiDi direction hint value which affect to textblock, text object. + * If a text that has only neutral BiDi direction is set to textblock or text, + * the BiDi direction hint will be used to decide alignment of paragraphs. + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas canvas + * @return BiDi direction hint + * + * @see evas_bidi_direction_hint_set(). + **/ +EAPI Evas_BiDi_Direction evas_bidi_direction_hint_get(Evas *e); + + +/* string and font handling */ + +/** + * @brief Gets the next character in the string. + * + * @remarks Given the UTF-8 string in @a str, and starting byte position in @a pos, + * this function places in @a decoded the decoded code point at @a pos + * and return the byte index for the next character in the string. + * The only boundary check done is that @a pos must be >= 0. Other than that, + * no checks are performed, so passing an index value that is not within the + * length of the string results in undefined behavior. + * + * @since_tizen 2.3 + * + * @param[in] str The UTF-8 string + * @param[in] pos The byte index where to start + * @param[out] decoded The address to store the decoded code point \n + * This is optional. + * @return The byte index of the next character + */ +EAPI int evas_string_char_next_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the previous character in the string + * + * @since_tizen 2.3 + * + * @remarks Given the UTF-8 string in @a str, and starting byte position in @a pos, + * this function places in @a decoded the decoded code point at @a pos + * and return the byte index for the previous character in the string. + * + * @remarks The only boundary check done is that @a pos must be >= 1. Other than that, + * no checks are performed, so passing an index value that is not within the + * length of the string results in undefined behavior. + * + * @param[in] str The UTF-8 string + * @param[in] pos The byte index where to start + * @param[out] decoded The address where to store the decoded code point \n + * This is optional. + * @return The byte index of the previous character + */ +EAPI int evas_string_char_prev_get(const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the length in characters of the string. + * + * @since_tizen 2.3 + * + * @param[in] str The string to get the length of + * @return The length in characters (not bytes) + */ +EAPI int evas_string_char_len_get(const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @} + */ + +/** + * @defgroup Evas_Keys Key Input Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions which feed key events to the canvas. + * + * Evas is @b not aware of input + * systems at all. Then, the user, if using it crudely (evas_new()), + * has to feed it with input events, so that it can react + * somehow. If, however, the user creates a canvas by means of the + * Ecore_Evas wrapper, it automatically binds the chosen display + * engine's input events to the canvas, for you. + * + * This group presents the functions dealing with the feeding of key + * events to the canvas. On most of them, one has to reference a given + * key by a name (<code>keyname</code> argument). Those are + * <b>platform dependent</b> symbolic names for the keys. Sometimes + * you get the right <code>keyname</code> by simply using an ASCII + * value of the key name, but it is not like that always. + * + * Typical platforms are Linux frame buffer (Ecore_FB) and X server + * (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer + * to your display engine's documentation when using evas through an + * Ecore helper wrapper when you need the <code>keyname</code>s. + * + * @{ + */ + +/** + * @brief Gets a handle to the list of modifier keys registered in the canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This is required to check for which modifiers are set + * at a given time with the evas_key_modifier_is_set() function. + * + * @param[in] e The pointer to the Evas canvas + * @return An Evas_Modifier handle to query Evas' keys subsystem with evas_key_modifier_is_set(), \n + * otherwise @c NULL on error + * + * @see evas_key_modifier_add + * @see evas_key_modifier_del + * @see evas_key_modifier_on + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + */ +EAPI const Evas_Modifier *evas_key_modifier_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Gets a handle to the list of lock keys registered in the canvas @a e. + * + * @since_tizen 2.3 + * + * @remarks This is required to check for which locks are set at a given + * time with the evas_key_lock_is_set() function. + * + * @param[in] e The pointer to the Evas canvas + * @return An Evas_Lock handle to query Evas' keys subsystem with evas_key_lock_is_set(), \n + * otherwise @c NULL on error + * + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_on + * @see evas_key_lock_off + * @see evas_key_lock_is_set + * + */ +EAPI const Evas_Lock *evas_key_lock_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * @brief Checks whether a given modifier key is set at the time of the call. + * + * @since_tizen 2.3 + * + * @remarks If the modifier is set, such as shift being pressed, this + * function returns @c Eina_True. + * + * @param[in] m The current modifiers set, as returned by evas_key_modifier_get() + * @param[in] keyname The name of the modifier key to check status for + * @return #EINA_TRUE if the modifier key named @a keyname is on, \n + * otherwise #EINA_FALSE if the modifier key is not on + * + * @see evas_key_modifier_add + * @see evas_key_modifier_del + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_off + */ +EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Checks whether the given lock key is set at the time of the call. + * + * @since_tizen 2.3 + * + * @remarks If the lock is set, such as caps lock, this function returns @c Eina_True. + * + * @param[in] l The current locks set, as returned by evas_key_lock_get() + * @param[in] keyname The name of the lock key to check status for + * @return #EINA_TRUE if the @a keyname lock key is set, \n + * otherwise @c Eina_False if the lock key is not set + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_on + * @see evas_key_lock_off + */ +EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds the @a keyname key to the current list of modifier keys. + * + * @since_tizen 2.3 + * + * @remarks Modifiers are keys like shift, alt and ctrl, that is, keys which are + * meant to be pressed together with others, altering the behavior of + * the secondly pressed keys somehow. Evas allows these keys to be + * user defined. + * + * @remarks This call allows custom modifiers to be added to the Evas system at + * run time. It is then possible to set and unset modifier keys + * programmatically for other parts of the program to check and act + * on. Programmers using Evas would check for modifier keys on key + * event callbacks using evas_key_modifier_is_set(). + * + * @remarks If you instantiate the canvas by means of the + * ecore_evas_new() family of helper functions, Ecore takes + * care of registering on it all standard modifiers: "Shift", + * "Control", "Alt", "Meta", "Hyper", "Super". + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the modifier key to add to the list of + * Evas modifiers + * + * @see evas_key_modifier_del + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + * + */ +EAPI void evas_key_modifier_add(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes the @a keyname key from the current list of modifier keys + * on canvas @a e. + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the key to remove from the modifiers list + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + */ +EAPI void evas_key_modifier_del(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Adds the @a keyname key to the current list of lock keys. + * + * @since_tizen 2.3 + * + * @remarks Locks are keys like caps lock, num lock or scroll lock, that is, keys + * which are meant to be pressed once -- toggling a binary state which + * is bound to it -- and thus altering the behavior of all + * subsequently pressed keys somehow, depending on its state. Evas is + * so that these keys can be defined by the user. + * + * @remarks This allows custom locks to be added to the evas system at run + * time. It is then possible to set and unset lock keys + * programmatically for other parts of the program to check and act + * on. Programmers using Evas would check for lock keys on key event + * callbacks using evas_key_lock_is_set(). + * + * @remarks If you instantiate the canvas by means of the + * ecore_evas_new() family of helper functions, Ecore takes + * care of registering on it all standard lock keys: "Caps_Lock", + * "Num_Lock", "Scroll_Lock". + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the key to add to the locks list + * + * @see evas_key_lock_get + * @see evas_key_lock_del + * @see evas_key_lock_on + * @see evas_key_lock_off + * @see evas_key_lock_is_set + */ +EAPI void evas_key_lock_add(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes the @a keyname key from the current list of lock keys on + * canvas @a e. + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the key to remove from the locks list + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_on + * @see evas_key_lock_off + */ +EAPI void evas_key_lock_del(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Enables or turns on programmatically the modifier key with name @a keyname. + * + * @since_tizen 2.3 + * + * @remarks The effect is as if the key is pressed for the whole time + * between this call and a matching evas_key_modifier_off(). + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the modifier to enable + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + */ +EAPI void evas_key_modifier_on(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Disables or turns off programmatically the modifier key with name @a keyname. + * + * @since_tizen 2.3 + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the modifier to disable + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_is_set + */ +EAPI void evas_key_modifier_off(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Enables or turns on programmatically the lock key with name @a keyname. + * + * @since_tizen 2.3 + * + * @remarks The effect is as if the key is put on its active state after + * this call. + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the lock to enable + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_off + */ +EAPI void evas_key_lock_on(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Disables or turns off programmatically the lock key with name @a keyname. + * + * @since_tizen 2.3 + * + * @remarks The effect is as if the key is put on its inactive state + * after this call. + * + * @param[in] e The pointer to the Evas canvas + * @param[in] keyname The name of the lock to disable + * + * @see evas_key_lock_get + * @see evas_key_lock_add + * @see evas_key_lock_del + * @see evas_key_lock_on + */ +EAPI void evas_key_lock_off(Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Creates a bit mask from the @a keyname @b modifier key. + * + * @since_tizen 2.3 + * + * @remarks Values returned from different calls to it may be ORed together, + * naturally. + * + * @remarks This function is meant to be used in conjunction with + * evas_object_key_grab()/evas_object_key_ungrab(). See their + * documentation for more information. + * + * @param[in] e The canvas to query the bit mask from + * @param[in] keyname The name of the modifier key to create the mask for + * @returns The bit mask or @c 0 if the @a keyname key is not registered as a + * modifier for canvas @a e + * + * @see evas_key_modifier_add + * @see evas_key_modifier_get + * @see evas_key_modifier_on + * @see evas_key_modifier_off + * @see evas_key_modifier_is_set + * @see evas_object_key_grab + * @see evas_object_key_ungrab + */ +EAPI Evas_Modifier_Mask evas_key_modifier_mask_get(const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Requests @a keyname key events be directed to @a obj. + * + * @since_tizen 2.3 + * + * @remarks Key grabs allow one or more objects to receive key events for + * specific key strokes even if other objects have focus. Whenever a + * key is grabbed, only the objects grabbing it gets the events + * for the given keys. + * + * @remarks @a keyname is a platform dependent symbolic name for the key + * pressed (see @ref Evas_Keys for more information). + * + * @remarks @a modifiers and @a not_modifiers are bit masks of all the + * modifiers that must and must not, respectively, be pressed along + * with @a keyname key in order to trigger this new key + * grab. Modifiers can be things such as Shift and Ctrl as well as + * user defined types via evas_key_modifier_add(). Retrieve them with + * evas_key_modifier_mask_get() or use @c 0 for empty masks. + * + * @remarks @a exclusive makes the given object the only one permitted to + * grab the given key. If given #EINA_TRUE, subsequent calls on this + * function with different @a obj arguments it fails, unless the key + * is ungrabbed again. + * + * @remarks Providing impossible modifier sets creates undefined behavior. + * + * @param[in] obj The object to direct @a keyname events to + * @param[in] keyname The key to request events for + * @param[in] modifiers A mask of modifiers that must be present to + * trigger the event + * @param[in] not_modifiers A mask of modifiers that must @b not be present + * to trigger the event + * @param[in] exclusive Set #EINA_TRUE to request that the @a obj is the only object + * receiving the @a keyname events, \n + * otherwise set #EINA_FALSE + * @return #EINA_TRUE if the call succeeded, \n + * otherwise #EINA_FALSE on failure + * + * @see evas_object_key_ungrab + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_focus_get + * @see evas_key_modifier_add + */ +EAPI Eina_Bool evas_object_key_grab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * @brief Removes the grab on @a keyname key events by @a obj. + * + * @since_tizen 2.3 + * + * @remarks Removes a key grab on @a obj if @a keyname, @a modifiers, + * and @a not_modifiers match. + * + * @param[in] obj The object that has an existing key grab + * @param[in] keyname The key the grab is set for + * @param[in] modifiers A mask of modifiers that must be present to + * trigger the event + * @param[in] not_modifiers A mask of modifiers that must not be + * present to trigger the event + * + * @see evas_object_key_grab + * @see evas_object_focus_set + * @see evas_object_focus_get + * @see evas_focus_get + */ +EAPI void evas_object_key_ungrab(Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) EINA_ARG_NONNULL(1, 2); + +/** + * @} + */ + +/** + * @internal + * @defgroup Evas_Touch_Point_List Touch Point List Functions + * @ingroup Evas_Canvas + * + * @brief This group provides functions to get information of touched points in the Evas. + * + * @remarks Evas maintains list of touched points on the canvas. Each point has + * its co-ordinates, ID and state. You can get the number of touched + * points and information of each point using evas_touch_point_list functions. + * + * @{ + */ + +/** + * @brief Gets the number of touched point in the evas. + * + * @since_tizen 2.3 + * + * @remarks New touched point is added to the list whenever touching the evas + * and point is removed whenever removing touched point from the evas. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int count; + * + * count = evas_touch_point_list_count(evas); + * printf("The count of touch points: %i\n", count); + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @return The number of touched point on the evas + * + * @see evas_touch_point_list_nth_xy_get() + * @see evas_touch_point_list_nth_id_get() + * @see evas_touch_point_list_nth_state_get() + */ +EAPI unsigned int evas_touch_point_list_count(Evas *e) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the nth touch point's co-ordinates. + * + * @since_tizen 2.3 + * + * @remarks Touch point's co-ordinates is updated whenever moving that point + * on the canvas. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * Evas_Coord x, y; + * + * if (evas_touch_point_list_count(evas)) + * { + * evas_touch_point_nth_xy_get(evas, 0, &x, &y); + * printf("The first touch point's co-ordinate: (%i, %i)\n", x, y); + * } + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @param[in] n The number of the touched point (0 being the first) + * @param[out] x The pointer to a Evas_Coord to be filled in + * @param[out] y The pointer to a Evas_Coord to be filled in + * + * @see evas_touch_point_list_count() + * @see evas_touch_point_list_nth_id_get() + * @see evas_touch_point_list_nth_state_get() + */ +EAPI void evas_touch_point_list_nth_xy_get(Evas *e, unsigned int n, Evas_Coord *x, Evas_Coord *y) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the @a id of nth touch point. + * + * @since_tizen 2.3 + * + * @remarks The point which comes from Mouse Event has @a id 0 and The point + * which comes from Multi Event has @a id that is same as Multi + * Event's device ID. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * int id; + * + * if (evas_touch_point_list_count(evas)) + * { + * id = evas_touch_point_nth_id_get(evas, 0); + * printf("The first touch point's id: %i\n", id); + * } + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @param[in] n The number of the touched point (@c 0 being the first) + * @return The ID of nth touch point, \n + * otherwise @c -1 + * + * @see evas_touch_point_list_count() + * @see evas_touch_point_list_nth_xy_get() + * @see evas_touch_point_list_nth_state_get() + */ +EAPI int evas_touch_point_list_nth_id_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1); + +/** + * @brief Gets the @a state of nth touch point. + * + * @since_tizen 2.3 + * + * @remarks The point's @a state is EVAS_TOUCH_POINT_DOWN when pressed, + * EVAS_TOUCH_POINT_STILL when the point is not moved after pressed, + * EVAS_TOUCH_POINT_MOVE when moved at least once after pressed and + * EVAS_TOUCH_POINT_UP when released. + * + * @remarks The following is an example: + * @code + * extern Evas *evas; + * Evas_Touch_Point_State state; + * + * if (evas_touch_point_list_count(evas)) + * { + * state = evas_touch_point_nth_state_get(evas, 0); + * printf("The first touch point's state: %i\n", state); + * } + * @endcode + * + * @param[in] e The pointer to the Evas canvas + * @param[in] n The number of the touched point (@c 0 being the first) + * @return @a state of nth touch point, \n + * otherwise EVAS_TOUCH_POINT_CANCEL + * + * @see evas_touch_point_list_count() + * @see evas_touch_point_list_nth_xy_get() + * @see evas_touch_point_list_nth_id_get() + */ +EAPI Evas_Touch_Point_State evas_touch_point_list_nth_state_get(Evas *e, unsigned int n) EINA_ARG_NONNULL(1); + +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/src/lib/evas/Evas_GL.h b/src/lib/evas/Evas_GL.h index a06b523277..7367905617 100644..100755 --- a/src/lib/evas/Evas_GL.h +++ b/src/lib/evas/Evas_GL.h @@ -15,8 +15,27 @@ extern "C" { * @brief This group discusses the functions that are used to do OpenGL rendering on Evas. Evas allows you * to use OpenGL to render to specially set up image objects (which act as * render target surfaces). + * By default, Evas GL will use an OpenGL-ES 2.0 context and API set. * * + * <h2> Evas GL vs. Elementary GLView </h2> + * + * While it is possible to Evas and Ecore_Evas to create an OpenGL application, + * using these low-level APIs can be troublesome for most users. Before + * diving in Evas GL, please refer to the page @ref elm_opengl_page. + * + * Elementary @ref GLView provides a set of helper functions in: + * @li @ref Elementary_GL_Helpers.h + * + * Similarly, two sets of helper functions are provided by Evas GL in the + * following header files: + * @li Evas_GL_GLES1_Helpers.h + * @li Evas_GL_GLES2_Helpers.h + * + * @{ + */ + +/* * <h2> Evas GL usage example </h2> * * Below is an illustrative example of how to use OpenGL to render to an @@ -328,13 +347,6 @@ init_shaders(GLData *gld) return 1; } * @endcode - * - * @ingroup Evas_Canvas - */ - -/** - * @addtogroup Evas_GL - * @{ */ /** @@ -393,38 +405,41 @@ typedef enum _Evas_GL_Color_Format { EVAS_GL_RGB_888 = 0, /**< Opaque RGB surface */ EVAS_GL_RGBA_8888 = 1, /**< RGBA surface with alpha */ - EVAS_GL_NO_FBO = 2 /**< Special value for creating PBuffer surfaces without any attached buffer. @see evas_gl_pbuffer_surface_create. @since 1.12*/ + EVAS_GL_NO_FBO = 2 /**< Special value for creating PBuffer surfaces without any attached buffer. @see evas_gl_pbuffer_surface_create. @since_tizen 2.3 */ } Evas_GL_Color_Format; /** * @brief Enumeration that defines the Surface Depth Format. + * @since_tizen 2.3 */ typedef enum _Evas_GL_Depth_Bits { EVAS_GL_DEPTH_NONE = 0, - EVAS_GL_DEPTH_BIT_8 = 1, /**< 8 bits precision surface depth */ - EVAS_GL_DEPTH_BIT_16 = 2, /**< 16 bits precision surface depth */ - EVAS_GL_DEPTH_BIT_24 = 3, /**< 24 bits precision surface depth */ - EVAS_GL_DEPTH_BIT_32 = 4 /**< 32 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_8 = 1, + EVAS_GL_DEPTH_BIT_16 = 2, + EVAS_GL_DEPTH_BIT_24 = 3, + EVAS_GL_DEPTH_BIT_32 = 4 } Evas_GL_Depth_Bits; /** * @brief Enumeration that defines the Surface Stencil Format. + * @since_tizen 2.3 */ typedef enum _Evas_GL_Stencil_Bits { EVAS_GL_STENCIL_NONE = 0, - EVAS_GL_STENCIL_BIT_1 = 1, /**< 1 bit precision for stencil buffer */ - EVAS_GL_STENCIL_BIT_2 = 2, /**< 2 bits precision for stencil buffer */ - EVAS_GL_STENCIL_BIT_4 = 3, /**< 4 bits precision for stencil buffer */ - EVAS_GL_STENCIL_BIT_8 = 4, /**< 8 bits precision for stencil buffer */ - EVAS_GL_STENCIL_BIT_16 = 5 /**< 16 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_1 = 1, + EVAS_GL_STENCIL_BIT_2 = 2, + EVAS_GL_STENCIL_BIT_4 = 3, + EVAS_GL_STENCIL_BIT_8 = 4, + EVAS_GL_STENCIL_BIT_16 = 5 } Evas_GL_Stencil_Bits; /** * @brief Enumeration that defines the Configuration Options. * * @since 1.1 + * @since_tizen 2.3 */ typedef enum _Evas_GL_Options_Bits { @@ -432,13 +447,14 @@ typedef enum _Evas_GL_Options_Bits EVAS_GL_OPTIONS_DIRECT = (1<<0),/**< Optional hint to allow rendering directly to the Evas window if possible */ EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION = (1<<1) /**< Force direct rendering even if the canvas is rotated. * In that case, it is the application's role to rotate the contents of - * the Evas_GL view. @see evas_gl_rotation_get. @since 1.12 */ + * the Evas_GL view. @see evas_gl_rotation_get */ } Evas_GL_Options_Bits; /** * @brief Enumeration that defines the configuration options for a Multisample Anti-Aliased (MSAA) rendering surface. * * @since 1.2 + * @since_tizen 2.3 * * @remarks This only works on devices that support the required extensions. */ @@ -454,7 +470,7 @@ typedef enum _Evas_GL_Multisample_Bits * @brief Enumeration that defines the available OpenGL ES version numbers. * They can be used to create OpenGL-ES 1.1 contexts. * - * @since 1.12 + * @since_tizen 2.3 * * @see evas_gl_context_version_create * @@ -477,6 +493,8 @@ typedef enum _Evas_GL_Context_Version * * @see evas_gl_surface_create * @see evas_gl_pbuffer_surface_create + * + * @since_tizen 2.3 */ struct _Evas_GL_Config { @@ -485,7 +503,7 @@ struct _Evas_GL_Config Evas_GL_Stencil_Bits stencil_bits; /**< Surface Stencil Bits */ Evas_GL_Options_Bits options_bits; /**< Extra Surface Options */ Evas_GL_Multisample_Bits multisample_bits; /**< Optional Surface MSAA Bits */ - Evas_GL_Context_Version gles_version; /**< @internal Special flag for OpenGL-ES 1.1 indirect rendering surfaces (since 1.12) */ + Evas_GL_Context_Version gles_version; /**< @internal Special flag for OpenGL-ES 1.1 indirect rendering surfaces */ }; /** @brief Constant to use when calling @ref evas_gl_string_query to retrieve the available Evas_GL extensions. */ @@ -498,6 +516,8 @@ struct _Evas_GL_Config * @param[in] e The given Evas canvas to use * * @return The created Evas_GL object, or @c NULL in case of failure + * + * @since_tizen 2.3 */ EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); @@ -507,6 +527,8 @@ EAPI Evas_GL *evas_gl_new (Evas *e) EINA_WARN_UNU * @param[in] evas_gl The given Evas_GL object to destroy * * @see evas_gl_new + * + * @since_tizen 2.3 */ EAPI void evas_gl_free (Evas_GL *evas_gl) EINA_ARG_NONNULL(1); @@ -517,6 +539,10 @@ EAPI void evas_gl_free (Evas_GL *evas_gl) EINA * of the backward compatibility issue. * * @see evas_gl_config_free + * + * @return A new config object + * + * @since_tizen 2.3 */ EAPI Evas_GL_Config *evas_gl_config_new (void); @@ -529,6 +555,8 @@ EAPI Evas_GL_Config *evas_gl_config_new (void); * of the backward compatibility issue. * * @see evas_gl_config_new + * + * @since_tizen 2.3 */ EAPI void evas_gl_config_free (Evas_GL_Config *cfg) EINA_ARG_NONNULL(1); @@ -544,6 +572,8 @@ EAPI void evas_gl_config_free (Evas_GL_Config *cfg) E * otherwise @c NULL on failure * * @see evas_gl_surface_destroy + * + * @since_tizen 2.3 */ 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); @@ -576,7 +606,7 @@ EAPI Evas_GL_Surface *evas_gl_surface_create (Evas_GL *evas_gl, Evas * * @see evas_gl_surface_destroy * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Evas_GL_Surface *evas_gl_pbuffer_surface_create(Evas_GL *evas_gl, Evas_GL_Config *cfg, int w, int h, const int *attrib_list) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1,2); @@ -591,13 +621,19 @@ EAPI Evas_GL_Surface *evas_gl_pbuffer_surface_create(Evas_GL *evas_gl, E EAPI void evas_gl_surface_destroy (Evas_GL *evas_gl, Evas_GL_Surface *surf) EINA_ARG_NONNULL(1,2); /** - * @brief Creates and returns a new Evas GL context object. + * @brief Creates and returns a new Evas GL context object (OpenGL-ES 2.0). * * @param[in] evas_gl The given Evas_GL object * @param[in] share_ctx An Evas_GL context to share with the new context * + * The API in use will be an OpenGL-ES 2.0 API (ie. with framebuffers and shaders). + * Consider calling @ref evas_gl_context_version_create if you need an OpenGL-ES 1.1 + * context instead. + * * @return The created context, * otherwise @c NULL on failure + * + * @see evas_gl_context_version_create */ 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); @@ -622,7 +658,7 @@ EAPI Evas_GL_Context *evas_gl_context_create (Evas_GL *evas_gl, Evas * @see Evas_GL_Context_Version * @see evas_gl_context_api_get * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Evas_GL_Context *evas_gl_context_version_create(Evas_GL *evas_gl, Evas_GL_Context *share_ctx, Evas_GL_Context_Version version) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); @@ -634,6 +670,8 @@ EAPI Evas_GL_Context *evas_gl_context_version_create(Evas_GL *evas_gl, E * * @see evas_gl_context_create * @see evas_gl_context_version_create + * + * @since_tizen 2.3 */ EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); @@ -645,6 +683,8 @@ EAPI void evas_gl_context_destroy (Evas_GL *evas_gl, Evas * @param[in] ctx The given Evas GL context * @return @c EINA_TRUE if successful, * otherwise @c EINA_FALSE if not + * + * @since_tizen 2.3 */ EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas_GL_Surface *surf, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1,2); @@ -653,11 +693,14 @@ EAPI Eina_Bool evas_gl_make_current (Evas_GL *evas_gl, Evas * * @param[in] evas_gl The given Evas_GL object * @param[in] name A symbolic constant, only @ref EVAS_GL_EXTENSIONS is supported for now + * @return A string describing some aspect of Evas GL + * + * @since_tizen 2.3 */ EAPI const char *evas_gl_string_query (Evas_GL *evas_gl, int name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * @brief Returns a extension function from OpenGL or the Evas_GL glue layer. + * @brief Returns a extension function from the Evas_GL glue layer. * * @param[in] evas_gl The given Evas_GL object * @param[in] name The name of the function to return @@ -665,7 +708,12 @@ EAPI const char *evas_gl_string_query (Evas_GL *evas_gl, int * The available extension functions may depend on the backend engine Evas GL is * running on. * + * @note Evas_GL extensions are not EGL or OpenGL extensions, but Evas_GL-specific + * features. + * * @return A function pointer to the Evas_GL extension. + * + * @since_tizen 2.3 */ 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; @@ -681,6 +729,8 @@ EAPI Evas_GL_Func evas_gl_proc_address_get (Evas_GL *evas_gl, cons * @details This function can be called to later set this native surface as * source of an Evas Object Image. Please refer to * @ref evas_object_image_native_surface_set. + * + * @since_tizen 2.3 */ 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); @@ -700,6 +750,8 @@ EAPI Eina_Bool evas_gl_native_surface_get (Evas_GL *evas_gl, Evas * @note This function will always return an OpenGL-ES 2.0 API, please use * @ref evas_gl_context_api_get instead to get an OpenGL-ES 1.1 set of APIs. * + * @since_tizen 2.3 + * * @see Evas_GL_API * @see evas_gl_context_api_get * @@ -729,7 +781,7 @@ EAPI Evas_GL_API *evas_gl_api_get (Evas_GL *evas_gl) EINA * @see evas_gl_api_get * @see evas_gl_context_version_create * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Evas_GL_API *evas_gl_context_api_get (Evas_GL *evas_gl, Evas_GL_Context *ctx) EINA_ARG_NONNULL(1); @@ -754,7 +806,7 @@ EAPI Evas_GL_API *evas_gl_context_api_get (Evas_GL *evas_gl, Evas * * @see EVAS_GL_OPTIONS_CLIENT_SIDE_ROTATION * - * @since 1.12 + * @since_tizen 2.3 */ EAPI int evas_gl_rotation_get (Evas_GL *evas_gl) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -774,7 +826,7 @@ EAPI int evas_gl_rotation_get (Evas_GL *evas_gl) EINA * * @return EINA_TRUE in case of success, EINA_FALSE in case of error. * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Eina_Bool evas_gl_surface_query (Evas_GL *evas_gl, Evas_GL_Surface *surface, int attribute, void *value) EINA_ARG_NONNULL(1,2); @@ -798,7 +850,7 @@ EAPI Eina_Bool evas_gl_surface_query (Evas_GL *evas_gl, Evas * information, so an application can not expect the exact same error * codes as EGL would return. * - * @since 1.12 + * @since_tizen 2.3 */ EAPI int evas_gl_error_get (Evas_GL *evas_gl) EINA_ARG_NONNULL(1); @@ -810,7 +862,7 @@ EAPI int evas_gl_error_get (Evas_GL *evas_gl) EINA * @return The current context for the calling thread, or @c NULL in case of * failure and when there is no current context in this thread. * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Evas_GL_Context *evas_gl_current_context_get (Evas_GL *evas_gl) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); @@ -828,7 +880,7 @@ EAPI Evas_GL_Context *evas_gl_current_context_get (Evas_GL *evas_gl) EIN * * @see evas_gl_make_current * - * @since 1.12 + * @since_tizen 2.3 */ EAPI Evas_GL_Surface *evas_gl_current_surface_get (Evas_GL *evas_gl) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); @@ -854,6 +906,8 @@ typedef khronos_uint64_t EvasGLuint64; #if !defined(__gl2_h_) # define __gl2_h_ +#define GL_ES_VERSION_2_0 1 + /* * This document is licensed under the SGI Free Software B License Version * 2.0. For details, see http://oss.sgi.com/projects/FreeB/ . @@ -879,6 +933,10 @@ typedef float GLfloat; // Changed khronos_float_t typedef float GLclampf; // Changed khronos_float_t typedef signed int GLfixed; // Changed khronos_int32_t +/* GL types for handling large vertex buffer objects */ +typedef signed long int GLintptr; // Changed khronos_intptr_t +typedef signed long int GLsizeiptr; // Changed khronos_ssize_t + /* OpenGL ES core versions */ //#define GL_ES_VERSION_2_0 1 @@ -3341,12 +3399,6 @@ typedef signed int GLfixed; // Changed khronos_int32_t # endif #endif -#ifndef GL_ES_VERSION_2_0 -/* GL types for handling large vertex buffer objects */ -#include <stddef.h> -typedef ptrdiff_t GLintptr; // Changed khronos_intptr_t -typedef ptrdiff_t GLsizeiptr; // Changed khronos_ssize_t -#endif /* Some definitions from GLES 3.0. * Note: Evas_GL does NOT support GLES 3. @@ -3432,7 +3484,7 @@ typedef unsigned long long EvasGLTime; * call the backend's GetError() function and translate to a valid @c EVAS_GL_ * error code. * - * @since 1.12 + * @since_tizen 2.3 * * @{ */ @@ -3619,7 +3671,7 @@ struct _Evas_GL_API void (*glSampleCoverage) (GLclampf value, GLboolean invert); void (*glScissor) (GLint x, GLint y, GLsizei width, GLsizei height); void (*glShaderBinary) (GLsizei n, const GLuint* shaders, GLenum binaryformat, const void* binary, GLsizei length); - void (*glShaderSource) (GLuint shader, GLsizei count, const char* const * string, const GLint* length); + void (*glShaderSource) (GLuint shader, GLsizei count, const char** string, const GLint* length); void (*glStencilFunc) (GLenum func, GLint ref, GLuint mask); void (*glStencilFuncSeparate) (GLenum face, GLenum func, GLint ref, GLuint mask); void (*glStencilMask) (GLuint mask); @@ -3812,7 +3864,7 @@ EvasGLImage *img = glapi->evasglCreateImageForContext * @li @c EVAS_GL_NATIVE_SURFACE_TIZEN (Tizen platform only):<br/> * Requires the @c EVAS_GL_TIZEN_image_native_surface extension. * - * @since 1.12 + * @since_tizen 2.3 */ EvasGLImage (*evasglCreateImageForContext) (Evas_GL *evas_gl, Evas_GL_Context *ctx, int target, void* buffer, const int* attrib_list) EINA_WARN_UNUSED_RESULT; diff --git a/src/modules/evas/engines/buffer/Evas_Engine_Buffer.h b/src/modules/evas/engines/buffer/Evas_Engine_Buffer.h index a9cbbfbf45..d35a7afe03 100644 --- a/src/modules/evas/engines/buffer/Evas_Engine_Buffer.h +++ b/src/modules/evas/engines/buffer/Evas_Engine_Buffer.h @@ -29,7 +29,7 @@ struct _Evas_Engine_Info_Buffer struct { void * (*new_update_region) (int x, int y, int w, int h, int *row_bytes); void (*free_update_region) (int x, int y, int w, int h, void *data); - void * (*switch_buffer) (void *data, void *dest_buffer); + void * (*switch_buffer) (void *data, void *dest_buffer); } func; void *switch_data; diff --git a/src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h b/src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h index e66539e021..05b440c87e 100644..100755 --- a/src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h +++ b/src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h @@ -1,6 +1,8 @@ #ifndef _EVAS_ENGINE_GL_X11_H #define _EVAS_ENGINE_GL_X11_H +#include <X11/Xlib.h> + typedef struct _Evas_Engine_Info_GL_X11 Evas_Engine_Info_GL_X11; /* have this feature */ @@ -24,21 +26,23 @@ struct _Evas_Engine_Info_GL_X11 /* engine specific data & parameters it needs to set up */ struct { - void *display; - unsigned long drawable; - void *visual; - unsigned long colormap; - int depth; - int screen; - int rotation; - unsigned int destination_alpha : 1; + Display *display; + Drawable drawable; + Drawable drawable_back; + Visual *visual; + Colormap colormap; + int depth; + int screen; + int rotation; + unsigned int destination_alpha : 1; + unsigned int offscreen : 1; } info; /* engine specific function calls to query stuff about the destination */ /* engine (what visual & colormap & depth to use, performance info etc. */ struct { - void *(*best_visual_get) (Evas_Engine_Info_GL_X11 *einfo); - unsigned long (*best_colormap_get) (Evas_Engine_Info_GL_X11 *einfo); - int (*best_depth_get) (Evas_Engine_Info_GL_X11 *einfo); + Visual * (*best_visual_get) (Evas_Engine_Info_GL_X11 *einfo); + Colormap (*best_colormap_get) (Evas_Engine_Info_GL_X11 *einfo); + int (*best_depth_get) (Evas_Engine_Info_GL_X11 *einfo); } func; struct { @@ -54,5 +58,12 @@ struct _Evas_Engine_Info_GL_X11 unsigned char vsync : 1; // does nothing right now unsigned char indirect : 1; // use indirect rendering unsigned char swap_mode : 4; // what swap mode to assume + + /* TIZEN ONLY + * Disable sync draw done from application side when it is needed. + * Currently this is set true when a back-end engine uses DRI2. + * This depends on engine so we need to check it from evas engine. + */ + Eina_Bool disable_sync_draw_done : 1; }; #endif diff --git a/src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h b/src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h index e42c10a618..98293cded3 100644 --- a/src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h +++ b/src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h @@ -47,6 +47,13 @@ struct _Evas_Engine_Info_Software_X11 /* non-blocking or blocking mode */ Evas_Engine_Render_Mode render_mode; + + /* TIZEN ONLY + * Disable sync draw done from application side when it is needed. + * Currently this is set true when a back-end engine uses DRI2. + * This depends on engine so we need to check it from evas engine. + */ + Eina_Bool disable_sync_draw_done : 1; }; #endif |