From 093bd1d9c24d50cf440231e9ada30ead0e7cccc7 Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Sat, 8 May 2004 04:44:04 +0000 Subject: [PATCH] nathan's docs :) SVN revision: 10113 --- legacy/ecore/AUTHORS | 1 + legacy/ecore/Doxyfile | 8 +- legacy/ecore/Makefile.am | 2 +- legacy/ecore/configure.in | 1 + legacy/ecore/ecore.c.in | 145 +++++++++++------- legacy/ecore/examples/Makefile.am | 25 +++ legacy/ecore/examples/args_example.c | 25 +++ legacy/ecore/examples/config_basic_example.c | 93 +++++++++++ legacy/ecore/examples/event_handler_example.c | 39 +++++ legacy/ecore/examples/timer_example.c | 41 +++++ legacy/ecore/src/lib/ecore/ecore_app.c | 24 --- legacy/ecore/src/lib/ecore/ecore_events.c | 39 ----- .../ecore/src/lib/ecore/ecore_idle_enterer.c | 29 ++-- .../ecore/src/lib/ecore/ecore_idle_exiter.c | 19 +-- legacy/ecore/src/lib/ecore/ecore_idler.c | 29 ++-- legacy/ecore/src/lib/ecore/ecore_list.c | 45 +++--- legacy/ecore/src/lib/ecore/ecore_main.c | 3 + legacy/ecore/src/lib/ecore/ecore_path.c | 2 +- legacy/ecore/src/lib/ecore/ecore_sheap.c | 15 +- legacy/ecore/src/lib/ecore/ecore_timer.c | 41 +---- legacy/ecore/src/lib/ecore/ecore_tree.c | 47 +++--- legacy/ecore/src/lib/ecore/ecore_value.c | 2 +- legacy/ecore/src/lib/ecore_evas/ecore_evas.c | 3 +- .../src/lib/ecore_x/ecore_x_window_prop.c | 54 +++---- 24 files changed, 430 insertions(+), 302 deletions(-) create mode 100644 legacy/ecore/examples/Makefile.am create mode 100644 legacy/ecore/examples/args_example.c create mode 100644 legacy/ecore/examples/config_basic_example.c create mode 100644 legacy/ecore/examples/event_handler_example.c create mode 100644 legacy/ecore/examples/timer_example.c diff --git a/legacy/ecore/AUTHORS b/legacy/ecore/AUTHORS index 410626cd48..1767c70321 100644 --- a/legacy/ecore/AUTHORS +++ b/legacy/ecore/AUTHORS @@ -10,3 +10,4 @@ Nicholas Curran Howell Tam Nathan Ingersoll Andrew Elcock +Nicholas Curran diff --git a/legacy/ecore/Doxyfile b/legacy/ecore/Doxyfile index 95a0951d68..2619f4f224 100644 --- a/legacy/ecore/Doxyfile +++ b/legacy/ecore/Doxyfile @@ -67,7 +67,7 @@ RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -EXAMPLE_PATH = +EXAMPLE_PATH = ./examples/ EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO INPUT_FILTER = @@ -137,9 +137,3 @@ MAX_DOT_GRAPH_HEIGHT = 512 GENERATE_LEGEND = YES DOT_CLEANUP = YES SEARCHENGINE = NO -CGI_NAME = search.cgi -CGI_URL = -DOC_URL = -DOC_ABSPATH = -BIN_ABSPATH = /usr/bin/ -EXT_DOC_PATHS = diff --git a/legacy/ecore/Makefile.am b/legacy/ecore/Makefile.am index 1bc3144f79..d1179050ec 100644 --- a/legacy/ecore/Makefile.am +++ b/legacy/ecore/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -SUBDIRS = src debian +SUBDIRS = src debian examples MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess \ config.h.in config.sub configure install-sh \ diff --git a/legacy/ecore/configure.in b/legacy/ecore/configure.in index a3c0df231b..402b3e5d4f 100644 --- a/legacy/ecore/configure.in +++ b/legacy/ecore/configure.in @@ -643,6 +643,7 @@ src/lib/ecore_ipc/Makefile src/lib/ecore_txt/Makefile src/lib/ecore_config/Makefile debian/Makefile +examples/Makefile ], [ chmod +x ecore-config ] diff --git a/legacy/ecore/ecore.c.in b/legacy/ecore/ecore.c.in index c61bc8522c..2105d4fc0b 100644 --- a/legacy/ecore/ecore.c.in +++ b/legacy/ecore/ecore.c.in @@ -7,8 +7,10 @@ These routines are used for Ecore Library interaction /** @mainpage Ecore + @image latex ecore_big.eps width=5cm @image html ecore.png + @version 1.0.0 @author Carsten Haitzler @author Tom Gilbert @@ -20,16 +22,6 @@ These routines are used for Ecore Library interaction - - - - - - - - - - @section intro What is Ecore? Ecore is a clean and tiny event loop library with many modules to do lots of @@ -64,19 +56,6 @@ Here is an exmaple of a simple program and its basic event loop flow: - - - - - - - - - - - - - @section work How does Ecore work? Ecore is very easy to learn and use. All the function calls are designed to @@ -141,15 +120,16 @@ int main(int argc, const char **argv) } @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(). +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 @@ -163,11 +143,6 @@ follows the same principles as shown in this example. - - - - - @section compiling How to compile using Ecore? This section has to be documented. Below is just a quick line to handle all @@ -183,17 +158,6 @@ gcc *.c \ - - - - - - - - - - - @section install How is it installed? Suggested configure options for evas for a Linux desktop X display: @@ -213,15 +177,6 @@ make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro" - - - - - - - - - @section tutorial Ecore Tutorial You will find a more comprehensive @ref tut here, going through many examples @@ -240,3 +195,79 @@ with tips and hints as to how best do some things. Here is a tutotial for using Ecore... */ + +/** +@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. + + + + */ + +// GROUP DEFINITIONS + +/** + * @defgroup Ecore_Main_Loop_Group Main Loop Functions + * + * Functions used to control the main loop. + */ + +/** + * @defgroup Ecore_Timer_Group Ecore Timer + * + * The timer allows callbacks to be called at specific intervals. + */ + +/** + * @defgroup Idle_Group Idle Handlers + * + * Callbacks that are called when the program enters or exits an idle state. + * + * The ecore main loop enters an idle state when it is waiting for + * timers to time out, data to come in on a file descriptor or any + * other event to occur. You can set callbacks to be called when the + * main loop enters an idle state, during an idle state or just after + * the program wakes up. + * + * Enterer callbacks are good for updating your program's state, if it + * has a state engine. Once all of the enterer handlers are called, + * the program will enter a "sleeping" state. + * + * Idler callbacks are called when the main loop has called all + * enterer handlers. They are useful for interfaces that require + * polling and timers would be too slow to use. + * + * If no idler callbacks are specified, then the process literally + * goes to sleep. Otherwise, the idler callbacks are called + * continuously while the loop is "idle", using as much CPU as is + * available to the process. + * + * Exiter callbacks are called when the main loop wakes up from an idle + * state. + */ + +// EXAMPLES + +/** + * @example args_example.c + * Shows how to set and retrieve the program arguments. + */ + +/** + * @example event_handler_example.c + * Shows how to use event handlers. + */ + +/** + * @example timer_example.c + * Demonstrates use of the ecore_timer. + */ + +/** + * @example 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. + */ diff --git a/legacy/ecore/examples/Makefile.am b/legacy/ecore/examples/Makefile.am new file mode 100644 index 0000000000..c369652f71 --- /dev/null +++ b/legacy/ecore/examples/Makefile.am @@ -0,0 +1,25 @@ +## Process this file with automake to produce Makefile.in + +bin_PROGRAMS = \ +timer_example \ +event_handler_example \ +args_example \ +config_basic_example + +INCLUDES = \ +-I$(top_srcdir)/src/lib/ecore \ +-I$(top_srcdir)/src/lib/ecore_config + +LDADD = \ +$(top_builddir)/src/lib/ecore/libecore.la \ +$(top_builddir)/src/lib/ecore_config/libecore_config.la \ +-lm @iconv_libs@ + +DEPENDENCIES = \ +$(top_builddir)/src/lib/ecore/libecore.la \ +$(top_builddir)/src/lib/ecore_config/libecore_config.la + +timer_example_SOURCES = timer_example.c +event_handler_example_SOURCES = event_handler_example.c +args_example_SOURCES = args_example.c +config_basic_example_SOURCES = config_basic_example.c diff --git a/legacy/ecore/examples/args_example.c b/legacy/ecore/examples/args_example.c new file mode 100644 index 0000000000..92585c61ee --- /dev/null +++ b/legacy/ecore/examples/args_example.c @@ -0,0 +1,25 @@ +/* Example of how to set and retrieve program arguments. + */ +#include + +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]); + ecore_main_loop_quit(); + return 1; +} + +int main(int argc, char **argv) +{ + ecore_init(); + ecore_app_args_set(argc, argv); + ecore_timer_add(2.0, timer_once, NULL); + ecore_main_loop_begin(); + ecore_shutdown(); + return 0; +} diff --git a/legacy/ecore/examples/config_basic_example.c b/legacy/ecore/examples/config_basic_example.c new file mode 100644 index 0000000000..1d917369c9 --- /dev/null +++ b/legacy/ecore/examples/config_basic_example.c @@ -0,0 +1,93 @@ +/* Shows how to handle the Enlightened Properties Library. + */ + +#include +#include +#include + +#define INT_VAL_KEY "int_val" +#define FLT_VAL_KEY "flt_val" +#define STR_VAL_KEY "str_val" +#define RGB_VAL_KEY "rgb_val" +#define THM_VAL_KEY "thm_val" + +long int_val; +float flt_val; +char *str_val; +char *rgb_val; +char *thm_val; + +void set_defaults (void) { + ecore_config_default_int(INT_VAL_KEY, 0); + ecore_config_default_float(FLT_VAL_KEY, 0.0); + ecore_config_default_string(STR_VAL_KEY, "test1"); + ecore_config_default_rgb(RGB_VAL_KEY, "#000000"); + ecore_config_default_theme(THM_VAL_KEY, "default"); +} + +void get_settings (void) { + /* Note the order here. Defaults are to be set before load, so that the + * types are definitely right. + */ + set_defaults(); + ecore_config_load(); + int_val = ecore_config_get_int(INT_VAL_KEY); + flt_val = ecore_config_get_float(FLT_VAL_KEY); + str_val = ecore_config_get_string(STR_VAL_KEY); + rgb_val = ecore_config_get_rgbstr(RGB_VAL_KEY); + thm_val = ecore_config_get_theme(THM_VAL_KEY); +} + +void change_settings(void) { + int_val += 1; + flt_val += 0.1; + if('9' == str_val[4]) { + str_val[4] = '0'; + } else { + str_val[4] += 1; + } + if('9' == rgb_val[1]) { + rgb_val[1] = '\0'; + rgb_val[3] = '\0'; + rgb_val[5] = '\0'; + } else { + rgb_val[1] += 1; + rgb_val[3] += 1; + rgb_val[5] += 1; + } + if(!strcmp(thm_val, "default")) { + thm_val = strdup("winter"); + } else { + thm_val = strdup("default"); + } +} + +void save_settings (void) { + ecore_config_set_int(INT_VAL_KEY, int_val); + ecore_config_set_float(FLT_VAL_KEY, flt_val); + ecore_config_set_string(STR_VAL_KEY, str_val); + ecore_config_set_rgb(RGB_VAL_KEY, rgb_val); + ecore_config_set_theme(THM_VAL_KEY, thm_val); + ecore_config_save(); +} + +void dump_settings (void) { + printf(" Int Value: %li\n", int_val); + printf(" Float Value: %f\n", flt_val); + printf(" String Value: %s\n", str_val); + printf(" RGB Value: %s\n", rgb_val); + printf(" Theme Value: %s\n", thm_val); +} + +int main (int argc, char **argv) { + ecore_config_init("config_basic_example"); + get_settings(); + printf("--- Original Values ---\n"); + dump_settings(); + change_settings(); + printf("--- Values to be Saved ---\n"); + dump_settings(); + save_settings(); + ecore_config_shutdown(); + return 0; +} diff --git a/legacy/ecore/examples/event_handler_example.c b/legacy/ecore/examples/event_handler_example.c new file mode 100644 index 0000000000..2fe6f60485 --- /dev/null +++ b/legacy/ecore/examples/event_handler_example.c @@ -0,0 +1,39 @@ +/* Ecore Event Handler Example. + */ + +#include + +Ecore_Event_Handler *handler1 = NULL, *handler2 = NULL; + +int event_hup(void *data, int ev_type, void *ev) +{ + printf("Hup signal! Remove the exit handler.\n"); + ecore_event_handler_del(handler1); + return 0; +} + +int event_exit(void *data, int ev_type, void *ev) +{ + 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(); +} diff --git a/legacy/ecore/examples/timer_example.c b/legacy/ecore/examples/timer_example.c new file mode 100644 index 0000000000..e165852da0 --- /dev/null +++ b/legacy/ecore/examples/timer_example.c @@ -0,0 +1,41 @@ +/* Timer example. + */ + +#include + +Ecore_Timer *timer1 = NULL; +Ecore_Timer *timer2 = NULL; +Ecore_Timer *timer3 = NULL; + +char *data1 = "data1"; +char *data2 = "data2"; +char *data3 = "data3"; + +int timer3_tick(void *data) { + printf("Tick timer %3.2f\n", ecore_time_get()); + return 1; +} + +int timer2_tick(void *data) { + printf("Repeat timer called at %3.2f seconds, data %p\n", + ecore_time_get(), data); + return 1; +} + +int timer1_tick(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, timer1_tick, data1); + timer2 = ecore_timer_add(0.5, timer2_tick, data2); + timer3 = ecore_timer_add(1.0, timer3_tick, data3); + ecore_main_loop_begin(); + ecore_shutdown(); + return 0; +} diff --git a/legacy/ecore/src/lib/ecore/ecore_app.c b/legacy/ecore/src/lib/ecore/ecore_app.c index d80b523730..8567699a70 100644 --- a/legacy/ecore/src/lib/ecore/ecore_app.c +++ b/legacy/ecore/src/lib/ecore/ecore_app.c @@ -11,30 +11,6 @@ static char **app_argv = NULL; * * 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 - * - * 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) diff --git a/legacy/ecore/src/lib/ecore/ecore_events.c b/legacy/ecore/src/lib/ecore/ecore_events.c index af49f53cec..37ef00a66e 100644 --- a/legacy/ecore/src/lib/ecore/ecore_events.c +++ b/legacy/ecore/src/lib/ecore/ecore_events.c @@ -37,45 +37,6 @@ static void *ecore_raw_event_event = NULL; * event type. If it returns 0, it will cease processing handlers for that * particular event, so all handler set to handle that event type that have not * already been called, will not be. - * - * @code - * #include - * - * Ecore_Event_Handler *handler1 = NULL, *handler2 = NULL; - * - * int event_hup(void *data, int ev_type, void *ev) - * { - * printf("Hup signal! Remove the exit handler.\n"); - * ecore_event_handler_del(handler1); - * return 0; - * } - * - * int event_exit(void *data, int ev_type, void *ev) - * { - * 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) (void *data, int type, void *event), const void *data) diff --git a/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c b/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c index 16143ce119..7b8c967dd7 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c +++ b/legacy/ecore/src/lib/ecore/ecore_idle_enterer.c @@ -6,18 +6,11 @@ static int idle_enterers_delete_me = 0; /** * Add an idle enterer handler. - * @param func The function to call when entering an idle state. - * @param data The data to be passed to the @p func call - * @return A handle to the idle enterer callback - * - * This function adds an idle enterer handler and returns its handle on success - * or NULL on failure. Idle enterers are called just before he program goes - * int an idle state where it is waiting on timers to time out, data to come - * in on file descriptors, etc. The program will be in a "sleeping" state - * after all the idle enterer callbacks are called. This is a good callback to - * use to update your program's state if it has a state engine. Do all your - * heavy processing here to update state (like drawing etc.). When @p func - * is called, it will be passed the pointer @p data. + * @param func The function to call when entering an idle state. + * @param data The data to be passed to the @p func call + * @return A handle to the idle enterer callback if successful. Otherwise, + * NULL is returned. + * @ingroup Idle_Group */ Ecore_Idle_Enterer * ecore_idle_enterer_add(int (*func) (void *data), const void *data) @@ -35,13 +28,11 @@ ecore_idle_enterer_add(int (*func) (void *data), const void *data) } /** - * Delete an idle enter handler. - * @param idle_enterer The idle enterer to delete - * - * Delete the specified @p idle_enterer from the set of idle_enterers that are - * executed during main loop execution. On success the data pointer that was - * being passed to the idle handler function, set by ecore_idle_enterer_add() - * will be returned. + * Delete an idle enterer callback. + * @param idle_enterer The idle enterer to delete + * @return The data pointer passed to the idler enterer callback on success. + * NULL otherwise. + * @ingroup Idle_Group */ void * ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer) diff --git a/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c b/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c index da45db166c..1b8a6ae7a9 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c +++ b/legacy/ecore/src/lib/ecore/ecore_idle_exiter.c @@ -8,13 +8,8 @@ static int idle_exiters_delete_me = 0; * Add an idle exiter handler. * @param func The function to call when exiting an idle state. * @param data The data to be passed to the @p func call - * @return A handle to the idle exiter callback - * - * This function adds an idle exiter handler and returns its handle on success - * or NULL on failure. Idle exiters are called just after he program wakes up - * from an idle state where it is waiting on timers to time out, data to come - * in on file descriptors, etc. When @p func is called, it will be passed - * the pointer @p data. + * @return A handle to the idle exiter callback on success. NULL otherwise. + * @ingroup Idle_Group */ Ecore_Idle_Exiter * ecore_idle_exiter_add(int (*func) (void *data), const void *data) @@ -32,13 +27,11 @@ ecore_idle_exiter_add(int (*func) (void *data), const void *data) } /** - * Delete an idle exit handler. + * Delete an idle exiter handler from the list to be run on exiting idle state. * @param idle_exiter The idle exiter to delete - * - * Delete the specified @p idle_exiter from the set of idle_exiters that are - * executed during main loop execution. On success the data pointer that was - * being passed to the idle handler function, set by ecore_idle_exiter_add() - * will be returned. + * @return The data pointer that was being being passed to the handler if + * successful. NULL otherwise. + * @ingroup Idle_Group */ void * ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter) diff --git a/legacy/ecore/src/lib/ecore/ecore_idler.c b/legacy/ecore/src/lib/ecore/ecore_idler.c index ed0b3ba675..43324390cd 100644 --- a/legacy/ecore/src/lib/ecore/ecore_idler.c +++ b/legacy/ecore/src/lib/ecore/ecore_idler.c @@ -6,19 +6,10 @@ static int idlers_delete_me = 0; /** * Add an idler handler. - * @param func The function to call when idling. - * @param data The data to be passed to this @p func call - * @return A idler handle - * - * This function adds an idler handler and returns its handle on success, or - * NULL on failure. Idlers will get called after idle enterer calls have all - * been called and the program is in an idle state waiting on data or timers. - * If no idler functions are set the process literally goes to sleep and uses - * no CPU. If You have idler functions set they will be called continuously - * during this "idle" time with your process consuming as much CPU as it can - * get to do so. This is useful for when there are interfaces that require - * polling and timers will mean too slow a response from the process if polling - * is done by timers. + * @param func The function to call when idling. + * @param data The data to be passed to this @p func call. + * @return A idler handle if successfully added. NULL otherwise. + * @ingroup Idle_Group */ Ecore_Idler * ecore_idler_add(int (*func) (void *data), const void *data) @@ -36,13 +27,11 @@ ecore_idler_add(int (*func) (void *data), const void *data) } /** - * Delete an idler handler. - * @param idler The idler to delete - * - * Delete the specified @p idler from the set of idlers that are executed - * during main loop execution. On success the data pointer set by - * ecore_idler_add() and passed to the idler function is returned, or NULL - * on failure. + * Delete an idler callback from the list to be executed. + * @param idler The handle of the idler callback to delete + * @return The data pointer passed to the idler callback on success. NULL + * otherwise. + * @ingroup Idle_Group */ void * ecore_idler_del(Ecore_Idler *idler) diff --git a/legacy/ecore/src/lib/ecore/ecore_list.c b/legacy/ecore/src/lib/ecore/ecore_list.c index a8a11a80c5..d058f2fb1c 100644 --- a/legacy/ecore/src/lib/ecore/ecore_list.c +++ b/legacy/ecore/src/lib/ecore/ecore_list.c @@ -344,9 +344,9 @@ int ecore_list_nodes(Ecore_List * list) /** * @brief Append data to the list. - * @param list: the list to append @data - * @param data: the data to append to @list. - * @return Returns FALSE if an error occurs, TRUE if appended successfully + * @param list The list to append @a data + * @param data The data to append to @a list. + * @return FALSE if an error occurs, TRUE if appended successfully */ inline int ecore_list_append(Ecore_List * list, void *data) { @@ -389,10 +389,10 @@ static int _ecore_list_append_0(Ecore_List * list, Ecore_List_Node *end) } /** - * @brief Prepend data to the beginning of the list - * @param list: the list to prepend @data - * @param data: the data to prepend to @list - * @return Returns FALSE if an error occurs, TRUE if prepended successfully + * Prepend data to the beginning of the list. + * @param list The list to prepend @a data. + * @param data The data to prepend to @a list. + * @return FALSE if an error occurs, TRUE if prepended successfully */ inline int ecore_list_prepend(Ecore_List * list, void *data) { @@ -432,10 +432,10 @@ static int _ecore_list_prepend_0(Ecore_List * list, Ecore_List_Node *start) } /** - * @brief Insert data at the current point in the list - * @param list: the list to hold the inserted @data - * @param data: the data to insert into @list - * @return Returns FALSE on an error, TRUE on success + * Insert data at the current point in the list. + * @param list The list to hold the inserted @a data. + * @param data The data to insert into @a list. + * @return FALSE if there is an error, TRUE on success */ inline int ecore_list_insert(Ecore_List * list, void *data) { @@ -1138,11 +1138,10 @@ inline int ecore_dlist_index(Ecore_DList * list) } /** - * @brief Append data to the list. - * @param list: the list to append @data - * @param data: the data to append to @list - * - * @return Returns FALSE if an error occurs, TRUE if appended successfully + * Append data to the list. + * @param list The list to append @a data + * @param data The data to append to @a list + * @return FALSE if an error occurs, TRUE if appended successfully */ int ecore_dlist_append(Ecore_DList * list, void *data) { @@ -1169,10 +1168,10 @@ int ecore_dlist_append(Ecore_DList * list, void *data) } /** - * @brief Prepend data to the beginning of the list - * @param list: the list to prepend @data - * @param data: the data to prepend to @list - * @return Returns FALSE if an error occurs, TRUE if prepended successfully + * Prepend data to the beginning of the list + * @param list The list to prepend @a data + * @param data The data to prepend to @a list + * @return FALSE if an error occurs, TRUE if prepended successfully */ int ecore_dlist_prepend(Ecore_DList * list, void *data) { @@ -1198,9 +1197,9 @@ int ecore_dlist_prepend(Ecore_DList * list, void *data) } /** - * @brief Insert data at the current point in the list - * @param list: the list to hold the inserted @data - * @param data: the data to insert into @list + * Insert data at the current point in the list. + * @param list The list to hold the inserted @a data. + * @param data The data to insert into @a list. * @return Returns FALSE on an error, TRUE on success */ int ecore_dlist_insert(Ecore_DList * list, void *data) diff --git a/legacy/ecore/src/lib/ecore/ecore_main.c b/legacy/ecore/src/lib/ecore/ecore_main.c index e36e40e50b..29644806a7 100644 --- a/legacy/ecore/src/lib/ecore/ecore_main.c +++ b/legacy/ecore/src/lib/ecore/ecore_main.c @@ -22,6 +22,7 @@ static double t2 = 0.0; /** * Run 1 iteration of the main loop and process everything on the queue. + * @ingroup Ecore_Main_Loop_Group * * This function Processes 1 iteration of the main loop, handling anything on * the queue. See ecore_main_loop_begin() for more information. @@ -34,6 +35,7 @@ ecore_main_loop_iterate(void) /** * Run the application main loop. + * @ingroup Ecore_Main_Loop_Group * * This function does not return until ecore_main_loop_quit() is called. It * will keep looping internally and call all callbacks set up to handle timers, @@ -51,6 +53,7 @@ ecore_main_loop_begin(void) /** * Quit the main loop after it is done processing. + * @ingroup Ecore_Main_Loop_Group * * This function will flag a quit of the main loop once the current loop has * finished processing all events. It will not quit instantly, so expect more diff --git a/legacy/ecore/src/lib/ecore/ecore_path.c b/legacy/ecore/src/lib/ecore/ecore_path.c index cc38398c6c..ffedf399cb 100644 --- a/legacy/ecore/src/lib/ecore/ecore_path.c +++ b/legacy/ecore/src/lib/ecore/ecore_path.c @@ -166,7 +166,7 @@ ecore_path_group_find(int group_id, char *name) * Get a list of all available files in the path * @param group_id The identifier for the path to get all available files * @return A pointer to a newly allocated list of all files found in the paths - * identified by @group_id, NULL on failure. + * identified by @a group_id, NULL on failure. */ Ecore_List * ecore_path_group_available(int group_id) diff --git a/legacy/ecore/src/lib/ecore/ecore_sheap.c b/legacy/ecore/src/lib/ecore/ecore_sheap.c index 06d9f105ac..8e2c074cdf 100644 --- a/legacy/ecore/src/lib/ecore/ecore_sheap.c +++ b/legacy/ecore/src/lib/ecore/ecore_sheap.c @@ -55,11 +55,11 @@ int ecore_sheap_init(Ecore_Sheap *heap, Ecore_Compare_Cb compare, int size) /** * Free up the memory used by the heap - * @param heap The heap to be freed - * @return No value. * - * Frees the memory used by @heap, calls the destroy function on each data + * Frees the memory used by @a heap, calls the destroy function on each data * item if necessary. + * + * @param heap The heap to be freed */ void ecore_sheap_destroy(Ecore_Sheap *heap) { @@ -74,9 +74,9 @@ void ecore_sheap_destroy(Ecore_Sheap *heap) } /** - * Insert new data into the heap - * @param heap The heap to insert @data - * @param data The data to add to @heap + * Insert new data into the heap. + * @param heap The heap to insert @a data. + * @param data The data to add to @a heap. * @return TRUE on success, NULL on failure. Increases the size of the heap if * it becomes larger than available space. */ @@ -257,7 +257,6 @@ int ecore_sheap_set_compare(Ecore_Sheap *heap, Ecore_Compare_Cb compare) * Change the order of the heap * @param heap The heap to change the order * @param order The new order of the heap - * @return No value. * * Changes the heap order of @heap and re-heapifies the data to this new * order. The default order is a min heap. @@ -274,7 +273,6 @@ void ecore_sheap_set_order(Ecore_Sheap *heap, char order) /** * Sort the data in the heap * @param heap The heap to be sorted - * @return No value. * * Sorts the data in the heap into the order that is used for the heap's * data. @@ -330,7 +328,6 @@ inline void *ecore_sheap_item(Ecore_Sheap *heap, int i) * Regain the heap properties starting at position i * @param heap The heap to regain heap properties * @param i The position to start heapifying - * @return No value. */ static void _ecore_sheap_heapify(Ecore_Sheap *heap, int i) { diff --git a/legacy/ecore/src/lib/ecore/ecore_timer.c b/legacy/ecore/src/lib/ecore/ecore_timer.c index 5ea73b1579..94a4855cfe 100644 --- a/legacy/ecore/src/lib/ecore/ecore_timer.c +++ b/legacy/ecore/src/lib/ecore/ecore_timer.c @@ -15,6 +15,7 @@ static Ecore_Timer *timers = NULL; * @param func The function to call when it expires * @param data The data to pass to the function * @return A handle to the new timer + * @ingroup Ecore_Timer_Group * * This function adds a timer and returns its handle on success and NULL on * failure. The function @p func will be called in @p in seconds from the @@ -27,43 +28,8 @@ static Ecore_Timer *timers = NULL; * @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_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(); - * ecore_shutdown(); - * } - * @endcode + * For more information, see the @link timer_example.c ecore_timer @endlink + * example. */ Ecore_Timer * ecore_timer_add(double in, int (*func) (void *data), const void *data) @@ -85,6 +51,7 @@ ecore_timer_add(double in, int (*func) (void *data), const void *data) * Delete the specified timer from the timer list. * @param timer * @return The data pointer set for the timer + * @ingroup Ecore_Timer_Group * * Delete the specified @p timer from the set of timers that are executed * during main loop execution. This function returns the data parameter that diff --git a/legacy/ecore/src/lib/ecore/ecore_tree.c b/legacy/ecore/src/lib/ecore/ecore_tree.c index 6b18c2eb2e..868e346866 100644 --- a/legacy/ecore/src/lib/ecore/ecore_tree.c +++ b/legacy/ecore/src/lib/ecore/ecore_tree.c @@ -285,10 +285,11 @@ void *ecore_tree_get(Ecore_Tree * tree, void *key) } /** - * @brief Find the closest value greater >= key - * @param tree: the tree to search - * @param key: the key to search for in @tree - * @return Returns NULL if no valid nodes, otherwise the node >= key + * @brief Find the closest value greater than or equal to the key. + * @param tree The tree to search. + * @param key The key to search for in @a tree. + * @return NULL if no valid nodes, otherwise the node greater than or + * equal to the key */ void *ecore_tree_get_closest_larger(Ecore_Tree * tree, void *key) { @@ -322,8 +323,8 @@ void *ecore_tree_get_closest_larger(Ecore_Tree * tree, void *key) /** * @brief Find the closest value <= key - * @param tree: the tree to search - * @param key: the key to search for in tree + * @param tree the tree to search + * @param key the key to search for in tree * @return Returns NULL if no valid nodes, otherwise the node <= key */ void *ecore_tree_get_closest_smaller(Ecore_Tree * tree, void *key) @@ -350,11 +351,11 @@ void *ecore_tree_get_closest_smaller(Ecore_Tree * tree, void *key) } /** - * @brief Set the value associated with key to @value - * @param tree: the tree that contains the key/value pair - * @param key: the key to identify which node to set a value - * @param value: value to set the found node - * @return Returns TRUE if successful, FALSE if not. + * Set the value associated with key to @a value. + * @param tree The tree that contains the key/value pair. + * @param key The key to identify which node to set a value. + * @param value Value to set the found node. + * @return TRUE if successful, FALSE if not. */ int ecore_tree_set(Ecore_Tree * tree, void *key, void *value) { @@ -383,10 +384,10 @@ int ecore_tree_set(Ecore_Tree * tree, void *key, void *value) } /** - * @brief Place a node in the tree - * @param tree: the tree to add @node - * @param node: the node to add to @tree - * @brief Returns TRUE on a successful add, FALSE otherwise. + * Place a node in the tree. + * @param tree The tree to add @a node. + * @param node The node to add to @a tree. + * @return TRUE on a successful add, FALSE otherwise. */ int ecore_tree_add_node(Ecore_Tree * tree, Ecore_Tree_Node * node) { @@ -418,10 +419,10 @@ int ecore_tree_add_node(Ecore_Tree * tree, Ecore_Tree_Node * node) /** - * @brief Remove the node from the tree - * @param tree: the tree to remove @node - * @param node: the node to remove from @tree - * @return Returns TRUE on a successful remove, FALSE otherwise. + * Remove the node from the tree. + * @param tree The tree to remove @a node from. + * @param node The node to remove from @a tree. + * @return TRUE on a successful remove, FALSE otherwise. */ int ecore_tree_remove_node(Ecore_Tree * tree, Ecore_Tree_Node * node) { @@ -526,10 +527,10 @@ int ecore_tree_remove_node(Ecore_Tree * tree, Ecore_Tree_Node * node) } /** - * @brief Remove the key from the tree - * @param tree: the tree to remove @key - * @param key: the key to remove from @tree - * @return Returns TRUE on a successful remove, FALSE otherwise. + * Remove the key from the tree. + * @param tree The tree to remove @a key. + * @param key The key to remove from @a tree. + * @return TRUE on a successful remove, FALSE otherwise. */ int ecore_tree_remove(Ecore_Tree * tree, void *key) { diff --git a/legacy/ecore/src/lib/ecore/ecore_value.c b/legacy/ecore/src/lib/ecore/ecore_value.c index 6274fcfcf0..880eb207d0 100644 --- a/legacy/ecore/src/lib/ecore/ecore_value.c +++ b/legacy/ecore/src/lib/ecore/ecore_value.c @@ -55,7 +55,7 @@ unsigned int ecore_direct_hash(void *key) /** * Compute the hash value of a string * @param key A pointer to the string to compute a hash value - * @return A computed hash value for @key. + * @return A computed hash value for @a key. */ unsigned int ecore_str_hash(void *key) { diff --git a/legacy/ecore/src/lib/ecore_evas/ecore_evas.c b/legacy/ecore/src/lib/ecore_evas/ecore_evas.c index d14ca74a9f..25478092f4 100644 --- a/legacy/ecore/src/lib/ecore_evas/ecore_evas.c +++ b/legacy/ecore/src/lib/ecore_evas/ecore_evas.c @@ -1005,7 +1005,8 @@ ecore_evas_size_step_get(Ecore_Evas *ee, int *w, int *h) /** * Set the cursor of an Ecore_Evas * @param ee The Ecore_Evas - * @param file The path to an image file for the cursor + * @param file The path to an image file for the cursor + * @param layer * @param hot_x The x coordinate of the cursor's hot spot * @param hot_y The y coordinate of the cursor's hot spot * diff --git a/legacy/ecore/src/lib/ecore_x/ecore_x_window_prop.c b/legacy/ecore/src/lib/ecore_x/ecore_x_window_prop.c index 6148615e9d..cf4512ac88 100644 --- a/legacy/ecore/src/lib/ecore_x/ecore_x_window_prop.c +++ b/legacy/ecore/src/lib/ecore_x/ecore_x_window_prop.c @@ -243,11 +243,11 @@ ecore_x_window_prop_title_get(Ecore_X_Window win) } /** - * Set a window command. - * @param win The window - * @param t The command string + * Sets the WM_COMMAND property for @a win. * - * Set a window command + * @param win The window. + * @param argc Number of arguments. + * @param argv Arguments. */ void ecore_x_window_prop_command_set(Ecore_X_Window win, int argc, char **argv) @@ -256,11 +256,13 @@ ecore_x_window_prop_command_set(Ecore_X_Window win, int argc, char **argv) } /** - * Get a window command. - * @param win The window - * @return The windows command string - * + * Get the WM_COMMAND property for @a win. + * * Return the command of a window. String must be free'd when done with. + * + * @param win The window. + * @param argc Number of arguments. + * @param argv Arguments. */ void ecore_x_window_prop_command_get(Ecore_X_Window win, int *argc, char ***argv) @@ -621,9 +623,9 @@ ecore_x_window_prop_xy_set(Ecore_X_Window win, int x, int y) } /** - * Sets the sticky state for @win + * Sets the sticky state for @a win. * @param win The window - * @param on Boolean representing the sticky state + * @param on Boolean representing the sticky state */ void ecore_x_window_prop_sticky_set(Ecore_X_Window win, int on) @@ -651,10 +653,10 @@ ecore_x_window_prop_sticky_set(Ecore_X_Window win, int on) } /** - * Sets the input mode for @win + * Sets the input mode for @a win * @param win The Window * @param mode The input mode. See the description of - * @Ecore_X_Window_Input_Mode for details + * #_Ecore_X_Window_Input_Mode for details. * @return 1 if the input mode could be set, else 0 */ int @@ -741,22 +743,22 @@ ecore_x_window_prop_borderless_set(Ecore_X_Window win, int borderless) } /** - * Puts @win in the desired layer. This currently works with + * Puts @a win in the desired layer. This currently works with * windowmanagers that are Gnome-compliant or support NetWM. * - * @param win - * @param layer If < 3, @win will be put below all other windows. - * If > 5, @win will be "always-on-top" - * If = 4, @win will be put in the default layer. - * Acceptable values range from 1 to 255 (0 reserved for - * desktop windows) - * @return 1 if the state could be set else 0 - * * Normally you will use this function with one of the predefined * layer constants: * ECORE_X_WINDOW_LAYER_BELOW - for windows to be stacked below * ECORE_X_WINDOW_LAYER_ABOVE - for windows to be stacked on top * ECORE_X_WINDOW_LAYER_NORMAL - for windows to be put in the default layer + + * @param win + * @param layer If < 3, @a win will be put below all other windows. + * If > 5, @a win will be "always-on-top" + * If = 4, @a win will be put in the default layer. + * Acceptable values range from 1 to 255 (0 reserved for + * desktop windows) + * @return 1 if the state could be set else 0 */ int ecore_x_window_prop_layer_set(Ecore_X_Window win, int layer) @@ -785,7 +787,6 @@ ecore_x_window_prop_layer_set(Ecore_X_Window win, int layer) * Set the withdrawn state of an Ecore_X_Window. * @param win The window whose withdrawn state is set. * @param withdrawn The window's new withdrawn state. - * */ void ecore_x_window_prop_withdrawn_set(Ecore_X_Window win, int withdrawn) @@ -817,8 +818,6 @@ ecore_x_window_prop_withdrawn_set(Ecore_X_Window win, int withdrawn) * Request the window manager to change this windows desktop. * @param win The Window * @param desktop The desktop number. - * - * Request the window manager to change this windows desktop. */ void ecore_x_window_prop_desktop_request(Ecore_X_Window win, long desktop) @@ -840,12 +839,13 @@ ecore_x_window_prop_desktop_request(Ecore_X_Window win, long desktop) /** * Request the window manager to change this window's state. - * @param win The Window - * @param state The requested state - * @param action The action to perform: 0 - unset, 1 - set, 2 - toggle * * Use this function to request the window manager to change the * specified window's state after it has been displayed (mapped). + * + * @param win The Window + * @param state The requested state + * @param action The action to perform: 0 - unset, 1 - set, 2 - toggle */ void ecore_x_window_prop_state_request(Ecore_X_Window win, Ecore_X_Window_State state, int action)