2 @brief Ecore Library Public API Calls
4 These routines are used for Ecore Library interaction
13 @version @PACKAGE_VERSION@
14 @author Carsten Haitzler <raster\@rasterman.com>
15 @author Tom Gilbert <tom\@linuxbrit.co.uk>
16 @author Burra <burra\@colorado.edu>
17 @author Chris Ross <chris\@darkrock.co.uk>
18 @author Term <term\@twistedpath.org>
19 @author Tilman Sauerbeck <tilman\@code-monkey.de>
20 @author Nathan Ingersoll <rbdpngn\@users.sourceforge.net>
23 @section intro Introduction
25 Ecore is a library of convenience functions.
27 The Ecore library provides the following modules:
28 @li @link Ecore.h Ecore - Main Loop and Job Functions. @endlink
29 @li @link Ecore_Con.h Ecore_Con - Connection functions. @endlink
30 @li @link Ecore_Config.h Ecore_Config - Configuration functions. @endlink
31 @li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink
32 @li @link Ecore_Fb.h Ecore_FB - Frame buffer convenience functions. @endlink
33 @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink
34 @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
36 @section compiling How to compile using Ecore?
38 This section has to be documented. Below is just a quick line to handle all
39 Ecore modules at once.
43 -I/usr/local/include -I/usr/X11R6/include \
44 -L/usr/local/lib -L/usr/X11R6/lib \
45 -lecore -lecore_evas -lecore_x -lecore_fb \
46 `pkg-config evas --cflags --libs`
49 @section install How is it installed?
51 Suggested configure options for evas for a Linux desktop X display:
58 --enable-ecore-evas-gl \
61 make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
64 @todo (1.0) Document API
69 @page Ecore_Main_Loop_Page The Ecore Main Loop
71 @section intro What is Ecore?
73 Ecore is a clean and tiny event loop library with many modules to do lots of
74 convenient things for a programmer, to save time and effort.
76 It's small and lean, designed to work on embedded systems all the way to
77 large and powerful multi-cpu workstations. It serialises all system signals,
78 events etc. into a single event queue, that is easily processed without
79 needing to worry about concurrency. A properly written, event-driven program
80 using this kind of programming doesn't need threads, nor has to worry about
81 concurrency. It turns a program into a state machine, and makes it very
82 robust and easy to follow.
84 Ecore gives you other handy primitives, such as timers to tick over for you
85 and call specified functions at particular times so the programmer can use
86 this to do things, like animate, or time out on connections or tasks that take
89 Idle handlers are provided too, as well as calls on entering an idle state
90 (often a very good time to update the state of the program). All events that
91 enter the system are passed to specific callback functions that the program
92 sets up to handle those events. Handling them is simple and other Ecore
93 modules produce more events on the queue, coming from other sources such as
96 Ecore also lets you have functions called when file descriptors become active
97 for reading or writing, allowing for streamlined, non-blocking IO.
99 Here is an exmaple of a simple program and its basic event loop flow:
101 @image html prog_flow.png
105 @section work How does Ecore work?
107 Ecore is very easy to learn and use. All the function calls are designed to
108 be easy to remember, explicit in describing what they do, and heavily
109 name-spaced. Ecore programs can start and be very simple.
116 int main(int argc, const char **argv)
119 ecore_app_args_set(argc, argv);
120 ecore_main_loop_begin();
126 This program is very simple and does't check for errors, but it does start up
127 and begin a main loop waiting for events or timers to tick off. This program
128 doesn't set up any, but now we can expand on this simple program a little
129 more by adding some event handlers and timers.
134 Ecore_Timer *timer1 = NULL;
135 Ecore_Event_Handler *handler1 = NULL;
136 double start_time = 0.0;
138 int timer_func(void *data)
140 printf("Tick timer. Sec: %3.2f\n", ecore_time_get() - start_time);
144 int exit_func(void *data, int ev_type, void *ev)
146 Ecore_Event_Signal_Exit *e;
148 e = (Ecore_Event_Signal_Exit *)ev;
149 if (e->interrupt) printf("Exit: interrupt\n");
150 else if (e->quit) printf("Exit: quit\n");
151 else if (e->terminate) printf("Exit: terminate\n");
152 ecore_main_loop_quit();
156 int main(int argc, const char **argv)
159 ecore_app_args_set(argc, argv);
160 start_time = ecore_time_get();
161 handler1 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, exit_func, NULL);
162 timer1 = ecore_timer_add(0.5, timer_func, NULL);
163 ecore_main_loop_begin();
169 In the previous example, we initialize our application and get the time at
170 which our program has started so we can calculate an offset. We set
171 up a timer to tick off in 0.5 seconds, and since it returns 1, will
172 keep ticking off every 0.5 seconds until it returns 0, or is deleted
173 by hand. An event handler is set up to call a function - exit_func(),
174 whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
175 on the command line will cause such an event to happen). If this event
176 occurs it tells you what kind of exit signal was received, and asks
177 the main loop to quit when it is finished by calling
178 ecore_main_loop_quit().
180 The handles returned by ecore_timer_add() and ecore_event_handler_add() are
181 only stored here as an example. If you don't need to address the timer or
182 event handler again you don't need to store the result, so just call the
183 function, and don't assign the result to any variable.
185 This program looks slightly more complex than needed to do these simple
186 things, but in principle, programs don't get any more complex. You add more
187 event handlers, for more events, will have more timers and such, BUT it all
188 follows the same principles as shown in this example.
193 @page Ecore_Config_Page The Enlightened Property Library
195 The Enlightened Property Library (Ecore_Config) is an adbstraction
196 from the complexities of writing your own configuration. It provides
197 many features using the Enlightenment 17 development libraries.
199 To use the library, you:
200 @li Set the default values of your properties.
201 @li Load the configuration from a file. You must set the default values
202 first, so that the library knows the correct type of each argument.
204 The following examples show how to use the Enlightened Property Library:
205 @li @link config_basic_example.c config_basic_example.c @endlink
206 @li @link config_listener_example.c config_listener_example.c @endlink
211 @page Ecore_ADT_Page Ecore Abstract Data Types
213 This page briefly describes the different abstract data types
214 that are provided by the Ecore library for general usage. You need to
215 include the @link Ecore_Data.h Ecore_Data.h @endlink to use them.
217 @section Ecore_ADT_List List
219 A list is a simple data type where one each piece of data points to
220 another piece of data.
222 Associated modules that describe the List ADT include:
223 @li @ref Ecore_Data_List_Creation_Group
224 @li @ref Ecore_Data_List_Add_Item_Group
225 @li @ref Ecore_Data_List_Remove_Item_Group
226 @li @ref Ecore_Data_List_Traverse_Group
227 @li @ref Ecore_Data_List_Node_Group
229 Examples involving lists include:
230 @li @link list_example.c list_example.c @endlink
232 @section Ecore_ADT_DList Doubly Linked List
234 A doubly linked list is like a linked list, only each piece of data
235 can also point to the piece before it. In other words, you can traverse
236 a doubly linked list in both directions.
238 Associated modules that describe the DList ADT include:
239 @li @ref Ecore_Data_DList_Creation_Group
240 @li @ref Ecore_Data_DList_Add_Item_Group
241 @li @ref Ecore_Data_DList_Remove_Item_Group
243 @section Ecore_ADT_Hash Hash
245 A hash is an abstract data type where one value is associated with another
246 value. Instead of each element of the group being accessible using a
247 number, each element is accessed using another object.
249 Associated modules that describe the Hash ADT include:
250 @li @ref Ecore_Data_Hash_ADT_Creation_Group
251 @li @ref Ecore_Data_Hash_ADT_Destruction_Group
252 @li @ref Ecore_Data_Hash_ADT_Data_Group
258 @page X_Window_System_Page X Window System
260 The Ecore library includes a wrapper for handling the X window system.
261 This page briefly explains what the X window system is and various terms
268 @defgroup Ecore_Timer_Group Ecore Timer
270 The timer allows callbacks to be called at specific intervals.
274 @defgroup Ecore_Job_Group Ecore Jobs
276 You can queue jobs that are to be done by the main loop when the current
281 @defgroup Idle_Group Idle Handlers
283 Callbacks that are called when the program enters or exits an idle state.
285 The ecore main loop enters an idle state when it is waiting for timers
286 to time out, data to come in on a file descriptor or any other event
287 to occur. You can set callbacks to be called when the main loop
288 enters an idle state, during an idle state or just after the program
291 Enterer callbacks are good for updating your program's state, if it
292 has a state engine. Once all of the enterer handlers are called, the
293 program will enter a "sleeping" state.
295 Idler callbacks are called when the main loop has called all enterer
296 handlers. They are useful for interfaces that require polling and
297 timers would be too slow to use.
299 If no idler callbacks are specified, then the process literally goes
300 to sleep. Otherwise, the idler callbacks are called continuously
301 while the loop is "idle", using as much CPU as is available to the
304 Exiter callbacks are called when the main loop wakes up from an idle
310 @defgroup Ecore_Config_Create_Group Ecore Config Create Functions
312 Convenience functions that set default values, bounds, option values and
313 descriptions in one call.
317 @defgroup Ecore_Config_File_Group Ecore Config File Functions
319 Functions that are used to load and save properties from and to files.
325 @example args_example.c
326 Shows how to set and retrieve the program arguments.
330 @example con_server_example.c
331 Shows how to write a simple server using the Ecore_Con library.
335 @example con_client_example.c
336 Shows how to write a simple client, that connects to the example server.
340 @example event_handler_example.c
341 Shows how to use event handlers.
345 @example timer_example.c
346 Demonstrates use of the ecore_timer.
350 @example config_basic_example.c
351 Provides an example of how to use the basic configuration functions.
352 See the file Ecore_Config.h for the full list of available functions.
356 @example config_listener_example.c
357 Shows how to set up a listener to listen for configuration changes.
361 @example list_example.c
362 Provides a basic example of how to append to and traverse a list.
366 @example list_destroy_example.c
367 Shows how to set and use a destructor for an Ecore_List.
371 @example x_window_example.c
372 Shows the basics of using the X Windows system through Ecore functions.