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
}
-/**
- * @}
- */
-
/**
* @}
*/