summaryrefslogtreecommitdiff
path: root/legacy/ecore/doc/ecore.dox.in
diff options
context:
space:
mode:
authorDaniel Kolesa <quaker66@gmail.com>2009-01-11 10:27:01 +0000
committerDaniel Kolesa <quaker66@gmail.com>2009-01-11 10:27:01 +0000
commitbae0ed2536649949aac0d7b3de77d56faf2090f6 (patch)
tree54a6409eba5d614506d13584db1ea358f1551f77 /legacy/ecore/doc/ecore.dox.in
parent6c874722eed9af5be362ed15a4a3e4e5a23399ed (diff)
Added some missing files for make doc support
SVN revision: 38546
Diffstat (limited to '')
-rw-r--r--legacy/ecore/doc/ecore.dox.in378
1 files changed, 378 insertions, 0 deletions
diff --git a/legacy/ecore/doc/ecore.dox.in b/legacy/ecore/doc/ecore.dox.in
new file mode 100644
index 0000000000..07cf5bf5b0
--- /dev/null
+++ b/legacy/ecore/doc/ecore.dox.in
@@ -0,0 +1,378 @@
1/**
2@brief Ecore Library Public API Calls
3
4These routines are used for Ecore Library interaction
5*/
6
7/**
8
9@mainpage Ecore
10
11@image latex ecore_big.eps width=5cm
12@image html ecore.png
13
14@version @PACKAGE_VERSION@
15@author Carsten Haitzler <raster\@rasterman.com>
16@author Tom Gilbert <tom\@linuxbrit.co.uk>
17@author Burra <burra\@colorado.edu>
18@author Chris Ross <chris\@darkrock.co.uk>
19@author Term <term\@twistedpath.org>
20@author Tilman Sauerbeck <tilman\@code-monkey.de>
21@author Nathan Ingersoll <rbdpngn\@users.sourceforge.net>
22@date 2000-2004
23
24@section intro Introduction
25
26Ecore is a library of convenience functions.
27
28The Ecore library provides the following modules:
29@li @link Ecore.h Ecore - Main Loop Functions. @endlink
30@li @link Ecore_Con.h Ecore_Con - Connection functions. @endlink
31@li @link Ecore_Config.h Ecore_Config - Configuration functions. @endlink
32@li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink
33@li @link Ecore_Fb.h Ecore_FB - Frame buffer convenience functions. @endlink
34@li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink
35@li @link Ecore_Job.h Ecore_Job - Job functions, to be used in the Ecore main loop. @endlink
36@li @link Ecore_Txt.h Ecore_Txt - Text encoding conversion. @endlink
37@li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
38
39@section compiling How to compile using Ecore?
40
41This section has to be documented. Below is just a quick line to handle all
42Ecore modules at once.
43
44@verbatim
45gcc *.c \
46-I/usr/local/include -I/usr/X11R6/include \
47-L/usr/local/lib -L/usr/X11R6/lib \
48-lecore -lecore_evas -lecore_x -lecore_fb -lecore_job \
49`pkg-config evas --cflags --libs`
50@endverbatim
51
52@section install How is it installed?
53
54Suggested configure options for evas for a Linux desktop X display:
55
56@verbatim
57./configure \
58--enable-ecore-x \
59--enable-ecore-fb \
60--enable-ecore-evas \
61--enable-ecore-evas-gl \
62--enable-ecore-job \
63--enable-ecore-con \
64--enable-ecore-ipc \
65--enable-ecore-txt
66make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
67@endverbatim
68
69@todo (1.0) Document API
70
71*/
72
73/*
74@page Ecore_Main_Loop_Page The Ecore Main Loop
75
76@section intro What is Ecore?
77
78Ecore is a clean and tiny event loop library with many modules to do lots of
79convenient things for a programmer, to save time and effort.
80
81It's small and lean, designed to work on embedded systems all the way to
82large and powerful multi-cpu workstations. It serialises all system signals,
83events etc. into a single event queue, that is easily processed without
84needing to worry about concurrency. A properly written, event-driven program
85using this kind of programming doesn't need threads, nor has to worry about
86concurrency. It turns a program into a state machine, and makes it very
87robust and easy to follow.
88
89Ecore gives you other handy primitives, such as timers to tick over for you
90and call specified functions at particular times so the programmer can use
91this to do things, like animate, or time out on connections or tasks that take
92too long etc.
93
94Idle handlers are provided too, as well as calls on entering an idle state
95(often a very good time to update the state of the program). All events that
96enter the system are passed to specific callback functions that the program
97sets up to handle those events. Handling them is simple and other Ecore
98modules produce more events on the queue, coming from other sources such as
99file descriptors etc.
100
101Ecore also lets you have functions called when file descriptors become active
102for reading or writing, allowing for streamlined, non-blocking IO.
103
104Here is an exmaple of a simple program and its basic event loop flow:
105
106@image html prog_flow.png
107
108
109
110@section work How does Ecore work?
111
112Ecore is very easy to learn and use. All the function calls are designed to
113be easy to remember, explicit in describing what they do, and heavily
114name-spaced. Ecore programs can start and be very simple.
115
116For example:
117
118@code
119#include <Ecore.h>
120
121int main(int argc, const char **argv)
122{
123 ecore_init();
124 ecore_app_args_set(argc, argv);
125 ecore_main_loop_begin();
126 ecore_shutdown();
127 return 0;
128}
129@endcode
130
131This program is very simple and does't check for errors, but it does start up
132and begin a main loop waiting for events or timers to tick off. This program
133doesn't set up any, but now we can expand on this simple program a little
134more by adding some event handlers and timers.
135
136@code
137#include <Ecore.h>
138
139Ecore_Timer *timer1 = NULL;
140Ecore_Event_Handler *handler1 = NULL;
141double start_time = 0.0;
142
143int timer_func(void *data)
144{
145 printf("Tick timer. Sec: %3.2f\n", ecore_time_get() - start_time);
146 return 1;
147}
148
149int exit_func(void *data, int ev_type, void *ev)
150{
151 Ecore_Event_Signal_Exit *e;
152
153 e = (Ecore_Event_Signal_Exit *)ev;
154 if (e->interrupt) printf("Exit: interrupt\n");
155 else if (e->quit) printf("Exit: quit\n");
156 else if (e->terminate) printf("Exit: terminate\n");
157 ecore_main_loop_quit();
158 return 1;
159}
160
161int main(int argc, const char **argv)
162{
163 ecore_init();
164 ecore_app_args_set(argc, argv);
165 start_time = ecore_time_get();
166 handler1 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, exit_func, NULL);
167 timer1 = ecore_timer_add(0.5, timer_func, NULL);
168 ecore_main_loop_begin();
169 ecore_shutdown();
170 return 0;
171}
172@endcode
173
174In the previous example, we initialize our application and get the time at
175which our program has started so we can calculate an offset. We set
176up a timer to tick off in 0.5 seconds, and since it returns 1, will
177keep ticking off every 0.5 seconds until it returns 0, or is deleted
178by hand. An event handler is set up to call a function - exit_func(),
179whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
180on the command line will cause such an event to happen). If this event
181occurs it tells you what kind of exit signal was received, and asks
182the main loop to quit when it is finished by calling
183ecore_main_loop_quit().
184
185The handles returned by ecore_timer_add() and ecore_event_handler_add() are
186only stored here as an example. If you don't need to address the timer or
187event handler again you don't need to store the result, so just call the
188function, and don't assign the result to any variable.
189
190This program looks slightly more complex than needed to do these simple
191things, but in principle, programs don't get any more complex. You add more
192event handlers, for more events, will have more timers and such, BUT it all
193follows the same principles as shown in this example.
194
195*/
196
197/**
198@page Ecore_Config_Page The Enlightened Property Library
199
200The Enlightened Property Library (Ecore_Config) is an adbstraction
201from the complexities of writing your own configuration. It provides
202many features using the Enlightenment 17 development libraries.
203
204To use the library, you:
205@li Set the default values of your properties.
206@li Load the configuration from a file. You must set the default values
207 first, so that the library knows the correct type of each argument.
208
209The following examples show how to use the Enlightened Property Library:
210@li @link config_basic_example.c config_basic_example.c @endlink
211@li @link config_listener_example.c config_listener_example.c @endlink
212
213*/
214
215/**
216@page Ecore_ADT_Page Ecore Abstract Data Types
217
218This page briefly describes the different abstract data types
219that are provided by the Ecore library for general usage. You need to
220include the @link Ecore_Data.h Ecore_Data.h @endlink to use them.
221
222@section Ecore_ADT_List List
223
224A list is a simple data type where one each piece of data points to
225another piece of data.
226
227Associated modules that describe the List ADT include:
228@li @ref Ecore_Data_List_Creation_Group
229@li @ref Ecore_Data_List_Add_Item_Group
230@li @ref Ecore_Data_List_Remove_Item_Group
231@li @ref Ecore_Data_List_Traverse_Group
232@li @ref Ecore_Data_List_Node_Group
233
234Examples involving lists include:
235@li @link list_example.c list_example.c @endlink
236
237@section Ecore_ADT_DList Doubly Linked List
238
239A doubly linked list is like a linked list, only each piece of data
240can also point to the piece before it. In other words, you can traverse
241a doubly linked list in both directions.
242
243Associated modules that describe the DList ADT include:
244@li @ref Ecore_Data_DList_Creation_Group
245@li @ref Ecore_Data_DList_Add_Item_Group
246@li @ref Ecore_Data_DList_Remove_Item_Group
247
248@section Ecore_ADT_Hash Hash
249
250A hash is an abstract data type where one value is associated with another
251value. Instead of each element of the group being accessible using a
252number, each element is accessed using another object.
253
254Associated modules that describe the Hash ADT include:
255@li @ref Ecore_Data_Hash_ADT_Creation_Group
256@li @ref Ecore_Data_Hash_ADT_Destruction_Group
257@li @ref Ecore_Data_Hash_ADT_Data_Group
258
259@todo Finish this.
260*/
261
262/**
263@page X_Window_System_Page X Window System
264
265The Ecore library includes a wrapper for handling the X window system.
266This page briefly explains what the X window system is and various terms
267that are used.
268*/
269
270// GROUP DEFINITIONS
271
272/**
273@defgroup Ecore_Timer_Group Ecore Timer
274
275The timer allows callbacks to be called at specific intervals.
276 */
277
278/**
279@defgroup Ecore_Job_Group Ecore Jobs
280
281You can queue jobs that are to be done by the main loop when the current
282event is dealt with.
283*/
284
285/**
286@defgroup Idle_Group Idle Handlers
287
288Callbacks that are called when the program enters or exits an idle state.
289
290The ecore main loop enters an idle state when it is waiting for timers
291to time out, data to come in on a file descriptor or any other event
292to occur. You can set callbacks to be called when the main loop
293enters an idle state, during an idle state or just after the program
294wakes up.
295
296Enterer callbacks are good for updating your program's state, if it
297has a state engine. Once all of the enterer handlers are called, the
298program will enter a "sleeping" state.
299
300Idler callbacks are called when the main loop has called all enterer
301handlers. They are useful for interfaces that require polling and
302timers would be too slow to use.
303
304If no idler callbacks are specified, then the process literally goes
305to sleep. Otherwise, the idler callbacks are called continuously
306while the loop is "idle", using as much CPU as is available to the
307process.
308
309Exiter callbacks are called when the main loop wakes up from an idle
310state.
311
312*/
313
314/**
315@defgroup Ecore_Config_Create_Group Ecore Config Create Functions
316
317Convenience functions that set default values, bounds, option values and
318descriptions in one call.
319*/
320
321/**
322@defgroup Ecore_Config_File_Group Ecore Config File Functions
323
324Functions that are used to load and save properties from and to files.
325*/
326
327// EXAMPLES
328
329/**
330@example args_example.c
331Shows how to set and retrieve the program arguments.
332*/
333
334/**
335@example con_server_example.c
336Shows how to write a simple server using the Ecore_Con library.
337*/
338
339/**
340@example con_client_example.c
341Shows how to write a simple client, that connects to the example server.
342*/
343
344/**
345@example event_handler_example.c
346Shows how to use event handlers.
347*/
348
349/**
350@example timer_example.c
351Demonstrates use of the ecore_timer.
352*/
353
354/**
355@example config_basic_example.c
356Provides an example of how to use the basic configuration functions.
357See the file Ecore_Config.h for the full list of available functions.
358*/
359
360/**
361@example config_listener_example.c
362Shows how to set up a listener to listen for configuration changes.
363*/
364
365/**
366@example list_example.c
367Provides a basic example of how to append to and traverse a list.
368*/
369
370/**
371@example list_destroy_example.c
372Shows how to set and use a destructor for an Ecore_List.
373*/
374
375/**
376@example x_window_example.c
377Shows the basics of using the X Windows system through Ecore functions.
378*/