diff --git a/legacy/ecore/src/lib/ecore/Ecore.h b/legacy/ecore/src/lib/ecore/Ecore.h index 175756a54f..97b488fe2a 100644 --- a/legacy/ecore/src/lib/ecore/Ecore.h +++ b/legacy/ecore/src/lib/ecore/Ecore.h @@ -19,7 +19,6 @@ 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_Group @li @ref Ecore_File_Group @li @ref Ecore_Con_Group @li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink @@ -303,25 +302,53 @@ extern "C" { #endif /** - * @file Ecore.h - * @defgroup Ecore_Group Ecore - Main Loop and Job Functions. - * @brief The file that provides the program utility, main loop and timer - * functions. + * @defgroup Ecore_Init_Group Ecore initialization and shutdown functions. * - * This header provides the Ecore event handling loop. For more - * details, see @ref Ecore_Main_Loop_Group. + * @{ + */ + + EAPI int ecore_init(void); + EAPI int ecore_shutdown(void); + + /** + * @} + */ + + /** * - * For the main loop to be of any use, you need to be able to add events - * and event handlers. Events for file descriptor events are covered in - * @ref Ecore_FD_Handler_Group. + * @defgroup Ecore_Main_Loop_Group Ecore main loop functions * - * Time functions are covered in @ref Ecore_Time_Group. + * These are functions acting on Ecore's main loop itself or on + * events and infrastructure directly linked to it. This loop is + * designed to work on embedded systems all the way to large and + * powerful multi-cpu workstations. + * + * It serialises all system signals and events into a single event + * queue, that can be easily processed without needing to worry + * about concurrency. A properly written, event-driven program + * using this kind of programming does not need threads. It makes + * the program very robust and easy to follow. + * + * For example, for the main loop to be of any use, you need to be + * able to add @b events and event handlers on it. Events for file + * descriptor events are covered in @ref Ecore_FD_Handler_Group. + * + * Timer functions are covered in @ref Ecore_Time_Group. * * There is also provision for callbacks for when the loop enters or - * exits an idle state. See @ref Ecore_Idle_Group for more information. + * exits an @b idle state. See @ref Ecore_Idle_Group for more + * information on it. * - * Functions are also provided for spawning child processes using fork. - * See @ref Ecore_Exe_Group for more details. + * Functions are also provided for spawning child processes using + * @c fork(). See @ref Ecore_Exe_Group for more details on it. + * + * Here is an example of simple program and its basic event loop + * flow: + * + * @image html prog_flow.png + * + * For examples of setting up and using a main loop, see + * @ref Ecore_Main_Loop_Page. * * @{ */ @@ -336,7 +363,7 @@ extern "C" { int micro; int revision; } Ecore_Version; - + EAPI extern Ecore_Version *ecore_version; #define ECORE_CALLBACK_CANCEL EINA_FALSE /**< Return value to remove a callback */ @@ -345,6 +372,97 @@ extern "C" { #define ECORE_CALLBACK_PASS_ON EINA_TRUE /**< Return value to pass event to next handler */ #define ECORE_CALLBACK_DONE EINA_FALSE /**< Return value to stop event handling */ + /** + * @typedef Ecore_Task_Cb Ecore_Task_Cb + * A callback run for a task (timer, idler, poller, animator, etc) + */ + typedef Eina_Bool (*Ecore_Task_Cb) (void *data); + + /** + * @typedef Ecore_Eselect_Function Ecore_Eselect_Function + * A function which 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); + + EAPI void ecore_main_loop_iterate(void); + + EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func); + EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void); + + EAPI Eina_Bool ecore_main_loop_glib_integrate(void); + EAPI void ecore_main_loop_glib_always_integrate_disable(void); + + EAPI void ecore_main_loop_begin(void); + EAPI void ecore_main_loop_quit(void); + + /** + * @typedef Ecore_Cb Ecore_Cb + * A generic callback called as a hook when a certain point in + * execution is reached. + */ + typedef void (*Ecore_Cb) (void *data); + + /** + * @brief Call callback in the main loop. + * + * @param callback The callback to call in the main loop + * @param data The data to give to that call back + * + * For all call that need to happen in the main loop (most EFL functions do), + * this helper function provide the infrastructure needed to do it safely + * by avoind dead lock, race condition and properly wake up the main loop. + * + * Remember after that function call, you should never touch again the @p data + * in the thread, it is owned by the main loop and you callback should take + * care of freeing it if necessary. + */ + EAPI void ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data); + + /** + * @} + */ + + /** + * @defgroup Ecore_Event_Group Ecore Event functions + * + * Ecore events are used to wake up the Ecore main loop to warn + * about state changes, tasks completed, data available for reading + * or writing, etc. They are the base of the event oriented + * programming. + * + * The idea is to write many functions (callbacks) that will be + * registered to specific events, and called when these events + * happen. This way, when the system state changes (a mouse click is + * detected, a key is pressed, or the content of a file changes, for + * example), the respective callbacks will be called with some + * information about that event. Usually the function/callback will + * have a data pointer to the event info (the position in the screen + * where the mouse was clicked, the name of the key that was + * pressed, or the name of the file that has changed). + * + * The basic usage, when one needs to watch for an existing event, + * is to register a callback to it using ecore_event_add(). Of + * course it's necessary to know beforehand what are the types of + * events that the system/library will emmit. This should be + * available with the documentation from that system/library. + * + * When writing a library or group of functions that need to inform + * about something, and you already are running on top of a main + * loop, it is usually a good approach to use events. This way you + * allow others to register as many callbacks as necessary to this + * event, and don't have to care about who is registering to it. The + * functions ecore_event_type_new() and ecore_event_add() are + * available for this purpose. + * + * Example that deals with events: + * + * @li @ref ecore_event_example_c + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + #define ECORE_EVENT_NONE 0 #define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */ #define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */ @@ -353,177 +471,41 @@ extern "C" { #define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */ #define ECORE_EVENT_COUNT 6 -#define ECORE_EXE_PRIORITY_INHERIT 9999 - - EAPI extern int ECORE_EXE_EVENT_ADD; /**< A child process has been added */ - EAPI extern int ECORE_EXE_EVENT_DEL; /**< A child process has been deleted (it exited, naming consistent with the rest of ecore). */ - EAPI extern int ECORE_EXE_EVENT_DATA; /**< Data from a child process. */ - EAPI extern int ECORE_EXE_EVENT_ERROR; /**< Errors from a child process. */ - - 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 */ - }; - typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags; - - 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 until a newline and delivered 1 event per line */ - ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, /**< Errors are buffered until a newline and delivered 1 event per 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 have the executed process be its own session leader */ - }; - typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags; - - 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 will 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; - - enum _Ecore_Poller_Type /* Poller types */ - { - ECORE_POLLER_CORE = 0 /**< The core poller interval */ - }; - typedef enum _Ecore_Poller_Type Ecore_Poller_Type; - - 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 end */ - ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a power factor, 0.0 being linear, 1.0 being normal accelerate, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc. */ - ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc. */ - ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc. */ - ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via power of v2 curve */ - ECORE_POS_MAP_BOUNCE, /**< Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v1 */ - ECORE_POS_MAP_SPRING /**< Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v1 */ - }; - typedef enum _Ecore_Pos_Map Ecore_Pos_Map; - - 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 that you need to call ecore_animator_trigger() to make it tick */ - }; - typedef enum _Ecore_Animator_Source Ecore_Animator_Source; - - typedef struct _Ecore_Exe Ecore_Exe; /**< A handle for spawned processes */ - typedef struct _Ecore_Timer Ecore_Timer; /**< A handle for timers */ - typedef struct _Ecore_Idler Ecore_Idler; /**< A handle for idlers */ - typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer; /**< A handle for idle enterers */ - typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter; /**< A handle for idle exiters */ - typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for Fd handlers */ typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< A handle for HANDLE handlers on Windows */ typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< A handle for an event handler */ typedef struct _Ecore_Event_Filter Ecore_Event_Filter; /**< A handle for an event filter */ typedef struct _Ecore_Event Ecore_Event; /**< A handle for an event */ - typedef struct _Ecore_Animator Ecore_Animator; /**< A handle for animators */ - typedef struct _Ecore_Pipe Ecore_Pipe; /**< A handle for pipes */ - typedef struct _Ecore_Poller Ecore_Poller; /**< A handle for pollers */ typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User; /**< User signal event */ typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup; /**< Hup signal event */ typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit; /**< Exit signal event */ typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power; /**< Power signal event */ typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime; /**< Realtime signal event */ - typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add; /**< Spawned Exe add event */ - typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< Spawned Exe exit event */ - typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< Lines from a child process */ - typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< Data from a child process */ - typedef struct _Ecore_Thread Ecore_Thread; /**< A handle for threaded jobs */ /** * @typedef Ecore_Data_Cb Ecore_Data_Cb * A callback which is used to return data to the main function */ typedef void *(*Ecore_Data_Cb) (void *data); + /** * @typedef Ecore_Filter_Cb * 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_Eselect_Function Ecore_Eselect_Function - * A function which 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); + /** * @typedef Ecore_End_Cb Ecore_End_Cb - * This is the callback which is called at the end of a function, usually for cleanup purposes. + * This is the callback which is called at the end of a function, + * usually for cleanup purposes. */ typedef void (*Ecore_End_Cb) (void *user_data, void *func_data); - /** - * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb - * The callback that data written to the pipe is sent to. - */ - typedef void (*Ecore_Pipe_Cb) (void *data, void *buffer, unsigned int nbyte); - /** - * @typedef Ecore_Exe_Cb Ecore_Exe_Cb - * A callback to run with the associated @ref Ecore_Exe, usually for cleanup purposes. - */ - typedef void (*Ecore_Exe_Cb)(void *data, const Ecore_Exe *exe); + /** * @typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb - * A callback used by the main loop to handle events of a specified type. + * A callback 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); - /** - * @typedef Ecore_Thread_Cb Ecore_Thread_Cb - * A callback used by Ecore_Thread helper. - */ - typedef void (*Ecore_Thread_Cb) (void *data, Ecore_Thread *thread); - /** - * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb - * A callback 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); - /** - * @typedef Ecore_Task_Cb Ecore_Task_Cb - * A callback run for a task (timer, idler, poller, animator, etc) - */ - typedef Eina_Bool (*Ecore_Task_Cb) (void *data); - /** - * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb - * A callback run for a task (animators with runtimes) - */ - typedef Eina_Bool (*Ecore_Timeline_Cb) (void *data, double pos); - /** - * @typedef Ecore_Cb Ecore_Cb - * A generic callback called as a hook when a certain point in execution is reached. - */ - typedef void (*Ecore_Cb) (void *data); - /** - * @typedef Ecore_Fd_Cb Ecore_Fd_Cb - * 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 - * A callback used by an @ref Ecore_Fd_Handler. - */ - typedef void (*Ecore_Fd_Prep_Cb) (void *data, Ecore_Fd_Handler *fd_handler); - /** - * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb - * A callback used by an @ref Ecore_Win32_Handler. - */ - typedef Eina_Bool (*Ecore_Win32_Handle_Cb) (void *data, Ecore_Win32_Handler *wh); - - - typedef struct _Ecore_Job Ecore_Job; /**< A job handle */ struct _Ecore_Event_Signal_User /** User signal event */ { @@ -574,6 +556,79 @@ extern "C" { #endif }; + EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); + EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); + EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data); + EAPI void *ecore_event_del(Ecore_Event *event); + EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); + EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); + EAPI int ecore_event_type_new(void); + 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); + EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); + EAPI int ecore_event_current_type_get(void); + EAPI void *ecore_event_current_event_get(void); + + /** + * @} + */ + + /** + * @defgroup Ecore_Exe_Group Process Spawning Functions + * + * Functions that deal with and send signals to spawned processes. + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + + #define ECORE_EXE_PRIORITY_INHERIT 9999 + + EAPI extern int ECORE_EXE_EVENT_ADD; /**< A child process has been added */ + EAPI extern int ECORE_EXE_EVENT_DEL; /**< A child process has been deleted (it exited, naming consistent with the rest of ecore). */ + EAPI extern int ECORE_EXE_EVENT_DATA; /**< Data from a child process. */ + EAPI extern int ECORE_EXE_EVENT_ERROR; /**< Errors from a child process. */ + + 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 until a newline and delivered 1 event per line */ + ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, /**< Errors are buffered until a newline and delivered 1 event per 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 have the executed process be its own session leader */ + }; + typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags; + + 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 will 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; /**< A handle for spawned processes */ + + /** + * @typedef Ecore_Exe_Cb Ecore_Exe_Cb + * A callback 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; /**< Spawned Exe add event */ + typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< Spawned Exe exit event */ + typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< Lines from a child process */ + typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< Data from a child process */ + struct _Ecore_Exe_Event_Add /** Process add event */ { Ecore_Exe *exe; /**< The handle to the added process */ @@ -608,59 +663,6 @@ extern "C" { Ecore_Exe_Event_Data_Line *lines; /**< an array of line data if line buffered, the last one has it's line member set to NULL */ }; - /** - * @defgroup Ecore_Init_Group Ecore initialisation and shutdown functions. - */ - - EAPI int ecore_init(void); - EAPI int ecore_shutdown(void); - - /** - * @} - */ - - /** - * @defgroup Ecore_Application_Group Ecore Application functions - * - * @{ - */ - - 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_Event_Group Ecore Event functions - * - * @{ - */ - - EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); - EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); - EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data); - EAPI void *ecore_event_del(Ecore_Event *event); - EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); - EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); - EAPI int ecore_event_type_new(void); - 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); - EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); - EAPI int ecore_event_current_type_get(void); - EAPI void *ecore_event_current_event_get(void); - - /** - * @} - */ - - /** - * @defgroup Ecore_Exe_Group Process Spawning Functions - * - * @{ - */ - 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); @@ -688,46 +690,68 @@ extern "C" { EAPI void ecore_exe_signal(Ecore_Exe *exe, int num); EAPI void ecore_exe_hup(Ecore_Exe *exe); - /** - * @} - */ + /** + * @} + */ - /** - * @defgroup Ecore_Idle_Group Ecore Idle functions - * - * @{ - */ + /** + * @defgroup Ecore_FD_Handler_Group File Event Handling Functions + * + * Functions that deal with file descriptor handlers. + * + * The @ref Ecore_Fd_Handler can be used to watch a file descriptor + * for data available for reading, for the availability to write + * without blocking, and for errors on the file descriptor. + * + * ecore_main_fd_handler_add() is used to setup a handler for a + * given file descriptor. This file descriptor can be the standard + * input, a network socket, a stream received through some driver + * of a hardware decoder, etc. Thus it can contain errors, like a + * disconnection, a broken pipe, and so, and that's why it's + * possible to check for these errors with the @ref ECORE_FD_ERROR + * flag. + * + * An @ref Ecore_Fd_Handler can be used to watch on a file + * descriptor without blocking, still being able to receive events, + * expire timers, and other watch for other things that happen in + * the Ecore main loop. + * + * Example of use of a file descriptor handler: + * @li @ref ecore_fd_handler_example_c + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ - EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data); - EAPI void *ecore_idler_del(Ecore_Idler *idler); + typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for Fd handlers */ - EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data); - EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data); - EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); + 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 */ + }; + typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags; - EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data); - EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); + /** + * @typedef Ecore_Fd_Cb Ecore_Fd_Cb + * 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 + * A callback used by an @ref Ecore_Fd_Handler. + */ + typedef void (*Ecore_Fd_Prep_Cb) (void *data, Ecore_Fd_Handler *fd_handler); - /** - * @defgroup Ecore_Main Loop_Group Ecore Main Loop functions - * - * @{ - */ + /** + * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb + * A callback used by an @ref Ecore_Win32_Handler. + */ + typedef Eina_Bool (*Ecore_Win32_Handle_Cb) (void *data, Ecore_Win32_Handler *wh); - EAPI void ecore_main_loop_iterate(void); - - EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func); - EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void); - - EAPI Eina_Bool ecore_main_loop_glib_integrate(void); - EAPI void ecore_main_loop_glib_always_integrate_disable(void); - - EAPI void ecore_main_loop_begin(void); - EAPI void ecore_main_loop_quit(void); 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); EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data); @@ -739,40 +763,497 @@ extern "C" { EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); + /** + * @} + */ + /** - * @brief Call callback in the main loop. + * @defgroup Ecore_Poller_Group Ecore Poll functions * - * @param callback The callback to call in the main loop - * @param data The data to give to that call back + * These functions are for the need to poll information, but provide + * a shared abstracted API to pool such polling to minimise wakeup + * and ensure all the polling happens in as few spots as possible + * areound a core poll interval. For now only 1 core poller type is + * supprted: ECORE_POLLER_CORE * - * For all call that need to happen in the main loop (most EFL functions do), - * this helper function provide the infrastructure needed to do it safely - * by avoind dead lock, race condition and properly wake up the main loop. + * Example of @ref Ecore_Poller: + * @li @ref ecore_poller_example_c * - * Remember after that function call, you should never touch again the @p data - * in the thread, it is owned by the main loop and you callback should take - * care of freeing it if necessary. + * @ingroup Ecore_Main_Loop_Group + * + * @{ */ - EAPI void ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data); + + enum _Ecore_Poller_Type /* Poller types */ + { + ECORE_POLLER_CORE = 0 /**< The core poller interval */ + }; + typedef enum _Ecore_Poller_Type Ecore_Poller_Type; + + typedef struct _Ecore_Poller Ecore_Poller; /**< A handle for pollers */ + + EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time); + EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type); + EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *poller, int interval); + EAPI int ecore_poller_poller_interval_get(Ecore_Poller *poller); + EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data); + EAPI void *ecore_poller_del(Ecore_Poller *poller); /** * @} */ /** - * @defgroup Ecore_Pipe_Group Pipe wrapper + * @defgroup Ecore_Animator_Group Ecore Animator functions + * + * @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 2 seconds. + * + * If your animation will run 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 to creating a timer for each animation in terms + * of performance. + * + * For a more detailed example that show several animation see + * @ref tutorial_ecore_animator. + * + * @ingroup Ecore_Main_Loop_Group * * @{ */ - EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); - EAPI void *ecore_pipe_del(Ecore_Pipe *p); - EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes); - EAPI void ecore_pipe_write_close(Ecore_Pipe *p); - EAPI void ecore_pipe_read_close(Ecore_Pipe *p); - EAPI void ecore_pipe_thaw(Ecore_Pipe *p); - EAPI void ecore_pipe_freeze(Ecore_Pipe *p); - EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); + typedef struct _Ecore_Animator Ecore_Animator; /**< A handle for animators */ + + 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 end */ + ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a power factor, 0.0 being linear, 1.0 being normal accelerate, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc. */ + ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc. */ + ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc. */ + ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via power of v2 curve */ + ECORE_POS_MAP_BOUNCE, /**< Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v1 */ + ECORE_POS_MAP_SPRING /**< Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v1 */ + }; + typedef enum _Ecore_Pos_Map Ecore_Pos_Map; + + 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 that you need to call ecore_animator_trigger() to make it tick */ + }; + typedef enum _Ecore_Animator_Source Ecore_Animator_Source; + + /** + * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb + * A callback run for a task (animators with runtimes) + */ + typedef Eina_Bool (*Ecore_Timeline_Cb) (void *data, double pos); + + /** + * @brief Add an animator to call @p func at every animaton tick during main + * loop execution. + * + * @param func The function to call when it ticks off + * @param data The data to pass to the function + * @return A handle to the new animator + * + * This function adds a animator and returns its handle on success and NULL on + * failure. The function @p func will be called every N seconds where N is the + * @p frametime interval set by ecore_animator_frametime_set(). The function + * will be passed the @p data pointer as its parameter. + * + * When the animator @p func is called, it must return a value of either 1 or + * 0. If it returns 1 (or ECORE_CALLBACK_RENEW), it will be called again at + * the next tick, or if it returns 0 (or ECORE_CALLBACK_CANCEL) it will be + * deleted automatically making any references/handles for it invalid. + * + * @note The default @p frametime value is 1/30th of a second. + * + * @see ecore_animator_timeline_add() + * @see ecore_animator_frametime_set() + */ + EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); + /** + * @brief Add a animator that runs for a limited time + * + * @param runtime The time to run in seconds + * @param func The function to call when it ticks off + * @param data The data to pass to the function + * @return A handle to the new animator + * + * This function is just like ecore_animator_add() except the animator only + * runs for a limited time specified in seconds by @p runtime. Once the + * runtime the animator has elapsed (animator finished) it will automatically + * be deleted. The callback function @p func can return ECORE_CALLBACK_RENEW + * to keep the animator running or ECORE_CALLBACK_CANCEL ro stop it and have + * it be deleted automatically at any time. + * + * The @p func will ALSO be passed a position parameter that will be in value + * from 0.0 to 1.0 to indicate where along the timeline (0.0 start, 1.0 end) + * the animator run is at. If the callback wishes not to have a linear + * transition it can "map" this value to one of several curves and mappings + * via ecore_animator_pos_map(). + * + * @note The default @p frametime value is 1/30th of a second. + * + * @see ecore_animator_add() + * @see ecore_animator_pos_map() + * @since 1.1.0 + */ + EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data); + /** + * @brief Delete the specified animator from the animator list. + * + * @param animator The animator to delete + * @return The data pointer set for the animator on add + * + * Delete the specified @p animator from the set of animators that are + * executed during main loop execution. This function returns the data + * parameter that was being passed to the callback on success, or NULL on + * failure. After this call returns the specified animator object @p animator + * is invalid and should not be used again. It will not get called again after + * deletion. + */ + EAPI void *ecore_animator_del(Ecore_Animator *animator); + /** + * @brief Suspend the specified animator. + * + * @param animator The animator to delete + * + * The specified @p animator will be temporarly removed from the set of + * animators that are executed during main loop. + * + * @warning Freezing an animator doesn't freeze accounting of how long that + * animator has been running. Therefore if the animator was created with + * ecore_animator_timeline_add() the @p pos argument given to the callback + * will increase as if the animator hadn't been frozen and the animator may + * have it's execution halted if @p runtime elapsed. + */ + EAPI void ecore_animator_freeze(Ecore_Animator *animator); + /** + * @brief Restore execution of the specified animator. + * + * @param animator The animator to delete + * + * The specified @p animator will be put back in the set of animators that are + * executed during main loop. + */ + EAPI void ecore_animator_thaw(Ecore_Animator *animator); + /** + * @brief Set the animator call interval in seconds. + * + * @param frametime The time in seconds in between animator ticks. + * + * This function sets the time interval (in seconds) between animator ticks. + * At every tick the callback of every existing animator will be called. + * + * @warning Too small a value may cause performance issues and too high a + * value may cause your animation to seem "jerky". + * + * @note The default @p frametime value is 1/30th of a second. + */ + EAPI void ecore_animator_frametime_set(double frametime); + /** + * @brief Get the animator call interval in seconds. + * + * @return The time in second in between animator ticks. + * + * This function retrieves 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 0.0 to 1.0 along a timeline to a + * position in a different curve. + * + * @param pos The input position to map + * @param map The mapping to use + * @param v1 A parameter use by the mapping (pass 0.0 if not used) + * @param v2 A parameter use by the mapping (pass 0.0 if not used) + * @return The mapped value + * + * Takes an input position (0.0 to 1.0) and maps to a new position (normally + * between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it + * has "overshot" the mark) using some interpolation (mapping) algorithm. + * + * This function useful to create non-linear animations. It offers a variety + * of possible animaton curves to be used: + * @li ECORE_POS_MAP_LINEAR - Linear, returns @p 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 end + * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a + * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 + * being much more pronounced accelerate (squared), 3.0 being cubed, etc. + * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a + * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 + * being much more pronounced decelerate (squared), 3.0 being cubed, etc. + * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down + * at end, v1 being a power factor, 0.0 being linear, 1.0 being + * ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal + * (squared), 3.0 being cubed, etc. + * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via + * power of v2 curve + * @li ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to + * the ground at 1.0, and bounce v2 times, with decay factor of v1 + * @li ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest + * position 1.0, and wobble v2 times, with decay factor of v1 + * @note When not listed v1 and v2 have no effect. + * + * @image html ecore-pos-map.png + * @image latex ecore-pos-map.eps width=\textwidth + * + * 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 will make an animaton that bounces 7 each times diminishing by a + * factor of 1.8. + * + * @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 Set the source of animator ticks for the mainloop + * + * @param source The source of animator ticks to use + * + * This sets the source of animator ticks. When an animator is active the + * mainloop will "tick" over frame by frame calling all animators that are + * registered until none are. The mainloop will tick at a given rate based + * on the animator source. The default source is the system clock timer + * source - 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 + * ECORE_ANIMATOR_SOURCE_CUSTOM and then drive it yourself based on some input + * tick source (like another application via ipc, some vertical blanking + * interrupt interrupt etc.) using + * ecore_animator_custom_source_tick_begin_callback_set() and + * ecore_animator_custom_source_tick_end_callback_set() to set the functions + * that will be called to start and stop the ticking source, which when it + * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over 1 + * frame. + */ + EAPI void ecore_animator_source_set(Ecore_Animator_Source source); + /** + * @brief Get the animator source currently set. + * + * @return The current animator source + * + * This gets the current animator source. + * + * @see ecore_animator_source_set() + */ + EAPI Ecore_Animator_Source ecore_animator_source_get(void); + /** + * @brief Set the function that begins a custom animator tick source + * + * @param func The function to call when ticking is to begin + * @param data The data passed to the tick begin function as its parameter + * + * The Ecore Animator infrastructure handles tracking if animators are needed + * or not 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 a frame tick happened. In order + * to allow the source of ticks to be dynamically enabled or disabled as + * needed, the @p func when set is called to enable the tick source to + * produce tick events that call ecore_animator_custom_tick(). If @p func + * is NULL then no function is called to begin custom ticking. + * + * @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 Set the function that ends a custom animator tick source + * + * @param func The function to call when ticking is to end + * @param data The data passed to the tick end function as its parameter + * + * 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 @p func is NULL then no function will be + * called to stop ticking. For more information please see + * ecore_animator_custom_source_tick_begin_callback_set(). + * + * @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 Trigger a custom animator tick + * + * When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM, then calling + * this function triggers a run of all animators currently registered with + * Ecore as this indicates a "frame tick" happened. This will do nothing if + * the animator source(set by ecore_animator_source_set()) is not set to + * 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_Time_Group Ecore Time functions + * + * Functions that deal with time. These functions include those + * that simply retrieve it in a given format, and those that create + * events based on it. + * + * The timer allows callbacks to be called at specific intervals. + * + * Examples with functions that deal with time: + * @li @ref ecore_time_functions_example_c + * @li @ref ecore_timer_example_c + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + + typedef struct _Ecore_Timer Ecore_Timer; /**< A handle for timers */ + + EAPI double ecore_time_get(void); + EAPI double ecore_time_unix_get(void); + EAPI double ecore_loop_time_get(void); + + EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data); + EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data); + EAPI void *ecore_timer_del(Ecore_Timer *timer); + EAPI void ecore_timer_interval_set(Ecore_Timer *timer, double in); + EAPI double ecore_timer_interval_get(Ecore_Timer *timer); + EAPI void ecore_timer_freeze(Ecore_Timer *timer); + EAPI void ecore_timer_thaw(Ecore_Timer *timer); + EAPI void ecore_timer_delay(Ecore_Timer *timer, double add); + EAPI double ecore_timer_pending_get(Ecore_Timer *timer); + EAPI double ecore_timer_precision_get(void); + EAPI void ecore_timer_precision_set(double precision); + EAPI char *ecore_timer_dump(void); + + /** + * @} + */ + + /** + * @defgroup Ecore_Idle_Group Ecore Idle functions + * + * Callbacks that are called when the program enters or exits an + * idle state. + * + * The ecore main loop enters an idle state when it is waiting for + * timers to time out, data to come in on a file descriptor or any + * other event to occur. You can set callbacks to be called when + * the main loop enters an idle state, during an idle state or just + * after the program wakes up. + * + * 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 will enter 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 would be too slow to use. + * + * 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. + * + * Exiter callbacks are called when the main loop wakes up from an + * idle state. + * + * @note Idle state doesn't mean that the @b program is idle, but + * that the main loop is idle. It doesn't have any timers, + * events, fd handlers or anything else to process (which in most + * event driven 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. + * + * Example with functions that deal with idle state: + * + * @li @ref ecore_idler_example_c + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + + typedef struct _Ecore_Idler Ecore_Idler; /**< A handle for idlers */ + typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer; /**< A handle for idle enterers */ + typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter; /**< A handle for idle exiters */ + + /** + * Add an idler handler. + * @param func The function to call when idling. + * @param data The data to be passed to this @p func call. + * @return A idler handle if successfully added. NULL otherwise. + * + * Add an idler handle to the event loop, returning a handle on + * success and NULL otherwise. The function @p func will be called + * repeatedly while no other events are ready to be processed, as + * long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0 + * (or ECORE_CALLBACK_CANCEL) deletes the idler. + * + * Idlers are useful for progressively prossessing data without blocking. + */ + EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data); + + /** + * Delete an idler callback from the list to be executed. + * @param idler The handle of the idler callback to delete + * @return The data pointer passed to the idler callback on success. NULL + * otherwise. + */ + EAPI void *ecore_idler_del(Ecore_Idler *idler); + + EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data); + EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data); + EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); + + EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data); + EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); /** * @} @@ -831,7 +1312,7 @@ extern "C" { * 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 Ecore handles: simple, or short, * workers and feedback workers. * @@ -863,11 +1344,25 @@ extern "C" { * * See an overview example in @ref ecore_thread_example_c. * - * @ingroup Ecore_Group + * @ingroup Ecore_Main_Loop_Group * * @{ */ + typedef struct _Ecore_Thread Ecore_Thread; /**< A handle for threaded jobs */ + + /** + * @typedef Ecore_Thread_Cb Ecore_Thread_Cb + * A callback used by Ecore_Thread helper. + */ + typedef void (*Ecore_Thread_Cb) (void *data, Ecore_Thread *thread); + /** + * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb + * A callback 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); + /** * Schedule a task to run in a parallel thread to avoid locking the main loop * @@ -1459,354 +1954,77 @@ extern "C" { */ EAPI void *ecore_thread_global_data_wait(const char *key, double seconds); + /** + * @} + */ + + /** + * @defgroup Ecore_Pipe_Group Pipe wrapper + * + * These functions wrap the pipe / write / read functions to easily + * integrate its use into ecore's main loop. + * + * The ecore_pipe_add() function creates file descriptors (sockets + * on Windows) and attach 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(). + * + * For examples see here: + * @li @ref tutorial_ecore_pipe_gstreamer_example + * @li @ref tutorial_ecore_pipe_simple_example + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ + */ + + typedef struct _Ecore_Pipe Ecore_Pipe; /**< A handle for pipes */ + /** - * @} + * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb + * The callback that data written to the pipe is sent to. + */ + typedef void (*Ecore_Pipe_Cb) (void *data, void *buffer, unsigned int nbyte); + + EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); + EAPI void *ecore_pipe_del(Ecore_Pipe *p); + EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes); + EAPI void ecore_pipe_write_close(Ecore_Pipe *p); + EAPI void ecore_pipe_read_close(Ecore_Pipe *p); + EAPI void ecore_pipe_thaw(Ecore_Pipe *p); + EAPI void ecore_pipe_freeze(Ecore_Pipe *p); + EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); + + /** + * @} + */ + + /** + * @defgroup Ecore_Job_Group Ecore Job functions + * + * 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 similarly to events. They + * also will be executed in the order in which they were added. + * + * A good use for them is when you don't want to execute an action + * immeditately, but want to give the control back to the main loop + * so that it will call your job callback when jobs start being + * processed (and if there are other jobs added before yours, they + * will be processed first). This also gives the chance to other + * actions in your program to cancel the job before it is started. + * + * Examples of using @ref Ecore_Job: + * @li @ref ecore_job_example_c + * + * @ingroup Ecore_Main_Loop_Group + * + * @{ */ - /** - * @defgroup Ecore_Time_Group Ecore Time functions - * - * @{ - */ - - EAPI double ecore_time_get(void); - EAPI double ecore_time_unix_get(void); - EAPI double ecore_loop_time_get(void); - - EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data); - EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data); - EAPI void *ecore_timer_del(Ecore_Timer *timer); - EAPI void ecore_timer_interval_set(Ecore_Timer *timer, double in); - EAPI double ecore_timer_interval_get(Ecore_Timer *timer); - EAPI void ecore_timer_freeze(Ecore_Timer *timer); - EAPI void ecore_timer_thaw(Ecore_Timer *timer); - EAPI void ecore_timer_delay(Ecore_Timer *timer, double add); - EAPI double ecore_timer_pending_get(Ecore_Timer *timer); - EAPI double ecore_timer_precision_get(void); - EAPI void ecore_timer_precision_set(double precision); - EAPI char *ecore_timer_dump(void); - - /** - * @} - */ - - /** - * @defgroup Ecore_Animator_Group Ecore Animator functions - * - * @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 @p my_evas_object from - * position (0,0) to (100,100) in 2 seconds. - * - * If your animation will run 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 to creating a timer for each animation in terms - * of performance. - * - * For a more detailed example that show several animation see @ref - * tutorial_ecore_animator. - * @{ - */ - - /** - * @brief Add an animator to call @p func at every animaton tick during main - * loop execution. - * - * @param func The function to call when it ticks off - * @param data The data to pass to the function - * @return A handle to the new animator - * - * This function adds a animator and returns its handle on success and NULL on - * failure. The function @p func will be called every N seconds where N is the - * @p frametime interval set by ecore_animator_frametime_set(). The function - * will be passed the @p data pointer as its parameter. - * - * When the animator @p func is called, it must return a value of either 1 or - * 0. If it returns 1 (or ECORE_CALLBACK_RENEW), it will be called again at - * the next tick, or if it returns 0 (or ECORE_CALLBACK_CANCEL) it will be - * deleted automatically making any references/handles for it invalid. - * - * @note The default @p frametime value is 1/30th of a second. - * - * @see ecore_animator_timeline_add() - * @see ecore_animator_frametime_set() - */ - EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); - /** - * @brief Add a animator that runs for a limited time - * - * @param runtime The time to run in seconds - * @param func The function to call when it ticks off - * @param data The data to pass to the function - * @return A handle to the new animator - * - * This function is just like ecore_animator_add() except the animator only - * runs for a limited time specified in seconds by @p runtime. Once the - * runtime the animator has elapsed (animator finished) it will automatically - * be deleted. The callback function @p func can return ECORE_CALLBACK_RENEW - * to keep the animator running or ECORE_CALLBACK_CANCEL ro stop it and have - * it be deleted automatically at any time. - * - * The @p func will ALSO be passed a position parameter that will be in value - * from 0.0 to 1.0 to indicate where along the timeline (0.0 start, 1.0 end) - * the animator run is at. If the callback wishes not to have a linear - * transition it can "map" this value to one of several curves and mappings - * via ecore_animator_pos_map(). - * - * @note The default @p frametime value is 1/30th of a second. - * - * @see ecore_animator_add() - * @see ecore_animator_pos_map() - * @since 1.1.0 - */ - EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data); - /** - * @brief Delete the specified animator from the animator list. - * - * @param animator The animator to delete - * @return The data pointer set for the animator on add - * - * Delete the specified @p animator from the set of animators that are - * executed during main loop execution. This function returns the data - * parameter that was being passed to the callback on success, or NULL on - * failure. After this call returns the specified animator object @p animator - * is invalid and should not be used again. It will not get called again after - * deletion. - */ - EAPI void *ecore_animator_del(Ecore_Animator *animator); - /** - * @brief Suspend the specified animator. - * - * @param animator The animator to delete - * - * The specified @p animator will be temporarly removed from the set of - * animators that are executed during main loop. - * - * @warning Freezing an animator doesn't freeze accounting of how long that - * animator has been running. Therefore if the animator was created with - * ecore_animator_timeline_add() the @p pos argument given to the callback - * will increase as if the animator hadn't been frozen and the animator may - * have it's execution halted if @p runtime elapsed. - */ - EAPI void ecore_animator_freeze(Ecore_Animator *animator); - /** - * @brief Restore execution of the specified animator. - * - * @param animator The animator to delete - * - * The specified @p animator will be put back in the set of animators that are - * executed during main loop. - */ - EAPI void ecore_animator_thaw(Ecore_Animator *animator); - /** - * @brief Set the animator call interval in seconds. - * - * @param frametime The time in seconds in between animator ticks. - * - * This function sets the time interval (in seconds) between animator ticks. - * At every tick the callback of every existing animator will be called. - * - * @warning Too small a value may cause performance issues and too high a - * value may cause your animation to seem "jerky". - * - * @note The default @p frametime value is 1/30th of a second. - */ - EAPI void ecore_animator_frametime_set(double frametime); - /** - * @brief Get the animator call interval in seconds. - * - * @return The time in second in between animator ticks. - * - * This function retrieves 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 0.0 to 1.0 along a timeline to a - * position in a different curve. - * - * @param pos The input position to map - * @param map The mapping to use - * @param v1 A parameter use by the mapping (pass 0.0 if not used) - * @param v2 A parameter use by the mapping (pass 0.0 if not used) - * @return The mapped value - * - * Takes an input position (0.0 to 1.0) and maps to a new position (normally - * between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it - * has "overshot" the mark) using some interpolation (mapping) algorithm. - * - * This function useful to create non-linear animations. It offers a variety - * of possible animaton curves to be used: - * @li ECORE_POS_MAP_LINEAR - Linear, returns @p 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 end - * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a - * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 - * being much more pronounced accelerate (squared), 3.0 being cubed, etc. - * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a - * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 - * being much more pronounced decelerate (squared), 3.0 being cubed, etc. - * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down - * at end, v1 being a power factor, 0.0 being linear, 1.0 being - * ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal - * (squared), 3.0 being cubed, etc. - * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via - * power of v2 curve - * @li ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to - * the ground at 1.0, and bounce v2 times, with decay factor of v1 - * @li ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest - * position 1.0, and wobble v2 times, with decay factor of v1 - * @note When not listed v1 and v2 have no effect. - * - * @image html ecore-pos-map.png - * @image latex ecore-pos-map.eps width=\textwidth - * - * 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 will make an animaton that bounces 7 each times diminishing by a - * factor of 1.8. - * - * @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 Set the source of animator ticks for the mainloop - * - * @param source The source of animator ticks to use - * - * This sets the source of animator ticks. When an animator is active the - * mainloop will "tick" over frame by frame calling all animators that are - * registered until none are. The mainloop will tick at a given rate based - * on the animator source. The default source is the system clock timer - * source - 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 - * ECORE_ANIMATOR_SOURCE_CUSTOM and then drive it yourself based on some input - * tick source (like another application via ipc, some vertical blanking - * interrupt interrupt etc.) using - * ecore_animator_custom_source_tick_begin_callback_set() and - * ecore_animator_custom_source_tick_end_callback_set() to set the functions - * that will be called to start and stop the ticking source, which when it - * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over 1 - * frame. - */ - EAPI void ecore_animator_source_set(Ecore_Animator_Source source); - /** - * @brief Get the animator source currently set. - * - * @return The current animator source - * - * This gets the current animator source. - * - * @see ecore_animator_source_set() - */ - EAPI Ecore_Animator_Source ecore_animator_source_get(void); - /** - * @brief Set the function that begins a custom animator tick source - * - * @param func The function to call when ticking is to begin - * @param data The data passed to the tick begin function as its parameter - * - * The Ecore Animator infrastructure handles tracking if animators are needed - * or not 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 a frame tick happened. In order - * to allow the source of ticks to be dynamically enabled or disabled as - * needed, the @p func when set is called to enable the tick source to - * produce tick events that call ecore_animator_custom_tick(). If @p func - * is NULL then no function is called to begin custom ticking. - * - * @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 Set the function that ends a custom animator tick source - * - * @param func The function to call when ticking is to end - * @param data The data passed to the tick end function as its parameter - * - * 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 @p func is NULL then no function will be - * called to stop ticking. For more information please see - * ecore_animator_custom_source_tick_begin_callback_set(). - * - * @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 Trigger a custom animator tick - * - * When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM, then calling - * this function triggers a run of all animators currently registered with - * Ecore as this indicates a "frame tick" happened. This will do nothing if - * the animator source(set by ecore_animator_source_set()) is not set to - * 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_Poller_Group Ecore Poll functions - * - * @{ - */ - - EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time); - EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type); - EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *poller, int interval); - EAPI int ecore_poller_poller_interval_get(Ecore_Poller *poller); - EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data); - EAPI void *ecore_poller_del(Ecore_Poller *poller); - - /** - * @} - */ - - /** - * @defgroup Ecore_Job_Group Ecore Job functions - * - * @{ - */ + typedef struct _Ecore_Job Ecore_Job; /**< A job handle */ EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data); EAPI void *ecore_job_del(Ecore_Job *job); @@ -1815,6 +2033,16 @@ extern "C" { * @} */ + /** + * @defgroup Ecore_Application_Group Ecore Application functions + * + * @{ + */ + + 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); + /** * @} */ @@ -1822,16 +2050,13 @@ extern "C" { /** * @defgroup Ecore_Throttle_Group Ecore Throttle functions * + * @ingroup Ecore_Main_Loop_Group + * * @{ */ EAPI void ecore_throttle_adjust(double amount ); EAPI double ecore_throttle_get(void); - - - /** - * @} - */ /** * @} diff --git a/legacy/ecore/src/lib/ecore/ecore.c b/legacy/ecore/src/lib/ecore/ecore.c index a1d0d3cab8..7f3ff58f37 100644 --- a/legacy/ecore/src/lib/ecore/ecore.c +++ b/legacy/ecore/src/lib/ecore/ecore.c @@ -74,7 +74,7 @@ static Eina_Lock _thread_safety; #endif /** - * @addtogroup Ecore_Init_Group Ecore initialisation and shutdown functions. + * @addtogroup Ecore_Init_Group * * @{ */ @@ -221,6 +221,10 @@ ecore_shutdown(void) return _ecore_init_count; } +/** + * @} + */ + EAPI void ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data) { @@ -249,10 +253,6 @@ ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data) eina_lock_release(&_thread_safety); } -/** - * @} - */ - EAPI void ecore_print_warning(const char *function, const char *sparam) { diff --git a/legacy/ecore/src/lib/ecore/ecore_app.c b/legacy/ecore/src/lib/ecore/ecore_app.c index c29480a9b0..296698bad3 100644 --- a/legacy/ecore/src/lib/ecore/ecore_app.c +++ b/legacy/ecore/src/lib/ecore/ecore_app.c @@ -21,13 +21,7 @@ static int app_argc = 0; static char **app_argv = NULL; /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Application_Group Ecore Application functions + * @addtogroup Ecore_Application_Group * * @{ */ @@ -95,7 +89,3 @@ ecore_app_restart(void) /** * @} */ - -/** - * @} - */ diff --git a/legacy/ecore/src/lib/ecore/ecore_events.c b/legacy/ecore/src/lib/ecore/ecore_events.c index 7f21771950..a982d725b7 100644 --- a/legacy/ecore/src/lib/ecore/ecore_events.c +++ b/legacy/ecore/src/lib/ecore/ecore_events.c @@ -73,43 +73,7 @@ static void *_ecore_event_del(Ecore_Event *event); /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Event_Group Ecore Event functions - * - * Ecore events are used to wake up the Ecore main loop to warn about state - * changes, tasks completed, data available for reading or writing, etc. They - * are the base of the event oriented programming. - * - * The idea is to write many functions (callbacks) that will be registered to - * specific events, and called when these events happen. This way, when the - * system state changes (a mouse click is detected, a key is pressed, or the - * content of a file changes, for example), the respective callbacks will be - * called with some information about that event. Usually the function/callback - * will have a data pointer to the event info (the position in the screen where - * the mouse was clicked, the name of the key that was pressed, or the name of - * the file that has changed). - * - * The basic usage, when one needs to watch for an existing event, is to - * register a callback to it using ecore_event_add(). Of course it's necessary - * to know beforehand what are the types of events that the system/library will - * emmit. This should be available with the documentation from that - * system/library. - * - * When writing a library or group of functions that need to inform about - * something, and you already are running on top of a main loop, it is usually a - * good approach to use events. This way you allow others to register as many - * callbacks as necessary to this event, and don't have to care about who is - * registering to it. The functions ecore_event_type_new() and ecore_event_add() - * are available for this purpose. - * - * Example that deals with events: - * - * @li @ref ecore_event_example_c + * @addtogroup Ecore_Event_Group * * @{ */ @@ -473,10 +437,6 @@ ecore_event_current_event_get(void) return ecore_raw_event_event; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_exe.c b/legacy/ecore/src/lib/ecore/ecore_exe.c index d5a626dbd1..12027bfedb 100644 --- a/legacy/ecore/src/lib/ecore/ecore_exe.c +++ b/legacy/ecore/src/lib/ecore/ecore_exe.c @@ -299,17 +299,8 @@ _ecore_exe_check_errno(int result, const char *file, int line) return result; } - /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Exe_Group Process Spawning Functions - * - * Functions that deal with and send signals to spawned processes. + * @addtogroup Ecore_Exe_Group * * @{ */ @@ -1314,10 +1305,6 @@ ecore_exe_hup(Ecore_Exe *exe) kill(exe->pid, SIGHUP); } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_glib.c b/legacy/ecore/src/lib/ecore/ecore_glib.c index dcc88df09b..71288e6545 100644 --- a/legacy/ecore/src/lib/ecore/ecore_glib.c +++ b/legacy/ecore/src/lib/ecore/ecore_glib.c @@ -220,13 +220,7 @@ _ecore_glib_shutdown(void) } /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Main_Loop_Group Ecore Main Loop functions + * @addtogroup Ecore_Main_Loop_Group * * @} */ @@ -321,7 +315,3 @@ ecore_main_loop_glib_always_integrate_disable(void) /** * @} */ - -/** - * @} - */ diff --git a/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c b/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c index c4a191528c..aa0b4a62fd 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c +++ b/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c @@ -27,13 +27,7 @@ static void * _ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Idle_Group Ecore Idle functions + * @addtogroup Ecore_Idle_Group * * @{ */ @@ -119,10 +113,6 @@ ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer) return data; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c b/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c index d7d52f4147..fc41f92627 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c +++ b/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c @@ -27,13 +27,7 @@ static void * _ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Idle_Group Ecore Idle functions + * @addtogroup Ecore_Idle_Group * * @{ */ @@ -88,10 +82,6 @@ ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter) return data; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_idler.c b/legacy/ecore/src/lib/ecore/ecore_idler.c index 672aff26ba..f39999fe05 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idler.c +++ b/legacy/ecore/src/lib/ecore/ecore_idler.c @@ -26,66 +26,6 @@ static int idlers_delete_me = 0; static void * _ecore_idler_del(Ecore_Idler *idler); -/** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Idle_Group Ecore Idle functions - * -Callbacks that are called when the program enters or exits an idle state. - -The ecore main loop enters an idle state when it is waiting for timers -to time out, data to come in on a file descriptor or any other event -to occur. You can set callbacks to be called when the main loop -enters an idle state, during an idle state or just after the program -wakes up. - -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 will enter 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 would be too slow to use. - -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. - -Exiter callbacks are called when the main loop wakes up from an idle -state. - -@note Idle state doesn't mean that the @b program is idle, but that the main -loop is idle. It doesn't have any timers, events, fd handlers or anything -else to process (which in most event driven 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. - -Example with functions that deal with idle state: - -@li @ref ecore_idler_example_c - - * @{ - */ - -/** - * Add an idler handler. - * @param func The function to call when idling. - * @param data The data to be passed to this @p func call. - * @return A idler handle if successfully added. NULL otherwise. - * - * Add an idler handle to the event loop, returning a handle on success and - * NULL otherwise. The function @p func will be called repeatedly while - * no other events are ready to be processed, as long as it returns 1 - * (or ECORE_CALLBACK_RENEW). A return of 0 (or ECORE_CALLBACK_CANCEL) deletes - * the idler. - * - * Idlers are useful for progressively prossessing data without blocking. - */ EAPI Ecore_Idler * ecore_idler_add(Ecore_Task_Cb func, const void *data) { @@ -104,12 +44,6 @@ unlock: return ie; } -/** - * Delete an idler callback from the list to be executed. - * @param idler The handle of the idler callback to delete - * @return The data pointer passed to the idler callback on success. NULL - * otherwise. - */ EAPI void * ecore_idler_del(Ecore_Idler *idler) { diff --git a/legacy/ecore/src/lib/ecore/ecore_job.c b/legacy/ecore/src/lib/ecore/ecore_job.c index 446547b6de..b4a7079bac 100644 --- a/legacy/ecore/src/lib/ecore/ecore_job.c +++ b/legacy/ecore/src/lib/ecore/ecore_job.c @@ -36,28 +36,7 @@ _ecore_job_shutdown(void) } /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Job_Group Ecore Job functions - * - * 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 similarly to events. They also will be - * executed in the order which they were added. - * - * A good use for them is when you don't want to execute an action immeditately, - * but want to give the control back to the main loop so that it will call your - * job callback when jobs start being processed (and if there are other jobs - * added before yours, they will be processed first). This also gives the chance - * to other actions in your program to cancel the job before it is started. - * - * Examples of using @ref Ecore_Job: - * @li @ref ecore_job_example_c + * @addtogroup Ecore_Job_Group * * @{ */ @@ -114,10 +93,6 @@ ecore_job_del(Ecore_Job *job) return data; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_main.c b/legacy/ecore/src/lib/ecore/ecore_main.c index 688c2c5895..edce31d8a3 100644 --- a/legacy/ecore/src/lib/ecore/ecore_main.c +++ b/legacy/ecore/src/lib/ecore/ecore_main.c @@ -790,29 +790,7 @@ _ecore_main_loop_shutdown(void) } /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Main_Loop_Group Ecore Main Loop functions - * - * These functions control the Ecore event handling loop. This loop is - * designed to work on embedded systems all the way to large and - * powerful mutli-cpu workstations. - * - * It serialises all system signals and events into a single event - * queue, that can be easily processed without needing to worry about - * concurrency. A properly written, event-driven program using this - * kind of programming does not need threads. It makes the program very - * robust and easy to follow. - * - * Here is an example of simple program and its basic event loop flow: - * @image html prog_flow.png - * - * For examples of setting up and using a main loop, see @ref - * Ecore_Main_Loop_Page. + * @addtogroup Ecore_Main_Loop_Group * * @{ */ @@ -917,29 +895,6 @@ ecore_main_loop_select_func_get(void) return main_loop_select; } -/** - * @defgroup Ecore_FD_Handler_Group File Event Handling Functions - * - * Functions that deal with file descriptor handlers. - * - * The @ref Ecore_Fd_Handler can be used to watch a file descriptor for data - * available for reading, for the availability to write without blocking, and - * for errors on the file descriptor. - * - * ecore_main_fd_handler_add() is used to setup a handler for a given file - * descriptor. This file descriptor can be the standard input, a network socket, - * a stream received through some driver of a hardware decoder, etc. Thus it can - * contain errors, like a disconnection, a broken pipe, and so, and that's why - * it's possible to check for these errors with the @ref ECORE_FD_ERROR flag. - * - * An @ref Ecore_Fd_Handler can be used to watch on a file descriptor without - * blocking, still being able to receive events, expire timers, and other watch - * for other things that happen in the Ecore main loop. - * - * Example of use of a file descriptor handler: - * @li @ref ecore_fd_handler_example_c - */ - /** * Adds a callback for activity on the given file descriptor. * @@ -1232,10 +1187,6 @@ unlock: _ecore_unlock(); } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_pipe.c b/legacy/ecore/src/lib/ecore/ecore_pipe.c index d3ac605961..9e290debfa 100644 --- a/legacy/ecore/src/lib/ecore/ecore_pipe.c +++ b/legacy/ecore/src/lib/ecore/ecore_pipe.c @@ -89,30 +89,13 @@ struct _Ecore_Pipe static Eina_Bool _ecore_pipe_read(void *data, Ecore_Fd_Handler *fd_handler); + /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. + * @addtogroup Ecore_Pipe_Group * * @{ */ -/** - * @addtogroup Ecore_Pipe_Group Pipe wrapper - * - * These functions wrap the pipe / write / read functions to easily integrate - * its use into ecore's main loop. - * - * The ecore_pipe_add() function creates file descriptors (sockets on - * Windows) and attach an 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(). - * - * For examples see here: - * @li @ref tutorial_ecore_pipe_gstreamer_example - * @li @ref tutorial_ecore_pipe_simple_example - */ - - /** * Create two file descriptors (sockets on Windows). Add * a callback that will be called when the file descriptor that @@ -460,10 +443,6 @@ ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes) return EINA_FALSE; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_poll.c b/legacy/ecore/src/lib/ecore/ecore_poll.c index d1ff9ac2bc..cc0ada6160 100644 --- a/legacy/ecore/src/lib/ecore/ecore_poll.c +++ b/legacy/ecore/src/lib/ecore/ecore_poll.c @@ -191,21 +191,7 @@ _ecore_poller_cb_timer(void *data __UNUSED__) } /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Poller_Group Ecore Poll functions - * - * These functions are for the need to poll information, but provide a shared - * abstracted API to pool such polling to minimise wakeup and ensure all the - * polling happens in as few spots as possible areound a core poll interval. - * For now only 1 core poller type is supprted: ECORE_POLLER_CORE - * - * Example of @ref Ecore_Poller: - * @li @ref ecore_poller_example_c + * @addtogroup Ecore_Poller_Group * * @{ */ @@ -430,10 +416,6 @@ ecore_poller_del(Ecore_Poller *poller) return data; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_throttle.c b/legacy/ecore/src/lib/ecore/ecore_throttle.c index 4f8ae8d175..1f972ab655 100644 --- a/legacy/ecore/src/lib/ecore/ecore_throttle.c +++ b/legacy/ecore/src/lib/ecore/ecore_throttle.c @@ -10,12 +10,6 @@ static int throttle_val = 0; -/** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - /** * @addtogroup Ecore_Throttle_Group Ecore Throttle functions * @@ -92,10 +86,6 @@ ecore_throttle_get(void) return (double)throttle_val / 1000000.0; } -/** - * @} - */ - /** * @} */ diff --git a/legacy/ecore/src/lib/ecore/ecore_time.c b/legacy/ecore/src/lib/ecore/ecore_time.c index 2bd5fa68cc..fd24446b3b 100644 --- a/legacy/ecore/src/lib/ecore/ecore_time.c +++ b/legacy/ecore/src/lib/ecore/ecore_time.c @@ -29,13 +29,7 @@ static double _ecore_time_clock_conversion = 1e-9; double _ecore_time_loop_time = -1.0; /** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ - -/** - * @addtogroup Ecore_Time_Group Ecore Time functions + * @addtogroup Ecore_Time_Group * * @{ */ @@ -133,10 +127,6 @@ ecore_loop_time_get(void) * @} */ -/** - * @} - */ - /********************** Internal methods ********************************/ diff --git a/legacy/ecore/src/lib/ecore/ecore_timer.c b/legacy/ecore/src/lib/ecore/ecore_timer.c index d190c7a4e2..9aee32fbea 100644 --- a/legacy/ecore/src/lib/ecore/ecore_timer.c +++ b/legacy/ecore/src/lib/ecore/ecore_timer.c @@ -48,23 +48,9 @@ static Ecore_Timer *suspended = NULL; static double last_check = 0.0; static double precision = 10.0 / 1000000.0; -/** - * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions. - * - * @{ - */ /** - * @addtogroup Ecore_Time_Group Ecore Time functions - * - * Functions that deal with time. These functions include those that simply - * retrieve it in a given format, and those that create events based on it. - * - * The timer allows callbacks to be called at specific intervals. - * - * Examples with functions that deal with time: - * @li @ref ecore_time_functions_example_c - * @li @ref ecore_timer_example_c + * @addtogroup Ecore_Time_Group * * @{ */ @@ -459,10 +445,6 @@ ecore_timer_dump(void) #endif } -/** - * @} - */ - /** * @} */