Ecore.h File Reference

The file that provides the program utility, main loop and timer functions. More...

Data Structures
struct	_Ecore_Event_Signal_User
	User signal event. More...
struct	_Ecore_Event_Signal_Hup
	Hup signal event. More...
struct	_Ecore_Event_Signal_Exit
	Exit request event. More...
struct	_Ecore_Event_Signal_Power
	Power event. More...
struct	_Ecore_Event_Signal_Realtime
	Realtime event. More...
struct	_Ecore_Exe_Event_Add
	Process add event. More...
struct	_Ecore_Exe_Event_Del
	Process exit event. More...
struct	_Ecore_Exe_Event_Data_Line
	< Lines from a child process More...
struct	_Ecore_Exe_Event_Data
	Data from a child process event. More...
Defines
#define	ECORE_CALLBACK_CANCEL EINA_FALSE
	Return value to remove a callback.
#define	ECORE_CALLBACK_RENEW EINA_TRUE
	Return value to keep a callback.
#define	ECORE_CALLBACK_PASS_ON EINA_TRUE
	Return value to pass event to next handler.
#define	ECORE_CALLBACK_DONE EINA_FALSE
	Return value to stop event handling.
#define	ECORE_EVENT_SIGNAL_USER 1
	User signal event.
#define	ECORE_EVENT_SIGNAL_HUP 2
	Hup signal event.
#define	ECORE_EVENT_SIGNAL_EXIT 3
	Exit signal event.
#define	ECORE_EVENT_SIGNAL_POWER 4
	Power signal event.
#define	ECORE_EVENT_SIGNAL_REALTIME 5
	Realtime signal event.
Typedefs
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_Job	Ecore_Job
	A job handle.
Enumerations
enum	_Ecore_Fd_Handler_Flags { ECORE_FD_READ = 1, ECORE_FD_WRITE = 2, ECORE_FD_ERROR = 4 }
enum	_Ecore_Exe_Flags { ECORE_EXE_PIPE_READ = 1, ECORE_EXE_PIPE_WRITE = 2, ECORE_EXE_PIPE_ERROR = 4, ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8, ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, ECORE_EXE_PIPE_AUTO = 32, ECORE_EXE_RESPAWN = 64, ECORE_EXE_USE_SH = 128, ECORE_EXE_NOT_LEADER = 256 }
enum	_Ecore_Exe_Win32_Priority { ECORE_EXE_WIN32_PRIORITY_IDLE, ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL, ECORE_EXE_WIN32_PRIORITY_NORMAL, ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL, ECORE_EXE_WIN32_PRIORITY_HIGH, ECORE_EXE_WIN32_PRIORITY_REALTIME }
enum	_Ecore_Poller_Type { ECORE_POLLER_CORE = 0 }
Functions
EAPI int	ecore_init (void)
	Set up connections, signal handlers, sockets etc.
EAPI int	ecore_shutdown (void)
	Shut down connections, signal handlers sockets etc.
EAPI void	ecore_app_args_set (int argc, const char **argv)
	Set up the programs command-line arguments.
EAPI void	ecore_app_args_get (int argc, char **argv)
	Return the programs stored command-line arguments.
EAPI void	ecore_app_restart (void)
	Restart the program executable with the command-line arguments stored.
EAPI Ecore_Event_Handler *	ecore_event_handler_add (int type, Eina_Bool(func)(void data, int type, void event), const void data)
	Add an event handler.
EAPI void *	ecore_event_handler_del (Ecore_Event_Handler *event_handler)
	Delete an event handler.
EAPI Ecore_Event *	ecore_event_add (int type, void ev, void(func_free)(void data, void ev), void *data)
	Add an event to the event queue.
EAPI void *	ecore_event_del (Ecore_Event *event)
	Delete an event from the queue.
EAPI int	ecore_event_type_new (void)
	Allocate a new event type id sensibly and return the new id.
EAPI Ecore_Event_Filter *	ecore_event_filter_add (void (func_start)(void data), Eina_Bool(func_filter)(void data, void loop_data, int type, void event), void(func_end)(void data, void loop_data), const void *data)
	Add a filter the current event queue.
EAPI void *	ecore_event_filter_del (Ecore_Event_Filter *ef)
	Delete an event filter.
EAPI int	ecore_event_current_type_get (void)
	Return the current event type being handled.
EAPI void *	ecore_event_current_event_get (void)
	Return the current event type pointer handled.
EAPI void	ecore_exe_run_priority_set (int pri)
	Sets the priority at which to launch processes.
EAPI int	ecore_exe_run_priority_get (void)
	Gets the priority at which to launch processes.
EAPI Ecore_Exe *	ecore_exe_run (const char exe_cmd, const void data)
	Spawns a child process.
EAPI Ecore_Exe *	ecore_exe_pipe_run (const char exe_cmd, Ecore_Exe_Flags flags, const void data)
	Spawns a child process with its stdin/out available for communication.
EAPI void	ecore_exe_callback_pre_free_set (Ecore_Exe exe, void(func)(void data, const Ecore_Exe exe))
	Defines a function to be called before really freeing the handle data.
EAPI Eina_Bool	ecore_exe_send (Ecore_Exe exe, const void data, int size)
	Sends data to the given child process which it recieves on stdin.
EAPI void	ecore_exe_close_stdin (Ecore_Exe *exe)
	The stdin of the given child process will close when the write buffer is empty.
EAPI void	ecore_exe_auto_limits_set (Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines)
	Sets the auto pipe limits for the given process handle.
EAPI Ecore_Exe_Event_Data *	ecore_exe_event_data_get (Ecore_Exe *exe, Ecore_Exe_Flags flags)
	Gets the auto pipe data for the given process handle.
EAPI void	ecore_exe_event_data_free (Ecore_Exe_Event_Data *data)
	Frees the given event data.
EAPI void *	ecore_exe_free (Ecore_Exe *exe)
	Frees the given process handle.
EAPI pid_t	ecore_exe_pid_get (const Ecore_Exe *exe)
	Retrieves the process ID of the given spawned process.
EAPI void	ecore_exe_tag_set (Ecore_Exe exe, const char tag)
	Sets the string tag for the given process handle.
EAPI const char *	ecore_exe_tag_get (const Ecore_Exe *exe)
	Retrieves the tag attached to the given process handle.
EAPI const char *	ecore_exe_cmd_get (const Ecore_Exe *exe)
	Retrieves the command of the given spawned process.
EAPI void *	ecore_exe_data_get (const Ecore_Exe *exe)
	Retrieves the data attached to the given process handle.
EAPI Ecore_Exe_Flags	ecore_exe_flags_get (const Ecore_Exe *exe)
	Retrieves the flags attached to the given process handle.
EAPI void	ecore_exe_pause (Ecore_Exe *exe)
	Pauses the given process by sending it a `SIGSTOP` signal.
EAPI void	ecore_exe_continue (Ecore_Exe *exe)
	Continues the given paused process by sending it a `SIGCONT` signal.
EAPI void	ecore_exe_interrupt (Ecore_Exe *exe)
	Sends the given spawned process a interrupt (`SIGINT`) signal.
EAPI void	ecore_exe_quit (Ecore_Exe *exe)
	Sends the given spawned process a quit (`SIGQUIT`) signal.
EAPI void	ecore_exe_terminate (Ecore_Exe *exe)
	Sends the given spawned process a terminate (`SIGTERM`) signal.
EAPI void	ecore_exe_kill (Ecore_Exe *exe)
	Kills the given spawned process by sending it a `SIGKILL` signal.
EAPI void	ecore_exe_signal (Ecore_Exe *exe, int num)
	Sends a `SIGUSR` signal to the given spawned process.
EAPI void	ecore_exe_hup (Ecore_Exe *exe)
	Sends a `SIGHUP` signal to the given spawned process.
EAPI Ecore_Idler *	ecore_idler_add (Eina_Bool(func)(void data), const void *data)
	Add an idler handler.
EAPI void *	ecore_idler_del (Ecore_Idler *idler)
	Delete an idler callback from the list to be executed.
EAPI Ecore_Idle_Enterer *	ecore_idle_enterer_add (Eina_Bool(func)(void data), const void *data)
	Add an idle enterer handler.
EAPI Ecore_Idle_Enterer *	ecore_idle_enterer_before_add (Eina_Bool(func)(void data), const void *data)
	Add an idle enterer handler at the start of the list so it gets called earlier than others.
EAPI void *	ecore_idle_enterer_del (Ecore_Idle_Enterer *idle_enterer)
	Delete an idle enterer callback.
EAPI Ecore_Idle_Exiter *	ecore_idle_exiter_add (Eina_Bool(func)(void data), const void *data)
	Add an idle exiter handler.
EAPI void *	ecore_idle_exiter_del (Ecore_Idle_Exiter *idle_exiter)
	Delete an idle exiter handler from the list to be run on exiting idle state.
EAPI void	ecore_main_loop_iterate (void)
	Runs a single iteration of the main loop to process everything on the queue.
EAPI void	ecore_main_loop_select_func_set (int(func)(int nfds, fd_set readfds, fd_set writefds, fd_set exceptfds, struct timeval *timeout))
	Sets the function to use when monitoring multiple file descriptors, and waiting until one of more of the file descriptors before ready for some class of I/O operation.
EAPI void *	ecore_main_loop_select_func_get (void)
	Gets the select function set by ecore_select_func_set(), or the native select function if none was set.
EAPI Eina_Bool	ecore_main_loop_glib_integrate (void)
	Request ecore to integrate GLib's main loop.
EAPI void	ecore_main_loop_glib_always_integrate_disable (void)
	Disable always integrating glib.
EAPI void	ecore_main_loop_begin (void)
	Runs the application main loop.
EAPI void	ecore_main_loop_quit (void)
	Quits the main loop once all the events currently on the queue have been processed.
EAPI Ecore_Fd_Handler *	ecore_main_fd_handler_add (int fd, Ecore_Fd_Handler_Flags flags, Eina_Bool(func)(void data, Ecore_Fd_Handler fd_handler), const void data, Eina_Bool(buf_func)(void buf_data, Ecore_Fd_Handler fd_handler), const void buf_data)
	Adds a callback for activity on the given file descriptor.
EAPI void *	ecore_main_fd_handler_del (Ecore_Fd_Handler *fd_handler)
	Deletes the given FD handler.
EAPI int	ecore_main_fd_handler_fd_get (Ecore_Fd_Handler *fd_handler)
	Retrieves the file descriptor that the given handler is handling.
EAPI int	ecore_main_fd_handler_active_get (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
	Return if read, write or error, or a combination thereof, is active on the file descriptor of the given FD handler.
EAPI void	ecore_main_fd_handler_active_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
	Set what active streams the given FD handler should be monitoring.
EAPI Ecore_Pipe *	ecore_pipe_add (void(handler)(void data, void buffer, unsigned int nbyte), const void data)
	Create two file descriptors (sockets on Windows).
EAPI void *	ecore_pipe_del (Ecore_Pipe *p)
	Free an Ecore_Pipe object created with ecore_pipe_add().
EAPI Eina_Bool	ecore_pipe_write (Ecore_Pipe p, const void buffer, unsigned int nbytes)
	Write on the file descriptor the data passed as parameter.
EAPI void	ecore_pipe_write_close (Ecore_Pipe *p)
	Close the write end of an Ecore_Pipe object created with ecore_pipe_add().
EAPI void	ecore_pipe_read_close (Ecore_Pipe *p)
	Close the read end of an Ecore_Pipe object created with ecore_pipe_add().
EAPI double	ecore_time_get (void)
	Retrieves the current system time as a floating point value in seconds.
EAPI double	ecore_loop_time_get (void)
	Retrieves the time at which the last loop stopped waiting for timeouts or events.
EAPI Ecore_Timer *	ecore_timer_add (double in, Eina_Bool(func)(void data), const void *data)
	Creates a timer to call the given function in the given period of time.
EAPI Ecore_Timer *	ecore_timer_loop_add (double in, Eina_Bool(func)(void data), const void *data)
	Creates a timer to call the given function in the given period of time.
EAPI void *	ecore_timer_del (Ecore_Timer *timer)
	Delete the specified timer from the timer list.
EAPI void	ecore_timer_interval_set (Ecore_Timer *timer, double in)
	Change the interval the timer ticks of.
EAPI double	ecore_timer_interval_get (Ecore_Timer *timer)
	Get the interval the timer ticks on.
EAPI void	ecore_timer_delay (Ecore_Timer *timer, double add)
	Add some delay for the next occurence of a timer.
EAPI double	ecore_timer_pending_get (Ecore_Timer *timer)
	Get the pending time regarding a timer.
EAPI double	ecore_timer_precision_get (void)
	Retrieves the current precision used by timer infrastructure.
EAPI void	ecore_timer_precision_set (double precision)
	Sets the precision to be used by timer infrastructure.
EAPI Ecore_Animator *	ecore_animator_add (Eina_Bool(func)(void data), const void *data)
	Add a animator to tick off at every animaton tick during main loop execution.
EAPI void *	ecore_animator_del (Ecore_Animator *animator)
	Delete the specified animator from the animator list.
EAPI void	ecore_animator_freeze (Ecore_Animator *animator)
	Suspend the specified animator.
EAPI void	ecore_animator_thaw (Ecore_Animator *animator)
	Restore execution of the specified animator.
EAPI void	ecore_animator_frametime_set (double frametime)
	Set the animator call interval in seconds.
EAPI double	ecore_animator_frametime_get (void)
	Get the animator call interval in seconds.
EAPI void	ecore_poller_poll_interval_set (Ecore_Poller_Type type, double poll_time)
	Sets the time between ticks (in seconds) for the given ticker clock.
EAPI double	ecore_poller_poll_interval_get (Ecore_Poller_Type type)
	Gets the time between ticks (in seconds) for the given ticker clock.
EAPI Eina_Bool	ecore_poller_poller_interval_set (Ecore_Poller *poller, int interval)
	Changes the polling interval rate of `poller`.
EAPI int	ecore_poller_poller_interval_get (Ecore_Poller *poller)
	Gets the polling interval rate of `poller`.
EAPI Ecore_Poller *	ecore_poller_add (Ecore_Poller_Type type, int interval, Eina_Bool(func)(void data), const void *data)
	Creates a poller to call the given function at a particular tick interval.
EAPI void *	ecore_poller_del (Ecore_Poller *poller)
	Delete the specified poller from the timer list.
EAPI Ecore_Job *	ecore_job_add (void(func)(void data), const void *data)
	Add a job to the event queue.
EAPI void *	ecore_job_del (Ecore_Job *job)
	Delete a queued job that has not yet been executed.
Variables
EAPI int	ECORE_EXE_EVENT_ADD
	A child process has been added.
EAPI int	ECORE_EXE_EVENT_DEL
	A child process has been deleted (it exited, naming consistant with the rest of ecore).
EAPI int	ECORE_EXE_EVENT_DATA
	Data from a child process.
EAPI int	ECORE_EXE_EVENT_ERROR
	Errors from a child process.

Detailed Description

The file that provides the program utility, main loop and timer functions.

This header provides the Ecore event handling loop. For more details, see Main Loop Functions.

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 File Event Handling Functions.

Time functions are covered in Ecore Time Functions.

There is also provision for callbacks for when the loop enters or exits an idle state. See Idle Handlers for more information.

Functions are also provided for spawning child processes using fork. See Process Spawning Functions and Spawned Process Signal Functions for more details.

Enumeration Type Documentation

enum _Ecore_Exe_Flags

Enumerator:

ECORE_EXE_PIPE_READ	Exe Pipe Read mask.
ECORE_EXE_PIPE_WRITE	Exe Pipe Write mask.
ECORE_EXE_PIPE_ERROR	Exe Pipe error mask.
ECORE_EXE_PIPE_READ_LINE_BUFFERED	Reads are buffered until a newline and delivered 1 event per line.
ECORE_EXE_PIPE_ERROR_LINE_BUFFERED	Errors are buffered until a newline and delivered 1 event per line.
ECORE_EXE_PIPE_AUTO	stdout and stderr are buffered automatically
ECORE_EXE_RESPAWN	FIXME: Exe is restarted if it dies.
ECORE_EXE_USE_SH	Use /bin/sh to run the command.
ECORE_EXE_NOT_LEADER	Do not use setsid() to have the executed process be its own session leader.

enum _Ecore_Exe_Win32_Priority

Enumerator:

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.

enum _Ecore_Fd_Handler_Flags

Enumerator:

ECORE_FD_READ	Fd Read mask.
ECORE_FD_WRITE	Fd Write mask.
ECORE_FD_ERROR	Fd Error mask.

enum _Ecore_Poller_Type

Enumerator:

ECORE_POLLER_CORE

The core poller interval.

Function Documentation

EAPI Ecore_Animator* ecore_animator_add	(	Eina_Bool()(void data)	func,
		const void *	data
	)

Add a animator to tick off at every animaton tick during main loop execution.

Parameters:

	func	The function to call when it ticks off
	data	The data to pass to the function

Returns:: A handle to the new animator

This function adds a animator and returns its handle on success and NULL on failure. The function func will be called every N seconds where N is the frametime interval set by ecore_animator_frametime_set(). The function will be passed the data pointer as its parameter.

When the animator 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.

References ecore_animator_add(), ecore_loop_time_get(), ecore_timer_delay(), and ecore_timer_loop_add().

Referenced by ecore_animator_add(), and ecore_init().

EAPI void* ecore_animator_del ( Ecore_Animator * animator )

Delete the specified animator from the animator list.

Parameters:

animator

The animator to delete

Returns:: The data pointer set for the animator

Delete the specified aqnimator 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 animator is invalid and should not be used again. It will not get called again after deletion.

References ecore_animator_del().

Referenced by ecore_animator_del().

EAPI double ecore_animator_frametime_get ( void )

Get the animator call interval in seconds.

Returns:: The time in second in between animator ticks.

this function retrieves the time inbetween animator ticks, in seconds.

References ecore_animator_frametime_get().

Referenced by ecore_animator_frametime_get().

EAPI void ecore_animator_frametime_set ( double frametime )

Set the animator call interval in seconds.

Parameters:

frametime

The time in seconds in between animator ticks.

This function sets the time interval (in seconds) inbetween animator ticks.

References ecore_animator_frametime_set(), ecore_timer_add(), and ecore_timer_del().

Referenced by ecore_animator_frametime_set().

EAPI void ecore_animator_freeze ( Ecore_Animator * animator )

Suspend the specified animator.

Parameters:

animator

The animator to delete

The specified animator will be temporarly removed from the set of animators that are executed during main loop execution.

References ecore_animator_freeze().

Referenced by ecore_animator_freeze().

EAPI void ecore_animator_thaw ( Ecore_Animator * animator )

Restore execution of the specified animator.

Parameters:

animator

The animator to delete

The specified animator will be put back in the set of animators that are executed during main loop execution.

References ecore_animator_thaw().

Referenced by ecore_animator_thaw().

EAPI void ecore_app_args_get	(	int *	argc,
		char ***	argv
	)

Return the programs stored command-line arguments.

Parameters:

	argc	A pointer to the return value to hold argc
	argv	A pointer to the return value to hold argv

When called, this funciton returns the arguments for the program stored by ecore_app_args_set(). The integer pointed to by argc will be filled, if the pointer is not NULL, and the string array pointer argv will be filled also if the pointer is not NULL. The values they are filled with will be the same set by ecore_app_args_set().

References ecore_app_args_get().

Referenced by ecore_app_args_get(), ecore_config_args_parse(), ecore_getopt_help(), ecore_getopt_parse(), and ecore_x_window_defaults_set().

EAPI void ecore_app_args_set	(	int	argc,
		const char **	argv
	)

Set up the programs command-line arguments.

Parameters:

	argc	The same as passed as argc to the programs main() function
	argv	The same as passed as argv to the programs main() function

A call to this function will store the programs command-line arguments for later use by ecore_app_restart() or ecore_app_args_get().

References ecore_app_args_set().

Referenced by ecore_app_args_set().

EAPI void ecore_app_restart ( void )

Restart the program executable with the command-line arguments stored.

This function will restart & re-execute this program in place of itself using the command-line arguments stored by ecore_app_args_set(). This is an easy way for a program to restart itself for cleanup purposes, configuration reasons or in the event of a crash.

References ecore_app_restart().

Referenced by ecore_app_restart().

EAPI Ecore_Event* ecore_event_add	(	int	type,
		void *	ev,
		void()(void data, void *ev)	func_free,
		void *	data
	)

Add an event to the event queue.

Parameters:

	type	The event type to add to the end of the event queue
	ev	The private data structure for this event type
	func_free	The function to be called to free this private structure
	data	The data pointer to be passed to the free function

Returns:: A Handle for that event

On success this function returns a handle to an event on the event queue, or NULL if it fails. If it succeeds, an event of type type will be added to the queue for processing by event handlers added by ecore_event_handler_add(). The ev parameter will be a pointer to the event private data that is specific to that event type. When the event is no longer needed, func_free will be called and passed the private structure pointer for cleaning up. If func_free is NULL, free() will be called with the private structure pointer. func_free is passed data as its data parameter.

References ecore_event_add().

Referenced by ecore_event_add(), ecore_exe_pipe_run(), ecore_imf_context_commit_event_add(), ecore_imf_context_delete_surrounding_event_add(), ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_preedit_end_event_add(), ecore_imf_context_preedit_start_event_add(), and ecore_job_add().

EAPI void* ecore_event_current_event_get ( void )

Return the current event type pointer handled.

Returns:: The current event pointer being handled if inside a handler callback

If the program is currently inside an Ecore event handler callback this will return the pointer of the current event being processed. If Ecore is not inside an event handler, NULL will be returned.

This is useful when certain Ecore modules such as Ecore_Evas "swallow" events and not all the original information is passed on. In special cases this extra information may be useful or needed and using this call can let the program access the event data if the type of the event is handled by the program.

References ecore_event_current_event_get().

Referenced by ecore_event_current_event_get().

EAPI int ecore_event_current_type_get ( void )

Return the current event type being handled.

Returns:: The current event type being handled if inside a handler callback

If the program is currently inside an Ecore event handler callback this will return the type of the current event being processed. If Ecore is not inside an event handler, ECORE_EVENT_NONE is returned.

This is useful when certain Ecore modules such as Ecore_Evas "swallow" events and not all the original information is passed on. In special cases this extra information may be useful or needed and using this call can let the program know if the event type being handled is one it wants to get more information about.

References ecore_event_current_type_get().

Referenced by ecore_event_current_type_get().

EAPI void* ecore_event_del ( Ecore_Event * event )

Delete an event from the queue.

Parameters:

event

The event handle to delete

Returns:: The data pointer originally set for the event free function

This deletes the event event from the event queue, and returns the data parameer originally set when adding it with ecore_event_add(). This does not immediately call the free function, and it may be called later on cleanup, and so if the free function depends on the data pointer to work, you should defer cleaning of this till the free function is called later.

References ecore_event_del().

Referenced by ecore_event_del(), and ecore_job_del().

EAPI Ecore_Event_Filter* ecore_event_filter_add	(	void ()(void *data)	func_start,
		Eina_Bool()(void data, void loop_data, int type, void event)	func_filter,
		void()(void data, void *loop_data)	func_end,
		const void *	data
	)

Add a filter the current event queue.

Parameters:

	func_start	Function to call just before filtering and return data
	func_filter	Function to call on each event
	func_end	Function to call after the queu has been filtered
	data	Data to pass to the filter functions

Returns:: A filter handle

This adds a filter to call callbacks to loop through the event queue and filter events out of the queue. On failure NULL is returned. On success a Filter handle is returned. Filters are called on the queue just before Event handler processing to try and remove redundant events. Just as processing starts func_start is called and passed the data pointer. This function returns a pointer that is used as loop_data that is now passed to func_filter as loop_data. func_filter is also passed data and the event type and private event structure. If this callback returns 0, the event is removed from the queue. If it returns 1, the event is kept. When processing is finished func_end is called and is passed the loop_data and data pointer to clean up.

References ecore_event_filter_add().

Referenced by ecore_event_filter_add(), and ecore_x_init().

EAPI void* ecore_event_filter_del ( Ecore_Event_Filter * ef )

Delete an event filter.

Parameters:

ef

The event filter handle

Returns:: The data set for the filter

Delete a filter that has been added by its ef handle. On success this will return the data pointer set when this filter was added. On failure NULL is returned.

References ecore_event_filter_del().

Referenced by ecore_event_filter_del().

EAPI Ecore_Event_Handler* ecore_event_handler_add	(	int	type,
		Eina_Bool()(void data, int type, void *event)	func,
		const void *	data
	)

Add an event handler.

Parameters:

	type	The type of the event this handler will get called for
	func	The function to call when the event is found in the queue
	data	A data pointer to pass to the called function `func`

Returns:: A new Event handler, or NULL on failure

Add an event handler to the list of handlers. This will, on success, return a handle to the event handler object that was created, that can be used later to remove the handler using ecore_event_handler_del(). The type parameter is the integer of the event type that will trigger this callback to be called. The callback func is called when this event is processed and will be passed the event type, a pointer to the private event structure that is specific to that event type, and a data pointer that is provided in this call as the data parameter.

When the callback func is called, it must return 1 or 0. If it returns 1 (or ECORE_CALLBACK_RENEW), It will keep being called as per normal, for each handler set up for that event type. If it returns 0 (or ECORE_CALLBACK_CANCEL), it will cease processing handlers for that particular event, so all handler set to handle that event type that have not already been called, will not be.

References ecore_event_handler_add().

Referenced by ecore_event_handler_add(), and ecore_ipc_init().

EAPI void* ecore_event_handler_del ( Ecore_Event_Handler * event_handler )

Delete an event handler.

Parameters:

event_handler

Event handler handle to delete

Returns:: Data passed to handler

Delete a specified event handler from the handler list. On success this will delete the event handler and return the pointer passed as data when the handler was added by ecore_event_handler_add(). On failure NULL will be returned. Once a handler is deleted it will no longer be called.

References ecore_event_handler_del().

Referenced by ecore_event_handler_del(), and ecore_ipc_shutdown().

EAPI int ecore_event_type_new ( void )

Allocate a new event type id sensibly and return the new id.

Returns:: A new event type id.

This function allocates a new event type id and returns it. Once an event type has been allocated it can never be de-allocated during the life of the program. There is no guarantee of the contents of this event ID, or how it is calculated, except that the ID will be unique to the current instance of the process.

References ecore_event_type_new().

Referenced by ecore_con_init(), ecore_con_url_init(), ecore_event_type_new(), ecore_fb_init(), ecore_imf_init(), ecore_ipc_init(), and ecore_x_init().

EAPI void ecore_exe_callback_pre_free_set	(	Ecore_Exe *	exe,
		void()(void data, const Ecore_Exe *exe)	func
	)

Defines a function to be called before really freeing the handle data.

This might be useful for language bindings such as Python and Perl that need to deallocate wrappers associated with this handle.

This handle should never be modified by this call. It should be considered informative only. All getters are valid when the given function is called back.

Parameters:

	exe	The child process to attach the pre_free function.
	func	The function to call before exe is freed.

References ecore_exe_callback_pre_free_set().

Referenced by ecore_exe_callback_pre_free_set().

EAPI int ecore_init ( void )

Set up connections, signal handlers, sockets etc.

Returns:: 1 or greater on success, 0 otherwise

This function sets up all singal handlers and the basic event loop. If it succeeds, 1 will be returned, otherwise 0 will be returned.

 #include <Ecore.h>

 int main(int argc, char **argv)
 {
   if (!ecore_init())
   {
     printf("ERROR: Cannot init Ecore!\n");
     return -1;
   }
   ecore_main_loop_begin();
   ecore_shutdown();
 }

References ecore_animator_add(), ecore_main_loop_glib_integrate(), and ecore_time_get().

EAPI void ecore_main_loop_glib_always_integrate_disable ( void )

Disable always integrating glib.

If ecore is compiled with --enable-glib-integration-always (to always call ecore_main_loop_glib_integrate() when ecore_init() is called), then calling this before calling ecore_init() will disable the integration. This is for apps that explicitly do not want this to happen for whatever reasons they may have.

References ecore_main_loop_glib_always_integrate_disable().

Referenced by ecore_main_loop_glib_always_integrate_disable().

EAPI Eina_Bool ecore_main_loop_glib_integrate ( void )

Request ecore to integrate GLib's main loop.

This will add a small overhead during every main loop interaction by checking glib's default main context (used by its main loop). If it have events to be checked (timers, file descriptors or idlers), then these will be polled alongside with Ecore's own events, then dispatched before Ecore's. This is done by calling ecore_main_loop_select_func_set().

This will cooperate with previously set ecore_main_loop_select_func_set() by calling the old function. Similarly, if you want to override ecore_main_loop_select_func_set() after main loop is integrated, call the new select function set by this call (get it by calling ecore_main_loop_select_func_get() right after ecore_main_loop_glib_integrate()).

This is useful to use GMainLoop libraries, like GTK, GUPnP, LibSoup, GConf and more. Adobe Flash plugin and other plugins systems depend on this as well.

Once initialized/integrated, it will be valid until Ecore is completely shut down.

Note:: this is only available if Ecore was compiled with GLib support.

Returns:: EINA_TRUE on success of EINA_FALSE if it failed, likely no GLib support in Ecore.

References ecore_main_loop_glib_integrate(), ecore_main_loop_select_func_get(), and ecore_main_loop_select_func_set().

Referenced by ecore_init(), and ecore_main_loop_glib_integrate().

EAPI Ecore_Poller* ecore_poller_add	(	Ecore_Poller_Type type	__UNUSED__,
		int	interval,
		Eina_Bool()(void data)	func,
		const void *	data
	)

Creates a poller to call the given function at a particular tick interval.

Parameters:

	type	The ticker type to attach the poller to
	interval	The poll interval
	func	The given function. If `func` returns 1, the poller is rescheduled for the next tick interval.
	data	Data to pass to `func` when it is called.

Returns:: A poller object on success. NULL on failure.

This function adds a poller callback that is to be called regularly along with all other poller callbacks so the pollers are synchronized with all other pollers running off the same poller type and at the same tick interval. This should be used for polling things when polling is desired or required, and you do not have specific requirements on the exact times to poll and want to avoid extra process wakeups for polling. This will save power as the CPU has more of a chance to go into a low power state the longer it is asleep for, so this should be used if you are at all power conscious.

The type parameter defines the poller tick type (there is a virtual clock ticking all the time - though ecore avoids making it tick when there will not be any work to do at that tick point). There is only one ticker at the moment - that is ECORE_POLLER_CORE. This is here for future expansion if multiple clocks with different frequencies are really required. The default time between ticks for the ECORE_POLLER_CORE ticker is 0.125 seconds.

The interval is the number of ticker ticks that will pass by in between invocations of the func callback. This must be between 1 and 32768 inclusive, and must be a power of 2 (i.e. 1, 2, 4, 8, 16, ... 16384, 32768). If it is 1, then the function will be called every tick. if it is 2, then it will be called every 2nd tick, if it is 8, then every 8th tick etc. Exactly which tick is undefined, as only the interval between calls can be defined. Ecore will endeavour to keep pollers synchronised and to call as many in 1 wakeup event as possible.

This function adds a poller and returns its handle on success and NULL on failure. The function func will be called at tick intervals described above. The function will be passed the data pointer as its parameter.

When the poller func is called, it must return a value of either 1 (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL). If it returns 1, it will be called again at the next tick, or if it returns 0 it will be deleted automatically making any references/handles for it invalid.

References ecore_poller_add().

Referenced by ecore_poller_add().

EAPI void* ecore_poller_del ( Ecore_Poller * poller )

Delete the specified poller from the timer list.

Parameters:

poller

The poller to delete.

Returns:: The data pointer set for the timer when ecore_poller_add was called. NULL is returned if the function is unsuccessful.

Note: poller must be a valid handle. If the poller function has already returned 0, the handle is no longer valid (and does not need to be delete).

References ecore_poller_del().

Referenced by ecore_poller_del().

EAPI double ecore_poller_poll_interval_get ( Ecore_Poller_Type type __UNUSED__ )

Gets the time between ticks (in seconds) for the given ticker clock.

Parameters:

type

The ticker type to query

Returns:: The time in seconds between ticks of the ticker clock

This will get the time between ticks of the specifider ticker clock.

References ecore_poller_poll_interval_get().

Referenced by ecore_poller_poll_interval_get().

EAPI void ecore_poller_poll_interval_set	(	Ecore_Poller_Type type	__UNUSED__,
		double	poll_time
	)

Sets the time between ticks (in seconds) for the given ticker clock.

Parameters:

	type	The ticker type to adjust
	poll_time	The time (in seconds) between ticks of the clock

This will adjust the time between ticks of the given ticker type defined by type to the time period defined by poll_time.

References ecore_poller_poll_interval_set().

Referenced by ecore_poller_poll_interval_set().

EAPI int ecore_poller_poller_interval_get ( Ecore_Poller * poller )

Gets the polling interval rate of poller.

Parameters:

poller

The Ecore_Poller to change the interval of

Returns:: Returns the interval, in ticks, that poller polls at

This returns a poller's polling interval, or 0 on error.

References ecore_poller_poller_interval_get().

Referenced by ecore_poller_poller_interval_get().

EAPI Eina_Bool ecore_poller_poller_interval_set	(	Ecore_Poller *	poller,
		int	interval
	)

Changes the polling interval rate of poller.

Parameters:

	poller	The Ecore_Poller to change the interval of
	interval	The tick interval to set; must be a power of 2 but <= 32768

Returns:: Returns true on success, false on failure

This allows the changing of a poller's polling interval. It is useful when you want to alter a poll rate without deleting and re-creating a poller.

References ecore_poller_poller_interval_set().

Referenced by ecore_poller_poller_interval_set().

EAPI int ecore_shutdown ( void )

Shut down connections, signal handlers sockets etc.

This function shuts down all things set up in ecore_init() and cleans up all event queues, handlers, filters, timers, idlers, idle enterers/exiters etc. set up after ecore_init() was called.

Do not call this function from any callback that may be called from the main loop, as the main loop will then fall over and not function properly.

EAPI double ecore_timer_precision_get ( void )

Retrieves the current precision used by timer infrastructure.

See also:: ecore_timer_precision_set()

References ecore_timer_precision_get().

Referenced by ecore_timer_precision_get().

EAPI void ecore_timer_precision_set ( double value )

Sets the precision to be used by timer infrastructure.

When system calculates time to expire the next timer we'll be able to delay the timer by the given amount so more timers will fit in the same dispatch, waking up the system less often and thus being able to save power.

Be aware that kernel may delay delivery even further, these delays are always possible due other tasks having higher priorities or other scheduler policies.

Example: We have 2 timers, one that expires in a 2.0s and another that expires in 2.1s, if precision is 0.1s, then the Ecore will request for the next expire to happen in 2.1s and not 2.0s and another one of 0.1 as it would before.

Note:: Ecore is smart enough to see if there are timers in the precision range, if it does not, in our example if no second timer in (T + precision) existed, then it would use the minimum timeout.

Parameters:

value

allowed introduced timeout delay, in seconds.

References ecore_timer_precision_set().

Referenced by ecore_timer_precision_set().