Enlightenment CVS committal
Author : raster
Project : e17
Module : libs/ecore
Dir : e17/libs/ecore/src/lib/ecore
Modified Files:
Tag: SPLIT
ecore.c ecore_app.c ecore_events.c ecore_exe.c ecore_main.c
ecore_timer.c
Log Message:
improve docs... :)
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore.c,v
retrieving revision 1.1.2.7
retrieving revision 1.1.2.8
diff -u -3 -r1.1.2.7 -r1.1.2.8
--- ecore.c 21 Feb 2003 04:59:13 -0000 1.1.2.7
+++ ecore.c 25 Feb 2003 04:32:26 -0000 1.1.2.8
@@ -7,7 +7,23 @@
* Set up connections, signal handlers, sockets etc.
* @return 1 or greater on success, 0 otherwise
*
- * This function sets up all singal handlers and the basic event loop.
+ * This function sets up all singal handlers and the basic event loop. If it
+ * succeeds, 1 will be returned, otherwise 0 will be returned.
+ *
+ * @code
+ * #include <Ecore.h>
+ *
+ * int main(int argc, char **argv)
+ * {
+ * if (!ecore_init())
+ * {
+ * printf("ERROR: Cannot init Ecore!\n");
+ * return -1;
+ * }
+ * ecore_main_loop_begin();
+ * ecore_shutdown();
+ * }
+ * @endcode
*/
int
ecore_init(void)
@@ -19,8 +35,8 @@
/**
* Shut down connections, signal handlers sockets etc.
*
- * This function shuts all things set up in ecore_init() and cleans up all
- * event queues, handles, filters, timers, idlers, idle enterers etc. set up
+ * This function shuts down all things set up in ecore_init() and cleans up all
+ * event queues, handlers, filters, timers, idlers, idle enterers etc. set up
* after ecore_init() was called.
*/
void
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore_app.c,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -3 -r1.1.2.2 -r1.1.2.3
--- ecore_app.c 20 Feb 2003 06:56:40 -0000 1.1.2.2
+++ ecore_app.c 25 Feb 2003 04:32:26 -0000 1.1.2.3
@@ -5,12 +5,36 @@
static char **app_argv = NULL;
/**
- * Set up the programs command-line arguments
+ * Set up the programs command-line arguments.
* @param argc The same as passed as argc to the programs main() function
* @param argv The same as passed as argv to the programs main() function
*
* A call to this function will store the programs command-line arguments
* for later use by ecore_app_restart() or ecore_app_args_get().
+ *
+ * @code
+ * #include <Ecore.h>
+ *
+ * int timer_once(void *data)
+ * {
+ * int argc;
+ * char **argv;
+ * int i;
+ *
+ * ecore_app_args_get(&argc, &argv);
+ * for (i = 0; i < argc; i++) printf("ARG %i: %s\n", i, argv[i]);
+ * return 0;
+ * }
+ *
+ * int main(int argc, char **argv)
+ * {
+ * ecore_init();
+ * ecore_app_args_set(argc, argv);
+ * ecore_timer_add(5.0, timer_once, NULL);
+ * ecore_main_loop_begin();
+ * ecore_shutdown();
+ * }
+ * @endcode
*/
void
ecore_app_args_set(int argc, const char **argv)
@@ -22,14 +46,15 @@
}
/**
- * Return the programs stored command-line arguments
+ * Return the programs stored command-line arguments.
* @param argc A pointer to the return value to hold argc
* @param argv A pointer to the return value to hold argv
*
* When called, this funciton returns the arguments for the program stored by
* ecore_app_args_set(). The integer pointed to by @p argc will be filled, if
* the pointer is not NULL, and the string array pointer @p argv will be filled
- * also if the pointer is not NULL.
+ * also if the pointer is not NULL. The values they are filled with will be the
+ * same set by ecore_app_args_set().
*/
void
ecore_app_args_get(int *argc, char ***argv)
@@ -39,7 +64,7 @@
}
/**
- * Restart the program executable with the command-line arguments stored
+ * Restart the program executable with the command-line arguments stored.
*
* This function will restart & re-execute this program in place of itself
* using the command-line arguments stored by ecore_app_args_set(). This is
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore_events.c,v
retrieving revision 1.1.2.7
retrieving revision 1.1.2.8
diff -u -3 -r1.1.2.7 -r1.1.2.8
--- ecore_events.c 20 Feb 2003 06:56:40 -0000 1.1.2.7
+++ ecore_events.c 25 Feb 2003 04:32:26 -0000 1.1.2.8
@@ -13,20 +13,65 @@
static int event_id_max = ECORE_EVENT_COUNT;
/**
- * Add an event handler
+ * Add an event handler.
* @param type The type of the event this handler will get called for
* @param func The function to call when the event is found in the queue
* @param data A data pointer to pass to the called function @p func
- * @return Handler handle, or NULL on failure
+ * @return A new Event handler, or NULL on failure
*
- * Add an event handler to the list of handlers. This will, on success return
- * a handle to the event handler that can be used later to remove the handler
- * using ecore_event_handler_del(). The @p type parameter is the iteger of the
- * event type that will trigger this callback to be called. The callback
- * @p func is called when this event is processed and will be passed the
- * event type, a pointer to the private event structure that is specific to
- * that event type, and a data pointer that is provided in this call as the
- * @p data parameter.
+ * Add an event handler to the list of handlers. This will, on success, return
+ * a handle to the event handler object that was created, that can be used
+ * later to remove the handler using ecore_event_handler_del(). The @p type
+ * parameter is the iteger of the event type that will trigger this callback
+ * to be called. The callback @p func is called when this event is processed
+ * and will be passed the event type, a pointer to the private event
+ * structure that is specific to that event type, and a data pointer that is
+ * provided in this call as the @p data parameter.
+ *
+ * When the callback @p func is called, it must return 1 or 0. If it returns
+ * 1, It will keep being called as per normal, when events come into the event
+ * queue. If it returns 0, it will be removed from the list of event handlers
+ * and be destroyed. If this happens the event handler object returned is no
+ * longer valid, and the handler will not be called again after it returns 0.
+ *
+ * @code
+ * #include <Ecore.h>
+ *
+ * Ecore_Event_Handler *handler1 = NULL, *handler2 = NULL;
+ *
+ * int event_hup(int ev_type, void *ev, void *data)
+ * {
+ * printf("Hup signal! Remove the exit handler.\n");
+ * ecore_event_handler_del(handler1);
+ * return 0;
+ * }
+ *
+ * int event_exit(int ev_type, void *ev, void *data)
+ * {
+ * Ecore_Event_Signal_Exit *e;
+ *
+ * e = (Ecore_Event_Signal_Exit *)ev;
+ * printf("This callback handles event type: %i\n", ECORE_EVENT_SIGNAL_EXIT);
+ * printf("Event type recieved: %i\n", ev_type);
+ * if (e->interrupt) printf("Exit: interrupt\n");
+ * if (e->quit) printf("Exit: quit\n");
+ * if (e->terminate) printf("Exit: terminate\n");
+ * ecore_main_loop_quit();
+ * return 1;
+ * }
+ *
+ * int main(int argc, char **argv)
+ * {
+ * ecore_init();
+ * ecore_app_args_set(argc, argv);
+ * handler1 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT,
+ * event_exit, NULL);
+ * handler2 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_HUP,
+ * event_hup, NULL);
+ * ecore_main_loop_begin();
+ * ecore_shutdown();
+ * }
+ * @endcode
*/
Ecore_Event_Handler *
ecore_event_handler_add(int type, int (*func) (int type, void *event, void *data),
const void *data)
@@ -46,14 +91,14 @@
}
/**
- * Delete an event handler
+ * Delete an event handler.
* @param event_handler Event handler handle to delete
* @return Data passed to handler
*
* Delete a specified event handler from the handler list. On success this will
* delete the event handler and return the pointer passed as @p data when the
* handler was added by ecore_event_handler_add(). On failure NULL will be
- * returned.
+ * returned. Once a handler is deleted it will no longer be called.
*/
void *
ecore_event_handler_del(Ecore_Event_Handler *event_handler)
@@ -70,7 +115,7 @@
}
/**
- * Add an event to the event queue
+ * Add an event to the event queue.
* @param type The event type to add to the end of the event queue
* @param ev The private data structure for this event type
* @param func_free The function to be called to free this private structure
@@ -97,7 +142,7 @@
}
/**
- * Delete an event from the queue
+ * Delete an event from the queue.
* @param event The event handle to delete
* @return The data pointer originally set for the event free function
*
@@ -121,7 +166,7 @@
}
/**
- * Allocate a new event type id sensibly and return the new id
+ * Allocate a new event type id sensibly and return the new id.
* @return A new event type id.
*
* This function allocates a new event type id and returns it. Once an event
@@ -138,7 +183,7 @@
}
/**
- * Add a filter the current event queue
+ * Add a filter the current event queue.
* @param func_start Function to call just before filtering and return data
* @param func_filter Function to call on each event
* @param func_end Function to call after the queu has been filtered
@@ -175,7 +220,7 @@
}
/**
- * Delete an event filter
+ * Delete an event filter.
* @param ef The event filter handle
* @return The data set for the filter
*
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore_exe.c,v
retrieving revision 1.1.2.6
retrieving revision 1.1.2.7
diff -u -3 -r1.1.2.6 -r1.1.2.7
--- ecore_exe.c 20 Feb 2003 06:56:40 -0000 1.1.2.6
+++ ecore_exe.c 25 Feb 2003 04:32:26 -0000 1.1.2.7
@@ -94,7 +94,7 @@
/**
* Get the data pointer attached to a process handle
* @param exe The process handle returned by ecore_exe_run()
- * @retrun An pointer to the attached data of the process handle
+ * @return An pointer to the attached data of the process handle
*
* This function returns the data pointer attached to the spawned off process
* whose handle is @p exe.
@@ -189,6 +189,7 @@
/**
* Send a user signal to a process
* @param exe The process handle to control
+ * @param num The signal number to send to the process
*
* This function sends a user signal (SIGUSR) to a process. @p num determines
* what numbered user signal to send. This may be either 1 or 2. Other values
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore_main.c,v
retrieving revision 1.1.2.6
retrieving revision 1.1.2.7
diff -u -3 -r1.1.2.6 -r1.1.2.7
--- ecore_main.c 20 Feb 2003 06:56:40 -0000 1.1.2.6
+++ ecore_main.c 25 Feb 2003 04:32:26 -0000 1.1.2.7
@@ -162,13 +162,19 @@
* @param flags To watch it for read and/or write ability
* @param func The function to call when the file descriptor becomes active
* @param data The data to pass to the @p func call
+ * @param buf_func The function to call to check if any data has been buffered and
already read from the fd.
+ * @param buf_data The data to pass to the @p buf_func call
* @return A fd handler handle
*
* This adds a fd handler, calling @p func whenever the fd is active for
* read or write (or both) depending what flags were set as @p flags. On
* failure NULL is returned. The @p func call will the triggered during
* execution of ecore_main_loop_begin() when a file descriptor (fd) is
- * available for reading or writing (or both).
+ * available for reading or writing (or both). The #p buf_func call is called
+ * during event loop handling to check if data that has already been read from
+ * the file descriptor is in a buffer and is available to read. This function
+ * is optional and can be NULL. If it is called it will be passed @p buf_data
+ * as the data parameter.
*
* Example:
*
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Attic/ecore_timer.c,v
retrieving revision 1.1.2.6
retrieving revision 1.1.2.7
diff -u -3 -r1.1.2.6 -r1.1.2.7
--- ecore_timer.c 23 Feb 2003 02:00:57 -0000 1.1.2.6
+++ ecore_timer.c 25 Feb 2003 04:32:26 -0000 1.1.2.7
@@ -18,6 +18,49 @@
* failure. The function @p func will be called in @p in seconds from the
* time this function call was made. The function @p func is passed the
* @p data pointer as its parameter.
+ *
+ * When the timer @p func is called, it must return a value of either 1 or 0.
+ * If it returns 1, it will be re-scheduled to repeat in the same interval
+ * after this timer was triggered (ie if this timer was triggered with an
+ * @p in value of 1.0 then the next timer will be triggered at the time this
+ * timer was called plus 1.0).
+ *
+ * @code
+ * #include <Ecore.h>
+ *
+ * Ecore_Timer *timer1 = NULL, *timer2 = NULL, *timer3 = NULL;
+ *
+ * int timer_tick(void *data)
+ * {
+ * printf("Tick timer %3.2f\n", ecore_time_get());
+ * return 1;
+ * }
+ *
+ * int timer_repeat(void *data)
+ * {
+ * printf("Repeat timer called at %3.2f seconds, data %p\n",
+ * ecore_time_get(), data);
+ * return 1;
+ * }
+ *
+ * int timer_once(void *data)
+ * {
+ * printf("Once only timer called at %3.2f seconds, data %p\n",
+ * ecore_time_get(), data);
+ * ecore_timer_del(timer2);
+ * return 0;
+ * }
+ *
+ * int main(int argc, char **argv)
+ * {
+ * ecore_init();
+ * ecore_app_args_set(argc, argv);
+ * timer1 = ecore_timer_add(5.0, timer_once, NULL);
+ * timer2 = ecore_timer_add(0.5, timer_repeat, NULL);
+ * timer3 = ecore_timer_add(1.0, timer_tick, NULL);
+ * ecore_main_loop_begin();
+ * }
+ * @endcode
*/
Ecore_Timer *
ecore_timer_add(double in, int (*func) (void *data), const void *data)
@@ -40,8 +83,11 @@
* @param timer
* @return The data pointer set for the timer
*
- * Delete the specified @p timer from the set of timers that ar executed
- * during main loop execution.
+ * Delete the specified @p timer from the set of timers that are executed
+ * during main loop execution. This function returns the data parameter that
+ * was being passed to the callback on success, or NULL on failure. After this
+ * call returns the specified timer object @p timer is invalid and should not
+ * be used again. It will not get called again after deletion.
*/
void *
ecore_timer_del(Ecore_Timer *timer)
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
