efl/legacy/ecore/ecore.c.in

/** 
@file
@brief Ecore Library Public API Calls
 
These routines are used for Ecore Library interaction
*/

/**

@mainpage Ecore
@image latex ecore_big.eps width=5cm
@image html  ecore.png
@version 1.0.0
@author Carsten Haitzler <raster@rasterman.com>
@date 2000-2003













@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.

Here is an exmaple of a simple program and its basic event loop flow:

@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(int ev_type, void *ev, void *data)
{
  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.








@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 \
-lecore -lecore_evas -lecore_x -lecore_fb -lecore_job \
`evas-config --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-job
make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim












@section tutorial Ecore Tutorial

You will find a more comprehensive @ref tut here, going through many examples
with tips and hints as to how best do some things.





@todo (1.0) Document API

*/

/** @page tut Ecore Tutorial

Here is a tutotial for using Ecore...

*/