ecore.c.in

   1 /**
   2 @brief Ecore Library Public API Calls
   3
   4 These 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 1.0.0
  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
  26 Ecore is a library of convenience functions.
  27
  28 The 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
  41 This section has to be documented. Below is just a quick line to handle all
  42 Ecore modules at once.
  43
  44 @verbatim
  45 gcc *.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 `evas-config --cflags --libs`
  50 @endverbatim
  51
  52 @section install How is it installed?
  53
  54 Suggested 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
  66 make 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
  78 Ecore is a clean and tiny event loop library with many modules to do lots of
  79 convenient things for a programmer, to save time and effort.
  80
  81 It's small and lean, designed to work on embedded systems all the way to
  82 large and powerful multi-cpu workstations. It serialises all system signals,
  83 events etc. into a single event queue, that is easily processed without
  84 needing to worry about concurrency. A properly written, event-driven program
  85 using this kind of programming doesn't need threads, nor has to worry about
  86 concurrency. It turns a program into a state machine, and makes it very
  87 robust and easy to follow.
  88
  89 Ecore gives you other handy primitives, such as timers to tick over for you
  90 and call specified functions at particular times so the programmer can use
  91 this to do things, like animate, or time out on connections or tasks that take
  92 too long etc.
  93
  94 Idle 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
  96 enter the system are passed to specific callback functions that the program
  97 sets up to handle those events. Handling them is simple and other Ecore
  98 modules produce more events on the queue, coming from other sources such as
  99 file descriptors etc.
 100
 101 Ecore also lets you have functions called when file descriptors become active
 102 for reading or writing, allowing for streamlined, non-blocking IO.
 103
 104 Here 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
 112 Ecore is very easy to learn and use. All the function calls are designed to
 113 be easy to remember, explicit in describing what they do, and heavily
 114 name-spaced. Ecore programs can start and be very simple.
 115
 116 For example:
 117
 118 @code
 119 #include <Ecore.h>
 120
 121 int 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
 131 This program is very simple and does't check for errors, but it does start up
 132 and begin a main loop waiting for events or timers to tick off. This program
 133 doesn't set up any, but now we can expand on this simple program a little
 134 more by adding some event handlers and timers.
 135
 136 @code
 137 #include <Ecore.h>
 138
 139 Ecore_Timer         *timer1     = NULL;
 140 Ecore_Event_Handler *handler1   = NULL;
 141 double               start_time = 0.0;
 142
 143 int timer_func(void *data)
 144 {
 145   printf("Tick timer. Sec: %3.2f\n", ecore_time_get() - start_time);
 146   return 1;
 147 }
 148
 149 int 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
 161 int 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
 174 In the previous example, we initialize our application and get the time at
 175 which our program has started so we can calculate an offset. We set
 176 up a timer to tick off in 0.5 seconds, and since it returns 1, will
 177 keep ticking off every 0.5 seconds until it returns 0, or is deleted
 178 by hand. An event handler is set up to call a function - exit_func(),
 179 whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
 180 on the command line will cause such an event to happen). If this event
 181 occurs it tells you what kind of exit signal was received, and asks
 182 the main loop to quit when it is finished by calling
 183 ecore_main_loop_quit().
 184
 185 The handles returned by ecore_timer_add() and ecore_event_handler_add() are
 186 only stored here as an example. If you don't need to address the timer or
 187 event handler again you don't need to store the result, so just call the
 188 function, and don't assign the result to any variable.
 189
 190 This program looks slightly more complex than needed to do these simple
 191 things, but in principle, programs don't get any more complex. You add more
 192 event handlers, for more events, will have more timers and such, BUT it all
 193 follows the same principles as shown in this example.
 194
 195 */
 196
 197 /**
 198 @page Ecore_Config_Page The Enlightened Property Library
 199
 200 The Enlightened Property Library (Ecore_Config) is an adbstraction
 201 from the complexities of writing your own configuration. It provides
 202 many features using the Enlightenment 17 development libraries.
 203
 204 To 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
 209 The 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
 218 This page briefly describes the different abstract data types
 219 that are provided by the Ecore library for general usage.  You need to
 220 include the @link Ecore_Data.h Ecore_Data.h @endlink to use them.
 221
 222 @section Ecore_ADT_List List
 223
 224 A list is a simple data type where one each piece of data points to
 225 another piece of data.
 226
 227 Associated 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
 234 Examples involving lists include:
 235 @li @link list_example.c list_example.c @endlink
 236
 237 @section Ecore_ADT_DList Doubly Linked List
 238
 239 A doubly linked list is like a linked list, only each piece of data
 240 can also point to the piece before it.  In other words, you can traverse
 241 a doubly linked list in both directions.
 242
 243 Associated 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
 250 A hash is an abstract data type where one value is associated with another
 251 value.  Instead of each element of the group being accessible using a
 252 number, each element is accessed using another object.
 253
 254 Associated 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
 265 The Ecore library includes a wrapper for handling the X window system.
 266 This page briefly explains what the X window system is and various terms
 267 that are used.
 268 */
 269
 270 // GROUP DEFINITIONS
 271
 272 /**
 273 @defgroup Ecore_Timer_Group Ecore Timer
 274
 275 The timer allows callbacks to be called at specific intervals.
 276  */
 277
 278 /**
 279 @defgroup Ecore_Job_Group Ecore Jobs
 280
 281 You can queue jobs that are to be done by the main loop when the current
 282 event is dealt with.
 283 */
 284
 285 /**
 286 @defgroup Idle_Group Idle Handlers
 287
 288 Callbacks that are called when the program enters or exits an idle state.
 289
 290 The ecore main loop enters an idle state when it is waiting for timers
 291 to time out, data to come in on a file descriptor or any other event
 292 to occur.  You can set callbacks to be called when the main loop
 293 enters an idle state, during an idle state or just after the program
 294 wakes up.
 295
 296 Enterer callbacks are good for updating your program's state, if it
 297 has a state engine.  Once all of the enterer handlers are called, the
 298 program will enter a "sleeping" state.
 299
 300 Idler callbacks are called when the main loop has called all enterer
 301 handlers.  They are useful for interfaces that require polling and
 302 timers would be too slow to use.
 303
 304 If no idler callbacks are specified, then the process literally goes
 305 to sleep.  Otherwise, the idler callbacks are called continuously
 306 while the loop is "idle", using as much CPU as is available to the
 307 process.
 308
 309 Exiter callbacks are called when the main loop wakes up from an idle
 310 state.
 311
 312 */
 313
 314 /**
 315 @defgroup Ecore_Config_Create_Group Ecore Config Create Functions
 316
 317 Convenience functions that set default values, bounds, option values and
 318 descriptions in one call.
 319 */
 320
 321 /**
 322 @defgroup Ecore_Config_File_Group Ecore Config File Functions
 323
 324 Functions that are used to load and save properties from and to files.
 325 */
 326
 327 // EXAMPLES
 328
 329 /**
 330 @example args_example.c
 331 Shows how to set and retrieve the program arguments.
 332 */
 333
 334 /**
 335 @example con_server_example.c
 336 Shows how to write a simple server using the Ecore_Con library.
 337 */
 338
 339 /**
 340 @example con_client_example.c
 341 Shows how to write a simple client, that connects to the example server.
 342 */
 343
 344 /**
 345 @example event_handler_example.c
 346 Shows how to use event handlers.
 347 */
 348
 349 /**
 350 @example timer_example.c
 351 Demonstrates use of the ecore_timer.
 352 */
 353
 354 /**
 355 @example config_basic_example.c
 356 Provides an example of how to use the basic configuration functions.
 357 See the file Ecore_Config.h for the full list of available functions.
 358 */
 359
 360 /**
 361 @example config_listener_example.c
 362 Shows how to set up a listener to listen for configuration changes.
 363 */
 364
 365 /**
 366 @example list_example.c
 367 Provides a basic example of how to append to and traverse a list.
 368 */
 369
 370 /**
 371 @example list_destroy_example.c
 372 Shows how to set and use a destructor for an Ecore_List.
 373 */
 374
 375 /**
 376 @example x_window_example.c
 377 Shows the basics of using the X Windows system through Ecore functions.
 378 */