more docs from nicholas curran

SVN revision: 10170
This commit is contained in:
atmosphere 2004-05-12 14:40:08 +00:00 committed by atmosphere
parent 67a93c6f68
commit 3bf171d7d0
9 changed files with 720 additions and 356 deletions

View File

@ -18,9 +18,64 @@ These routines are used for Ecore Library interaction
@author Chris Ross <chris\@darkrock.co.uk>
@author Term <term\@twistedpath.org>
@author Tilman Sauerbeck <tilman\@code-monkey.de>
@date 2000-2003
@date 2000-2004
@section intro Introduction
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
@section compiling How to compile using Ecore?
This section has to be documented. Below is just a quick line to handle all
Ecore modules at once.
@verbatim
gcc *.c \
-I/usr/local/include -I/usr/X11R6/include \
-L/usr/local/lib -L/usr/X11R6/lib \
-lecore -lecore_evas -lecore_x -lecore_fb -lecore_job \
`evas-config --cflags --libs`
@endverbatim
@section install How is it installed?
Suggested configure options for evas for a Linux desktop X display:
@verbatim
./configure \
--enable-ecore-x \
--enable-ecore-fb \
--enable-ecore-evas \
--enable-ecore-evas-gl \
--enable-ecore-job \
--enable-ecore-con \
--enable-ecore-ipc \
--enable-ecore-txt
make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim
@section tutorial Ecore Tutorial
You will find a more comprehensive @ref tut here, going through many examples
with tips and hints as to how best do some things.
@todo (1.0) Document API
*/
/** @page tut Ecore Tutorial
Here is a tutotial for using Ecore...
*/
/**
@page Ecore_Main_Loop_Page The Ecore Main Loop
@section intro What is Ecore?
@ -141,125 +196,198 @@ things, but in principle, programs don't get any more complex. You add more
event handlers, for more events, will have more timers and such, BUT it all
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
Ecore modules at once.
@verbatim
gcc *.c \
-I/usr/local/include -I/usr/X11R6/include \
-L/usr/local/lib -L/usr/X11R6/lib \
-lecore -lecore_evas -lecore_x -lecore_fb -lecore_job \
`evas-config --cflags --libs`
@endverbatim
@section install How is it installed?
Suggested configure options for evas for a Linux desktop X display:
@verbatim
./configure \
--enable-ecore-x \
--enable-ecore-fb \
--enable-ecore-evas \
--enable-ecore-evas-gl \
--enable-ecore-job \
--enable-ecore-con \
--enable-ecore-ipc \
--enable-ecore-txt
make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
@endverbatim
@section tutorial Ecore Tutorial
You will find a more comprehensive @ref tut here, going through many examples
with tips and hints as to how best do some things.
@todo (1.0) Document API
*/
/** @page tut Ecore Tutorial
Here is a tutotial for using Ecore...
*/
/**
@page The Enlightened Property Library
@page Ecore_Config_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.
To use the library, you:
@li Set the default values of your properties.
@li Load the configuration from a file. You must set the default values
first, so that the library knows the correct type of each argument.
See @ref config_basic_example.c for an example.
*/
*/
/**
@page Ecore_ADT_Page Ecore Abstract Data Types
This page briefly describes the different abstract data types
that are provided by the Ecore library for general usage. You need to
include the @link Ecore_Data.h Ecore_Data.h @endlink to use them.
@section Ecore_ADT_List List
A list is a simple data type where one each piece of data points to
another piece of data.
Associated modules include the following:
@li @ref Ecore_Data_List_Add_Item_Group
@section Ecore_ADT_DList Doubly Linked List
A doubly linked list is like a linked list, only each piece of data
can also point to the piece before it.
@section Ecore_ADT_Hash Hash
@todo Finish this.
*/
/**
@page X_Window_System_Page X Window System
The Ecore library includes a wrapper for handling the X window system.
This page briefly explains what the X window system is and various terms
that are used.
*/
// GROUP DEFINITIONS
/**
* @defgroup Ecore_Main_Loop_Group Main Loop Functions
*
* Functions used to control the main loop.
@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 Ecore_Timer_Group Ecore Timer
*
* The timer allows callbacks to be called at specific intervals.
*/
@defgroup Ecore_Job_Group Ecore Jobs
You can queue jobs that are to be done by the main loop when the current
event is dealt with.
*/
/**
* @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.
*/
@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.
*/
/**
@defgroup Ecore_Data_List_Creation_Group List Creation/Destruction Functions
Functions that create, initialize and destory Ecore_Lists.
*/
/**
@defgroup Ecore_Data_List_Add_Item_Group List Item Adding Functions
Functions that are used to add nodes to an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Remove_Item_Group List Item Removing Functions
Functions that remove nodes from an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Traverse_Group List Traversal Functions
Functions that can be used to traverse an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Node_Group List Node Functions
Functions that are used in the creation, maintenance and destruction of
Ecore_List nodes.
*/
/**
@defgroup Ecore_Config_Lib_Group Ecore Config Library Functions
Functions that are used to start up and shutdown the Ecore Configuration
Library.
*/
/**
@defgroup Ecore_Config_Property_Group Ecore Config Property Functions
Functions that retrieve or set the attributes relating to a property.
*/
/**
@defgroup Ecore_Config_Get_Group Ecore Config Retrievers
Functions that return the value of a property, based on its key.
*/
/**
@defgroup Ecore_Config_Default_Group Ecore Config Defaults
Functions that are used to set the default values of properties.
*/
/**
@defgroup Ecore_Config_Create_Group Ecore Config Create Functions
Convenience functions that set default values, bounds, option values and
descriptions in one call.
*/
/**
@defgroup Ecore_Config_Set_Group Ecore Config Setters
Functions that set the value of a property.
*/
/**
@defgroup Ecore_Config_Listeners_Group Ecore Config Listeners
Functions that set and unset property listener callbacks.
*/
/**
@defgroup Ecore_Config_File_Group Ecore Config File Functions
Functions that are used to load and save properties from and to files.
*/
// EXAMPLES
/**
* @example args_example.c
* Shows how to set and retrieve the program arguments.
*/
@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 event_handler_example.c
Shows how to use event handlers.
*/
/**
* @example timer_example.c

View File

@ -1,6 +1,6 @@
## Process this file with automake to produce Makefile.in
bin_PROGRAMS = \
noinst_PROGRAMS = \
timer_example \
event_handler_example \
args_example \

View File

@ -31,7 +31,6 @@ int timer1_tick(void *data) {
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);

View File

@ -202,8 +202,9 @@ _ecore_list_find(void *in_list, void *in_item)
/* XXX: End deprecated code */
/**
* @brief Create and initialize a new list.
* @return Returns a new initialized list on success, NULL on failure.
* Create and initialize a new list.
* @return A new initialized list on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Creation_Group
*/
Ecore_List *ecore_list_new()
{
@ -222,9 +223,10 @@ Ecore_List *ecore_list_new()
}
/**
* @brief Initialize a list to some sane starting values.
* @param list: the list to initialize
* @return Returns FALSE if an error occurs, TRUE if successful
* Initialize a list to some sane starting values.
* @param list The list to initialize.
* @return @c TRUE if successful, @c FALSE if an error occurs.
* @ingroup Ecore_Data_List_Creation_Group
*/
int ecore_list_init(Ecore_List *list)
{
@ -238,9 +240,9 @@ int ecore_list_init(Ecore_List *list)
}
/**
* @brief Free a list and all of it's nodes.
* @param list: the list to be freed
* @return Returns no value
* Free a list and all of it's nodes.
* @param list The list to be freed.
* @ingroup Ecore_Data_List_Creation_Group
*/
void ecore_list_destroy(Ecore_List * list)
{
@ -263,10 +265,11 @@ void ecore_list_destroy(Ecore_List * list)
}
/**
* @brief Set the function for freeing data
* @param list: the list that will use this function when nodes are destroyed.
* @param free_func: the function that will free the key data
* @return Returns TRUE on successful set, FALSE otherwise.
* Set the function for freeing data.
* @param list The list that will use this function when nodes are
* destroyed.
* @param free_func The function that will free the key data.
* @return @c TRUE on successful set, @c FALSE otherwise.
*/
int ecore_list_set_free_cb(Ecore_List * list, Ecore_Free_Cb free_func)
{
@ -282,9 +285,9 @@ int ecore_list_set_free_cb(Ecore_List * list, Ecore_Free_Cb free_func)
}
/**
* @brief Checks the list for any nodes.
* @param list: the list to check for nodes
* @return Returns TRUE if no nodes in list, FALSE if the list contains nodes
* Checks the list for any nodes.
* @param list The list to check for nodes
* @return @c TRUE if no nodes in list, @c FALSE if the list contains nodes
*/
int ecore_list_is_empty(Ecore_List * list)
{
@ -303,9 +306,9 @@ int ecore_list_is_empty(Ecore_List * list)
}
/**
* @brief Returns the number of the current node
* @param list: the list to return the number of the current node
* @return Returns the number of the current node in the list.
* Returns the number of the current node.
* @param list The list to return the number of the current node.
* @return The number of the current node in the list.
*/
int ecore_list_index(Ecore_List * list)
{
@ -323,9 +326,9 @@ int ecore_list_index(Ecore_List * list)
}
/**
* @brief Find the number of nodes in the list.
* @param list: the list to find the number of nodes
* @return Returns the number of nodes in the list.
* Find the number of nodes in the list.
* @param list The list to find the number of nodes
* @return The number of nodes in the list.
*/
int ecore_list_nodes(Ecore_List * list)
{
@ -343,10 +346,11 @@ int ecore_list_nodes(Ecore_List * list)
}
/**
* @brief 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
* Append data to the list.
* @param list The list.
* @param data The data to append.
* @return @c FALSE if an error occurs, @c TRUE if appended successfully
* @ingroup Ecore_Data_List_Add_Item_Group
*/
inline int ecore_list_append(Ecore_List * list, void *data)
{
@ -390,9 +394,10 @@ static int _ecore_list_append_0(Ecore_List * list, Ecore_List_Node *end)
/**
* 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
* @param list The list.
* @param data The data to prepend.
* @return @c FALSE if an error occurs, @c TRUE if prepended successfully.
* @ingroup Ecore_Data_List_Add_Item_Group
*/
inline int ecore_list_prepend(Ecore_List * list, void *data)
{
@ -433,9 +438,10 @@ static int _ecore_list_prepend_0(Ecore_List * list, Ecore_List_Node *start)
/**
* 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
* @param list The list to hold the inserted @p data.
* @param data The data to insert into @p list.
* @return @c FALSE if there is an error, @c TRUE on success
* @ingroup Ecore_Data_List_Add_Item_Group
*/
inline int ecore_list_insert(Ecore_List * list, void *data)
{
@ -494,9 +500,10 @@ static int _ecore_list_insert(Ecore_List * list, Ecore_List_Node *new_node)
}
/**
* @brief Remove the current item from the list.
* @param list: the list to remove the current item
* @return Returns a pointer to the removed data on success, NULL on failure.
* Remove the current item from the list.
* @param list The list to remove the current item
* @return A pointer to the removed data on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Remove_Item_Group
*/
inline void *ecore_list_remove(Ecore_List * list)
{
@ -556,9 +563,10 @@ static void *_ecore_list_remove_0(Ecore_List * list)
}
/**
* @brief Remove and free the data in lists current position
* @param list: the list to remove and free the current item
* @return Returns TRUE on success, FALSE on error
* Remove and free the data in lists current position.
* @param list The list to remove and free the current item.
* @return @c TRUE on success, @c FALSE on error
* @ingroup Ecore_Data_List_Remove_Item_Group
*/
int ecore_list_remove_destroy(Ecore_List *list)
{
@ -577,9 +585,11 @@ int ecore_list_remove_destroy(Ecore_List *list)
}
/**
* @brief Remove the first item from the list.
* @param list: the list to remove the current item
* @return Returns a pointer to the removed data on success, NULL on failure.
* Remove the first item from the list.
* @param list The list to remove the current item
* @return Returns a pointer to the removed data on success, @c NULL on
* failure.
* @ingroup Ecore_Data_List_Remove_Item_Group
*/
inline void *ecore_list_remove_first(Ecore_List * list)
{
@ -635,9 +645,10 @@ static void *_ecore_list_remove_first(Ecore_List * list)
}
/**
* @brief Remove the last item from the list.
* @param list: the list to remove the last node from
* @return Returns a pointer to the removed data on success, NULL on failure.
* Remove the last item from the list.
* @param list The list to remove the last node from
* @return A pointer to the removed data on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Remove_Item_Group
*/
inline void *ecore_list_remove_last(Ecore_List * list)
{
@ -698,10 +709,11 @@ static void *_ecore_list_remove_last(Ecore_List * list)
}
/**
* @brief Move the current item to the index number
* @param list: the list to move the current item
* @param index: the position to move the current item
* @return Returns a pointer to new current item on success, NULL on failure.
* Make the current item the item with the given index number.
* @param list The list.
* @param index The position to move the current item.
* @return A pointer to new current item on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Traverse_Group
*/
inline void *ecore_list_goto_index(Ecore_List * list, int index)
{
@ -741,11 +753,11 @@ static void *_ecore_list_goto_index(Ecore_List *list, int index)
}
/**
* @brief Move the current item to the node that contains data
* @param list: the list to move the current item in
* @param data: the data to find and set the current item to
*
* @return Returns a pointer to @a data on success, NULL on failure.
* Make the current item the node that contains @p data.
* @param list The list.
* @param data The data to find.
* @return A pointer to @p data on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Traverse_Group
*/
inline void *ecore_list_goto(Ecore_List * list, void *data)
{
@ -799,9 +811,10 @@ static void *_ecore_list_goto(Ecore_List * list, void *data)
}
/**
* @brief Move the current pointer to the first item in the list
* @param list: the list to move the current pointer in
* @return Returns a pointer to the first item on success, NULL on failure
* Make the current item the first item in the list
* @param list The list.
* @return A pointer to the first item on success, @c NULL on failure
* @ingroup Ecore_Data_List_Traverse_Group
*/
inline void *ecore_list_goto_first(Ecore_List *list)
{
@ -831,9 +844,10 @@ static void *_ecore_list_goto_first(Ecore_List * list)
}
/**
* @brief Move the pointer to current to the last item in the list
* @param list: the list to move the current pointer in
* @return Returns a pointer to the last item on success, NULL on failure.
* Make the current item the last item in the list.
* @param list The list.
* @return A pointer to the last item on success, @c NULL on failure.
* @ingroup Ecore_Data_List_Traverse_Group
*/
inline void *ecore_list_goto_last(Ecore_List * list)
{
@ -861,9 +875,9 @@ static void *_ecore_list_goto_last(Ecore_List * list)
}
/**
* @brief Retrieve the data in the current node
* @param list: the list to retrieve the current data from
* @return Returns the data at current position, can be NULL.
* Retrieve the data pointed to by the current item in @p list.
* @param list The list.
* @return Returns the data at current position, can be @c NULL.
*/
inline void *ecore_list_current(Ecore_List * list)
{
@ -892,10 +906,10 @@ static void *_ecore_list_current(Ecore_List * list)
}
/**
* @brief Retrieve the data at the current node and move to the next
* @param list: the list to move to the next item
*
* @return Returns the current item in the list on success, NULL on failure.
* Retrieve the data pointed to by the current item, and make the next item
* the current item.
* @param list The list to retrieve data from.
* @return The current item in the list on success, @c NULL on failure.
*/
inline void *ecore_list_next(Ecore_List * list)
{
@ -936,11 +950,11 @@ static void *_ecore_list_next(Ecore_List * list)
}
/**
* @brief Remove all nodes from the list
* @param list: the list that will have it's nodes removed
* @return Returns TRUE on success, FALSE on error.
*
* The data for each item on the list is not freed by ecore_list_clear.
* Remove all nodes from @p list.
* @param list The list.
* @return Returns @c TRUE on success, @c FALSE on error.
* @note The data for each item on the list is not freed by
* @c ecore_list_clear().
*/
int ecore_list_clear(Ecore_List * list)
{
@ -957,11 +971,11 @@ int ecore_list_clear(Ecore_List * list)
}
/**
* @brief Execute function for each node in the list.
* @param list: the list to retrieve nodes from.
* @param function: The function to pass each node from the list to.
*
* @return Returns TRUE on success, FALSE on failure.
* Execute function for each node in @p list.
* @param list The list.
* @param function The function to pass each node from @p list to.
* @return Returns @c TRUE on success, @c FALSE on failure.
* @ingroup Ecore_Data_List_Traverse_Group
*/
int ecore_list_for_each(Ecore_List *list, Ecore_For_Each function)
{
@ -1005,7 +1019,11 @@ int ecore_list_node_init(Ecore_List_Node * node)
return TRUE;
}
/* Allocate and initialize a new list node */
/**
* Allocate and initialize a new list node
* @return A new Ecore_List_Node on success, @c NULL otherwise.
* @ingroup Ecore_Data_List_Node_Group
*/
Ecore_List_Node *ecore_list_node_new()
{
Ecore_List_Node *new_node;
@ -1020,7 +1038,13 @@ Ecore_List_Node *ecore_list_node_new()
return new_node;
}
/* Here we actually call the function to free the data and free the node */
/**
* Here we actually call the function to free the data and free the node
* @param node Node to destroy.
* @param free_func Function to call if @p node points to data to free.
* @return @c TRUE.
* @ingroup Ecore_Data_List_Node_Group
*/
int ecore_list_node_destroy(Ecore_List_Node * node, Ecore_Free_Cb free_func)
{
CHECK_PARAM_POINTER_RETURN("node", node, FALSE);

View File

@ -10,6 +10,22 @@ extern int ecore_config_bound(Ecore_Config_Prop * e);
/* shorthand prop setup code to make client apps a little smaller ;) */
/**
* Creates a new property, if it does not already exist, and sets its
* attributes to those given.
*
* The type of the property is guessed from the key and the value
* given.
*
* @param key The property key.
* @param val Pointer to default value of key.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_create(const char *key, void *val, char short_opt, char *long_opt,
char *desc)
@ -19,6 +35,19 @@ ecore_config_create(const char *key, void *val, char short_opt, char *long_opt,
return ecore_config_typed_create(key, val, type, short_opt, long_opt, desc);
}
/**
* Creates a new property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Pointer to default value of key.
* @param type Type of the property.
* @param short_opt Short option used to set the property from
* command line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_typed_create(const char *key, void *val, int type, char short_opt,
char *long_opt, char *desc)
@ -38,6 +67,18 @@ ecore_config_typed_create(const char *key, void *val, int type, char short_opt,
return ret;
}
/**
* Creates a new integer property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default integer value of key.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_int_create(const char *key, int val, char short_opt,
char *long_opt, char *desc)
@ -47,6 +88,21 @@ ecore_config_int_create(const char *key, int val, char short_opt,
desc);
}
/**
* Creates a new integer property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default integer value of key.
* @param low Lowest valid integer value for the property.
* @param high Highest valid integer value for the property.
* @param step Increment value for the property.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_int_create_bound(const char *key, int val, int low, int high,
int step, char short_opt, char *long_opt,
@ -72,6 +128,18 @@ ecore_config_int_create_bound(const char *key, int val, int low, int high,
return ret;
}
/**
* Creates a new string property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default value of key.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_string_create(const char *key, char *val, char short_opt,
char *long_opt, char *desc)
@ -81,6 +149,18 @@ ecore_config_string_create(const char *key, char *val, char short_opt,
desc);
}
/**
* Creates a new float property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default float value of key.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_float_create(const char *key, float val, char short_opt,
char *long_opt, char *desc)
@ -90,6 +170,21 @@ ecore_config_float_create(const char *key, float val, char short_opt,
desc);
}
/**
* Creates a new float property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default float value of key.
* @param low Lowest valid float value for the property.
* @param high Highest valid float value for the property.
* @param step Increment value for the property.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_float_create_bound(const char *key, float val, float low,
float high, float step, char short_opt,
@ -113,6 +208,18 @@ ecore_config_float_create_bound(const char *key, float val, float low,
return ret;
}
/**
* Creates a new color property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default color value of key, as a hexadecimal string.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_rgb_create(const char *key, char *val, char short_opt,
char *long_opt, char *desc)
@ -122,6 +229,18 @@ ecore_config_rgb_create(const char *key, char *val, char short_opt,
desc);
}
/**
* Creates a new theme property, if it does not already exist, and sets its
* attributes to those given.
* @param key The property key.
* @param val Default theme name for the property.
* @param short_opt Short option used to set the property from command
* line.
* @param long_opt Long option used to set the property from command line.
* @param desc String description of property.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Create_Group
*/
int
ecore_config_theme_create(const char *key, char *val, char short_opt,
char *long_opt, char *desc)
@ -134,10 +253,10 @@ ecore_config_theme_create(const char *key, char *val, char short_opt,
/* this should only be built if evas is present */
/**
* Calls evas_font_path_append on @evas for each of the font names stored
* Calls evas_font_path_append on @p evas for each of the font names stored
* in the property "/e/font/path".
* @param evas Evas object to append the font names to.
* @return ECORE_CONFIG_ERR_SUCC on success. ECORE_CONFIG_ERR_NODATA
* @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
* is returned if the property has not been set.
*/
int
@ -206,7 +325,7 @@ ecore_config_args_display(void)
}
}
int
static int
ecore_config_parse_set(Ecore_Config_Prop * prop, char *arg, char *opt,
char opt2)
{
@ -223,6 +342,15 @@ ecore_config_parse_set(Ecore_Config_Prop * prop, char *arg, char *opt,
return ECORE_CONFIG_PARSE_CONTINUE;
}
/**
* Parse the arguments set by @ref ecore_app_args_set and set properties
* accordingly.
*
* @return ECORE_CONFIG_PARSE_CONTINUE if successful.
* ECORE_CONFIG_PARSE_EXIT is returned if an unrecognised option
* is found. ECORE_CONFIG_PARSE_HELP is returned if help was
* displayed.
*/
int
ecore_config_args_parse(void)
{
@ -331,6 +459,10 @@ ecore_config_args_parse(void)
return ECORE_CONFIG_PARSE_CONTINUE;
}
/**
* Sets the description string used by @ref ecore_config_args_display .
* @param description Description of application.
*/
void
ecore_config_app_describe(char *description)
{

View File

@ -27,7 +27,7 @@ static char *_ecore_config_type[] =
/**
* Removes the given property from the local configuration and destroys it.
* @param e Property to destroy.
* @return NULL
* @return @c NULL
*/
Ecore_Config_Prop *
ecore_config_dst(Ecore_Config_Prop * e)
@ -78,11 +78,11 @@ ecore_config_dst(Ecore_Config_Prop * e)
}
/**
* Returns the property of the config bundle with the given key.
* @param t Ecore_Config_Bundle to search.
* @param key The unique name of the wanted property.
* @return The property that corresponds to tnhe given key. NULL if the key
* could not be found.
* Returns the property with the given key.
* @param key The unique name of the wanted property.
* @return The property that corresponds to the given key. @c NULL if the
* key could not be found.
* @ingroup Ecore_Config_Get_Group
*/
Ecore_Config_Prop *
ecore_config_get(const char *key)
@ -108,6 +108,7 @@ ecore_config_get(const char *key)
* @param e Property to get the type of.
* @returns The type of the property. If the property is invalid, then the
* string "not found" is returned.
* @ingroup Ecore_Config_Property_Group
*/
const char *
ecore_config_type_get(const Ecore_Config_Prop * e)
@ -121,8 +122,9 @@ ecore_config_type_get(const Ecore_Config_Prop * e)
/**
* Obtains the data pointed to by the specified property.
* @param key The property key.
* @return Data pointer used by the property.
* @param key The property key.
* @return Data pointer used by the property.
* @ingroup Ecore_Config_Get_Group
*/
void *
ecore_config_data_get(const char *key)
@ -136,9 +138,10 @@ ecore_config_data_get(const char *key)
/**
* Returns the specified property as a string.
* @param key The property key.
* @return The string value of the property. The function returns NULL if the
* property is not a string or is not set.
* @param key The property key.
* @return The string value of the property. The function returns @c NULL if
* the property is not a string or is not set.
* @ingroup Ecore_Config_Get_Group
*/
char *
ecore_config_string_get(const char *key)
@ -151,9 +154,10 @@ ecore_config_string_get(const char *key)
/**
* Returns the specified property as a long integer.
* @param key The property key.
* @return The integer value of the property. The function returns 0 if the
* property is not an integer or is not set.
* @param key The property key.
* @return The integer value of the property. The function returns 0 if the
* property is not an integer or is not set.
* @ingroup Ecore_Config_Get_Group
*/
long
ecore_config_int_get(const char *key)
@ -166,9 +170,10 @@ ecore_config_int_get(const char *key)
/**
* Returns the specified property as a float.
* @param key The property key.
* @return The float value of the property. The function returns 0.0 if the
* property is not a float or is not set.
* @param key The property key.
* @return The float value of the property. The function returns 0.0 if the
* property is not a float or is not set.
* @ingroup Ecore_Config_Get_Group
*/
float
ecore_config_float_get(const char *key)
@ -183,12 +188,13 @@ ecore_config_float_get(const char *key)
/**
* Finds the red, green and blue values of a color property.
* @param key The property key.
* @param r A pointer to an integer to store the red value into.
* @param g A pointer to an integer to store the green value into.
* @param b A pointer to an integer to store the blue value into.
* @return @a ECORE_CONFIG_ERR_SUCC on success. @a ECORE_CONFIG_ERR_FAIL
* otherwise.
* @param key The property key.
* @param r A pointer to an integer to store the red value into.
* @param g A pointer to an integer to store the green value into.
* @param b A pointer to an integer to store the blue value into.
* @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_FAIL
* otherwise.
* @ingroup Ecore_Config_Get_Group
*/
int
ecore_config_rgb_get(const char *key, int *r, int *g, int *b)
@ -209,8 +215,9 @@ ecore_config_rgb_get(const char *key, int *r, int *g, int *b)
/**
* Returns a color property as a string of hexadecimal characters.
* @param key The property key.
* @return A string of hexadecimal characters in the format #rrggbb.
* @param key The property key.
* @return A string of hexadecimal characters in the format #rrggbb.
* @ingroup Ecore_Config_Get_Group
*/
char *
ecore_config_rgbstr_get(const char *key)
@ -224,9 +231,10 @@ ecore_config_rgbstr_get(const char *key)
/**
* Returns a theme property.
* @param key The property key.
* @return The name of the theme the property refers to. The function returns
* NULL if the property is not a theme or is not set.
* @param key The property key.
* @return The name of the theme the property refers to. The function returns
* @c NULL if the property is not a theme or is not set.
* @ingroup Ecore_Config_Get_Group
*/
char *
ecore_config_theme_get(const char *key)
@ -239,9 +247,10 @@ ecore_config_theme_get(const char *key)
/**
* Retrieves the key as a string.
* @param key The property key.
* @return Returns a character array in the form of 'key:type=value'. NULL is
* returned if the property does not exist.
* @param key The property key.
* @return Returns a character array in the form of 'key:type=value'. @c NULL
* is returned if the property does not exist.
* @ingroup Ecore_Config_Get_Group
*/
char *
ecore_config_as_string_get(const char *key)
@ -346,12 +355,12 @@ ecore_config_bound(Ecore_Config_Prop * e)
*
* This function first checks to see if the property exists. If it does, then
* the type of the stored property is returned. Otherwise, the function tries
* to guess the type of the property based on @a val.
* to guess the type of the property based on @p val.
*
* @param key The property key.
* @param val The value in string form.
* @return The type of the property determined by the function. Note that if
* val is NULL, PT_NIL will be returned.
* val is @c NULL, @c PT_NIL will be returned.
*/
int
ecore_config_type_guess(const char *key, char *val)
@ -504,8 +513,9 @@ ecore_config_add(const char *key, char *val)
* Sets the description field of the indicated property.
* @param key The property key.
* @param desc Description string.
* @note The description string is copied for the property's use. You can
* free @a desc once this function is called.
* @note The description string is copied for the property's use. You can
* free @p desc once this function is called.
* @ingroup Ecore_Config_Property_Group
*/
int
ecore_config_describe(const char *key, char *desc)
@ -518,6 +528,14 @@ ecore_config_describe(const char *key, char *desc)
return ECORE_CONFIG_ERR_SUCC;
}
/**
* Set the short option character of a property.
* @param key The property key.
* @param short_opt Character used to indicate the value of a property
* given on the command line.
* @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
* is returned if the property does not exist.
*/
int
ecore_config_short_opt_set(const char *key, char short_opt)
{
@ -529,6 +547,14 @@ ecore_config_short_opt_set(const char *key, char short_opt)
return ECORE_CONFIG_ERR_SUCC;
}
/**
* Set the long option string of the property.
* @param key The property key.
* @param long_opt String used to indicate the value of a property given
* on the command line.
* @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
* is returned if the property does not exist.
*/
int
ecore_config_long_opt_set(const char *key, char *long_opt)
{
@ -544,11 +570,10 @@ ecore_config_long_opt_set(const char *key, char *long_opt)
/**
* Sets the indicated property to the given value and type.
* @param t Configuration bundle to use.
* @param key The property key.
* @param val A pointer to the value to set the property to.
* @param type The type of the property.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
*/
int
ecore_config_typed_set(const char *key, void *val, int type)
@ -573,7 +598,7 @@ ecore_config_typed_set(const char *key, void *val, int type)
if ((ret = ecore_config_typed_val(e, val, type)) == ECORE_CONFIG_ERR_SUCC)
{
for (l = e->listeners; l; l = l->next)
l->listener(e->key, e->type, l->tag, l->data);
l->listener(e->key, e->type, l->tag, l->data);
}
else
{
@ -587,10 +612,10 @@ ecore_config_typed_set(const char *key, void *val, int type)
/**
* Sets the indicated property to the value indicated by @a val.
* @param t Configuration bundle to use.
* @param key The property key.
* @param val String representation of value to set.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val String representation of value to set.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_set(const char *key, char *val)
@ -616,9 +641,10 @@ ecore_config_set(const char *key, char *val)
/**
* Sets the indicated property to the value given in the string.
* @param key The property key.
* @param val String representation of the value.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val String representation of the value.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_as_string_set(const char *key, char *val)
@ -628,9 +654,10 @@ ecore_config_as_string_set(const char *key, char *val)
/**
* Sets the indicated property to the given integer.
* @param key The property key.
* @param val Integer to set the property to.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val Integer to set the property to.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_int_set(const char *key, int val)
@ -640,9 +667,10 @@ ecore_config_int_set(const char *key, int val)
/**
* Sets the indicated property to the given string.
* @param key The property key.
* @param val String to set the property to.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val String to set the property to.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_string_set(const char *key, char *val)
@ -652,9 +680,10 @@ ecore_config_string_set(const char *key, char *val)
/**
* Sets the indicated property to the given float value.
* @param key The property key.
* @param val Float to set the property to.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val Float to set the property to.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_float_set(const char *key, float val)
@ -664,9 +693,10 @@ ecore_config_float_set(const char *key, float val)
/**
* Sets the indicated property to a color value.
* @param key The property key
* @param val Color value in RGB format.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key
* @param val Color value in RGB format.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_rgb_set(const char *key, char *val)
@ -676,9 +706,10 @@ ecore_config_rgb_set(const char *key, char *val)
/**
* Sets the indicated property to a theme name.
* @param key The property key.
* @param val String giving the name of the theme.
* @return ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @param key The property key.
* @param val String giving the name of the theme.
* @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_theme_set(const char *key, char *val)
@ -688,9 +719,10 @@ ecore_config_theme_set(const char *key, char *val)
/**
* Sets the theme preview group of an indicated property.
* @param key The property key.
* @param group The group name.
* @return ECORE_CONFIG_ERR_SUCC on success.
* @param key The property key.
* @param group The group name.
* @return @c ECORE_CONFIG_ERR_SUCC on success.
* @ingroup Ecore_Config_Set_Group
*/
int
ecore_config_theme_preview_group_set(const char *key, char *group)
@ -735,14 +767,15 @@ ecore_config_typed_default(const char *key, void *val, int type)
/**
* Sets the indicated property if it has not already been set or loaded.
* @param key The property key.
* @param val Default value of the key.
* @param lo Lowest valid value for the key.
* @param hi Highest valid value for the key.
* @param step Used by integer and float values.
* @return ECORE_CONFIG_ERR_SUCC if there are no