2009-01-11 02:27:01 -08:00
|
|
|
/**
|
|
|
|
@brief Ecore Library Public API Calls
|
|
|
|
|
|
|
|
These routines are used for Ecore Library interaction
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
|
|
@mainpage Ecore
|
|
|
|
|
2009-09-28 02:13:23 -07:00
|
|
|
@image html e.png
|
2009-01-11 02:27:01 -08:00
|
|
|
|
|
|
|
@version @PACKAGE_VERSION@
|
|
|
|
@author Carsten Haitzler <raster\@rasterman.com>
|
|
|
|
@author Tom Gilbert <tom\@linuxbrit.co.uk>
|
|
|
|
@author Burra <burra\@colorado.edu>
|
|
|
|
@author Chris Ross <chris\@darkrock.co.uk>
|
|
|
|
@author Term <term\@twistedpath.org>
|
|
|
|
@author Tilman Sauerbeck <tilman\@code-monkey.de>
|
2010-09-20 13:04:05 -07:00
|
|
|
@author Ibukun Olumuyiwa <ibukun\@computer.org>
|
|
|
|
@author Yuri <da2001\@hotmail.ru>
|
|
|
|
@author Nicholas Curran <quasar\@bigblue.net.au>
|
|
|
|
@author Howell Tam <pigeon\@pigeond.net>
|
2009-01-11 02:27:01 -08:00
|
|
|
@author Nathan Ingersoll <rbdpngn\@users.sourceforge.net>
|
2010-09-20 13:04:05 -07:00
|
|
|
@author Andrew Elcock <andy\@elcock.org>
|
|
|
|
@author Kim Woelders <kim\@woelders.dk>
|
|
|
|
@author Sebastian Dransfeld <sebastid\@tango.flipp.net>
|
|
|
|
@author Simon Poole <simon.armlinux\@themalago.net>
|
|
|
|
@author Jorge Luis Zapata Muga <jorgeluis.zapata\@gmail.com>
|
|
|
|
@author dan sinclair <zero\@everburning.com>
|
|
|
|
@author Michael 'Mickey' Lauer <mickey\@tm.informatik.uni-frankfurt.de>
|
|
|
|
@author David 'onefang' Seikel <onefang\@gmail.com>
|
|
|
|
@author Hisham 'CodeWarrior' Mardam Bey <hisham\@hisham.cc>
|
|
|
|
@author Brian 'rephorm' Mattern <rephorm\@rephorm.com>
|
|
|
|
@author Tim Horton <hortont424\@gmail.com>
|
|
|
|
@author Arnaud de Turckheim 'quarium' <quarium\@gmail.com>
|
|
|
|
@author Matt Barclay <mbarclay\@gmail.com>
|
|
|
|
@author Peter Wehrfritz <peter.wehrfritz\@web.de>
|
|
|
|
@author Albin "Lutin" Tonnerre <albin.tonnerre\@gmail.com>
|
|
|
|
@author Vincent Torri <vincent.torri\@gmail.com>
|
|
|
|
@author Lars Munch <lars\@segv.dk>
|
|
|
|
@author Andre Dieb <andre.dieb\@gmail.com>
|
|
|
|
@author Mathieu Taillefumier <mathieu.taillefumier\@free.fr>
|
|
|
|
@author Rui Miguel Silva Seabra <rms\@1407.org>
|
2010-09-20 13:33:50 -07:00
|
|
|
@author Saumsung Electronics
|
|
|
|
@author Samsung SAIT
|
2010-09-20 13:04:05 -07:00
|
|
|
@author Nicolas Aguirre <aguirre.nicolas\@gmail.com>
|
|
|
|
@author Brett Nash <nash\@nash.id.au>
|
|
|
|
@author Mike Blumenkrantz <mike\@zentific.com>
|
|
|
|
@date 2000-2010
|
2009-01-11 02:27:01 -08:00
|
|
|
|
|
|
|
@section intro Introduction
|
|
|
|
|
|
|
|
Ecore is a library of convenience functions.
|
|
|
|
|
|
|
|
The Ecore library provides the following modules:
|
2010-10-17 00:03:28 -07:00
|
|
|
@li @ref Ecore_Group
|
2010-09-20 23:49:22 -07:00
|
|
|
@li @ref Ecore_Con_Group
|
2009-01-11 02:27:01 -08:00
|
|
|
@li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink
|
2010-10-12 00:55:24 -07:00
|
|
|
@li @ref Ecore_FB_Group
|
2009-01-11 02:27:01 -08:00
|
|
|
@li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink
|
|
|
|
@li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
|
2010-09-23 11:53:25 -07:00
|
|
|
@li @ref Ecore_Win32_Group
|
|
|
|
@li @ref Ecore_WinCE_Group
|
2009-01-11 02:27:01 -08:00
|
|
|
|
|
|
|
@section compiling How to compile using Ecore?
|
|
|
|
|
|
|
|
This section has to be documented. Below is just a quick line to handle all
|
|
|
|
Ecore modules at once.
|
|
|
|
|
|
|
|
@verbatim
|
|
|
|
gcc *.c \
|
|
|
|
-I/usr/local/include -I/usr/X11R6/include \
|
|
|
|
-L/usr/local/lib -L/usr/X11R6/lib \
|
2010-03-08 00:34:18 -08:00
|
|
|
-lecore -lecore_evas -lecore_x -lecore_fb \
|
2009-01-11 02:27:01 -08:00
|
|
|
`pkg-config evas --cflags --libs`
|
|
|
|
@endverbatim
|
|
|
|
|
|
|
|
@section install How is it installed?
|
|
|
|
|
|
|
|
Suggested configure options for evas for a Linux desktop X display:
|
|
|
|
|
|
|
|
@verbatim
|
|
|
|
./configure \
|
|
|
|
--enable-ecore-x \
|
|
|
|
--enable-ecore-fb \
|
|
|
|
--enable-ecore-evas \
|
|
|
|
--enable-ecore-evas-gl \
|
|
|
|
--enable-ecore-con \
|
2010-03-08 00:21:25 -08:00
|
|
|
--enable-ecore-ipc
|
2009-01-11 02:27:01 -08:00
|
|
|
make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
|
|
|
|
@endverbatim
|
|
|
|
|
|
|
|
@todo (1.0) Document API
|
|
|
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
/*
|
|
|
|
@page Ecore_Main_Loop_Page The Ecore Main Loop
|
|
|
|
|
|
|
|
@section intro What is Ecore?
|
|
|
|
|
|
|
|
Ecore is a clean and tiny event loop library with many modules to do lots of
|
|
|
|
convenient things for a programmer, to save time and effort.
|
|
|
|
|
|
|
|
It's small and lean, designed to work on embedded systems all the way to
|
|
|
|
large and powerful multi-cpu workstations. It serialises all system signals,
|
|
|
|
events etc. into a single event queue, that is easily processed without
|
|
|
|
needing to worry about concurrency. A properly written, event-driven program
|
|
|
|
using this kind of programming doesn't need threads, nor has to worry about
|
|
|
|
concurrency. It turns a program into a state machine, and makes it very
|
|
|
|
robust and easy to follow.
|
|
|
|
|
|
|
|
Ecore gives you other handy primitives, such as timers to tick over for you
|
|
|
|
and call specified functions at particular times so the programmer can use
|
|
|
|
this to do things, like animate, or time out on connections or tasks that take
|
|
|
|
too long etc.
|
|
|
|
|
|
|
|
Idle handlers are provided too, as well as calls on entering an idle state
|
|
|
|
(often a very good time to update the state of the program). All events that
|
|
|
|
enter the system are passed to specific callback functions that the program
|
|
|
|
sets up to handle those events. Handling them is simple and other Ecore
|
|
|
|
modules produce more events on the queue, coming from other sources such as
|
|
|
|
file descriptors etc.
|
|
|
|
|
|
|
|
Ecore also lets you have functions called when file descriptors become active
|
|
|
|
for reading or writing, allowing for streamlined, non-blocking IO.
|
|
|
|
|
2010-09-08 04:23:42 -07:00
|
|
|
Here is an example of a simple program and its basic event loop flow:
|
2009-01-11 02:27:01 -08:00
|
|
|
|
|
|
|
@image html prog_flow.png
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@section work How does Ecore work?
|
|
|
|
|
|
|
|
Ecore is very easy to learn and use. All the function calls are designed to
|
|
|
|
be easy to remember, explicit in describing what they do, and heavily
|
|
|
|
name-spaced. Ecore programs can start and be very simple.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
@code
|
|
|
|
#include <Ecore.h>
|
|
|
|
|
|
|
|
int main(int argc, const char **argv)
|
|
|
|
{
|
|
|
|
ecore_init();
|
|
|
|
ecore_app_args_set(argc, argv);
|
|
|
|
ecore_main_loop_begin();
|
|
|
|
ecore_shutdown();
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
@endcode
|
|
|
|
|
|
|
|
This program is very simple and does't check for errors, but it does start up
|
|
|
|
and begin a main loop waiting for events or timers to tick off. This program
|
|
|
|
doesn't set up any, but now we can expand on this simple program a little
|
|
|
|
more by adding some event handlers and timers.
|
|
|
|
|
|
|
|
@code
|
|
|
|
#include <Ecore.h>
|
|
|
|
|
|
|
|
Ecore_Timer *timer1 = NULL;
|
|
|
|
Ecore_Event_Handler *handler1 = NULL;
|
|
|
|
double start_time = 0.0;
|
|
|
|
|
|
|
|
int timer_func(void *data)
|
|
|
|
{
|
|
|
|
printf("Tick timer. Sec: %3.2f\n", ecore_time_get() - start_time);
|
|
|
|
return 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
int exit_func(void *data, int ev_type, void *ev)
|
|
|
|
{
|
|
|
|
Ecore_Event_Signal_Exit *e;
|
|
|
|
|
|
|
|
e = (Ecore_Event_Signal_Exit *)ev;
|
|
|
|
if (e->interrupt) printf("Exit: interrupt\n");
|
|
|
|
else if (e->quit) printf("Exit: quit\n");
|
|
|
|
else if (e->terminate) printf("Exit: terminate\n");
|
|
|
|
ecore_main_loop_quit();
|
|
|
|
return 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
int main(int argc, const char **argv)
|
|
|
|
{
|
|
|
|
ecore_init();
|
|
|
|
ecore_app_args_set(argc, argv);
|
|
|
|
start_time = ecore_time_get();
|
|
|
|
handler1 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, exit_func, NULL);
|
|
|
|
timer1 = ecore_timer_add(0.5, timer_func, NULL);
|
|
|
|
ecore_main_loop_begin();
|
|
|
|
ecore_shutdown();
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
@endcode
|
|
|
|
|
|
|
|
In the previous example, we initialize our application and get the time at
|
|
|
|
which our program has started so we can calculate an offset. We set
|
|
|
|
up a timer to tick off in 0.5 seconds, and since it returns 1, will
|
|
|
|
keep ticking off every 0.5 seconds until it returns 0, or is deleted
|
|
|
|
by hand. An event handler is set up to call a function - exit_func(),
|
|
|
|
whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
|
|
|
|
on the command line will cause such an event to happen). If this event
|
|
|
|
occurs it tells you what kind of exit signal was received, and asks
|
|
|
|
the main loop to quit when it is finished by calling
|
|
|
|
ecore_main_loop_quit().
|
|
|
|
|
|
|
|
The handles returned by ecore_timer_add() and ecore_event_handler_add() are
|
|
|
|
only stored here as an example. If you don't need to address the timer or
|
|
|
|
event handler again you don't need to store the result, so just call the
|
|
|
|
function, and don't assign the result to any variable.
|
|
|
|
|
|
|
|
This program looks slightly more complex than needed to do these simple
|
|
|
|
things, but in principle, programs don't get any more complex. You add more
|
|
|
|
event handlers, for more events, will have more timers and such, BUT it all
|
|
|
|
follows the same principles as shown in this example.
|
|
|
|
|
|
|
|
*/
|
|
|
|
|
2010-09-20 13:33:50 -07:00
|
|
|
/*
|
2009-01-11 02:27:01 -08:00
|
|
|
@page Ecore_Config_Page The Enlightened Property Library
|
|
|
|
|
|
|
|
The Enlightened Property Library (Ecore_Config) is an adbstraction
|
|
|
|
from the complexities of writing your own configuration. It provides
|
|
|
|
many features using the Enlightenment 17 development libraries.
|
|
|
|
|
|
|
|
To use the library, you:
|
|
|
|
@li Set the default values of your properties.
|
|
|
|
@li Load the configuration from a file. You must set the default values
|
|
|
|
first, so that the library knows the correct type of each argument.
|
|
|
|
|
|
|
|
The following examples show how to use the Enlightened Property Library:
|
|
|
|
@li @link config_basic_example.c config_basic_example.c @endlink
|
|
|
|
@li @link config_listener_example.c config_listener_example.c @endlink
|
|
|
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
@page X_Window_System_Page X Window System
|
|
|
|
|
|
|
|
The Ecore library includes a wrapper for handling the X window system.
|
|
|
|
This page briefly explains what the X window system is and various terms
|
|
|
|
that are used.
|
|
|
|
*/
|
|
|
|
|
|
|
|
// EXAMPLES
|
|
|
|
|
|
|
|
/**
|
2010-09-20 13:33:50 -07:00
|
|
|
@example ecore_args_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Shows how to set and retrieve the program arguments.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
2010-09-20 13:33:50 -07:00
|
|
|
@example ecore_event_handler_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Shows how to use event handlers.
|
|
|
|
*/
|
|
|
|
|
2010-09-29 12:12:43 -07:00
|
|
|
/**
|
|
|
|
@example ecore_fd_handler_example.c
|
|
|
|
Shows how to use fd handlers.
|
|
|
|
*/
|
|
|
|
|
2009-01-11 02:27:01 -08:00
|
|
|
/**
|
2010-09-20 13:33:50 -07:00
|
|
|
@example ecore_timer_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Demonstrates use of the ecore_timer.
|
|
|
|
*/
|
|
|
|
|
2010-09-20 13:33:50 -07:00
|
|
|
/*
|
|
|
|
@example ecore_config_basic_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Provides an example of how to use the basic configuration functions.
|
|
|
|
See the file Ecore_Config.h for the full list of available functions.
|
|
|
|
*/
|
|
|
|
|
2010-09-20 13:33:50 -07:00
|
|
|
/*
|
|
|
|
@example ecore_config_listener_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Shows how to set up a listener to listen for configuration changes.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
2010-09-20 13:33:50 -07:00
|
|
|
@example ecore_x_window_example.c
|
2009-01-11 02:27:01 -08:00
|
|
|
Shows the basics of using the X Windows system through Ecore functions.
|
|
|
|
*/
|