Some restructuring, clean up, grouping, explaining, etc. Getting there...
SVN revision: 11696
This commit is contained in:
ncn
ncn
parent
e1191d8aab
commit
4dc39d4dfa
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <sys/types.h>
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue