summaryrefslogtreecommitdiff
path: root/legacy/ecore/doc/ecore.dox.in
blob: 0d605a60dd0321913f1c758f83383b6fa87005de (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
/** 
@brief Ecore Library Public API Calls
 
These routines are used for Ecore Library interaction
*/

/**

@mainpage Ecore

@image html  e.png

@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>
@author Ibukun Olumuyiwa <ibukun@computer.org>
@author Yuri <da2001@hotmail.ru>
@author Nicholas Curran <quasar@bigblue.net.au>
@author Howell Tam <pigeon@pigeond.net>
@author Nathan Ingersoll <rbdpngn@users.sourceforge.net>
@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>
@author Samsung Electronics
@author Samsung SAIT
@author Nicolas Aguirre <aguirre.nicolas@gmail.com>
@author Brett Nash <nash@nash.id.au>
@author Mike Blumenkrantz <mike@zentific.com>
@author Leif Middelschulte <leif.middelschulte@gmail.com>
@author Mike McCormack <mj.mccormack@samsung.com>
@author Sangho Park <gouache95@gmail.com>
@author Jihoon Kim <jihoon48.kim@samsung.com> <imfine98@gmail.com>
@author Daniel Juyung Seo <seojuyung2@gmail.com> <juyung.seo@samsung.com>
@date 2000-2011

@section intro Introduction

Ecore is a library of convenience functions.

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
@li @ref Ecore_FB_Group
@li @link Ecore_Ipc.h    Ecore_IPC - Inter Process Communication functions. @endlink
@li @link Ecore_X.h      Ecore_X - X Windows System wrapper. @endlink
@li @ref Ecore_Win32_Group
@li @ref Ecore_WinCE_Group

@section compiling How to compile using Ecore?
pkgconfig (.pc) files are installed for every ecore module.
Thus, to compile using any of them, you can use something like the following:

@verbatim
gcc *.c $(pkg-config ecore ecore-$x ecore-$y [...] --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 \
--enable-ecore-ipc
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.

Here is an example 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(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.

*/

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

/**
@example ecore_args_example.c
Shows how to set and retrieve the program arguments.
*/

/**
@example ecore_event_handler_example.c
Shows how to use event handlers.
*/

/**
@example ecore_fd_handler_example.c
Shows how to use fd handlers.
*/

/**
@example ecore_timer_example.c
Demonstrates use of the ecore_timer.
*/

/*
@example ecore_config_basic_example.c
Provides an example of how to use the basic configuration functions.
See the file Ecore_Config.h for the full list of available functions.
*/

/*
@example ecore_config_listener_example.c
Shows how to set up a listener to listen for configuration changes.
*/

/**
@example ecore_x_window_example.c
Shows the basics of using the X Windows system through Ecore functions.
*/