diff --git a/legacy/ecore/ecore.c.in b/legacy/ecore/ecore.c.in index f2337a5810..3780e2850c 100644 --- a/legacy/ecore/ecore.c.in +++ b/legacy/ecore/ecore.c.in @@ -25,10 +25,16 @@ These routines are used for Ecore Library interaction Ecore is a library of convenience functions. -Currently, Ecore provides the following modules: -@li @ref Ecore_Main_Loop_Page -@li @ref Ecore_Config_Page -@li @ref X_Window_System_Page +The Ecore library provides the following modules: +@li @link Ecore.h Ecore - Main Loop Functions. @endlink +@li @link Ecore_Con.h Ecore_Con - Connection functions. @endlink +@li @link Ecore_Config.h Ecore_Config - Configuration functions. @endlink +@li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink +@li @link Ecore_Fb.h Ecore_FB - Frame buffer convenience functions. @endlink +@li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink +@li @link Ecore_Job.h Ecore_Job - Job functions, to be used in the Ecore main loop. @endlink +@li @link Ecore_Txt.h Ecore_Txt - Text encoding conversion. @endlink +@li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink @section compiling How to compile using Ecore? @@ -64,7 +70,7 @@ make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro" */ -/** +/* @page Ecore_Main_Loop_Page The Ecore Main Loop @section intro What is Ecore? @@ -188,33 +194,6 @@ follows the same principles as shown in this example. */ -/** -@page Ecore_Con_Page The Ecore Connection Library - -The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms -for communications between programs using reliable sockets. It saves -the programmer from having to worry about file descripters and waiting -for incoming connections. - -There are two main objects in the @c Ecore_Con library: the @c -Ecore_Con_Server and the @c Ecore_Con_Client. - -The @c Ecore_Con_Server represents a server to connect to. It is -represents a server that can be connected to. It is used regardless -of whether the program is acting as a server or client itself. - -To create a listening server, call @c ecore_con_server_add(). - -To connect to a server, call @c ecore_Con_server_connect(). Data can -then be sent to the server using the @c ecore_con_server_send(). - -Whenever a client connection is made to an @c Ecore_Con_Server, a -@c ECORE_CON_CLIENT_ADD event is emitted. Any event callbacks that are -called receive a @c Ecore_Con_Client object, which represents a -connection that that particular client. - - */ - /** @page Ecore_Config_Page The Enlightened Property Library @@ -290,12 +269,6 @@ that are used. // GROUP DEFINITIONS -/** -@defgroup Ecore_Main_Loop_Group Main Loop Functions - -Functions used to control the main loop. -*/ - /** @defgroup Ecore_Timer_Group Ecore Timer diff --git a/legacy/ecore/src/lib/ecore/Ecore.h b/legacy/ecore/src/lib/ecore/Ecore.h index 87568caf53..4c876586a1 100644 --- a/legacy/ecore/src/lib/ecore/Ecore.h +++ b/legacy/ecore/src/lib/ecore/Ecore.h @@ -6,9 +6,18 @@ * @brief The file that provides the program utility, main loop and timer * functions. * - * The following groups of functions are included with this file: - * @li @ref Ecore_Exe_Basic_Group - * @li @ref Ecore_Exe_Signal_Group + * This header provides the Ecore event handling loop. For more + * details, see @ref Ecore_Main_Loop_Group. + * + * For the main loop to be of any use, you need to be able to add events + * and event handlers. + * + * There is also provision for callbacks for when the loop enters or + * exits an idle state. See @ref Idle_Group for more information. + * + * Functions are also provided for spawning child processes using fork. + * See @ref Ecore_Exe_Basic_Group and @ref Ecore_Exe_Signal_Group for + * more details. */ #include diff --git a/legacy/ecore/src/lib/ecore/ecore_main.c b/legacy/ecore/src/lib/ecore/ecore_main.c index c87ad6922e..b964bb4218 100644 --- a/legacy/ecore/src/lib/ecore/ecore_main.c +++ b/legacy/ecore/src/lib/ecore/ecore_main.c @@ -31,11 +31,29 @@ static double t1 = 0.0; static double t2 = 0.0; /** - * Run 1 iteration of the main loop and process everything on the queue. - * @ingroup Ecore_Main_Loop_Group + * @defgroup Ecore_Main_Loop_Group Main Loop Functions + * + * These functions control the Ecore event handling loop. This loop is + * designed to work on embedded systems all the way to large and + * powerful mutli-cpu workstations. + * + * It serialises all system signals and events into a single event + * queue, that can be easily processed without needing to worry about + * concurrency. A properly written, event-driven program using this + * kind of programming does not need threads. It makes the program very + * robust and easy to follow. * - * This function Processes 1 iteration of the main loop, handling anything on - * the queue. See ecore_main_loop_begin() for more information. + * Here is an example of simple program and its basic event loop flow: + * @image html prog_flow.png + * + * For examples of setting up and using a main loop, see + * @ref event_handler_example.c and @ref timer_example.c. + */ + +/** + * Runs a single iteration of the main loop to process everything on the + * queue. + * @ingroup Ecore_Main_Loop_Group */ void ecore_main_loop_iterate(void) @@ -44,13 +62,11 @@ ecore_main_loop_iterate(void) } /** - * Run the application main loop. + * Runs the application main loop. + * + * This function will not return until @ref ecore_main_loop_quit is called. + * * @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, - * idle state and events Ecore recieves from X, fd's, IPC, signals etc. and - * anything else that has registered a handler with ecore itself. */ void ecore_main_loop_begin(void) @@ -62,12 +78,9 @@ ecore_main_loop_begin(void) } /** - * Quit the main loop after it is done processing. + * Quits the main loop once all the events currently on the queue have + * been processed. * @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 - * callbacks to be called after this command has been issued. */ void ecore_main_loop_quit(void) @@ -75,6 +88,12 @@ ecore_main_loop_quit(void) do_quit = 1; } +/** + * @defgroup Ecore_FD_Handler_Group File Event Handling Functions + * + * To be written. + */ + /** * Add a handler for read/write notification of a file descriptor. * @param fd The file descriptor to watch @@ -155,11 +174,10 @@ ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler) } /** - * Return the file descriptor that the handler is handling - * @param fd_handler The fd handler to query - * @return The fd the handler is watching - * - * This returns the fd the @p fd_handler is monitoring. + * Returns the file descriptor that the given handler is handling. + * @param fd_handler The given FD handler. + * @return The file descriptor the handler is watching + * @ingroup Ecore_FD_Handler_Group */ int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler) diff --git a/legacy/ecore/src/lib/ecore_con/ecore_con.c b/legacy/ecore/src/lib/ecore_con/ecore_con.c index 3b1b077de0..f802ed98c1 100644 --- a/legacy/ecore/src/lib/ecore_con/ecore_con.c +++ b/legacy/ecore/src/lib/ecore_con/ecore_con.c @@ -46,10 +46,18 @@ static int init_count = 0; #define LENGTH_OF_SOCKADDR_UN(s) (strlen((s)->sun_path) + (size_t)(((struct sockaddr_un *)NULL)->sun_path)) +/** + * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions + * + * Utility functions that set up and shut down the Ecore Connection + * library. + */ + /** * Initialises the Ecore_Con library. - * @return Number of times the library has been initialised without being - * shut down. + * @return Number of times the library has been initialised without being + * shut down. + * @ingroup Ecore_Con_Lib_Group */ int ecore_con_init(void) @@ -74,8 +82,9 @@ ecore_con_init(void) /** * Shuts down the Ecore_Con library. - * @return Number of times the library has been initialised without being - * shut down. + * @return Number of times the library has been initialised without being + * shut down. + * @ingroup Ecore_Con_Lib_Group */ int ecore_con_shutdown(void) @@ -89,6 +98,12 @@ ecore_con_shutdown(void) return 0; } +/** + * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions + * + * Functions that operate on Ecore server objects. + */ + /** * Creates a server to listen for connections. * @@ -113,6 +128,7 @@ ecore_con_shutdown(void) * @param data Data to associate with the created Ecore_Con_Server * object. * @return A new Ecore_Con_Server. + * @ingroup Ecore_Con_Server_Group */ Ecore_Con_Server * ecore_con_server_add(Ecore_Con_Type compl_type, @@ -331,6 +347,7 @@ ecore_con_server_add(Ecore_Con_Type compl_type, * @param data Data to associate with the created Ecore_Con_Server * object. * @return A new Ecore_Con_Server. + * @ingroup Ecore_Con_Server_Group */ Ecore_Con_Server * ecore_con_server_connect(Ecore_Con_Type compl_type, @@ -478,8 +495,9 @@ ecore_con_server_connect(Ecore_Con_Type compl_type, /** * Closes the connection and frees the given server. - * @param svr The given server. - * @return Data associated with the server when it was created. + * @param svr The given server. + * @return Data associated with the server when it was created. + * @ingroup Ecore_Con_Server_Group */ void * ecore_con_server_del(Ecore_Con_Server *svr) @@ -499,8 +517,9 @@ ecore_con_server_del(Ecore_Con_Server *svr) /** * Retrieves the data associated with the given server. - * @param svr The given server. - * @return The associated data. + * @param svr The given server. + * @return The associated data. + * @ingroup Ecore_Con_Server_Group */ void * ecore_con_server_data_get(Ecore_Con_Server *svr) @@ -517,8 +536,9 @@ ecore_con_server_data_get(Ecore_Con_Server *svr) /** * Retrieves whether the given server is currently connected. * @todo Check that this function does what the documenter believes it does. - * @param svr The given server. - * @return @c 1 if the server is connected. @c 0 otherwise. + * @param svr The given server. + * @return @c 1 if the server is connected. @c 0 otherwise. + * @ingroup Ecore_Con_Server_Group */ int ecore_con_server_connected_get(Ecore_Con_Server *svr) @@ -535,11 +555,12 @@ ecore_con_server_connected_get(Ecore_Con_Server *svr) /** * Sends the given data to the given server. - * @param svr The given server. - * @param data The given data. - * @param size Length of the data, in bytes, to send. - * @return The number of bytes sent. @c 0 will be returned if there is an - * error. + * @param svr The given server. + * @param data The given data. + * @param size Length of the data, in bytes, to send. + * @return The number of bytes sent. @c 0 will be returned if there is an + * error. + * @ingroup Ecore_Con_Server_Group */ int ecore_con_server_send(Ecore_Con_Server *svr, void *data, int size) @@ -573,14 +594,21 @@ ecore_con_server_send(Ecore_Con_Server *svr, void *data, int size) } return size; } - + +/** + * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions + * + * Functions that operate on Ecore connection client objects. + */ + /** * Sends the given data to the given client. - * @param cl The given client. - * @param data The given data. - * @param size Length of the data, in bytes, to send. - * @return The number of bytes sent. @c 0 will be returned if there is an - * error. + * @param cl The given client. + * @param data The given data. + * @param size Length of the data, in bytes, to send. + * @return The number of bytes sent. @c 0 will be returned if there is an + * error. + * @ingroup Ecore_Con_Client_Group */ int ecore_con_client_send(Ecore_Con_Client *cl, void *data, int size) @@ -618,8 +646,9 @@ ecore_con_client_send(Ecore_Con_Client *cl, void *data, int size) /** * Retrieves the server representing the socket the client has * connected to. - * @param cl The given client. - * @return The server that the client connected to. + * @param cl The given client. + * @return The server that the client connected to. + * @ingroup Ecore_Con_Client_Group */ Ecore_Con_Server * ecore_con_client_server_get(Ecore_Con_Client *cl) @@ -635,8 +664,9 @@ ecore_con_client_server_get(Ecore_Con_Client *cl) /** * Closes the connection and frees memory allocated to the given client. - * @param cl The given client. - * @return Data associated with the client. + * @param cl The given client. + * @return Data associated with the client. + * @ingroup Ecore_Con_Client_Group */ void * ecore_con_client_del(Ecore_Con_Client *cl) @@ -656,8 +686,9 @@ ecore_con_client_del(Ecore_Con_Client *cl) /** * Sets the data associated with the given client to @p data. - * @param cl The given client. - * @param data What to set the data to. + * @param cl The given client. + * @param data What to set the data to. + * @ingroup Ecore_Con_Client_Group */ void ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data) @@ -673,8 +704,9 @@ ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data) /** * Retrieves the data associated with the given client. - * @param cl The given client. - * @return The data associated with @p cl. + * @param cl The given client. + * @return The data associated with @p cl. + * @ingroup Ecore_Con_Client_Group */ void * ecore_con_client_data_get(Ecore_Con_Client *cl) diff --git a/legacy/ecore/src/lib/ecore_x/Ecore_X.h b/legacy/ecore/src/lib/ecore_x/Ecore_X.h index fed1bfb715..9112161430 100644 --- a/legacy/ecore/src/lib/ecore_x/Ecore_X.h +++ b/legacy/ecore/src/lib/ecore_x/Ecore_X.h @@ -7,7 +7,14 @@ /** * @file - * @brief Ecore functions for dealing with the X Windows system + * @brief Ecore functions for dealing with the X Windows System + * + * Ecore_X provides a wrapper and convenience functions for using the + * X Windows System. Function groups for this part of the library + * include the following: + * @li @ref Ecore_X_Init_Group + * @li @ref Ecore_X_Display_Attr_Group + * @li @ref Ecore_X_Flush_Group */ typedef unsigned int Ecore_X_ID; diff --git a/legacy/ecore/src/lib/ecore_x/ecore_x.c b/legacy/ecore/src/lib/ecore_x/ecore_x.c index ed49c76f19..a29ff464fc 100644 --- a/legacy/ecore/src/lib/ecore_x/ecore_x.c +++ b/legacy/ecore/src/lib/ecore_x/ecore_x.c @@ -211,7 +211,7 @@ int ECORE_X_LOCK_NUM = 0; int ECORE_X_LOCK_CAPS = 0; /** - * @defgroup Ecore_X_Init_Group Ecore X Library Init and Shutdown Functions + * @defgroup Ecore_X_Init_Group X Library Init and Shutdown Functions * * Functions that start and shut down the Ecore X Library. */ @@ -537,7 +537,7 @@ ecore_x_disconnect(void) } /** - * @defgroup Ecore_X_Display_Attr_Group Ecore X Display Attributes + * @defgroup Ecore_X_Display_Attr_Group X Display Attributes * * Functions that set and retrieve X display attributes. */ @@ -596,7 +596,7 @@ ecore_x_double_click_time_get(void) } /** - * @defgroup Ecore_X_Flush_Group Ecore X Synchronization Functions + * @defgroup Ecore_X_Flush_Group X Synchronization Functions * * Functions that ensure that all commands that have been issued by the * Ecore X library have been sent to the server.