diff options
| author | Cedric BAIL <cedric@osg.samsung.com> | 2014-10-20 18:33:11 +0200 |
|---|---|---|
| committer | Cedric BAIL <cedric@osg.samsung.com> | 2014-10-20 18:35:22 +0200 |
| commit | 30abbb31a18207ca25a6735825222a37ad0e9c92 (patch) | |
| tree | 8bdbe44a9124bd7f3d45f59def414f1f408c8dd3 | |
| parent | f8db9a85fb0d878026f4b3e3e0e8f263a272c624 (diff) | |
| parent | b473a56733efa890dbd9962306ad597fa08c6614 (diff) | |
| download | efl-30abbb31a18207ca25a6735825222a37ad0e9c92.tar.gz | |
Merge branch 'devs/captainigloo/doc'
Improve documentation accross all EFL libraries. Work was done on
behalf of Samsung by Cadoles, Openwide and Zefla.
Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
42 files changed, 4603 insertions, 854 deletions
diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h index bef9db8d28..a6ac338cab 100644 --- a/src/lib/ecore/Ecore.h +++ b/src/lib/ecore/Ecore.h @@ -23,16 +23,23 @@ it can be found in @ref Ecore_Main_Loop_Page. The Ecore library provides the following modules: + @li @ref Ecore_Init_Group + @li @ref Ecore_Getopt_Group @li @ref Ecore_Main_Loop_Group + @li @ref Ecore_System_Events + @li @ref Ecore_Time_Group + @li @ref Ecore_Thread_Group + @li @ref Ecore_Pipe_Group + @li @ref Ecore_Application_Group + @li @ref Ecore_Throttle_Group + @li @ref Ecore_Job_Group @li @ref Ecore_File_Group @li @ref Ecore_Con_Group @li @ref Ecore_Evas_Group @li @ref Ecore_FB_Group + @li @ref Ecore_Input_Group @li @ref Ecore_IMF_Lib_Group - @li @ref Ecore_IMF_Context_Group - @li @ref Ecore_IMF_Context_Module_Group - @li @ref Ecore_IMF_Evas_Group - @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink + @li @ref Ecore_IPC_Group @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink @li @ref Ecore_Win32_Group @li @ref Ecore_Audio_Group @@ -80,6 +87,9 @@ @li @ref Ecore_FD_Handler_Group @li @ref Ecore_Event_Group @li @ref Ecore_Exe_Group + @li @ref Ecore_Animator_Group + @li @ref Ecore_Poller_Group + @section ecore_main_intro_example Introductory Examples diff --git a/src/lib/ecore/Ecore_Common.h b/src/lib/ecore/Ecore_Common.h index b45af6ce1f..f47ab39997 100644 --- a/src/lib/ecore/Ecore_Common.h +++ b/src/lib/ecore/Ecore_Common.h @@ -67,15 +67,36 @@ EAPI int ecore_shutdown(void); * @{ */ -#define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR -#define ECORE_VERSION_MINOR EFL_VERSION_MINOR +#define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR /**< Ecore version major number */ +#define ECORE_VERSION_MINOR EFL_VERSION_MINOR /**< Ecore version minor number */ +/** + * @typedef Ecore_Version + * + * This is the Ecore version information structure that can be used at + * runtime to detect which version of ecore is being used and adapt + * appropriately as follows for example: + * + * @code + * #if defined(ECORE_VERSION_MAJOR) && (ECORE_VERSION_MAJOR >= 1) && defined(ECORE_VERSION_MINOR) && (ECORE_VERSION_MINOR > 0) + * printf("Ecore version: %i.%i.%i\n", + * ecore_version->major, + * ecore_version->minor, + * ecore_version->micro); + * if (ecore_version->revision > 0) + * { + * printf(" Built from Git revision # %i\n", ecore_version->revision); + * } + * #endif + * @endcode + * + */ typedef struct _Ecore_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ecore is built from) */ } Ecore_Version; EAPI extern Ecore_Version *ecore_version; @@ -128,6 +149,7 @@ EAPI void ecore_main_loop_iterate(void); * DO NOT use this function unless you are the person God comes to ask for * advice when He has trouble managing the Universe. * + * @return 1 if event exists, else 0. * @see ecore_main_loop_iterate() */ EAPI int ecore_main_loop_iterate_may_block(int may_block); @@ -274,10 +296,14 @@ typedef void *(*Ecore_Data_Cb)(void *data); /** * Add a function to be called by ecore_fork_reset() * + * @param func The function to add. + * @param data The data to pass to this function. + * * This queues @p func to be called (and passed @p data as its argument) when * ecore_fork_reset() is called. This allows other libraries and subsystems * to also reset their internal state after a fork. * + * @return EINA_TRUE on success, else EINA_FALSE. * @since 1.7 */ EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); @@ -285,9 +311,13 @@ EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); /** * This removes the callback specified * + * @param func The function to delete. + * @param data The data passed to this function. + * * This deletes the callback added by ecore_fork_reset_callback_add() using * the function and data pointer to specify which to remove. * + * @return EINA_TRUE on success, else EINA_FALSE. * @since 1.7 */ EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data); @@ -451,7 +481,7 @@ EAPI int ecore_thread_main_loop_end(void); * @{ */ -#define ECORE_EVENT_NONE 0 +#define ECORE_EVENT_NONE 0 /**< None event */ #define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */ #define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */ #define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */ @@ -462,7 +492,7 @@ EAPI int ecore_thread_main_loop_end(void); #define ECORE_EVENT_LOCALE_CHANGED 8 /**< Locale changed */ #define ECORE_EVENT_HOSTNAME_CHANGED 9 /**< Hostname changed */ #define ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED 10 /**< Time or Date changed */ -#define ECORE_EVENT_COUNT 11 +#define ECORE_EVENT_COUNT 11 /**< Number of events */ typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< A handle for HANDLE handlers on Windows */ typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< A handle for an event handler */ @@ -494,7 +524,11 @@ typedef void (*Ecore_End_Cb)(void *user_data, void *func_data); */ typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event); -struct _Ecore_Event_Signal_User /** User signal event */ +/** + * @struct _Ecore_Event_Signal_User + * @brief A structure that stores information of a User signal event. + */ +struct _Ecore_Event_Signal_User { int number; /**< The signal number. Either 1 or 2 */ void *ext_data; /**< Extension data - not used */ @@ -504,7 +538,11 @@ struct _Ecore_Event_Signal_User /** User signal event */ #endif }; -struct _Ecore_Event_Signal_Hup /** Hup signal event */ +/** + * @struct _Ecore_Event_Signal_Hup + * @brief A structure that stores information of a Hup signal event. + */ +struct _Ecore_Event_Signal_Hup { void *ext_data; /**< Extension data - not used */ @@ -513,7 +551,11 @@ struct _Ecore_Event_Signal_Hup /** Hup signal event */ #endif }; -struct _Ecore_Event_Signal_Exit /** Exit request event */ +/** + * @struct _Ecore_Event_Signal_Exit + * @brief A structure that stores information of an Exit request event. + */ +struct _Ecore_Event_Signal_Exit { Eina_Bool interrupt : 1; /**< Set if the exit request was an interrupt signal*/ Eina_Bool quit : 1; /**< set if the exit request was a quit signal */ @@ -525,7 +567,11 @@ struct _Ecore_Event_Signal_Exit /** Exit request event */ #endif }; -struct _Ecore_Event_Signal_Power /** Power event */ +/** + * @struct _Ecore_Event_Signal_Power + * @brief A structure that stores information of a Power event. + */ +struct _Ecore_Event_Signal_Power { void *ext_data; /**< Extension data - not used */ @@ -534,7 +580,11 @@ struct _Ecore_Event_Signal_Power /** Power event */ #endif }; -struct _Ecore_Event_Signal_Realtime /** Realtime event */ +/** + * @struct _Ecore_Event_Signal_Realtime + * @brief A structure that stores information of a Realtime event. + */ +struct _Ecore_Event_Signal_Realtime { int num; /**< The realtime signal's number */ @@ -907,13 +957,21 @@ typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< Spawned Exe typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< Lines from a child process */ typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< Data from a child process */ -struct _Ecore_Exe_Event_Add /** Process add event */ +/** + * @struct _Ecore_Exe_Event_Add + * @brief A structure that stores information of a Process add event. + */ +struct _Ecore_Exe_Event_Add { Ecore_Exe *exe; /**< The handle to the added process */ void *ext_data; /**< Extension data - not used */ }; -struct _Ecore_Exe_Event_Del /** Process exit event */ +/** + * @struct _Ecore_Exe_Event_Del + * @brief A structure that stores information of a Process exit event. + */ +struct _Ecore_Exe_Event_Del { pid_t pid; /**< The process ID of the process that exited */ int exit_code; /**< The exit code of the process */ @@ -927,13 +985,21 @@ struct _Ecore_Exe_Event_Del /** Process exit event */ #endif }; -struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */ +/** + * @struct _Ecore_Exe_Event_Data_Line + * @brief A structure that stores information of lines data from a child process. + */ +struct _Ecore_Exe_Event_Data_Line { char *line; /**< The bytes of a line of buffered data */ int size; /**< The size of the line buffer in bytes */ }; -struct _Ecore_Exe_Event_Data /** Data from a child process event */ +/** + * @struct _Ecore_Exe_Event_Data + * @brief A structure that stores information of data from a child process event. + */ +struct _Ecore_Exe_Event_Data { Ecore_Exe *exe; /**< The handle to the process */ void *data; /**< the raw binary data from the child process that was received */ @@ -1072,7 +1138,7 @@ EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Fl /** * Frees the given event data. * - * @param e The given event data. + * @param data The given event data. */ EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data); @@ -1388,7 +1454,19 @@ EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ec */ EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); +/** + * @brief Create a Ecore_Win32_Handler object and add it to the win32_handlers list. + * @param h The win32 handler. + * @param func The function to add as a callback. + * @param data The data to pass to the callback when it is called. + */ EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); +/** + * @brief Set Ecore_Win32_Handler object to delete state. + * The handler will be deleted in the _ecore_main_win32_handlers_cleanup function. + * + * @param win32_handler The Ecore_Win32_Handler object. + */ EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); /** @@ -2244,7 +2322,7 @@ EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); /** * Create a pipe with more parameters * - * @param hanlder Same as ecore_pipe_add() + * @param handler Same as ecore_pipe_add() * @param data Same as ecore_pipe_add() * @param fd_read An fd to use for reading or -1 otherwise * @param fd_write An fd to use for writing or -1 otherwise @@ -2252,7 +2330,8 @@ EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); * @param write_survive_fork Should write fd survive a fork * * This is the same as ecore_pipe_add() but with some added parameters. - * + * + * @return A pointer to the new Ecore_Pipe object on success, else NULL. * @see ecore_pipe_add() */ EAPI Ecore_Pipe *ecore_pipe_full_add(Ecore_Pipe_Cb handler, @@ -2921,7 +3000,7 @@ EAPI double ecore_timer_precision_get(void); /** * @brief Sets the precision to be used by timer infrastructure. * - * @param value allowed introduced timeout delay, in seconds. + * @param precision allowed introduced timeout delay, in seconds. * * This sets the precision for @b all timers. The precision determines how much * of an difference from the requested interval is acceptable. One common reason diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h index 33e4dbf1f3..a20cc98e02 100644 --- a/src/lib/ecore/Ecore_Getopt.h +++ b/src/lib/ecore/Ecore_Getopt.h @@ -31,8 +31,10 @@ #endif /* ! _WIN32 */ /** - * @file Ecore_Getopt.h - * @brief Contains powerful getopt replacement. + * @defgroup Ecore_Getopt_Group Ecore Getopt + * @ingroup Ecore + * + * This group contains powerful getopt replacement. * * This replacement handles both short (-X) or long options (--ABC) * options, with various actions supported, like storing one value and @@ -46,45 +48,62 @@ * Values will be stored elsewhere indicated by an array of pointers * to values, it is given in separate to parser description so you can * use multiple values with the same parser. + * + * @{ */ #ifdef __cplusplus extern "C" { #endif +/** + * @typedef Ecore_Getopt_Action + * @brief Enumeration that defines the actions to do when parsing command line + * parameters. + */ typedef enum { - ECORE_GETOPT_ACTION_STORE, - ECORE_GETOPT_ACTION_STORE_CONST, - ECORE_GETOPT_ACTION_STORE_TRUE, - ECORE_GETOPT_ACTION_STORE_FALSE, - ECORE_GETOPT_ACTION_CHOICE, - ECORE_GETOPT_ACTION_APPEND, - ECORE_GETOPT_ACTION_COUNT, - ECORE_GETOPT_ACTION_CALLBACK, - ECORE_GETOPT_ACTION_HELP, - ECORE_GETOPT_ACTION_VERSION, - ECORE_GETOPT_ACTION_COPYRIGHT, - ECORE_GETOPT_ACTION_LICENSE, - ECORE_GETOPT_ACTION_BREAK, + ECORE_GETOPT_ACTION_STORE, /**< Store a value */ + ECORE_GETOPT_ACTION_STORE_CONST, /**< Store a const */ + ECORE_GETOPT_ACTION_STORE_TRUE, /**< Store TRUE */ + ECORE_GETOPT_ACTION_STORE_FALSE, /**< Store FALSE */ + ECORE_GETOPT_ACTION_CHOICE, /**< Store a choice between several values */ + ECORE_GETOPT_ACTION_APPEND, /**< Allocate and store a new value of type Ecore_Getopt_Type */ + ECORE_GETOPT_ACTION_COUNT, /**< Store a count number */ + ECORE_GETOPT_ACTION_CALLBACK, /**< Call a callback */ + ECORE_GETOPT_ACTION_HELP, /**< Show help text */ + ECORE_GETOPT_ACTION_VERSION, /**< Show version */ + ECORE_GETOPT_ACTION_COPYRIGHT, /**< Show copyright */ + ECORE_GETOPT_ACTION_LICENSE, /**< Show license */ + ECORE_GETOPT_ACTION_BREAK, /**< Stop parsing options */ ECORE_GETOPT_ACTION_CATEGORY } Ecore_Getopt_Action; +/** + * @typedef Ecore_Getopt_Type + * @brief Enumeration that defines the type of the values to store when using + * append action. + */ typedef enum { - ECORE_GETOPT_TYPE_STR, - ECORE_GETOPT_TYPE_BOOL, - ECORE_GETOPT_TYPE_SHORT, - ECORE_GETOPT_TYPE_INT, - ECORE_GETOPT_TYPE_LONG, - ECORE_GETOPT_TYPE_USHORT, - ECORE_GETOPT_TYPE_UINT, - ECORE_GETOPT_TYPE_ULONG, - ECORE_GETOPT_TYPE_DOUBLE + ECORE_GETOPT_TYPE_STR, /**< Value of type string */ + ECORE_GETOPT_TYPE_BOOL, /**< Value of type boolean */ + ECORE_GETOPT_TYPE_SHORT, /**< Value of type short */ + ECORE_GETOPT_TYPE_INT, /**< Value of type int */ + ECORE_GETOPT_TYPE_LONG, /**< Value of type long */ + ECORE_GETOPT_TYPE_USHORT, /**< Value of type unsigned short */ + ECORE_GETOPT_TYPE_UINT, /**< Value of type unsigned int */ + ECORE_GETOPT_TYPE_ULONG, /**< Value of type unsigned long */ + ECORE_GETOPT_TYPE_DOUBLE /**< Value of type double */ } Ecore_Getopt_Type; +/** + * @typedef Ecore_Getopt_Desc_Arg_Requirement + * @brief Enumeration that defines if the command line options require an + * argument. + */ typedef enum { - ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, - ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, - ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 + ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, /**< Argument is not required */ + ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, /**< Argument is required */ + ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 /**< Argument is optional */ } Ecore_Getopt_Desc_Arg_Requirement; typedef struct _Ecore_Getopt_Desc_Store Ecore_Getopt_Desc_Store; @@ -103,51 +122,69 @@ typedef union _Ecore_Getopt_Value Ecore_Getopt_Value; #define _ECORE_GETOPT_VALUE_PREDEF 1 #endif +/** + * @union _Ecore_Getopt_Value + * @brief Union listing the types of parameters that can take Getopt values. + */ union _Ecore_Getopt_Value { - char **strp; - unsigned char *boolp; - short *shortp; - int *intp; - long *longp; - unsigned short *ushortp; - unsigned int *uintp; - unsigned long *ulongp; - double *doublep; - Eina_List **listp; - void **ptrp; + char **strp; /**< String pointer */ + unsigned char *boolp; /**< Boolean pointer */ + short *shortp; /**< Short pointer */ + int *intp; /**< Int pointer */ + long *longp; /**< Long pointer */ + unsigned short *ushortp; /**< Unsigned short pointer */ + unsigned int *uintp; /**< Unsigned int pointer */ + unsigned long *ulongp; /**< Unsigned long pointer */ + double *doublep; /**< Double pointer */ + Eina_List **listp; /**< List pointer */ + void **ptrp; /**< Void pointer */ }; +/** + * @struct _Ecore_Getopt_Desc_Store + * @brief Structure used when action is ECORE_GETOPT_ACTION_STORE. It contains + * information about the value to store. + */ struct _Ecore_Getopt_Desc_Store { Ecore_Getopt_Type type; /**< type of data being handled */ - Ecore_Getopt_Desc_Arg_Requirement arg_req; + Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ union { - const char *strv; - Eina_Bool boolv; - short shortv; - int intv; - long longv; - unsigned short ushortv; - unsigned int uintv; - unsigned long ulongv; - double doublev; - } def; + const char *strv; /**< String value */ + Eina_Bool boolv; /**< Boolean value */ + short shortv; /**< Short value */ + int intv; /**< Int value */ + long longv; /**< Long value */ + unsigned short ushortv; /**< Unsigned short value */ + unsigned int uintv; /**< Unsigned int value */ + unsigned long ulongv; /**< Unsigned long value */ + double doublev; /**< Double value */ + } def; /**< value of data being handled */ }; +/** + * @struct _Ecore_Getopt_Desc_Callback + * @brief Structure used when action is ECORE_GETOPT_ACTION_CALLBACK. It + * contains information about the callback to call. + */ struct _Ecore_Getopt_Desc_Callback { Eina_Bool (*func)(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, - Ecore_Getopt_Value *storage); - const void *data; - Ecore_Getopt_Desc_Arg_Requirement arg_req; + Ecore_Getopt_Value *storage); /**< function to call as a callback */ + const void *data; /**< data to pass to the callback */ + Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ const char *def; }; +/** + * @struct _Ecore_Getopt_Desc + * @brief Structure that describe an option of the command line. + */ struct _Ecore_Getopt_Desc { char shortname; /**< used with a single dash */ @@ -164,9 +201,13 @@ struct _Ecore_Getopt_Desc const Ecore_Getopt_Type append_type; const Ecore_Getopt_Desc_Callback callback; const void *dummy; - } action_param; + } action_param; /**< Action parameter */ }; +/** + * @struct _Ecore_Getopt + * @brief Structure that contains information on all command line options. + */ struct _Ecore_Getopt { const char *prog; /**< to be used when ecore_app_args_get() fails */ @@ -176,215 +217,701 @@ struct _Ecore_Getopt const char *license; /**< if exists, --license will work */ const char *description; /**< long description, possible multiline */ Eina_Bool strict : 1; /**< fail on errors */ - const Ecore_Getopt_Desc descs[]; /* NULL terminated. */ + const Ecore_Getopt_Desc descs[]; /**< A table that contains the description of all the other options (NULL terminated).*/ + }; +/** + * @brief Macro that helps to fill the Ecore_Getopt_Desc table. + */ #define ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, arg_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_STORE, \ {.store = {type, arg_requirement, default_value}}} +/** + * @brief Macro that fills an option in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param type The option value type. + */ #define ECORE_GETOPT_STORE(shortname, longname, help, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) - +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type string. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_STR(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_STR) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type boolean. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_BOOL(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_BOOL) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type short. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_SHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_SHORT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type int. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_INT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_INT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type long. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_LONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_LONG) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ushort. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_USHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_USHORT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type uint. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_UINT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_UINT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ulong. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_ULONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_ULONG) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type double. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_DOUBLE(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_DOUBLE) +/** + * Macro that helps to fill the Ecore_Getopt_Desc table with a metavar after + * the description of the option. + */ #define ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type string and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_STR(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_STR) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_BOOL(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_BOOL) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type short and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_SHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_SHORT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type int and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_INT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_INT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type long and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_LONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_LONG) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_USHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_USHORT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_UINT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_UINT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_ULONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_ULONG) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type double and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_DOUBLE(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_DOUBLE) +/** + * Macro that helps to fill the Ecore_Getopt_Desc table with a default value. + */ #define ECORE_GETOPT_STORE_DEF(shortname, longname, help, type, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL, \ default_value) +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type string and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_STR(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_STR, \ {.strv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_BOOL(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_BOOL, \ {.boolv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type short and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_SHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_SHORT, \ {.shortv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type int and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_INT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_INT, \ {.intv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type long and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_LONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_LONG, \ {.longv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_USHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_USHORT, \ {.ushortv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_UINT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_UINT, \ {.uintv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_ULONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_ULONG, \ {.ulongv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type double and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_DOUBLE(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_DOUBLE, \ {.doublev = default_value}) +/** + * @brief Fill full string type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_STR(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_STR, \ arg_requirement, \ {.strv = default_value}) + +/** + * @brief Fill full boolean type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_BOOL(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_BOOL, \ arg_requirement, \ {.boolv = default_value}) + +/** + * @brief Fill full short type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_SHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_SHORT, \ arg_requirement, \ {.shortv = default_value}) + +/** + * @brief Fill full int type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_INT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_INT, \ arg_requirement, \ {.intv = default_value}) + +/** + * @brief Fill full long type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_LONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_LONG, \ arg_requirement, \ {.longv = default_value}) + +/** + * @brief Fill full unsigned short type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_USHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_USHORT, \ arg_requirement, \ {.ushortv = default_value}) + +/** + * @brief Fill full unsigned int type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_UINT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_UINT, \ arg_requirement, \ {.uintv = default_value}) + +/** + * @brief Fill full unsigned long type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_ULONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_ULONG, \ arg_requirement, \ {.ulongv = default_value}) + +/** + * @brief Fill full double type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_DOUBLE(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_DOUBLE, \ arg_requirement, \ {.doublev = default_value}) +/** + * @brief Fill Ecore_Getopt_Desc table with a constant value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param value The constant value to store. + */ #define ECORE_GETOPT_STORE_CONST(shortname, longname, help, value) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_CONST, \ {.store_const = value}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a true boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_TRUE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_TRUE, \ {.dummy = NULL}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a false boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_FALSE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_FALSE, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a true boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param choices_array An string array of different choices. + */ #define ECORE_GETOPT_CHOICE(shortname, longname, help, choices_array) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a choice. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param choices_array An string array of different choices. + */ #define ECORE_GETOPT_CHOICE_METAVAR(shortname, longname, help, metavar, choices_array) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} +/** + * @brief Fill Ecore_Getopt_Desc table with an append action. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param sub_type The type of the new value to store. + */ #define ECORE_GETOPT_APPEND(shortname, longname, help, sub_type) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = sub_type}} + +/** + * @brief Fill Ecore_Getopt_Desc table with an append action and a metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param type The type of the new value to store. + */ #define ECORE_GETOPT_APPEND_METAVAR(shortname, longname, help, metavar, type) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = type}} +/** + * @brief Fill Ecore_Getopt_Desc table with an count action. + * + * This will store the number of time the option has been passed to the command + * line. + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_COUNT(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_COUNT, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action and argument requirements. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + * @param argument_requirement the required arguments to this option. + * @param default_value The default values for these arguments. + */ #define ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, callback_func, callback_data, argument_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CALLBACK, \ {.callback = {callback_func, callback_data, \ argument_requirement, default_value}}} + +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action and no arguments. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + */ #define ECORE_GETOPT_CALLBACK_NOARGS(shortname, longname, help, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, NULL, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO, \ NULL) + +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + */ #define ECORE_GETOPT_CALLBACK_ARGS(shortname, longname, help, metavar, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, \ NULL) +/** + * @brief Fill Ecore_Getopt_Desc table with a help action. + * + * @param shortname The help option short name. + * @param longname The help option long name. + */ #define ECORE_GETOPT_HELP(shortname, longname) \ {shortname, longname, "show this message.", "CATEGORY", \ ECORE_GETOPT_ACTION_HELP, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a version action. + * + * @param shortname The version option short name. + * @param longname The version option long name. + */ #define ECORE_GETOPT_VERSION(shortname, longname) \ {shortname, longname, "show program version.", NULL, \ ECORE_GETOPT_ACTION_VERSION, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a copyright action. + * + * @param shortname The copyright option short name. + * @param longname The copyright option long name. + */ #define ECORE_GETOPT_COPYRIGHT(shortname, longname) \ {shortname, longname, "show copyright.", NULL, \ ECORE_GETOPT_ACTION_COPYRIGHT, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a license action. + * + * @param shortname The license option short name. + * @param longname The license option long name. + */ #define ECORE_GETOPT_LICENSE(shortname, longname) \ {shortname, longname, "show license.", NULL, \ ECORE_GETOPT_ACTION_LICENSE, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a break action. + * + * @param shortname The option short name. + * @param longname The option long name. + */ #define ECORE_GETOPT_BREAK(shortname, longname) \ {shortname, longname, "stop parsing options.", NULL, \ ECORE_GETOPT_ACTION_BREAK, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a break action with help message. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_BREAK_STR(shortname, longname, help) \ {shortname, longname, help, NULL, \ ECORE_GETOPT_ACTION_BREAK, \ @@ -393,27 +920,108 @@ struct _Ecore_Getopt #define ECORE_GETOPT_CATEGORY(name, help) \ {0, name, help, NULL, ECORE_GETOPT_ACTION_CATEGORY, {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a sentinel to indicate the end of descriptions. + * + */ #define ECORE_GETOPT_SENTINEL {0, NULL, NULL, NULL, 0, {.dummy = NULL}} +/** + * @brief options that store a single value in a variable of type string. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_STR(val) {.strp = &(val)} + +/** + * @brief options that store a single value in a variable of type boolean. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_BOOL(val) {.boolp = &(val)} + +/** + * @brief options that store a single value in a variable of type short. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_SHORT(val) {.shortp = &(val)} + +/** + * @brief options that store a single value in a variable of type int. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_INT(val) {.intp = &(val)} + +/** + * @brief options that store a single value in a variable of type long. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_LONG(val) {.longp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned short. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_USHORT(val) {.ushortp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned int. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_UINT(val) {.uintp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned long. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_ULONG(val) {.ulongp = &(val)} + +/** + * @brief options that store a single value in a variable of type double. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_DOUBLE(val) {.doublep = &(val)} + +/** + * @brief options that store a single value in a variable of type pointer. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_PTR(val) {.ptrp = &(val)} + +/** + * @brief options that store a single value in a variable of type pointer casted. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_PTR_CAST(val) {.ptrp = (void **)&(val)} + +/** + * @brief options that store a single value in a variable of type list. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_LIST(val) {.listp = &(val)} + +/** + * @brief options that store a NULL value. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_NONE {.ptrp = NULL} /** * Show nicely formatted help message for the given parser. * * @param fp The file the message will be printed on. - * @param parser The parser to be used. + * @param info The structure containing information about command line options. * * @see ecore_getopt_help_category() */ @@ -423,7 +1031,7 @@ EAPI void ecore_getopt_help(FILE *fp, const Ecore_Getopt *info); * Show help for a single category (along with program usage and description). * * @param fp The file the message will be printed on. - * @param parser The parser to be used. + * @param info The structure containing information about command line options. * @param category The category to print. * * @return @c EINA_TRUE when the category exists, @c EINA_FALSE otherwise. @@ -602,4 +1210,9 @@ EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, con #ifdef __cplusplus } #endif + +/** + * @} + */ + #endif /* _ECORE_GETOPT_H */ diff --git a/src/lib/ecore_audio/Ecore_Audio.h b/src/lib/ecore_audio/Ecore_Audio.h index e97706032f..dda0c1bec5 100644 --- a/src/lib/ecore_audio/Ecore_Audio.h +++ b/src/lib/ecore_audio/Ecore_Audio.h @@ -82,6 +82,7 @@ typedef struct _Ecore_Audio_Module Ecore_Audio_Module; typedef struct _Ecore_Audio_Object Ecore_Audio_Object; /**< The audio object */ /* + * @brief Structure to hold the callbacks needed to implement virtual file IO * @since 1.8 */ struct _Ecore_Audio_Vio { diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h index a5adb2558b..6cfea2eff3 100644 --- a/src/lib/ecore_con/Ecore_Con.h +++ b/src/lib/ecore_con/Ecore_Con.h @@ -426,7 +426,7 @@ typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress; */ struct _Ecore_Con_Event_Client_Add { - Ecore_Con_Client *client; /** the client that connected */ + Ecore_Con_Client *client; /**< the client that connected */ }; /** @@ -436,7 +436,7 @@ struct _Ecore_Con_Event_Client_Add */ struct _Ecore_Con_Event_Client_Upgrade { - Ecore_Con_Client *client; /** the client that completed handshake */ + Ecore_Con_Client *client; /**< the client that completed handshake */ }; /** @@ -445,7 +445,7 @@ struct _Ecore_Con_Event_Client_Upgrade */ struct _Ecore_Con_Event_Client_Del { - Ecore_Con_Client *client; /** the client that was lost */ + Ecore_Con_Client *client; /**< the client that was lost */ }; /** @@ -454,7 +454,7 @@ struct _Ecore_Con_Event_Client_Del */ struct _Ecore_Con_Event_Client_Error { - Ecore_Con_Client *client; /** the client for which an error occurred */ + Ecore_Con_Client *client; /**< the client for which an error occurred */ char *error; /**< the error string describing what happened */ }; @@ -464,7 +464,7 @@ struct _Ecore_Con_Event_Client_Error */ struct _Ecore_Con_Event_Server_Add { - Ecore_Con_Server *server; /** the server that was connected to */ + Ecore_Con_Server *server; /**< the server that was connected to */ }; /** @@ -474,7 +474,7 @@ struct _Ecore_Con_Event_Server_Add */ struct _Ecore_Con_Event_Server_Upgrade { - Ecore_Con_Server *server; /** the server that was connected to */ + Ecore_Con_Server *server; /**< the server that was connected to */ }; /** @@ -483,7 +483,7 @@ struct _Ecore_Con_Event_Server_Upgrade */ struct _Ecore_Con_Event_Server_Del { - Ecore_Con_Server *server; /** the client that was lost */ + Ecore_Con_Server *server; /**< the client that was lost */ }; /** @@ -492,7 +492,7 @@ struct _Ecore_Con_Event_Server_Del */ struct _Ecore_Con_Event_Server_Error { - Ecore_Con_Server *server; /** the server for which an error occurred */ + Ecore_Con_Server *server; /**< the server for which an error occurred */ char *error; /**< the error string describing what happened */ }; diff --git a/src/lib/ecore_con/Ecore_Con_Eet.h b/src/lib/ecore_con/Ecore_Con_Eet.h index bdf0d2d605..a6c52bd328 100644 --- a/src/lib/ecore_con/Ecore_Con_Eet.h +++ b/src/lib/ecore_con/Ecore_Con_Eet.h @@ -31,43 +31,254 @@ # endif #endif +/** + * @defgroup Ecore_Con_Eet_Group Eet connection functions + * @ingroup Ecore_Con_Group + * + * The Ecore Connection Eet library ( @c Ecore_Con_Eet) adds @c Eet data + * serialization features to Ecore Connection objects. Its main aim is to + * provide a way to send @c Eet data streams to another program through sockets + * using @c Ecore_Con objects. + * + * @{ + */ + typedef struct _Ecore_Con_Eet Ecore_Con_Eet; typedef struct _Ecore_Con_Reply Ecore_Con_Reply; +/** + * @typedef Ecore_Con_Eet_Data_Cb + * @brief Called when an Ecore_Con_Eet object receives data. + */ typedef void (*Ecore_Con_Eet_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, void *value); + +/** + * @typedef Ecore_Con_Eet_Raw_Data_Cb + * @brief Called when an Ecore_Con_Eet object receives raw data. + */ typedef void (*Ecore_Con_Eet_Raw_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, size_t length); + +/** + * @typedef Ecore_Con_Eet_Client_Cb + * @brief Called when a client connects to the server. + */ typedef Eina_Bool (*Ecore_Con_Eet_Client_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Client *conn); + +/** + * @typedef Ecore_Con_Eet_Server_Cb + * @brief Called when the server has accepted the connection of the client. + */ typedef Eina_Bool (*Ecore_Con_Eet_Server_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Server *conn); +/** + * Create a Ecore_Con_Eet server. + * + * @param server An existing Ecore_Con_Server that have been previously + * created by the server program with @ref + * ecore_con_server_add. + * + * @return A new Ecore_Con_Eet server. + */ EAPI Ecore_Con_Eet *ecore_con_eet_server_new(Ecore_Con_Server *server); + +/** + * Create a Ecore_Con_Eet client. + * + * @param server An existing Ecore_Con_Server that have been previously + * returned by a call to @ref ecore_con_server_connect in the + * client program. + * + * @return A new Ecore_Con_Eet client. + */ EAPI Ecore_Con_Eet *ecore_con_eet_client_new(Ecore_Con_Server *server); + +/** + * Free an existing Ecore_Con_Eet object. + * + * @param server An existing Ecore_Con_Eet object that have been previously + * allocated by a @ref ecore_con_eet_server_new or @ref + * ecore_con_eet_client_new. + * + */ EAPI void ecore_con_eet_server_free(Ecore_Con_Eet *ece); +/** + * Register an @c Eet data descriptor on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to connect. + * @param edd A Eet data descriptor that describes the data organization + * in the Eet stream. + * + */ EAPI void ecore_con_eet_register(Ecore_Con_Eet *ece, const char *name, Eet_Data_Descriptor *edd); +/** + * Register a data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to connect. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + * + */ EAPI void ecore_con_eet_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Data_Cb func, const void *data); + +/** + * Remove a data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to remove callback on. + * + */ EAPI void ecore_con_eet_data_callback_del(Ecore_Con_Eet *ece, const char *name); +/** + * Register a raw data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the raw Eet stream to connect. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + * + */ EAPI void ecore_con_eet_raw_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Raw_Data_Cb func, const void *data); + +/** + * Remove a raw data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the raw Eet stream to remove callback on. + * + */ EAPI void ecore_con_eet_raw_data_callback_del(Ecore_Con_Eet *ece, const char *name); +/** + * Register a client connect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the server program to know when a + * client connects. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_client_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); + +/** + * Remove a client connect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_client_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); +/** + * Register a client disconnect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the server program to know when a + * client disconnects. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_client_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); + +/** + * Remove a client disconnect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_client_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); +/** + * Register a server connect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the client program to be called + * when it has been connected to the server. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_server_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); + +/** + * Remove a server connect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_server_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); +/** + * Register a server disconnect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the client program to be called + * when it has been disconnected from the server. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_server_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); + +/** + * Remove a server disconnect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_server_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); +/** + * Attach data to an Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param data The data to attach to the Ecore_Con_Eet object. + */ EAPI void ecore_con_eet_data_set(Ecore_Con_Eet *ece, const void *data); + +/** + * Get the data attached to an Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @return The data attached to the Ecore_Con_Eet object. + */ EAPI void *ecore_con_eet_data_get(Ecore_Con_Eet *ece); +/** + * Get the Ecore_Con_Eet object corresponding to the Ecore_Con_Reply object. + * + * @param reply An Ecore_Con_Reply object. + * @return The corresponding Ecore_Con_Eet object. + */ EAPI Ecore_Con_Eet *ecore_con_eet_reply(Ecore_Con_Reply *reply); + +/** + * Send some data using a protocol type. + * + * @param reply An Ecore_Con_Reply object. + * @param protocol_name The protocol type to use. + * @param value The data to send. + */ EAPI void ecore_con_eet_send(Ecore_Con_Reply *reply, const char *protocol_name, void *value); + +/** + * Send some raw data using a protocol type. + * + * @param reply An Ecore_Con_Reply object. + * @param protocol_name The protocol type to use. + * @param section The section to add to the protocol. + * @param value The data to send. + * @param length The data length. + */ EAPI void ecore_con_eet_raw_send(Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, unsigned int length); +/** + * @} + */ + #endif diff --git a/src/lib/ecore_file/Ecore_File.h b/src/lib/ecore_file/Ecore_File.h index 530b3cd028..806ad87f84 100644 --- a/src/lib/ecore_file/Ecore_File.h +++ b/src/lib/ecore_file/Ecore_File.h @@ -140,7 +140,6 @@ EAPI Eina_Bool ecore_file_can_write (const char *file); EAPI Eina_Bool ecore_file_can_exec (const char *file); EAPI char *ecore_file_readlink (const char *link); EAPI Eina_List *ecore_file_ls (const char *dir); -EAPI Eina_Iterator *ecore_file_ls_iterator (const char *dir); EAPI char *ecore_file_app_exe_get (const char *app); EAPI char *ecore_file_escape_name (const char *filename); EAPI char *ecore_file_strip_ext (const char *file); diff --git a/src/lib/ecore_imf/Ecore_IMF.h b/src/lib/ecore_imf/Ecore_IMF.h index e77437270e..5618f3130d 100644 --- a/src/lib/ecore_imf/Ecore_IMF.h +++ b/src/lib/ecore_imf/Ecore_IMF.h @@ -78,6 +78,11 @@ extern "C" { */ /* ecore_imf_context_input_panel_event_callback_add() flag */ + +/** + * @typedef Ecore_IMF_Input_Panel_Event + * Enum containing input panel events. + */ typedef enum { ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< called when the state of the input panel is changed. @since 1.7 */ @@ -88,6 +93,10 @@ typedef enum ECORE_IMF_CANDIDATE_PANEL_GEOMETRY_EVENT /**< called when the size of the candidate word panel is changed. @since 1.7 */ } Ecore_IMF_Input_Panel_Event; +/** + * @typedef Ecore_IMF_Input_Panel_State + * Enum containing input panel state notifications. + */ typedef enum { ECORE_IMF_INPUT_PANEL_STATE_SHOW, /**< Notification after the display of the input panel @since 1.7 */ @@ -95,12 +104,20 @@ typedef enum ECORE_IMF_INPUT_PANEL_STATE_WILL_SHOW /**< Notification prior to the display of the input panel @since 1.7 */ } Ecore_IMF_Input_Panel_State; +/** + * @typedef Ecore_IMF_Input_Panel_Shift_Mode + * Enum containing input shift mode states. + */ typedef enum { ECORE_IMF_INPUT_PANEL_SHIFT_MODE_OFF, /**< @since 1.7 */ ECORE_IMF_INPUT_PANEL_SHIFT_MODE_ON /**< @since 1.7 */ } Ecore_IMF_Input_Panel_Shift_Mode; +/** + * @typedef Ecore_IMF_Candidate_Panel_State + * Enum containing candidate word panel state notifications. + */ typedef enum { ECORE_IMF_CANDIDATE_PANEL_SHOW, /**< Notification after the display of the candidate word panel @since 1.7 */ @@ -139,6 +156,13 @@ EAPI extern int ECORE_IMF_EVENT_PREEDIT_CHANGED; EAPI extern int ECORE_IMF_EVENT_COMMIT; EAPI extern int ECORE_IMF_EVENT_DELETE_SURROUNDING; +/** + * @typedef Ecore_IMF_Event_Cb + * + * @brief Called when a Ecore_IMF event happens. + * + * @see ecore_imf_context_event_callback_add() + */ typedef void (*Ecore_IMF_Event_Cb) (void *data, Ecore_IMF_Context *ctx, void *event_info); /** @@ -214,6 +238,10 @@ typedef enum ECORE_IMF_MOUSE_TRIPLE_CLICK = 1 << 1 /**< A triple click */ } Ecore_IMF_Mouse_Flags; +/** + * @typedef Ecore_IMF_Input_Mode + * Type for Ecore_IMF input mode + */ typedef enum { ECORE_IMF_INPUT_MODE_ALPHA = 1 << 0, @@ -362,27 +390,47 @@ typedef enum ECORE_IMF_BIDI_DIRECTION_RTL /**< The Right to Left mode @since 1.12 */ } Ecore_IMF_BiDi_Direction; +/** + * @struct _Ecore_IMF_Event_Preedit_Start + * @brief The structure type used with the Preedit_Start Input Method event + */ struct _Ecore_IMF_Event_Preedit_Start { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Preedit_End + * @brief The structure type used with the Preedit_End Input Method event + */ struct _Ecore_IMF_Event_Preedit_End { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Preedit_Changed + * @brief The structure type used with the Preedit_Changed Input Method event + */ struct _Ecore_IMF_Event_Preedit_Changed { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Commit + * @brief The structure type used with the Commit Input Method event + */ struct _Ecore_IMF_Event_Commit { Ecore_IMF_Context *ctx; char *str; }; +/** + * @struct _Ecore_IMF_Event_Delete_Surrounding + * @brief The structure type used with the Delete_Surrounding Input Method event + */ struct _Ecore_IMF_Event_Delete_Surrounding { Ecore_IMF_Context *ctx; @@ -390,6 +438,10 @@ struct _Ecore_IMF_Event_Delete_Surrounding int n_chars; }; +/** + * @struct _Ecore_IMF_Event_Selection + * @brief The structure type used with the Selection Input Method event + */ struct _Ecore_IMF_Event_Selection { Ecore_IMF_Context *ctx; @@ -397,6 +449,10 @@ struct _Ecore_IMF_Event_Selection int end; }; +/** + * @struct _Ecore_IMF_Event_Mouse_Down + * @brief The structure type used with the Mouse_Down event + */ struct _Ecore_IMF_Event_Mouse_Down { int button; /**< The button which has been pressed */ @@ -412,6 +468,10 @@ struct _Ecore_IMF_Event_Mouse_Down unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Up + * @brief The structure type used with the Mouse_Up event + */ struct _Ecore_IMF_Event_Mouse_Up { int button; /**< The button which has been pressed */ @@ -427,6 +487,10 @@ struct _Ecore_IMF_Event_Mouse_Up unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_In + * @brief The structure type used with the Mouse_In event + */ struct _Ecore_IMF_Event_Mouse_In { int buttons; @@ -441,6 +505,10 @@ struct _Ecore_IMF_Event_Mouse_In unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Out + * @brief The structure type used with the Mouse_Out event + */ struct _Ecore_IMF_Event_Mouse_Out { int buttons; @@ -455,6 +523,10 @@ struct _Ecore_IMF_Event_Mouse_Out unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Move + * @brief The structure type used with the Mouse_Move event + */ struct _Ecore_IMF_Event_Mouse_Move { int buttons; @@ -471,6 +543,10 @@ struct _Ecore_IMF_Event_Mouse_Move unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Wheel + * @brief The structure type used with the Mouse_Wheel event + */ struct _Ecore_IMF_Event_Mouse_Wheel { int direction; /* 0 = default up/down wheel */ @@ -486,6 +562,10 @@ struct _Ecore_IMF_Event_Mouse_Wheel unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Key_Down + * @brief The structure type used with the Key_Down event + */ struct _Ecore_IMF_Event_Key_Down { const char *keyname; /**< The string name of the key pressed */ @@ -497,6 +577,10 @@ struct _Ecore_IMF_Event_Key_Down unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Key_Up + * @brief The structure type used with the Key_Up event + */ struct _Ecore_IMF_Event_Key_Up { const char *keyname; /**< The string name of the key pressed */ @@ -508,6 +592,9 @@ struct _Ecore_IMF_Event_Key_Up unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @brief A union of IMF events. + */ union _Ecore_IMF_Event { Ecore_IMF_Event_Mouse_Down mouse_down; @@ -520,6 +607,10 @@ union _Ecore_IMF_Event Ecore_IMF_Event_Key_Up key_up; }; +/** + * @struct _Ecore_IMF_Preedit_Attr + * @brief Structure that contains preedit attribute information. + */ struct _Ecore_IMF_Preedit_Attr { Ecore_IMF_Preedit_Type preedit_type; /**< preedit style type */ @@ -527,47 +618,58 @@ struct _Ecore_IMF_Preedit_Attr unsigned int end_index; /**< end index of the range (in bytes) */ }; +/** + * @struct _Ecore_IMF_Context_Class + * @brief Structure used when creating a new Input Method Context. This + * structure is mainly used by modules implementing the Input Method Context + * interface. + * + */ struct _Ecore_IMF_Context_Class { - void (*add) (Ecore_IMF_Context *ctx); - void (*del) (Ecore_IMF_Context *ctx); - void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); - void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); - void (*show) (Ecore_IMF_Context *ctx); - void (*hide) (Ecore_IMF_Context *ctx); - void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); - void (*focus_in) (Ecore_IMF_Context *ctx); - void (*focus_out) (Ecore_IMF_Context *ctx); - void (*reset) (Ecore_IMF_Context *ctx); - void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); - void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); - void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); - Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); - void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); - void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); - void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); - void (*control_panel_show) (Ecore_IMF_Context *ctx); - void (*control_panel_hide) (Ecore_IMF_Context *ctx); - void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); - Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); - void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); - Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); - void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); - void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); - void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); - void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); - void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); - void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); - void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); - Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); - void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); - void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); - void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); - void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); - void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); - void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); + void (*add) (Ecore_IMF_Context *ctx); /**< Create the Input Method Context */ + void (*del) (Ecore_IMF_Context *ctx); /**< Delete the Input Method Context */ + void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); /**< Set the client window for the Input Method Context */ + void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); /**< Set the client canvas for the Input Method Context */ + void (*show) (Ecore_IMF_Context *ctx); /**< Show the Input Method Context */ + void (*hide) (Ecore_IMF_Context *ctx); /**< Hide the Input Method Context */ + void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); /**< Return current preedit string and cursor position */ + void (*focus_in) (Ecore_IMF_Context *ctx); /**< Input Method context widget has gained focus */ + void (*focus_out) (Ecore_IMF_Context *ctx); /**< Input Method context widget has lost focus */ + void (*reset) (Ecore_IMF_Context *ctx); /**< A change has been made */ + void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); /**< Cursor position changed */ + void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); /**< Use preedit string to display feedback */ + void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); /**< Set the input mode */ + Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); /**< Internally handle an event */ + void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); /**< return current preedit string, attributes, and cursor position */ + void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); /**< Allow text prediction */ + void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); /**< Set auto-capitalization type */ + void (*control_panel_show) (Ecore_IMF_Context *ctx); /**< Show the control panel */ + void (*control_panel_hide) (Ecore_IMF_Context *ctx); /**< Hide the control panel */ + void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); /**< Set the layout of the input panel */ + Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); /**< Return the current layout of the input panel */ + void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); /**< Set the language of the input panel */ + Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); /**< Get the current language of the input panel */ + void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); /**< Set the cursor location */ + void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); /**< Set panel-specific data to the input panel */ + void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); /**< Get current panel-specific data from the input panel */ + void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); /**< Set the return key theme of the input panel based on return key type provided */ + void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); /**< Disable return key of the input panel */ + void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); /**< Set input panel caps lock mode */ + void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return input panel geometry */ + Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); /**< Return input panel state */ + void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); /**< Add a callback on input panel state,language,mode change */ + void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); /**< Delete the input panel event callback */ + void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); /**< Return the current language locale */ + void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return the candidate panel geometry */ + void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); /**< Sets input hint to fine-tune input methods behavior */ + void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); /**< Set bidirectionality at the cursor position */ }; +/** + * @struct _Ecore_IMF_Context_Info + * @brief A IMF structure containing context information. + */ struct _Ecore_IMF_Context_Info { const char *id; /* ID */ @@ -597,6 +699,15 @@ EAPI int ecore_imf_init(void); */ EAPI int ecore_imf_shutdown(void); +/** + * Register an Ecore_IMF module. + * + * @param info An Ecore_IMF_Context_Info structure + * @param imf_module_create A function to call at the creation + * @param imf_module_exit A function to call when exiting + * + * @ingroup Ecore_IMF_Lib_Group + */ EAPI void ecore_imf_module_register(const Ecore_IMF_Context_Info *info, Ecore_IMF_Context *(*imf_module_create)(void), Ecore_IMF_Context *(*imf_module_exit)(void)); /** @@ -619,6 +730,18 @@ EAPI Eina_Bool ecore_imf_input_panel_hide(void); * @ingroup Ecore_IMF_Context_Group */ EAPI Eina_List *ecore_imf_context_available_ids_get(void); + +/** + * Get the list of the available Input Method Context ids by canvas type. + * + * Note that the caller is responsible for freeing the Eina_List + * when finished with it. There is no need to finish the list strings. + * + * @param canvas_type A string containing the canvas type. + * @return Return an Eina_List of strings; + * on failure it returns NULL. + * @ingroup Ecore_IMF_Context_Group + */ EAPI Eina_List *ecore_imf_context_available_ids_by_canvas_type_get(const char *canvas_type); /** @@ -631,6 +754,18 @@ EAPI Eina_List *ecore_imf_context_available_ids_by_canvas_typ * @ingroup Ecore_IMF_Context_Group */ EAPI const char *ecore_imf_context_default_id_get(void); + +/** + * Get the id of the default Input Method Context corresponding to a canvas + * type. + * The id may be used to create a new instance of an Input Method + * Context object. + * + * @param canvas_type A string containing the canvas type. + * @return Return a string containing the id of the default Input + * Method Context; on failure it returns NULL. + * @ingroup Ecore_IMF_Context_Group + */ EAPI const char *ecore_imf_context_default_id_by_canvas_type_get(const char *canvas_type); /** @@ -1670,6 +1805,7 @@ EAPI Eina_Bool ecore_imf_context_input_panel_show_on_demand_ /** * @brief Sets the bidirectionality at the current cursor position. * + * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context @@ -1680,6 +1816,7 @@ EAPI void ecore_imf_context_bidi_direction_set(Ecore_IM /** * @brief Gets the bidirectionality at the current cursor position. * + * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context diff --git a/src/lib/ecore_input/Ecore_Input.h b/src/lib/ecore_input/Ecore_Input.h index 46e3e6ea87..f9f781a7fc 100644 --- a/src/lib/ecore_input/Ecore_Input.h +++ b/src/lib/ecore_input/Ecore_Input.h @@ -39,6 +39,12 @@ extern "C" { #endif +/** + * @defgroup Ecore_Input_Group Ecore Input + * @ingroup Ecore_Group + * + *@{ + */ EAPI extern int ECORE_EVENT_KEY_DOWN; EAPI extern int ECORE_EVENT_KEY_UP; EAPI extern int ECORE_EVENT_MOUSE_BUTTON_DOWN; @@ -72,7 +78,11 @@ extern "C" { typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move; typedef struct _Ecore_Event_Mouse_IO Ecore_Event_Mouse_IO; typedef struct _Ecore_Event_Modifiers Ecore_Event_Modifiers; - + + /** + * @typedef Ecore_Event_Modifier + * An enum of modifier events. + */ typedef enum _Ecore_Event_Modifier { ECORE_NONE, @@ -86,18 +96,30 @@ extern "C" { ECORE_LAST } Ecore_Event_Modifier; + /** + * @typedef Ecore_Event_Press + * An enum of press events. + */ typedef enum _Ecore_Event_Press { ECORE_DOWN, ECORE_UP } Ecore_Event_Press; + /** + * @typedef Ecore_Event_IO + * An enum of Input/Output events. + */ typedef enum _Ecore_Event_IO { ECORE_IN, ECORE_OUT } Ecore_Event_IO; + /** + * @typedef Ecore_Compose_State + * An enum of Compose states. + */ typedef enum _Ecore_Compose_State { ECORE_COMPOSE_NONE, @@ -105,140 +127,197 @@ extern "C" { ECORE_COMPOSE_DONE } Ecore_Compose_State; + /** + * @struct _Ecore_Event_Key + * Contains information about an Ecore keyboard event. + */ struct _Ecore_Event_Key { - const char *keyname; - const char *key; + const char *keyname; /**< The key name */ + const char *key; /**< The key symbol */ const char *string; - const char *compose; - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; + const char *compose; /**< final string corresponding to the key symbol composed */ + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ - unsigned int timestamp; - unsigned int modifiers; + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - int same_screen; + int same_screen; /**< same screen flag */ unsigned int keycode; /**< Key scan code numeric value @since 1.10 */ void *data; /**< User data associated with an Ecore_Event_Key @since 1.10 */ }; + /** + * @struct _Ecore_Event_Mouse_Button + * Contains information about an Ecore mouse button event. + */ struct _Ecore_Event_Mouse_Button { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; - - unsigned int timestamp; - unsigned int modifiers; - unsigned int buttons; - unsigned int double_click; - unsigned int triple_click; - int same_screen; + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ + + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ + unsigned int buttons; /**< The button that was used */ + unsigned int double_click; /**< Double click event */ + unsigned int triple_click; /**< Triple click event */ + int same_screen; /**< Same screen flag */ - int x; - int y; + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ struct { int x; int y; - } root; + } root; /**< Coordinates relative to root window */ struct { - int device; /* 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /* radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /* angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /* same as x, y root.x, root.y, but with sub-pixel precision, if available */ + int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ + double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /**< same as x, y, but with sub-pixel precision, if available */ struct { double x, y; - } root; + } root; /**< same as root.x, root.y, but with sub-pixel precision, if available */ } multi; }; - + + /** + * @struct _Ecore_Event_Mouse_Wheel + * Contains information about an Ecore mouse wheel event. + */ struct _Ecore_Event_Mouse_Wheel { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ - unsigned int timestamp; - unsigned int modifiers; + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - int same_screen; - int direction; - int z; + int same_screen; /**< Same screen flag */ + int direction; /**< Orientation of the wheel (horizontal/vertical) */ + int z; /**< Value of the wheel event (+1/-1) */ - int x; - int y; + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ struct { int x; int y; - } root; + } root; /**< Coordinates relative to root window */ }; - + + /** + * @struct _Ecore_Event_Mouse_Move + * Contains information about an Ecore mouse move event. + */ struct _Ecore_Event_Mouse_Move { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ - unsigned int timestamp; - unsigned int modifiers; + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - int same_screen; + int same_screen; /**< Same screen flag */ - int x; - int y; + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ struct { int x; int y; - } root; + } root; /**< Coordinates relative to root window */ struct { - int device; /* 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /* radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /* angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /* same as x, y root.x, root.y, but with sub-pixel precision, if available */ + int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ + double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /**< same as x, y root.x, root.y, but with sub-pixel precision, if available */ struct { double x, y; } root; } multi; }; - + + /** + * @struct _Ecore_Event_Mouse_IO + * Contains information about an Ecore mouse input/output event. + */ struct _Ecore_Event_Mouse_IO { - Ecore_Window window; - Ecore_Window event_window; + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ - unsigned int timestamp; - unsigned int modifiers; + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - int x; - int y; + int x /**< x coordinate relative to window where event happened */ + int y /**< y coordinate relative to window where event happened */ }; + /** + * @struct _Ecore_Event_Modifiers + * Contains information about an Ecore event modifier. + */ struct _Ecore_Event_Modifiers { unsigned int size; unsigned int array[ECORE_LAST]; }; - + + /** + * Initialises the Ecore Event system. + */ EAPI int ecore_event_init(void); + /** + * Shutdowns the Ecore Event system. + */ EAPI int ecore_event_shutdown(void); - + + /** + * Return the Ecore modifier event integer associated to a + * Ecore_Event_Modifier modifier event. + * + * @param modifier A Ecore_Event_Modifier event. + * @return A event_modifier integer that matches with the provided modifier + * event. + */ EAPI unsigned int ecore_event_modifier_mask(Ecore_Event_Modifier modifier); + + /** + * Update a Ecore_Event_Modifiers array with "key" modifier. + * + * @param key A string describing a modifier key. + * @param modifiers A Ecore_Event_Modifiers structure. + * @param inc The value to increment in the modifiers array. + * + * @return ECORE_NONE if the key does not match with an existing one, else + * the corresponding Ecore_Event_Modifier. + */ EAPI Ecore_Event_Modifier ecore_event_update_modifier(const char *key, Ecore_Event_Modifiers *modifiers, int inc); /** - * @since 1.7 + * Handle a sequence of key symbols to make a final compose string. + * + * The final compose string seqstr_ret is allocated in this function and + * thus shall be freed when not needed anymore. + * + * @param seq The sequence of key symbols in a Eina_List. + * @param seqstr_ret The final compose string. + * @return The status of the composition. */ EAPI Ecore_Compose_State ecore_compose_get(const Eina_List *seq, char **seqstr_ret); - + #ifdef __cplusplus } #endif +/** @} */ #endif diff --git a/src/lib/ecore_ipc/Ecore_Ipc.h b/src/lib/ecore_ipc/Ecore_Ipc.h index 71cfa17ed9..a3e38710b4 100644 --- a/src/lib/ecore_ipc/Ecore_Ipc.h +++ b/src/lib/ecore_ipc/Ecore_Ipc.h @@ -30,8 +30,11 @@ #endif /** - * @file Ecore_Ipc.h - * @brief Ecore inter-process communication functions. + * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions. + * @ingroup Ecore + * + * + * @{ */ #ifdef __cplusplus @@ -217,6 +220,11 @@ EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED } \ return d +/** + * @typedef Ecore_Ipc_Type + * + * Enum containing IPC types. + */ typedef enum _Ecore_Ipc_Type { ECORE_IPC_LOCAL_USER, @@ -233,50 +241,81 @@ typedef struct _Ecore_Ipc_Event_Server_Del Ecore_Ipc_Event_Server_Del; typedef struct _Ecore_Ipc_Event_Client_Data Ecore_Ipc_Event_Client_Data; typedef struct _Ecore_Ipc_Event_Server_Data Ecore_Ipc_Event_Server_Data; +/** + * @struct _Ecore_Ipc_Event_Client_Add + * + * An IPC structure for client_add event. + */ struct _Ecore_Ipc_Event_Client_Add { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Client_Del + * + * An IPC structure for client_del event. + */ struct _Ecore_Ipc_Event_Client_Del { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Server_Add + * + * An IPC structure for server_add event. + */ struct _Ecore_Ipc_Event_Server_Add { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Server_Del + * + * An IPC structure for server_del event. + */ struct _Ecore_Ipc_Event_Server_Del { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ + }; - + +/** + * @struct _Ecore_Ipc_Event_Client_Data + * + * An IPC structure for client_data event. + */ struct _Ecore_Ipc_Event_Client_Data { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ /* FIXME: this needs to become an ipc message */ - int major; - int minor; - int ref; - int ref_to; - int response; - void *data; - int size; + int major; /**< The message major opcode number */ + int minor; /**< The message minor opcode number */ + int ref; /**< The message reference number */ + int ref_to; /**< Reference number of the message it refers to */ + int response; /**< Requires response */ + void *data; /**< The message data */ + int size; /**< The data length (in bytes) */ }; - + +/** + * @struct _Ecore_Ipc_Event_Server_Data + * + * An IPC structure for server_data event. + */ struct _Ecore_Ipc_Event_Server_Data { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ /* FIXME: this needs to become an ipc message */ - int major; - int minor; - int ref; - int ref_to; - int response; - void *data; - int size; + int major; /**< The message major opcode number */ + int minor; /**< The message minor opcode number */ + int ref; /**< The message reference number */ + int ref_to; /**< Reference number of the message it refers to */ + int response; /**< Requires response */ + void *data; /**< The message data */ + int size; /**< The data length (in bytes) */ }; EAPI extern int ECORE_IPC_EVENT_CLIENT_ADD; @@ -325,4 +364,7 @@ EAPI int ecore_ipc_ssl_available_get(void); } #endif +/** + * @} + */ #endif diff --git a/src/lib/ecore_x/Ecore_X.h b/src/lib/ecore_x/Ecore_X.h index 2db94da391..c3f0726b2b 100644 --- a/src/lib/ecore_x/Ecore_X.h +++ b/src/lib/ecore_x/Ecore_X.h @@ -28,13 +28,16 @@ #define ECORE_X_VERSION_MAJOR EFL_VERSION_MAJOR #define ECORE_X_VERSION_MINOR EFL_VERSION_MINOR - +/** + * @typedef Ecore_X_Version + * Represents the current version of Ecore_X + */ typedef struct _Ecore_X_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ecore_X is built from) */ } Ecore_X_Version; EAPI extern Ecore_X_Version *ecore_x_version; diff --git a/src/lib/edje/Edje_Common.h b/src/lib/edje/Edje_Common.h index 918553eea8..1051f2e039 100644 --- a/src/lib/edje/Edje_Common.h +++ b/src/lib/edje/Edje_Common.h @@ -8,10 +8,10 @@ */ typedef struct _Edje_Version { - int major; - int minor; - int micro; - int revision; + int major; /**< The major number of Edje version. */ + int minor; /**< The minor number of Edje version. */ + int micro; /**< The micro number of Edje version. */ + int revision; /**< The revision of Edje version) */ } Edje_Version; EAPI extern Edje_Version *edje_version; @@ -669,7 +669,8 @@ EAPI void edje_external_type_array_unregister (const Edje_External_T EAPI unsigned int edje_external_type_abi_version_get (void) EINA_CONST; /** - * Returns an interator of all the registered EXTERNAL types. + * + * @return an iterator of all the registered EXTERNAL types. * * Each item in the iterator is an @c Eina_Hash_Tuple which has the type * of the external in the @c key and #Edje_External_Type as @c data. @@ -823,6 +824,8 @@ EAPI Eina_Bool edje_external_param_choice_get (const Eina_ * @b NOT translated. One must use * Edje_External_Type::translate() to translate those. * + * @param type_name Edje external type name + * * @return the NULL terminated array, or @c NULL if type is unknown or * it does not have any parameter information. * @@ -955,21 +958,36 @@ struct _Edje_Entry_Change_Info */ typedef struct _Edje_Entry_Change_Info Edje_Entry_Change_Info; +/** + * @typedef Edje_Text_Filter_Type + * + * All Edje text filters type values. + */ typedef enum _Edje_Text_Filter_Type { - EDJE_TEXT_FILTER_TEXT = 0, - EDJE_TEXT_FILTER_FORMAT = 1, - EDJE_TEXT_FILTER_MARKUP = 2 + EDJE_TEXT_FILTER_TEXT = 0, /**< Text type filter */ + EDJE_TEXT_FILTER_FORMAT = 1, /**< Format type filter */ + EDJE_TEXT_FILTER_MARKUP = 2 /**< Markup type filter */ } Edje_Text_Filter_Type; +/** + * @typedef Edje_Text_Autocapital_Type + * + * All Text auto capital mode type values + * + */ typedef enum _Edje_Text_Autocapital_Type { - EDJE_TEXT_AUTOCAPITAL_TYPE_NONE, - EDJE_TEXT_AUTOCAPITAL_TYPE_WORD, - EDJE_TEXT_AUTOCAPITAL_TYPE_SENTENCE, - EDJE_TEXT_AUTOCAPITAL_TYPE_ALLCHARACTER + EDJE_TEXT_AUTOCAPITAL_TYPE_NONE, /**< None mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_WORD, /**< Word mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_SENTENCE, /**< Sentence mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_ALLCHARACTER /**< All characters mode value */ } Edje_Text_Autocapital_Type; +/** + * @typedef Edje_Input_Panel_Lang + * + */ typedef enum _Edje_Input_Panel_Lang { EDJE_INPUT_PANEL_LANG_AUTOMATIC, /**< Automatic @since 1.2 */ @@ -989,6 +1007,10 @@ typedef enum _Edje_Input_Panel_Return_Key_Type EDJE_INPUT_PANEL_RETURN_KEY_TYPE_SIGNIN /**< Sign-in @since 1.8 */ } Edje_Input_Panel_Return_Key_Type; +/** + * @typedef Edje_Input_Panel_Layout + * @brief Edje input panel layout + */ typedef enum _Edje_Input_Panel_Layout { EDJE_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */ @@ -1007,6 +1029,10 @@ typedef enum _Edje_Input_Panel_Layout EDJE_INPUT_PANEL_LAYOUT_EMOTICON /**< Emoticon layout @since 1.10 */ } Edje_Input_Panel_Layout; +/* + * @typedef Edje_Input_Hints + * @brief Edje input hints + */ typedef enum { EDJE_INPUT_HINT_NONE = 0, /**< No active hints @since 1.12 */ @@ -1035,8 +1061,33 @@ enum EDJE_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY /**< The password layout to allow only number @since 1.12 */ }; +/** + * @typedef (*Edje_Text_Filter_Cb) + * @brief Callback prototype for Edje_Text_Filter + * @param obj The Evas_Object to filter. + * @param type The filter type. + * @param text The text of the filter. + */ typedef void (*Edje_Text_Filter_Cb) (void *data, Evas_Object *obj, const char *part, Edje_Text_Filter_Type type, char **text); + +/** + * @typedef (*Edje_Markup_Filter_Cb) + * @brief Callback prototype for Edje_Text_Filter + * @param obj The Evas_Object to filter. + * @param part Edje part name. + * @param text The text of the filter. + */ typedef void (*Edje_Markup_Filter_Cb) (void *data, Evas_Object *obj, const char *part, char **text); + +/** + * @typedef (*Edje_Item_Provider_Cb) + * @brief Callback prototype for Edje_Item_Provider + * @param data some data provided by user + * @param obj The Evas_Object to filter. + * @param part Edje part name + * @param item Item of container + * @return must be an Evas_Object. + */ typedef Evas_Object *(*Edje_Item_Provider_Cb) (void *data, Evas_Object *obj, const char *part, const char *item); /** @@ -1126,6 +1177,8 @@ EAPI void edje_password_show_last_timeout_set(double password_show_last_timeout) * * @note unlike Evas, Edje colors are @b not pre-multiplied. That is, * half-transparent white is 255 255 255 128. + * + * @return Eina_Bool, EINA_TRUE on success and EINA_FALSE on failure. */ EAPI Eina_Bool edje_color_class_set (const char *color_class, int r, int g, int b, int a, int r2, int g2, int b2, int a2, int r3, int g3, int b3, int a3); @@ -1216,22 +1269,28 @@ EAPI Eina_List *edje_color_class_list (void); * @{ */ +/** + * @typedef Edje_Part_Type + * + * All possible "part" types in Edje + */ typedef enum _Edje_Part_Type { - EDJE_PART_TYPE_NONE = 0, - EDJE_PART_TYPE_RECTANGLE = 1, - EDJE_PART_TYPE_TEXT = 2, - EDJE_PART_TYPE_IMAGE = 3, - EDJE_PART_TYPE_SWALLOW = 4, - EDJE_PART_TYPE_TEXTBLOCK = 5, - EDJE_PART_TYPE_GRADIENT = 6, - EDJE_PART_TYPE_GROUP = 7, - EDJE_PART_TYPE_BOX = 8, - EDJE_PART_TYPE_TABLE = 9, - EDJE_PART_TYPE_EXTERNAL = 10, - EDJE_PART_TYPE_PROXY = 11, - EDJE_PART_TYPE_SPACER = 12, /**< @since 1.7 */ - EDJE_PART_TYPE_LAST = 13 + EDJE_PART_TYPE_NONE = 0, /**< None type value */ + EDJE_PART_TYPE_RECTANGLE = 1, /**< Rectangle type value */ + EDJE_PART_TYPE_TEXT = 2, /**< Text type value */ + EDJE_PART_TYPE_IMAGE = 3, /**< Image type value */ + EDJE_PART_TYPE_SWALLOW = 4, /**< Swallow type value */ + EDJE_PART_TYPE_TEXTBLOCK = 5, /**< Text block type value */ + EDJE_PART_TYPE_GRADIENT = 6, /**< Gradient type value */ + EDJE_PART_TYPE_GROUP = 7, /**< Group type value */ + EDJE_PART_TYPE_BOX = 8, /**< Box type value */ + EDJE_PART_TYPE_TABLE = 9, /**< Table type value */ + EDJE_PART_TYPE_EXTERNAL = 10, /**< External type value */ + EDJE_PART_TYPE_PROXY = 11, /**< Proxy type value */ + EDJE_PART_TYPE_SPACER = 12, /**< Spacer type value @since 1.7 */ + EDJE_PART_TYPE_LAST = 13 /**< Last type value */ + } Edje_Part_Type; /** * @} @@ -1261,32 +1320,45 @@ typedef enum _Edje_Part_Type #define EDJE_TEXT_EFFECT_SHADOW_DIRECTION_SET(x, s) \ do { x = ((x) & ~EDJE_TEXT_EFFECT_MASK_SHADOW_DIRECTION) | (s); } while (0) +/** + * @typedef Edje_Text_Effect + * + * All possible text effects in Edje + */ typedef enum _Edje_Text_Effect { - EDJE_TEXT_EFFECT_NONE = 0, - EDJE_TEXT_EFFECT_PLAIN = 1, - EDJE_TEXT_EFFECT_OUTLINE = 2, - EDJE_TEXT_EFFECT_SOFT_OUTLINE = 3, - EDJE_TEXT_EFFECT_SHADOW = 4, - EDJE_TEXT_EFFECT_SOFT_SHADOW = 5, - EDJE_TEXT_EFFECT_OUTLINE_SHADOW = 6, - EDJE_TEXT_EFFECT_OUTLINE_SOFT_SHADOW = 7, - EDJE_TEXT_EFFECT_FAR_SHADOW = 8, - EDJE_TEXT_EFFECT_FAR_SOFT_SHADOW = 9, - EDJE_TEXT_EFFECT_GLOW = 10, - - EDJE_TEXT_EFFECT_LAST = 11, - - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_LEFT = (0x3 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP = (0x5 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_RIGHT = (0x7 << 4) + EDJE_TEXT_EFFECT_NONE = 0, /**< None text effect value */ + EDJE_TEXT_EFFECT_PLAIN = 1, /**< Plain text effect value */ + EDJE_TEXT_EFFECT_OUTLINE = 2, /**< Outline text effect value */ + EDJE_TEXT_EFFECT_SOFT_OUTLINE = 3, /**< Soft outline text effect value */ + EDJE_TEXT_EFFECT_SHADOW = 4, /**< Shadown text effect value */ + EDJE_TEXT_EFFECT_SOFT_SHADOW = 5, /**< Soft shadow text effect value */ + EDJE_TEXT_EFFECT_OUTLINE_SHADOW = 6, /**< Outline shadow text effect value */ + EDJE_TEXT_EFFECT_OUTLINE_SOFT_SHADOW = 7, /**< Outline soft shadow text effect value */ + EDJE_TEXT_EFFECT_FAR_SHADOW = 8, /**< Far shadow text effect value */ + EDJE_TEXT_EFFECT_FAR_SOFT_SHADOW = 9, /**< Far soft shadow text effect value */ + EDJE_TEXT_EFFECT_GLOW = 10, /**< Glow text effect value */ + + EDJE_TEXT_EFFECT_LAST = 11, /**< Last text effect value */ + + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< Bottom right shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< Bottom shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< Bottom left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< Left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< Top left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< Top shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< Top right shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< right shadow direction value */ } Edje_Text_Effect; +/** + * @typedef (*Edje_Text_Change_Cb) + * + * Callback prototype for Edje_Text_Change + * @param data user provided data to pass to the callback + * @param obj the Evas_Object + * @param The edje part + */ typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, const char *part); /** * @} @@ -1328,15 +1400,21 @@ typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, c * @{ */ +/** + * @typedef Edje_Cursor + * + * All available cursor states + * + */ typedef enum _Edje_Cursor { - EDJE_CURSOR_MAIN, - EDJE_CURSOR_SELECTION_BEGIN, - EDJE_CURSOR_SELECTION_END, - EDJE_CURSOR_PREEDIT_START, - EDJE_CURSOR_PREEDIT_END, - EDJE_CURSOR_USER, - EDJE_CURSOR_USER_EXTRA, + EDJE_CURSOR_MAIN, /*< Main cursor state */ + EDJE_CURSOR_SELECTION_BEGIN, /*< Selection begin cursor state */ + EDJE_CURSOR_SELECTION_END, /*< Selection end cursor state */ + EDJE_CURSOR_PREEDIT_START, /*< Pre-edit start cursor state */ + EDJE_CURSOR_PREEDIT_END, /*< Pre-edit end cursor starge */ + EDJE_CURSOR_USER, /*< User cursor state */ + EDJE_CURSOR_USER_EXTRA, /*< User extra cursor state */ // more later } Edje_Cursor; @@ -1363,13 +1441,19 @@ typedef enum _Edje_Cursor * @{ */ +/** + * @typedef Edje_Aspect_Control + * + * All Edje aspect control values + * + */ typedef enum _Edje_Aspect_Control { - EDJE_ASPECT_CONTROL_NONE = 0, - EDJE_ASPECT_CONTROL_NEITHER = 1, - EDJE_ASPECT_CONTROL_HORIZONTAL = 2, - EDJE_ASPECT_CONTROL_VERTICAL = 3, - EDJE_ASPECT_CONTROL_BOTH = 4 + EDJE_ASPECT_CONTROL_NONE = 0, /*< None aspect control value */ + EDJE_ASPECT_CONTROL_NEITHER = 1, /*< Neither aspect control value */ + EDJE_ASPECT_CONTROL_HORIZONTAL = 2, /*< Horizontal aspect control value */ + EDJE_ASPECT_CONTROL_VERTICAL = 3, /*< Vertical aspect control value */ + EDJE_ASPECT_CONTROL_BOTH = 4 /*< Both aspect control value */ } Edje_Aspect_Control; /** @@ -1416,12 +1500,17 @@ typedef enum _Edje_Aspect_Control * @{ */ +/** + * @typedef Edje_Drag_Dir + * + * Dragable properties values + */ typedef enum _Edje_Drag_Dir { - EDJE_DRAG_DIR_NONE = 0, - EDJE_DRAG_DIR_X = 1, - EDJE_DRAG_DIR_Y = 2, - EDJE_DRAG_DIR_XY = 3 + EDJE_DRAG_DIR_NONE = 0, /*< Not dragable value */ + EDJE_DRAG_DIR_X = 1, /*< X dragable value */ + EDJE_DRAG_DIR_Y = 2, /*< Y dragable value */ + EDJE_DRAG_DIR_XY = 3 /*< X and Y dragable value */ } Edje_Drag_Dir; /** @@ -1482,11 +1571,17 @@ EAPI void edje_box_layout_register (const char *name, Evas_Object * @{ */ +/** + * @typedef Edje_Object_Table_Homogeneous_Mode + * + * Table homogeneous modes + * + */ typedef enum _Edje_Object_Table_Homogeneous_Mode { - EDJE_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, - EDJE_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, - EDJE_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 + EDJE_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, /*< None homogeneous mode */ + EDJE_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, /*< Table homogeneous mode */ + EDJE_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 /*< Item homogeneous mode */ } Edje_Object_Table_Homogeneous_Mode; /** @@ -1688,53 +1783,64 @@ EAPI const char *edje_load_error_str (Edje_Load_Error error); * @{ */ +/** + * @typedef Edje_Tween_Mode + * + * Available tween mode for edje animations + */ typedef enum _Edje_Tween_Mode { - EDJE_TWEEN_MODE_NONE = 0, - EDJE_TWEEN_MODE_LINEAR = 1, - EDJE_TWEEN_MODE_SINUSOIDAL = 2, - EDJE_TWEEN_MODE_ACCELERATE = 3, - EDJE_TWEEN_MODE_DECELERATE = 4, - EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, - EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, - EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, - EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, - EDJE_TWEEN_MODE_BOUNCE = 9, - EDJE_TWEEN_MODE_SPRING = 10, - EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, - EDJE_TWEEN_MODE_LAST = 12, - EDJE_TWEEN_MODE_MASK = 0xff, - EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) + EDJE_TWEEN_MODE_NONE = 0, /**< None tween mode value */ + EDJE_TWEEN_MODE_LINEAR = 1, /**< Linear tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL = 2, /**< Sinusoidal tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE = 3, /**< Accelerate tween mode value */ + EDJE_TWEEN_MODE_DECELERATE = 4, /**< Decelerate tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, /**< Accelerate factor tween mode value */ + EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, /**< Decelerate factor tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, /**< Sinusoidal factgor tween mode value */ + EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, /**< Divisor iterp tween mode value */ + EDJE_TWEEN_MODE_BOUNCE = 9, /**< Bounce tween mode value */ + EDJE_TWEEN_MODE_SPRING = 10, /**< Spring tween mode value */ + EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, /**< Cubic Bezier tween mode value */ + EDJE_TWEEN_MODE_LAST = 12, /**< Last tween mode value */ + EDJE_TWEEN_MODE_MASK = 0xff, /**< Mask tween mode value */ + EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) /**< Options from current tween mode value */ } Edje_Tween_Mode; +/** + * @typedef Edje_Action_Type + * + * All actions available in Edje programs. + * + */ typedef enum _Edje_Action_Type { - EDJE_ACTION_TYPE_NONE = 0, - EDJE_ACTION_TYPE_STATE_SET = 1, - EDJE_ACTION_TYPE_ACTION_STOP = 2, - EDJE_ACTION_TYPE_SIGNAL_EMIT = 3, - EDJE_ACTION_TYPE_DRAG_VAL_SET = 4, - EDJE_ACTION_TYPE_DRAG_VAL_STEP = 5, - EDJE_ACTION_TYPE_DRAG_VAL_PAGE = 6, - EDJE_ACTION_TYPE_SCRIPT = 7, - EDJE_ACTION_TYPE_FOCUS_SET = 8, - EDJE_ACTION_TYPE_RESERVED00 = 9, - EDJE_ACTION_TYPE_FOCUS_OBJECT = 10, - EDJE_ACTION_TYPE_PARAM_COPY = 11, - EDJE_ACTION_TYPE_PARAM_SET = 12, - EDJE_ACTION_TYPE_SOUND_SAMPLE = 13, /**< @since 1.1 */ - EDJE_ACTION_TYPE_SOUND_TONE = 14, /**< @since 1.1 */ - EDJE_ACTION_TYPE_PHYSICS_IMPULSE = 15, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_TORQUE_IMPULSE = 16, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_FORCE = 17, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_TORQUE = 18, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_FORCES_CLEAR = 19, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_VEL_SET = 20, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_ANG_VEL_SET = 21, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_STOP = 22, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_ROT_SET = 23, /**< @since 1.8 */ - EDJE_ACTION_TYPE_VIBRATION_SAMPLE = 24, /**< @since 1.10 */ - EDJE_ACTION_TYPE_LAST = 25 + EDJE_ACTION_TYPE_NONE = 0, /**< None action value */ + EDJE_ACTION_TYPE_STATE_SET = 1, /**< State set action value */ + EDJE_ACTION_TYPE_ACTION_STOP = 2, /**< Action stop action value */ + EDJE_ACTION_TYPE_SIGNAL_EMIT = 3, /**< Signal emit action value */ + EDJE_ACTION_TYPE_DRAG_VAL_SET = 4, /**< Drag val set action value */ + EDJE_ACTION_TYPE_DRAG_VAL_STEP = 5, /**< Drag val step action value */ + EDJE_ACTION_TYPE_DRAG_VAL_PAGE = 6, /**< Drag val page action value */ + EDJE_ACTION_TYPE_SCRIPT = 7, /**< Script action value */ + EDJE_ACTION_TYPE_FOCUS_SET = 8, /**< Forcus set action value */ + EDJE_ACTION_TYPE_RESERVED00 = 9, /**< Reversed do action value */ + EDJE_ACTION_TYPE_FOCUS_OBJECT = 10, /**< Forcus object action value */ + EDJE_ACTION_TYPE_PARAM_COPY = 11, /**< Param copy action value */ + EDJE_ACTION_TYPE_PARAM_SET = 12, /**< Param set action value */ + EDJE_ACTION_TYPE_SOUND_SAMPLE = 13, /**< @since 1.1 @brief Sound sample action value */ + EDJE_ACTION_TYPE_SOUND_TONE = 14, /**< @since 1.1 @brief Sound tone action value */ + EDJE_ACTION_TYPE_PHYSICS_IMPULSE = 15, /**< @since 1.8 @brief Physics impulse action value */ + EDJE_ACTION_TYPE_PHYSICS_TORQUE_IMPULSE = 16, /**< @since 1.8 @brief Physics torque impulse action value */ + EDJE_ACTION_TYPE_PHYSICS_FORCE = 17, /**< @since 1.8 @brief Physics force action value */ + EDJE_ACTION_TYPE_PHYSICS_TORQUE = 18, /**< @since 1.8 @brief Physics torque action value */ + EDJE_ACTION_TYPE_PHYSICS_FORCES_CLEAR = 19, /**< @since 1.8 @brief Physics forces clear action value */ + EDJE_ACTION_TYPE_PHYSICS_VEL_SET = 20, /**< @since 1.8 @brief Physics velocity set action value */ + EDJE_ACTION_TYPE_PHYSICS_ANG_VEL_SET = 21, /**< @since 1.8 @brief Physics angle velocity set action value */ + EDJE_ACTION_TYPE_PHYSICS_STOP = 22, /**< @since 1.8 @brief Physics stop action value */ + EDJE_ACTION_TYPE_PHYSICS_ROT_SET = 23, /**< @since 1.8 @brief Physics rotation set action value */ + EDJE_ACTION_TYPE_VIBRATION_SAMPLE = 24, /**< @since 1.10 @brief vibration sample action value */ + EDJE_ACTION_TYPE_LAST = 25 /**< Last action value */ } Edje_Action_Type; /** @@ -2091,24 +2197,24 @@ typedef enum _Edje_Channel /** * Set the mute state of audio for the process as a whole - * + * * @param channel The channel to set the mute state of * @param mute The mute state - * + * * This sets the mute (no output) state of audio for the given channel. - * + * * @see edje_audio_channel_mute_get() - * + * * @since 1.9 */ EAPI void edje_audio_channel_mute_set(Edje_Channel channel, Eina_Bool mute); /** * Get the mute state of the given channel - * + * * @param channel The channel to get the mute state of * @return The mute state of the channel - * + * * @see edje_audio_channel_mute_set() * * @since 1.9 @@ -2127,4 +2233,3 @@ EAPI const char *edje_object_part_object_name_get(const Evas_Object *obj); /** * @} */ - diff --git a/src/lib/edje/edje_container.h b/src/lib/edje/edje_container.h index 0fba62c45d..d7f9a1df99 100644 --- a/src/lib/edje/edje_container.h +++ b/src/lib/edje/edje_container.h @@ -32,36 +32,48 @@ typedef struct _Smart_Data_Colinfo Smart_Data_Colinfo; struct _Smart_Data { - Evas_Coord x, y, w, h; - Eina_List *children; - Evas_Object *smart_obj; - int cols, rows; - - Evas_Coord contents_w, contents_h; - Evas_Coord min_row_h, max_row_h; - Evas_Coord min_w, max_w, min_h, max_h; + Evas_Coord x; /**< horizontal coordinate */ + Evas_Coord y; /**< vertical coordinate */ + Evas_Coord w; /**< width */ + Evas_Coord h; /**< height */ + Eina_List *children; /**< list of children */ + Evas_Object *smart_obj; /**< actual smart object */ + int cols; /**< columns count */ + int rows; /**< rows count */ + + Evas_Coord contents_w; /**< contents width */ + Evas_Coord contents_h; /**< contents height */ + Evas_Coord min_row_h; /**< minimum row height */ + Evas_Coord max_row_h; /**< maximum row height */ + Evas_Coord min_w; /**< minimum width */ + Evas_Coord max_w; /**< maximum width */ + Evas_Coord min_h; /**< minimum height */ + Evas_Coord max_h; /**< maximum height */ Smart_Data_Colinfo *colinfo; int freeze; - double scroll_x, scroll_y; - double align_x, align_y; + double scroll_x; /**< horizontal scroll */ + double scroll_y; /**< vertical scroll */ + double align_x; /**< horizontal alignment */ + double align_y; /**< vertical alignment */ - unsigned char changed : 1; - unsigned char change_child : 1; - unsigned char change_child_list : 1; - unsigned char change_cols : 1; - unsigned char change_scroll : 1; + unsigned char changed : 1; /**< some property changed */ + unsigned char change_child : 1; /**< a child changed */ + unsigned char change_child_list : 1; /**< child list changed */ + unsigned char change_cols : 1; /**< columns changed */ + unsigned char change_scroll : 1; /**< scroll changed */ - unsigned char need_layout : 1; + unsigned char need_layout : 1; /**< layout computation needed */ - unsigned char homogenous : 1; + unsigned char homogenous : 1; /**< homogeneous layout */ }; struct _Smart_Data_Colinfo { - Evas_Coord minw, maxw; + Evas_Coord minw; /**< minimum width */ + Evas_Coord maxw; /**< maximum width */ }; /* All items are virtual constructs that provide Evas_Objects at some point. @@ -90,36 +102,42 @@ struct _Edje_Item_Class /* private */ struct _Edje_Item { - Edje_Item_Class *class; + Edje_Item_Class *class; /**< item class */ void *class_data; - void *sd; + void *sd; /**< smart data */ void *data; - Evas_Object *object; - Evas_Object *overlay_object; + Evas_Object *object; /**< actual object */ + Evas_Object *overlay_object; /**< overlay object */ int freeze; - Evas_Coord y, h; + Evas_Coord y; /**< vertical position */ + Evas_Coord h; /**< height */ - Evas_Coord minh, maxh; + Evas_Coord minh; /**< minimum height */ + Evas_Coord maxh; /**< maximum height */ - int cells_num; + int cells_num; /**< cells count */ Edje_Item_Cell *cells; unsigned char accessible : 1; unsigned char recalc : 1; - unsigned char selected : 1; - unsigned char disabled : 1; - unsigned char focused : 1; + unsigned char selected : 1; /**< selected item */ + unsigned char disabled : 1; /**< disabled item */ + unsigned char focused : 1; /**< focused item */ }; struct _Edje_Item_Cell { - Evas_Object *obj; - Evas_Coord x, w; - Evas_Coord minw, minh, maxw, maxh; + Evas_Object *obj; /**< actual cell object */ + Evas_Coord x; /**< horizontal position */ + Evas_Coord w; /**< width */ + Evas_Coord minw; /**< minimum width */ + Evas_Coord minh; /**< minimum height */ + Evas_Coord maxw; /**< maximum width */ + Evas_Coord maxh; /**< maximum height */ }; /* here is an item for a vertical list - with 1 or more columns. this has 3 */ diff --git a/src/lib/edje/edje_convert.h b/src/lib/edje/edje_convert.h index fcc2781f49..c37afd7bb8 100644 --- a/src/lib/edje/edje_convert.h +++ b/src/lib/edje/edje_convert.h @@ -1,72 +1,98 @@ #ifndef EDJE_CONVERT_H__ # define EDJE_CONVERT_H__ -typedef struct _Old_Edje_Image_Directory Old_Edje_Image_Directory; -typedef struct _Old_Edje_Font_Directory Old_Edje_Font_Directory; -typedef struct _Old_Edje_External_Directory Old_Edje_External_Directory; -typedef struct _Old_Edje_Part Old_Edje_Part; -typedef struct _Old_Edje_Part_Collection Old_Edje_Part_Collection; -typedef struct _Old_Edje_Part_Description Old_Edje_Part_Description; -typedef struct _Old_Edje_Part_Description_Spec_Image Old_Edje_Part_Description_Spec_Image; -typedef struct _Edje_Data Edje_Data; - +typedef struct _Old_Edje_Image_Directory Old_Edje_Image_Directory; /**< An old Edje image directory */ +typedef struct _Old_Edje_Font_Directory Old_Edje_Font_Directory; /**< An old Edje font directory */ +typedef struct _Old_Edje_External_Directory Old_Edje_External_Directory; /**< An old Edje external directory */ +typedef struct _Old_Edje_Part Old_Edje_Part; /**< An old Edje part */ +typedef struct _Old_Edje_Part_Collection Old_Edje_Part_Collection; /**< An old Edje part collection */ +typedef struct _Old_Edje_Part_Description Old_Edje_Part_Description; /**< An old Edje part description */ +typedef struct _Old_Edje_Part_Description_Spec_Image Old_Edje_Part_Description_Spec_Image; /**< An old Edje part description image */ +typedef struct _Edje_Data Edje_Data; /**< A key/value tuple */ + + +/** + * @struct _Edje_Data + * @brief A structure that stores a key/value tuple. + */ struct _Edje_Data { - const char *key; - char *value; + const char *key; /**< key name */ + char *value; /**< contents value */ }; /*----------*/ +/** + * @struct _Old_Edje_Font_Directory + * @brief A structure that stores old font directory entries. + */ struct _Old_Edje_Font_Directory { - Eina_List *entries; /* a list of Edje_Font_Directory_Entry */ + Eina_List *entries; /**< a list of Edje_Font_Directory_Entry */ }; +/** + * @struct _Old_Edje_Image_Directory + * @brief A structure that stores old image directory entries. + */ struct _Old_Edje_Image_Directory { - Eina_List *entries; /* a list of Edje_Image_Directory_Entry */ - Eina_List *sets; /* a list of Edje_Image_Directory_Set */ + Eina_List *entries; /**< a list of Edje_Image_Directory_Entry */ + Eina_List *sets; /**< a list of Edje_Image_Directory_Set */ }; +/** + * @struct _Old_Edje_External_Directory + * @brief A structure that stores old external directory entries. + */ struct _Old_Edje_External_Directory { - Eina_List *entries; /* a list of Edje_External_Directory_Entry */ + Eina_List *entries; /**< a list of Edje_External_Directory_Entry */ }; +/** + * @struct _Old_Edje_File + * @brief A structure that stores old Edje files information. + */ struct _Old_Edje_File { - const char *path; - time_t mtime; - - Old_Edje_External_Directory *external_dir; - Old_Edje_Font_Directory *font_dir; - Old_Edje_Image_Directory *image_dir; - Edje_Part_Collection_Directory *collection_dir; - Eina_List *data; - Eina_List *styles; - Eina_List *color_classes; - - const char *compiler; - int version; - int feature_ver; + const char *path; /**< path */ + time_t mtime; /**< modification time */ + + Old_Edje_External_Directory *external_dir; /**< external directory */ + Old_Edje_Font_Directory *font_dir; /**< fonts directory */ + Old_Edje_Image_Directory *image_dir; /**< images directory */ + Edje_Part_Collection_Directory *collection_dir; /**< collection directory */ + Eina_List *data; /**< list of Edje_Data */ + Eina_List *styles; /**< list of Edje_Style */ + Eina_List *color_classes; /**< list of Edje_Color_Class */ + + const char *compiler; /**< compiler name */ + int version; /**< Edje version */ + int feature_ver; /**< features version */ }; +/** + * @struct _Old_Edje_Part_Collection + * @brief A structure that stores old Edje part collection information. + */ struct _Old_Edje_Part_Collection { - Eina_List *programs; /* a list of Edje_Program */ - Eina_List *parts; /* a list of Edje_Part */ - Eina_List *data; + Eina_List *programs; /**< a list of Edje_Program */ + Eina_List *parts; /**< a list of Edje_Part */ + Eina_List *data; /**< a list of Edje_Data */ - int id; /* the collection id */ + int id; /**< the collection id */ - Eina_Hash *alias; /* aliasing part*/ + Eina_Hash *alias; /**< aliasing part*/ struct { - Edje_Size min, max; + Edje_Size min; /**< minimum size */ + Edje_Size max; /**< maximum size */ } prop; - int references; + int references; /**< references count */ #ifdef EDJE_PROGRAM_CACHE struct { Eina_Hash *no_matches; @@ -74,70 +100,122 @@ struct _Old_Edje_Part_Collection } prog_cache; #endif - Embryo_Program *script; /* all the embryo script code for this group */ - const char *part; + Embryo_Program *script; /**< all the embryo script code for this group */ + const char *part; /**< part name */ - unsigned char script_only; + unsigned char script_only; /**< script only */ - unsigned char lua_script_only; + unsigned char lua_script_only; /** LUA script only */ - unsigned char checked : 1; + unsigned char checked : 1; /**< contents checked and registered */ }; +/** + * @struct _Old_Edje_Part + * @brief A structure that stores old Edje part information. + */ struct _Old_Edje_Part { - const char *name; /* the name if any of the part */ - Old_Edje_Part_Description *default_desc; /* the part descriptor for default */ - Eina_List *other_desc; /* other possible descriptors */ + const char *name; /**< the name if any of the part */ + Old_Edje_Part_Description *default_desc; /**< the part descriptor for default */ + Eina_List *other_desc; /**< other possible descriptors */ const char *source, *source2, *source3, *source4, *source5, *source6; - int id; /* its id number */ - int clip_to_id; /* the part id to clip this one to */ - Edje_Part_Dragable dragable; - Eina_List *items; /* packed items for box and table */ - unsigned char type; /* what type (image, rect, text) */ - unsigned char effect; /* 0 = plain... */ - unsigned char mouse_events; /* it will affect/respond to mouse events */ - unsigned char repeat_events; /* it will repeat events to objects below */ - Evas_Event_Flags ignore_flags; - unsigned char scale; /* should certain properties scale with edje scale factor? */ - unsigned char precise_is_inside; - unsigned char use_alternate_font_metrics; - unsigned char pointer_mode; - unsigned char entry_mode; - unsigned char select_mode; - unsigned char multiline; - Edje_Part_Api api; + int id; /**< its id number */ + int clip_to_id; /**< the part id to clip this one to */ + Edje_Part_Dragable dragable; /**< dragable part */ + Eina_List *items; /**< packed items for box and table */ + unsigned char type; /**< what type (image, rect, text) */ + unsigned char effect; /**< 0 = plain... */ + unsigned char mouse_events; /**< it will affect/respond to mouse events */ + unsigned char repeat_events; /**< it will repeat events to objects below */ + Evas_Event_Flags ignore_flags; /**< ignore flags */ + unsigned char scale; /**< should certain properties scale with edje scale factor? */ + unsigned char precise_is_inside; /**< whether is precisely inside */ + unsigned char use_alternate_font_metrics; /**< use alternate font metrics */ + unsigned char pointer_mode; /**< pointer mode */ + unsigned char entry_mode; /**< entry mode */ + unsigned char select_mode; /**< entry selection mode */ + unsigned char multiline; /**< multiline enabled */ + Edje_Part_Api api; /**< part API */ }; +/** + * @struct _Old_Edje_Part_Description_Spec_Image + * @brief A structure that stores old Edje part description image information. + */ struct _Old_Edje_Part_Description_Spec_Image { - Eina_List *tween_list; /* list of Edje_Part_Image_Id */ - int id; /* the image id to use */ - int scale_hint; /* evas scale hint */ - Eina_Bool set; /* if image condition it's content */ + Eina_List *tween_list; /**< list of Edje_Part_Image_Id */ + int id; /**< the image id to use */ + int scale_hint; /**< evas scale hint */ + Eina_Bool set; /**< if image condition it's content */ - Edje_Part_Description_Spec_Border border; - Edje_Part_Description_Spec_Fill fill; + Edje_Part_Description_Spec_Border border; /**< border settings */ + Edje_Part_Description_Spec_Fill fill; /**< fill settings */ }; +/** + * @struct _Old_Edje_Part_Description + * @brief A structure that stores old Edje part description information. + */ struct _Old_Edje_Part_Description { - Edje_Part_Description_Common common; - Old_Edje_Part_Description_Spec_Image image; - Edje_Part_Description_Spec_Text text; - Edje_Part_Description_Spec_Box box; - Edje_Part_Description_Spec_Table table; + Edje_Part_Description_Common common; /**< common part description */ + Old_Edje_Part_Description_Spec_Image image; /**< image part description */ + Edje_Part_Description_Spec_Text text; /**< text part description */ + Edje_Part_Description_Spec_Box box; /**< box part description */ + Edje_Part_Description_Spec_Table table; /**< table part description */ - Eina_List *external_params; /* parameters for external objects */ + Eina_List *external_params; /**< list of Edje_External_Param */ }; +/** + * Convert old Edje files into new Edje files. + * + * @param file an Eet_File to write the new Edje file to + * @param oedf the old Edje file + * + * @return an Edje_File pointer to the converted file + */ Edje_File *_edje_file_convert(Eet_File *file, Old_Edje_File *oedf); + +/** + * Convert old edje part collection into the new Edje file. + * + * @param file an Eet_File to write the new Edje file to + * @param oedc The Old edje part collection + * + * @return a new Edje part collection + */ Edje_Part_Collection *_edje_collection_convert(Edje_File *file, - Old_Edje_Part_Collection *oedc); + Old_Edje_Part_Collection *oedc); + +/** + * Convert old Edje part descripton into new format. + * + * @param type The edje par description common type + * @param ce an edje collection directory entry + * @param the old edje part descripton + * + * @return a new edje part descripton common + */ Edje_Part_Description_Common *_edje_description_convert(int type, - Edje_Part_Collection_Directory_Entry *ce, - Old_Edje_Part_Description *oed); + Edje_Part_Collection_Directory_Entry *ce, + Old_Edje_Part_Description *oed); + +/** + * Get the current Edje file. + * + * @return the current Edje file + */ const Edje_File *_edje_file_get(void); + +/** + * Set the current Edje file. + * + * @param edf the Edje file to set + * + */ void _edje_file_set(const Edje_File *edf); #endif diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h index 0fdad3976a..b3451fa4fa 100644 --- a/src/lib/eet/Eet.h +++ b/src/lib/eet/Eet.h @@ -137,7 +137,15 @@ extern "C" { * */ +/** + * @def EET_VERSION_MAJOR + * The major number of eet version + */ #define EET_VERSION_MAJOR EFL_VERSION_MAJOR +/** + * @def EET_VERSION_MINOR + * The minor number of eet version + */ #define EET_VERSION_MINOR EFL_VERSION_MINOR /** * @typedef Eet_Version @@ -210,7 +218,7 @@ typedef enum _Eet_Error /** * @} */ - + /** * @defgroup Eet_Compression Eet Compression Levels * @ingroup Eet @@ -233,14 +241,14 @@ typedef enum _Eet_Compression EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */ EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */ EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */ - + EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */ } Eet_Compression; /**< Eet compression modes @since 1.7 */ - + /** * @} */ @@ -1457,6 +1465,7 @@ eet_data_image_header_read_cipher(Eet_File *ef, * * @param ef A valid eet file handle opened for reading. * @param name Name of the entry. eg: "/base/file_i_want". + * @param cipher_key The key to use as cipher. * @param cspaces Returned pointer by Eet to a list of possible decoding colorspace finished by @c EET_COLORSPACE_ARGB8888. If @c NULL, only EET_COLORSPACE_ARGB8888 is supported. * @return 1 on successful get, 0 otherwise. * @@ -1591,7 +1600,7 @@ eet_data_image_read_to_surface_cipher(Eet_File *ef, * @param row_stride The length of a pixels line in the destination surface. * @param cspace The color space of the pixels bsurface. * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. + * @param comp A pointer to the int to hold the compression amount. * @param quality A pointer to the int to hold the quality amount. * @param lossy A pointer to the int to hold the lossiness flag. * @return 1 on success, 0 otherwise. @@ -1653,7 +1662,7 @@ eet_data_image_read_to_cspace_surface_cipher(Eet_File *ef, * @param row_stride The length of a pixels line in the destination surface. * @param cspace The color space of the pixel surface * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. + * @param comp A pointer to the int to hold the compression amount. * @param quality A pointer to the int to hold the quality amount. * @param lossy A pointer to the int to hold the lossiness flag. * @return 1 on success, 0 otherwise. @@ -2606,24 +2615,168 @@ typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor; */ typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class; +/** + * @typedef (*Eet_Descriptor_Hash_Foreach_Callback_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Foreach_Callback + * @param h the hash + * @param k the key + * @param dt the data + * @param fdt the data passed to the callback + * @return an integer + */ typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt); +/** + * @typedef (*Eet_Descriptor_Mem_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Mem_Alloc + * @param size is the size of memory to alloc on call of the callback + */ typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size); + +/** + * @typedef (*Eet_Descriptor_Mem_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Mem_Alloc + * @param mem must be a pointer to free on call of the callback + */ typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem); + +/** + * @typedef (*Eet_Descriptor_Str_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Alloc + * @param str must be the string to alloc + * @return have must be an allocated char * for the given string + */ typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_Str_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Free + * @param str must be an allocated string to free + */ typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_List_Next_Callback) + * + * Callback prototype for Eet_Descriptor_List_Next + * @param l must be a pointer to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_List_Append_Callback) + * + * Callback prototype for Eet_Descriptor_List_Append + * @param l must be a pointer to the list + * @param d the data to append to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d); + + +/** + * @typedef (*Eet_Descriptor_List_Data_Callback) + * + * Callback prototype for Eet_Descriptor_List_Data + * @param l must be a pointer to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_List_Free_Callback) + * + * Callback prototype for Eet_Descriptor_List_Free + * @param l must be a pointer to the list to free + */ typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_Hash_Foreach_Callback) + * + * Callback for Eet_Descriptor_Hash_Foreach + * @param h the hash + * @param func the function callback to call on each iteration + * @param fdt the data to pass to the callbac setted in param func + */ typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt); + +/** + * @typedef (*Eet_Descriptor_Hash_Add_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Add + * @param h the hash + * @param k the key + * @param d the data to associate with the 'k' key + */ typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d); + +/** + * @typedef (*Eet_Descriptor_Hash_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Free + * @param h the hash to free + */ typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h); + +/** + * @typedef (*Eet_Descriptor_Str_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Alloc + * @param str the string to allocate + * @return an allocated pointer to the string + */ typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_Str_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Free + * @param str the string to free + */ typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str); + + +/** + * @typedef (*Eet_Descriptor_Type_Get_Callback) + * + * Callback prototype for Eet_Descriptor_Type_Get + * @param data data to pass to the callback + * @param unknow Eina_Bool __FIXME__ + */ typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow); + +/** + * @typedef (*Eet_Descriptor_Type_Set_Callback) + * + * Callback prototype for Eet_Descriptor_Type_Set + * @param type the type to set + * @param data to pass to the callback + * @param unknow Eina_Bool __FIXME__ + */ typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow); + + +/** + * @typedef (*Eet_Descriptor_Array_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Array_Alloc + * @param size The size of the array + */ typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size); + +/** + * @typedef (*Eet_Descriptor_Array_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Array_Free + * @param size The size of the array + */ typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem); /** * @struct _Eet_Data_Descriptor_Class @@ -3006,6 +3159,15 @@ eet_data_write(Eet_File *ef, const void *data, int compress); +/** + * @typedef Eet_Data_Descriptor_Class + * + * Callback protoype for Eet_Dump + * + * @param data to passe to the callback + * @param str the string to dump + * + */ typedef void (*Eet_Dump_Callback)(void *data, const char *str); /** @@ -3702,7 +3864,8 @@ eet_data_read_cipher(Eet_File *ef, * @param edd The data descriptor handle to use when decoding. * @param name The key the data is stored under in the eet file. * @param cipher_key The key to use as cipher. - * @param buffer Buffer + * @param buffer Buffer. + * @param buffer_size The buffer size. * @return A pointer to buffer if successful and NULL on error. * * This function decodes a data structure stored in an eet file, returning @@ -4078,7 +4241,10 @@ struct _Eet_Node_Data */ /** - * TODO FIX ME + * Create a new character node. + * @param name Name of the node. + * @param c Character value. + * @return A new character node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4086,7 +4252,10 @@ eet_node_char_new(const char *name, char c); /** - * TODO FIX ME + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4094,7 +4263,10 @@ eet_node_short_new(const char *name, short s); /** - * TODO FIX ME + * Create a new integer node. + * @param name Name of the node. + * @param i integer value. + * @return A new integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4102,7 +4274,10 @@ eet_node_int_new(const char *name, int i); /** - * TODO FIX ME + * Create a new long long integer node. + * @param name Name of the node. + * @param l long long integer value. + * @return A new long long integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4110,7 +4285,10 @@ eet_node_long_long_new(const char *name, long long l); /** - * TODO FIX ME + * Create a new float node. + * @param name Name of the node. + * @param f float value. + * @return A new float node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4118,7 +4296,10 @@ eet_node_float_new(const char *name, float f); /** - * TODO FIX ME + * Create a new double node. + * @param name Name of the node. + * @param d double value. + * @return A new double node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4126,7 +4307,10 @@ eet_node_double_new(const char *name, double d); /** - * TODO FIX ME + * Create a new unsigned character node. + * @param name Name of the node. + * @param uc unsigned char value. + * @return A new unsigned char node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4134,7 +4318,10 @@ eet_node_unsigned_char_new(const char *name, unsigned char uc); /** - * TODO FIX ME + * Create a new unsigned short node. + * @param name Name of the node. + * @param us unsigned short value. + * @return A new unsigned short node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4142,7 +4329,10 @@ eet_node_unsigned_short_new(const char *name, unsigned short us); /** - * TODO FIX ME + * Create a new unsigned integer node. + * @param name Name of the node. + * @param ui unsigned integer value. + * @return A new unsigned integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4150,7 +4340,10 @@ eet_node_unsigned_int_new(const char *name, unsigned int ui); /** - * TODO FIX ME + * Create a new unsigned long long integer node. + * @param name Name of the node. + * @param l unsigned long long integer value. + * @return A new unsigned long long integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4158,7 +4351,10 @@ eet_node_unsigned_long_long_new(const char *name, unsigned long long l); /** - * TODO FIX ME + * Create a new string node. + * @param name Name of the node. + * @param str string value. + * @return A new string node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4166,7 +4362,10 @@ eet_node_string_new(const char *name, const char *str); /** - * TODO FIX ME + * Create a new inlined string node. + * @param name Name of the node. + * @param str string value. + * @return A new inlined string node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4174,14 +4373,19 @@ eet_node_inlined_string_new(const char *name, const char *str); /** - * TODO FIX ME + * Create a new empty node. + * @param name Name of the node. + * @return A new empty node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_node_null_new(const char *name); /** - * TODO FIX ME + * Create a new list node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new list node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4189,7 +4393,11 @@ eet_node_list_new(const char *name, Eina_List *nodes); /** - * TODO FIX ME + * Create a new array node. + * @param name Name of the node. + * @param count number of nodes + * @param nodes list of nodes. + * @return A new array node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4198,7 +4406,10 @@ eet_node_array_new(const char *name, Eina_List *nodes); /** - * TODO FIX ME + * Create a new variable array node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new variable array node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4209,13 +4420,23 @@ eet_node_var_array_new(const char *name, * TODO FIX ME * @ingroup Eet_Node_Group */ +/** + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. + * @ingroup Eet_Node_Group + */ EAPI Eet_Node * eet_node_hash_new(const char *name, const char *key, Eet_Node *node); /** - * TODO FIX ME + * Create a new struct node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new struct node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4226,6 +4447,13 @@ eet_node_struct_new(const char *name, * TODO FIX ME * @ingroup Eet_Node_Group */ +/** + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. + * @ingroup Eet_Node_Group + */ EAPI Eet_Node * eet_node_struct_child_new(const char *parent, Eet_Node *child); @@ -4260,7 +4488,7 @@ EAPI Eet_Node * eet_node_parent_get(Eet_Node *node); /** - * TODO FIX ME + * @brief Append a "list" node TODO FIX ME * @ingroup Eet_Node_Group */ EAPI void @@ -4368,9 +4596,37 @@ eet_data_node_write_cipher(Eet_File *ef, */ typedef struct _Eet_Node_Walk Eet_Node_Walk; +/** + * @typedef (*Eet_Node_Walk_Struct_Alloc_Callback) + * + * Callback prototype for Eet_Node_Walk_Struct_Alloc + * @param type The allocation type + * @param user_data the data passed by the user to the callback + */ typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data); + +/** + * @typedef (*Eet_Node_Walk_Struct_Add_Callback) + * + * Callback prototype for Eet_Node_Walk_Struct_Add + * @param parent The parent node + * @param name the name for the new node + * @param child the child node + * @param user_data the data passed by the user to the callback + */ typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data); + +/** + * @typedef (*Eet_Node_Walk_Array_Callback) + * + * Callback prototype for Eet_Node_Walk_Array + * @param variable EINA_TRUE or EINA_FALSE + * @param name a name + * @param count a counter + * @param user_data the data passed by the user to the callback + */ typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data); + typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data); typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data); typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data); diff --git a/src/lib/eeze/Eeze.h b/src/lib/eeze/Eeze.h index d63c54413f..be9f9a9a9b 100644 --- a/src/lib/eeze/Eeze.h +++ b/src/lib/eeze/Eeze.h @@ -289,13 +289,16 @@ typedef struct Eeze_Udev_Watch Eeze_Udev_Watch; #define EEZE_VERSION_MAJOR EFL_VERSION_MAJOR #define EEZE_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Eeeze_Version + * Represents the current version of Eeze + */ typedef struct _Eeze_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Eeze is built from) */ } Eeze_Version; EAPI extern Eeze_Version *eeze_version; diff --git a/src/lib/efreet/Efreet.h b/src/lib/efreet/Efreet.h index e2360ee0e7..419e5ff531 100644 --- a/src/lib/efreet/Efreet.h +++ b/src/lib/efreet/Efreet.h @@ -106,13 +106,16 @@ extern "C" { #define EFREET_VERSION_MAJOR EFL_VERSION_MAJOR #define EFREET_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Efreet_Version + * Represents the current version of Efreet + */ typedef struct _Efreet_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Efreet is built from) */ } Efreet_Version; EAPI extern Efreet_Version *efreet_version; diff --git a/src/lib/eina/Eina.h b/src/lib/eina/Eina.h index 9a8341d527..bb6d32555b 100644 --- a/src/lib/eina/Eina.h +++ b/src/lib/eina/Eina.h @@ -66,6 +66,7 @@ * Linux, BSD, Opensolaris and Windows (XP and CE). * * The data types that are available are (see @ref Eina_Data_Types_Group): + * @li @ref Eina_Fp_Group standard floating point numbers. * @li @ref Eina_Inline_Array_Group standard array of inlined members. * @li @ref Eina_Array_Group standard array of @c void* data. * @li @ref Eina_Hash_Group standard hash of @c void* data. @@ -86,6 +87,7 @@ * @li @ref Eina_Benchmark_Group helper to write benchmarks. * @li @ref Eina_Convert_Group faster conversion from strings to integers, double, etc. * @li @ref Eina_Counter_Group measures number of calls and their time. + * @li @ref Eina_Cpu_Group Cpu and architecture related helpers. * @li @ref Eina_Error_Group error identifiers. * @li @ref Eina_File_Group simple file list and path split. * @li @ref Eina_Lalloc_Group simple lazy allocator. diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h index e31ed76735..e871774aa2 100644 --- a/src/lib/eina/eina_cpu.h +++ b/src/lib/eina/eina_cpu.h @@ -19,8 +19,30 @@ #ifndef EINA_CPU_H_ #define EINA_CPU_H_ +/** + * @addtogroup Eina_Cpu_Group Cpu + * + * @brief Cpu and architecture related helpers + */ + +/** + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ + +/** + * @defgroup Eina_Cpu_Group Cpu + * + * @{ + */ + #include "eina_types.h" +/** + * @typedef Eina_Cpu_Features + * Enumerates different hardware architectures. + */ typedef enum _Eina_Cpu_Features { EINA_CPU_MMX = 0x00000001, @@ -36,16 +58,78 @@ typedef enum _Eina_Cpu_Features EINA_CPU_SSE42 = 0x00000200 } Eina_Cpu_Features; +/** + * @brief Global hardware architecture handler + * + * @return the current cpu features + */ EAPI extern Eina_Cpu_Features eina_cpu_features; +/** + * @brief Cpu features accessor + * + * @return the current cpu features + */ EAPI Eina_Cpu_Features eina_cpu_features_get(void); + +/** + * @brief Get the current number of precessors + * + * @return the number of processors that are online, that + * is available when the function is called. + */ EAPI int eina_cpu_count(void); + +/** + * @brief Get the current virtual page size + * + * @return the fixed length that represents the smallest unit of data for memory + * allocation performed by the operating system on behalf of the program, and + * for transfers between the main memory and any other auxiliary store. + */ EAPI int eina_cpu_page_size(void); +/** + * @brief Reverses the byte order of a 16-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 16-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned short eina_swap16(unsigned short x); + +/** + * @brief Reverses the byte order of a 32-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 32-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned int eina_swap32(unsigned int x); + +/** + * @brief Reverses the byte order of a 64-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 64-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned long long eina_swap64(unsigned long long x); #include "eina_inline_cpu.x" +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_CPU_H_ */ diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h index bc6c78d196..7a169a20f5 100644 --- a/src/lib/eina/eina_fp.h +++ b/src/lib/eina/eina_fp.h @@ -20,6 +20,24 @@ #ifndef EINA_FP_H_ # define EINA_FP_H_ +/** + * @addtogroup Eina_Fp_Group Fp + * + * @brief Floating point numbers data type management. + */ + +/** + * @addtogroup Eina_Data_Types_Group Data Types + * + * @{ + */ + +/** + * @defgroup Eina_Fp_Group Fp + * + * @{ + */ + #include "eina_types.h" #ifdef _MSC_VER @@ -30,83 +48,436 @@ typedef signed int int32_t; # include <stdint.h> #endif +/** + * @def EINA_F32P32_PI + * @brief Yields the 32-bit PI constant + */ #define EINA_F32P32_PI 0x00000003243f6a89 +/** + * @typedef Eina_F32p32 + * Type for floating point number where the size of the integer part is 32-bit + * and the size of the decimal part is 32-bit + */ typedef int64_t Eina_F32p32; + +/** + * @typedef Eina_F16p16 + * Type for floating point number where the size of the integer part is 16-bit + * and the size of the decimal part is 16-bit + */ typedef int32_t Eina_F16p16; + +/** + * @typedef Eina_F8p24 + * Type for floating point number where the size of the integer part is 8-bit + * and the size of the decimal part is 24bits + */ typedef int32_t Eina_F8p24; +/** + * @brief Create a new Eina_F32p32 floating point number from standard 32-bit + * integer + * + * @param v 32-bit integer value to convert + * @return The value converted into Eina_F32p32 format + */ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v); + +/** + * @brief Create a new standard 32-bit integer from Eina_F32p32 floating point + * number + * + * @param v Eina_F32p32 value to convert + * @return The value converted into 32-bit integer + */ static inline int32_t eina_f32p32_int_to(Eina_F32p32 v); + +/** + * @brief Create a new Eina_F32p32 floating point number from standard double + * + * @param v double value to convert + * @return The value converted into Eina_F32p32 format + */ static inline Eina_F32p32 eina_f32p32_double_from(double v); + +/** + * @brief Create a new standard double from Eina_F32p32 floating point + * number + * + * @param v Eina_F32p32 value to convert + * @return The value converted into double + */ static inline double eina_f32p32_double_to(Eina_F32p32 v); -static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, - int b); -static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, - Eina_F32p32 b); +/** + * @brief Calculates the sum of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the substraction of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the multiplication of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + * + * To prevent overflow during multiplication we need to reduce the precision of + * the fraction part Shift both values to only contain 16 bit of the fraction + * part (rounded). After multiplication we again have a value with a 32-bit + * fraction part. + */ +static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F32p32 floating point + * number with an integer + * + * @param a The Eina_F32p32 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b); + +/** + * @brief Calculates the division of two Eina_F32p32 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the square root of an Eina_F32p32 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F32p32 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v); -// dont use llabs - issues if not on 64bit +/** + * @brief Get the absolute value of an Eina_F32p32 floating point number + * + * @param a The floating point number + * @return The absolute value for the number @p a + * @warning Has known issues on 64-bit architecture, prefer + * eina_f32p32_fracc_get() instead + */ #define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a)) +/** + * @brief Calculates the cosinus of a floating point number + * + * @param a The angle in radians to calculate the cosinus from. + * @return The cosinus value of the angle @p a + */ EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a); + +/** + * @brief Calculates the sinus of a floating point number + * + * @param a The angle in radians to calculate the sinus from. + * @return The cosinus value of the angle @p a + */ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a); +/** + * @def EINA_F16P16_ONE + * + * Yields the maximum 16-bit unsigned integer size (= 65536) + */ #define EINA_F16P16_ONE (1 << 16) + +/** + * @def EINA_F16P16_HALF + * + * Yields the maximum 16-bit signed integer size (= 32768) + */ #define EINA_F16P16_HALF (1 << 15) +/** + * @brief Create a new Eina_F16p316 floating point number from standard 32-bit + * integer + * + * @param v 32-bit integer value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v); + +/** + * @brief Create a new standard 32-bit integer from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into 32-bit integer + */ static inline int32_t eina_f16p16_int_to(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p16 floating point number from standard double + * + * @param v double value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_double_from(double v); + +/** + * @brief Create a new standard double from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into double + */ static inline double eina_f16p16_double_to(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p16 floating point number from standard float + * + * @param v float value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_float_from(float v); + +/** + * @brief Create a new standard float from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into float + */ static inline float eina_f16p16_float_to(Eina_F16p16 v); -static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, - int b); -static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, - Eina_F16p16 b); +/** + * @brief Calculates the sum of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the substraction of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the multiplication of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F16p16 floating point + * number with an integer + * + * @param a The Eina_F16p16 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b); + +/** + * @brief Calculates the division of two Eina_F16p16 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the square root of an Eina_F16p16 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F16p16 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p316 floating point number from standard 32-bit + * integer + * + * @param v 32-bit integer value to convert + * @return The value converted into Eina_F8p24 format + */ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v); + +/** + * @brief Create a new standard 32-bit integer from Eina_F8p24 floating point + * number + * + * @param v Eina_F8p24 value to convert + * @return The value converted into 32-bit integer + */ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); + +/** + * @brief Create a new Eina_F8p24 floating point number from standard float + * + * @param v float value to convert + * @return The value converted into Eina_F8p24 format + */ static inline Eina_F8p24 eina_f8p24_float_from(float v); + +/** + * @brief Create a new standard float from Eina_F8p24 floating point number + * + * @param v Eina_F8p24 value to convert + * @return The value converted into float + */ static inline float eina_f8p24_float_to(Eina_F8p24 v); -static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, - int b); -static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, - Eina_F8p24 b); +/** + * @brief Calculates the sum of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the substraction of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the multiplication of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F8p24 floating point + * number with an integer + * + * @param a The Eina_F16p16 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b); + +/** + * @brief Calculates the division of two Eina_F8p24 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the square root of an Eina_F8p24 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F8p24 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f8p24_fracc_get(Eina_F8p24 v); +/** + * @brief Converts an Eina_F16p16 floating point number into Eina_F32p32 format + * + * @param a The Eina_F16p16 floating point number + * @return The converted Eina_F32p32 floating point number + */ static inline Eina_F32p32 eina_f16p16_to_f32p32(Eina_F16p16 a); + +/** + * @brief Converts an Eina_F8p24 floating point number into Eina_F32p32 format + * + * @param a The Eina_F8p24 floating point number + * @return The converted Eina_F32p32 floating point number + */ static inline Eina_F32p32 eina_f8p24_to_f32p32(Eina_F8p24 a); + +/** + * @brief Converts an Eina_F32p32 floating point number into Eina_F16p16 format + * + * @param a The Eina_F32p32 floating point number + * @return The converted Eina_F16p16 floating point number + */ static inline Eina_F16p16 eina_f32p32_to_f16p16(Eina_F32p32 a); + +/** + * @brief Converts an Eina_F8p24 floating point number into Eina_F16p16 format + * + * @param a The Eina_F8p24 floating point number + * @return The converted Eina_F16p16 floating point number + */ static inline Eina_F16p16 eina_f8p24_to_f16p16(Eina_F8p24 a); + +/** + * @brief Converts an Eina_F32p32 floating point number into Eina_F8p24 format + * + * @param a The Eina_F32p32 floating point number + * @return The converted Eina_F8p16 floating point number + */ static inline Eina_F8p24 eina_f32p32_to_f8p24(Eina_F32p32 a); + +/** + * @brief Converts an Eina_F16p16 floating point number into Eina_F8p16 format + * + * @param a The Eina_F16p16 floating point number + * @return The converted Eina_F8p16 floating point number + */ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f32p32.x" @@ -114,4 +485,12 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f8p24.x" #include "eina_inline_fp.x" +/** + * @} + */ + +/** + * @} + */ + #endif diff --git a/src/lib/eina/eina_inline_list.x b/src/lib/eina/eina_inline_list.x index 9faac2de2f..17830ba29f 100644 --- a/src/lib/eina/eina_inline_list.x +++ b/src/lib/eina/eina_inline_list.x @@ -64,16 +64,6 @@ eina_list_count(const Eina_List *list) return list->accounting->count; } - -/** - * @brief Returns the last list node's data - * - * @param list The list - * @return The node's data, or @c NULL on being passed a @c NULL pointer - * - * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) - * @since 1.8 - */ static inline void * eina_list_last_data_get(const Eina_List *list) { diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x index fc3dd00add..59bf523e1e 100644 --- a/src/lib/eina/eina_inline_mempool.x +++ b/src/lib/eina/eina_inline_mempool.x @@ -21,26 +21,36 @@ #include <string.h> -/** - * @addtogroup Eina_Memory_Pool_Group Memory Pool - * - * @{ - */ - /* Memory Pool */ typedef struct _Eina_Mempool_Backend_ABI1 Eina_Mempool_Backend_ABI1; typedef struct _Eina_Mempool_Backend_ABI2 Eina_Mempool_Backend_ABI2; struct _Eina_Mempool_Backend { + /** Name of the mempool backend */ const char *name; + /** Function to initialize the backend. */ void *(*init)(const char *context, const char *options, va_list args); + /** Function to free memory back to the mempool. */ void (*free)(void *data, void *element); + /** Function to allocate memory from the mempool. */ void *(*alloc)(void *data, unsigned int size); + /** Function to change the size of a block of memory that is currently + * allocated. */ void *(*realloc)(void *data, void *element, unsigned int size); + /** Function to trigger a garbage collection; can be NULL if the feature + * isn't available in the backend. */ void (*garbage_collect)(void *data); + /** Report statistics on the content of the mempool; can be NULL if the + * feature isn't available in the backend. */ void (*statistics)(void *data); + /** Function to destroy the backend, freeing memory back to the operating + * system. */ void (*shutdown)(void *data); + /** Function to optimize the placement of objects in the mempool (it's + * different from garbage_collect); can be NULL if the feature isn't + * available in the backend. + * @see Eina_Mempool_Repack_Cb */ void (*repack)(void *data, Eina_Mempool_Repack_Cb cb, void *cb_data); }; @@ -68,53 +78,18 @@ struct _Eina_Mempool Eina_Mempool_Backend_ABI2 *backend2; }; -/** - * @brief Re-allocate an amount memory by the given mempool. - * - * @param mp The mempool. - * @param element The element to re-allocate. - * @param size The size in bytes to re-allocate. - * @return The newly re-allocated data. - * - * This function re-allocates and returns @p element with @p size bytes using the - * mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - */ static inline void * eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) { return mp->backend.realloc(mp->backend_data, element, size); } -/** - * @brief Allocate memory using the given mempool. - * - * @param mp The mempool. - * @param size The size in bytes to allocate. - * @return The newly allocated data. - * - * This function allocates and returns @p size bytes using the mempool @p mp. - * If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - */ static inline void * eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) { return mp->backend.alloc(mp->backend_data, size); } -/** - * @brief Allocate and zero memory using the given mempool. - * - * @param mp The mempool. - * @param size The size in bytes to allocate. - * @return The newly allocated data. - * - * This function allocates, zeroes, and returns @p size bytes using the mempool @p mp. - * If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - * @since 1.2 - */ static inline void * eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) { @@ -124,17 +99,6 @@ eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) return r; } -/** - * @brief Free resources previously allocated by the given mempool. - * - * @param mp The mempool. - * @param element The data to free. - * - * This function frees @p element allocated by @p mp. @p element must - * have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or - * eina_mempool_realloc(). - * @warning No checks are done for @p mp. - */ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) { @@ -174,8 +138,4 @@ eina_mempool_alignof(unsigned int size) return ((size / align) + (size % align ? 1 : 0)) * align; } -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_inline_rectangle.x b/src/lib/eina/eina_inline_rectangle.x index e25942bd46..fafe1394a6 100644 --- a/src/lib/eina/eina_inline_rectangle.x +++ b/src/lib/eina/eina_inline_rectangle.x @@ -19,61 +19,18 @@ #ifndef EINA_INLINE_RECTANGLE_H__ #define EINA_INLINE_RECTANGLE_H__ -/** - * @addtogroup Eina_Rectangle_Group Rectangle - * - * @brief These functions provide rectangle management. - * - * @{ - */ - -/** - * @brief Check if the given spans intersect. - * - * @param c1 The column of the first span. - * @param l1 The length of the first span. - * @param c2 The column of the second span. - * @param l2 The length of the second span. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE - * otherwise. - */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) { return (!(((c2 + l2) <= c1) || (c2 >= (c1 + l1)))); } -/** - * @brief Check if the given rectangle is empty. - * - * @param r The rectangle to check. - * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE - * otherwise. No check is done on @p r, so it must be a valid - * rectangle. - */ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) { return ((r->w < 1) || (r->h < 1)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Set the coordinates and size of the given rectangle. - * - * @param r The rectangle. - * @param x The top-left x coordinate of the rectangle. - * @param y The top-left y coordinate of the rectangle. - * @param w The width of the rectangle. - * @param h The height of the rectangle. - * - * This function sets its top-left x coordinate to @p x, its top-left - * y coordinate to @p y, its width to @p w and its height to @p h. No - * check is done on @p r, so it must be a valid rectangle. - */ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) { @@ -83,85 +40,30 @@ eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) r->h = h; } -/** - * @brief Check if the given rectangles intersect. - * - * @param r1 The first rectangle. - * @param r2 The second rectangle. - * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE - * otherwise. No check is done on @p r1 and @p r2, so they must be valid - * rectangles. - */ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) { return (eina_spans_intersect(r1->x, r1->w, r2->x, r2->w) && eina_spans_intersect(r1->y, r1->h, r2->y, r2->h)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given x-coordinate is in the rectangle . - * - * @param r The rectangle. - * @param x The x coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p x is in @p r with respect to - * the horizontal direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) { return ((x >= r->x) && (x < (r->x + r->w))) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given y-coordinate is in the rectangle . - * - * @param r The rectangle. - * @param y The y coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p y is in @p r with respect to - * the vertical direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) { return ((y >= r->y) && (y < (r->y + r->h))) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given point is in the rectangle . - * - * @param r The rectangle. - * @param x The x coordinate of the point. - * @param y The y coordinate of the point. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if the point of coordinate (@p x, - * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, - * so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) { return (eina_rectangle_xcoord_inside(r, x) && eina_rectangle_ycoord_inside(r, y)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Get the union of two rectangles. - * - * @param dst The first rectangle. - * @param src The second rectangle. - * - * This function get the union of the rectangles @p dst and @p src. The - * result is stored in @p dst. No check is done on @p dst or @p src, - * so they must be valid rectangles. - */ static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) { @@ -185,18 +87,6 @@ eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) dst->h = src->y + src->h - dst->y; } -/** - * @brief Get the intersection of two rectangles. - * - * @param dst The first rectangle. - * @param src The second rectangle. - * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE - * otherwise. - * - * This function get the intersection of the rectangles @p dst and - * @p src. The result is stored in @p dst. No check is done on @p dst - * or @p src, so they must be valid rectangles. - */ static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) { @@ -319,16 +209,6 @@ eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rect return EINA_TRUE; } -/** - * @brief Subtract two rectangles. - * - * @param thiz The minuend rectangle - * @param other The subtrahend rectangle - * - * This function subtract two rectangles. The difference is stored on @p out - * There will be at most four differences, use eina_rectangle_is_valid to - * confirm the number of differences. - */ static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) { @@ -385,8 +265,4 @@ eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectan return EINA_TRUE; } -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h index 7a720b076c..91de6ea08c 100644 --- a/src/lib/eina/eina_list.h +++ b/src/lib/eina/eina_list.h @@ -1267,6 +1267,16 @@ static inline void *eina_list_data_set(Eina_List *list, const void *data) */ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; +/** + * @brief Returns the last list node's data + * + * @param list The list + * @return The node's data, or @c NULL on being passed a @c NULL pointer + * + * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) + * @since 1.8 + */ +static inline void *eina_list_last_data_get(const Eina_List *list); /** * @brief Returned a new iterator associated to a list. diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h index 2dd4787972..7aaffc2652 100644 --- a/src/lib/eina/eina_mempool.h +++ b/src/lib/eina/eina_mempool.h @@ -39,8 +39,8 @@ * @li @c pass_through: it just call malloc() and free(). It may be * faster on some computers than using our own allocators (like having * a huge L2 cache, over 4MB). - * @li @c one_big: It call just one time malloc for the requested number - * of items. Useful when you know in advance how many object of some + * @li @c one_big: It calls just one time malloc for the requested number + * of items. Useful when you know in advance how many objects of some * type will live during the life of the mempool. */ @@ -71,29 +71,154 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend; /** * @typedef Eina_Mempool_Repack_Cb - * Type for a callback who need to unreference an old object from a mempool - * and reference the new one instead. Memcpy is taken care by the mempool. + * + * Type for a callback which is called when the mempool "repacks" its data, + * i.e. moves it around to optimize the way it is stored in memory. This is + * useful to improve data locality and to free internal pools back to the OS. + * + * The callback needs to update users of the data to stop accessing the object + * from the old location and access it using the new location instead. The copy + * of memory is taken care of by the mempool. */ typedef void (*Eina_Mempool_Repack_Cb)(void *dst, void *src, void *data); EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE; -EAPI Eina_Mempool *eina_mempool_add(const char *module, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +/** + * + * @brief Create a new mempool of the given type + * + * @param name Name of the mempool kind to use. + * @param context Identifier of the mempool created (for debug purposes). + * @param options Unused. Use the variable arguments list instead to pass options to the mempool. + * @param ... Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big. + * @return Newly allocated mempool instance, NULL otherwise. + * + */ +EAPI Eina_Mempool *eina_mempool_add(const char *name, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * + * @brief Delete the given mempool. + * + * @param mp The mempool to delete + * + */ EAPI void eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1); +/** + * @brief Re-allocate an amount memory by the given mempool. + * + * @param mp The mempool. + * @param element The element to re-allocate. + * @param size The size in bytes to re-allocate. + * @return The newly re-allocated data. + * + * This function re-allocates and returns @p element with @p size bytes using the + * mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + */ static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Allocate memory using the given mempool. + * + * @param mp The mempool. + * @param size The size in bytes to allocate. + * @return The newly allocated data. + * + * This function allocates and returns @p size bytes using the mempool @p mp. + * If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + */ static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Allocate and zero memory using the given mempool. + * + * @param mp The mempool. + * @param size The size in bytes to allocate. + * @return The newly allocated data. + * + * This function allocates, zeroes, and returns @p size bytes using the mempool @p mp. + * If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + * @since 1.2 + */ +static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Free resources previously allocated by the given mempool. + * + * @param mp The mempool. + * @param element The data to free. + * + * This function frees @p element allocated by @p mp. @p element must + * have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or + * eina_mempool_realloc(). + * @warning No checks are done for @p mp. + */ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1); -EAPI void eina_mempool_repack(Eina_Mempool *mp, - Eina_Mempool_Repack_Cb cb, - void *data) EINA_ARG_NONNULL(1, 2); +/** + * @brief Repack the objects in the mempool. + * + * @param mp The mempool + * @param cb A callback to update the pointers the objects with their new location. + * @param data Data to pass as third argument to @p cb. + * + * @see Eina_Mempool_Repack_Cb + * @see _Eina_Mempool_Backend + * + */ +EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * + * @brief Run a garbage collection cycle. + * + * @param mp The mempool + * + */ EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1); + +/** + * + * @brief Have the backend update its internal statistics. + * + * @param mp The mempool + * + */ EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1); +/** + * + * @brief Register the given memory pool backend. + * + * @param be The backend + * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE + * otherwise. + * + */ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); + +/** + * + * @brief Unregister the given memory pool backend. + * + * @param be The backend + * + */ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); +/** + * + * @brief Computer the alignment that would be used when allocating a object of size @p size. + * + * @param size + * @return The alignment for an allocation of size @p size. + * + */ static inline unsigned int eina_mempool_alignof(unsigned int size); #include "eina_inline_mempool.x" diff --git a/src/lib/eina/eina_rectangle.h b/src/lib/eina/eina_rectangle.h index 8f5eead1de..55d370ff25 100644 --- a/src/lib/eina/eina_rectangle.h +++ b/src/lib/eina/eina_rectangle.h @@ -74,24 +74,269 @@ typedef enum { Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */ } Eina_Rectangle_Packing; +/** + * @brief Check if the given spans intersect. + * + * @param c1 The column of the first span. + * @param l1 The length of the first span. + * @param c2 The column of the second span. + * @param l2 The length of the second span. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE + * otherwise. + */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given rectangle is empty. + * + * @param r The rectangle to check. + * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE + * otherwise. No check is done on @p r, so it must be a valid + * rectangle. + */ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Set the coordinates and size of the given rectangle. + * + * @param r The rectangle. + * @param x The top-left x coordinate of the rectangle. + * @param y The top-left y coordinate of the rectangle. + * @param w The width of the rectangle. + * @param h The height of the rectangle. + * + * This function sets its top-left x coordinate to @p x, its top-left + * y coordinate to @p y, its width to @p w and its height to @p h. No + * check is done on @p r, so it must be a valid rectangle. + */ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Check if the given rectangles intersect. + * + * @param r1 The first rectangle. + * @param r2 The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE + * otherwise. No check is done on @p r1 and @p r2, so they must be valid + * rectangles. + */ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given x-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p x is in @p r with respect to + * the horizontal direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given y-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param y The y coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p y is in @p r with respect to + * the vertical direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given point is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate of the point. + * @param y The y coordinate of the point. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the point of coordinate (@p x, + * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, + * so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the union of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * + * This function get the union of the rectangles @p dst and @p src. The + * result is stored in @p dst. No check is done on @p dst or @p src, + * so they must be valid rectangles. + */ static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Get the intersection of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE + * otherwise. + * + * This function get the intersection of the rectangles @p dst and + * @p src. The result is stored in @p dst. No check is done on @p dst + * or @p src, so they must be valid rectangles. + */ static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief FIXME I am useless and used by no one + * + * @param in The inner rectangle. + * @param out The outer rectangle. + * @param res The resulting rectangle. + * + */ static inline void eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief FIXME I am useless and used by no one + * + * @param in The inner rectangle. + * @param out The outer rectangle. + * @param res The resulting rectangle. + * + */ static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); + +/** + * + * @brief Tells whether a rectangle is valid or not. + * + * @param r The rectangle + * @return #EINA_TRUE if the rectangle is valid, #EINA_FALSE otherwise. + * + * This function checks if both width and height attributes of the rectangle are + * positive integers. If so, the rectangle is considered valid, else the + * rectangle is invalid. + */ static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1); + +/** + * + * @brief Gives the rectangle maximum x coordinate. + * + * @param thiz The rectangle + * @return the maximum x coordinate + * + * This function calculates the maximum x coordinate of the rectangle by summing + * the @p width with the current @p x coodinate of the rectangle. + */ +static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); + +/** + * + * @brief Gives the rectangle maximum y coordinate. + * + * @param thiz The rectangle + * @return the maximum y coordinate + * + * This function calculates the maximum y coordinate of the rectangle by summing + * the @p height with the current @p y coodinate of the rectangle. + */ +static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle vertically into two subrectangles starting from left edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The x inner coordinate of the rectangle where to perform the + * slicing. + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle vertically. The @p amount + * parameter defines the x inner coordinate where to do the cut, starting from + * the left edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle horizontally into two subrectangles starting from bottom edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The y inner coordinate of the rectangle where to perform the + * slicing. + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle horizontally. The @p amount + * parameter defines the y inner coordinate where to do the cut, starting from + * the bottom edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle vertically starting from right edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The amount to cut off the rectangle starting from the right + * edge + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle vertically. The @p amount + * parameter defines the inner x coordinate where to do the cut, starting from + * the right edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle horizontally starting from top edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The amount to cut off the rectangle starting from the top edge + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle horizontally. The @p amount + * parameter defines the inner y coordinate where to do the cut, starting from + * the top edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); +/** + * @brief Subtract two rectangles. + * + * @param thiz The minuend rectangle + * @param other The subtrahend rectangle + * + * This function subtract two rectangles. The difference is stored on @p out + * There will be at most four differences, use eina_rectangle_is_valid to + * confirm the number of differences. + */ +static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); /** * @brief Add a rectangle in a new pool. diff --git a/src/lib/eina/eina_thread.h b/src/lib/eina/eina_thread.h index 3e89ea9f24..3ad5486ddd 100644 --- a/src/lib/eina/eina_thread.h +++ b/src/lib/eina/eina_thread.h @@ -42,10 +42,22 @@ * @{ */ +/** + * @typedef Eina_Thread + * Type for a generic thread. + */ typedef unsigned long int Eina_Thread; +/** + * @typedef Eina_Thread_Cb + * Type for the definition of a thread callback function + */ typedef void *(*Eina_Thread_Cb)(void *data, Eina_Thread t); +/** + * @typedef Eina_Thead_Priority + * Type to enumerate different thread priorities + */ typedef enum _Eina_Thread_Priority { EINA_THREAD_URGENT, diff --git a/src/lib/eio/Eio.h b/src/lib/eio/Eio.h index 348ed74d46..0eb38c88b0 100644 --- a/src/lib/eio/Eio.h +++ b/src/lib/eio/Eio.h @@ -446,6 +446,9 @@ EAPI Eio_File *eio_file_mkdir(const char *path, * @param done_cb Callback called when the move is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. + * + * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation * * This function will copy a file from source to dest. It will try to use splice * if possible, if not it will fallback to mmap/write. It will try to preserve @@ -467,6 +470,8 @@ EAPI Eio_File *eio_file_move(const char *source, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation + * * This function will copy a file from source to dest. It will try to use splice * if possible, if not it will fallback to mmap/write. It will try to preserve * access right, but not user/group identification. @@ -487,6 +492,9 @@ EAPI Eio_File *eio_file_copy(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. + * + * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation * * This function will move a directory and all its content from source to dest. * It will try first to rename the directory, if not it will try to use splice @@ -515,6 +523,9 @@ EAPI Eio_File *eio_dir_move(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. + * + * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation * * This function will copy a directory and all its content from source to dest. * It will try to use splice if possible, if not it will fallback to mmap/write. @@ -539,6 +550,9 @@ EAPI Eio_File *eio_dir_copy(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. + * + * @return an Eio_File pointer, handler to the unlink operation, can be used to cancel the operation * * This function will remove a directory and all its content. * Every file will be passed to the filter_cb, so it's your job to decide if you diff --git a/src/lib/eldbus/Eldbus.h b/src/lib/eldbus/Eldbus.h index 478fcea92f..3e51b3d3c5 100644 --- a/src/lib/eldbus/Eldbus.h +++ b/src/lib/eldbus/Eldbus.h @@ -116,28 +116,32 @@ extern "C" { * * @{ */ -#define ELDBUS_VERSION_MAJOR EFL_VERSION_MAJOR -#define ELDBUS_VERSION_MINOR EFL_VERSION_MINOR - -#define ELDBUS_FDO_BUS "org.freedesktop.DBus" -#define ELDBUS_FDO_PATH "/org/freedesktop/DBus" -#define ELDBUS_FDO_INTERFACE ELDBUS_FDO_BUS -#define ELDBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties" -#define ELDBUS_FDO_INTERFACE_OBJECT_MANAGER "org.freedesktop.DBus.ObjectManager" -#define ELDBUS_FDO_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable" -#define ELDBUS_FDO_INTEFACE_PEER "org.freedesktop.DBus.Peer" -#define ELDBUS_ERROR_PENDING_CANCELED "org.enlightenment.DBus.Canceled" -#define ELDBUS_ERROR_PENDING_TIMEOUT "org.freedesktop.DBus.Error.NoReply" +#define ELDBUS_VERSION_MAJOR EFL_VERSION_MAJOR /**< Eldbus version major number */ +#define ELDBUS_VERSION_MINOR EFL_VERSION_MINOR /**< Eldbus version minor number */ + +#define ELDBUS_FDO_BUS "org.freedesktop.DBus" /**< Eldbus bus name */ +#define ELDBUS_FDO_PATH "/org/freedesktop/DBus" /**< Eldbus path name */ +#define ELDBUS_FDO_INTERFACE ELDBUS_FDO_BUS /**< Eldbus interface name */ +#define ELDBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties" /**< Eldbus object properties request name */ +#define ELDBUS_FDO_INTERFACE_OBJECT_MANAGER "org.freedesktop.DBus.ObjectManager" /**< Eldbus object manager request name */ +#define ELDBUS_FDO_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable" /**< Eldbus object introspect request name */ +#define ELDBUS_FDO_INTEFACE_PEER "org.freedesktop.DBus.Peer" /**< Eldbus object peer request name */ +#define ELDBUS_ERROR_PENDING_CANCELED "org.enlightenment.DBus.Canceled" /**< Eldbus canceled answer */ +#define ELDBUS_ERROR_PENDING_TIMEOUT "org.freedesktop.DBus.Error.NoReply" /**< Eldbus timeout error answer */ +/** + * @typedef Eldbus_Version + * Represents the current version of Eldbus + */ typedef struct _Eldbus_Version { - int major; - int minor; - int micro; - int revision; + int major; /**< major (binary or source incompatible changes) */ + int minor; /**< minor (new features, bugfixes, major improvements version) */ + int micro; /**< micro (bugfix, internal improvements, no new features version) */ + int revision; /**< git revision (0 if a proper release or the git revision number Eldbus is built from) */ } Eldbus_Version; -EAPI extern const Eldbus_Version * eldbus_version; +EAPI extern const Eldbus_Version * eldbus_version; /**< Global Eldbus_Version object */ /** * @brief Initialize eldbus. @@ -152,6 +156,11 @@ EAPI int eldbus_init(void); */ EAPI int eldbus_shutdown(void); +/** + * @typedef Eldbus_Free_Cb + * + * Callback that is called when the connection is freed. + */ typedef void (*Eldbus_Free_Cb)(void *data, const void *deadptr); /** @@ -202,7 +211,18 @@ typedef struct _Eldbus_Pending Eldbus_Pending; */ typedef struct _Eldbus_Signal_Handler Eldbus_Signal_Handler; +/** + * @typedef Eldbus_Message_Cb + * + * Callback that is called when answer of a method call message comes. + */ typedef void (*Eldbus_Message_Cb)(void *data, const Eldbus_Message *msg, Eldbus_Pending *pending); + +/** + * @typedef Eldbus_Signal_Cb + * + * Callback that is called when a signal is received. + */ typedef void (*Eldbus_Signal_Cb)(void *data, const Eldbus_Message *msg); /** * @} diff --git a/src/lib/eldbus/eldbus_connection.h b/src/lib/eldbus/eldbus_connection.h index e8542b47a3..10995a7081 100644 --- a/src/lib/eldbus/eldbus_connection.h +++ b/src/lib/eldbus/eldbus_connection.h @@ -7,6 +7,11 @@ * * @{ */ + +/** + * @typedef Eldbus_Connection_Type + * Enum of several Eldbus connection types. + */ typedef enum { ELDBUS_CONNECTION_TYPE_UNKNOWN = 0, /**< sentinel, not a real type */ @@ -17,7 +22,7 @@ typedef enum ELDBUS_CONNECTION_TYPE_LAST /**< sentinel, not a real type */ } Eldbus_Connection_Type; -#define ELDBUS_TIMEOUT_INFINITE ((int) 0x7fffffff) +#define ELDBUS_TIMEOUT_INFINITE ((int) 0x7fffffff) /**< Infinite timeout definition */ /** * Establish a connection to bus and integrate it with the ecore main @@ -70,7 +75,8 @@ EAPI Eldbus_Connection *eldbus_private_address_connection_get(const char *addres /** * @brief Increment connection reference count. * - * @param conn The given Eldbus_Connection object to reference + * @param conn The given Eldbus_Connection object to reference. + * @return The Eldbus_Connection object given as parameter. */ EAPI Eldbus_Connection *eldbus_connection_ref(Eldbus_Connection *conn) EINA_ARG_NONNULL(1); @@ -79,6 +85,8 @@ EAPI Eldbus_Connection *eldbus_connection_ref(Eldbus_Connection *conn) EINA_ARG_ * * If reference count reaches 0, the connection to bus will be dropped and all * its children will be invalidated. + * + * @param conn The given Eldbus_Connection object to unreference. */ EAPI void eldbus_connection_unref(Eldbus_Connection *conn) EINA_ARG_NONNULL(1); @@ -125,6 +133,10 @@ EAPI void *eldbus_connection_data_get(const Eldbus_Connection *conn, */ EAPI void *eldbus_connection_data_del(Eldbus_Connection *conn, const char *key) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Connection_Event_Type + * Enum of several Eldbus connection events. + */ typedef enum { ELDBUS_CONNECTION_EVENT_DEL, @@ -132,6 +144,11 @@ typedef enum ELDBUS_CONNECTION_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Connection_Event_Type; +/** + * @typedef Eldbus_Connection_Event_Cb + * + * Callback called when we receive an event. + */ typedef void (*Eldbus_Connection_Event_Cb)(void *data, Eldbus_Connection *conn, void *event_info); /** @@ -155,6 +172,7 @@ EAPI void eldbus_connection_event_callback_del(Eldbus_Connectio * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to use default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending struct. */ EAPI Eldbus_Pending *eldbus_connection_send(Eldbus_Connection *conn, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); diff --git a/src/lib/eldbus/eldbus_freedesktop.h b/src/lib/eldbus/eldbus_freedesktop.h index 8a66b068eb..1b2901ca4d 100644 --- a/src/lib/eldbus/eldbus_freedesktop.h +++ b/src/lib/eldbus/eldbus_freedesktop.h @@ -17,6 +17,16 @@ #define ELDBUS_NAME_REQUEST_REPLY_EXISTS 3 /**< Service is already in the queue */ #define ELDBUS_NAME_REQUEST_REPLY_ALREADY_OWNER 4 /**< Service is already the primary owner */ +/** + * Send a "RequestName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param flags Parameter of the "RequestName" method. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_request(Eldbus_Connection *conn, const char *bus, unsigned int flags, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); /* Replies to releasing a name */ @@ -24,19 +34,90 @@ EAPI Eldbus_Pending *eldbus_name_request(Eldbus_Connection *conn, const char *bu #define ELDBUS_NAME_RELEASE_REPLY_NON_EXISTENT 2 /**< The given name does not exist on the bus */ #define ELDBUS_NAME_RELEASE_REPLY_NOT_OWNER 3 /**< Service is not an owner of the given name */ +/** + * Send a "ReleaseName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_release(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); + +/** + * Send a "GetNameOwner" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_owner_get(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); + +/** + * Send a "NameHasOwner" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_owner_has(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data); + +/** + * Send a "ListNames" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_names_list(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); + +/** + * Send a "ListActivatableNames" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_names_activatable_list(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); + +/** + * Send a "Hello" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_hello(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); /* Replies to service starts */ #define ELDBUS_NAME_START_REPLY_SUCCESS 1 /**< Service was auto started */ #define ELDBUS_NAME_START_REPLY_ALREADY_RUNNING 2 /**< Service was already running */ +/** + * Send a "StartServiceByName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus. + * @param flags Parameter of the "StartServiceByName" method. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_start(Eldbus_Connection *conn, const char *bus, unsigned int flags, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Name_Owner_Changed_Cb + * + * Callback called when unique id of a bus name changed. + */ typedef void (*Eldbus_Name_Owner_Changed_Cb)(void *data, const char *bus, const char *old_id, const char *new_id); /** @@ -70,7 +151,25 @@ EAPI void eldbus_name_owner_changed_callback_del(Eldbus_Connect * * @{ */ + +/** + * Call the method "Ping" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_peer_ping(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Call the method "GetMachineId" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_peer_machine_id_get(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** @@ -82,6 +181,15 @@ EAPI Eldbus_Pending *eldbus_object_peer_machine_id_get(Eldbus_Object *obj * * @{ */ + +/** + * Call the method "Introspect" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_introspect(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @} @@ -107,24 +215,72 @@ EAPI Eldbus_Pending *eldbus_object_introspect(Eldbus_Object *obj, Eldbus_ */ EAPI Eina_Bool eldbus_proxy_properties_monitor(Eldbus_Proxy *proxy, Eina_Bool enable) EINA_ARG_NONNULL(1); +/** + * Get a property. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_get(Eldbus_Proxy *proxy, const char *name, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * Set a property. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @param sig + * @param value The value to set. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_set(Eldbus_Proxy *proxy, const char *name, const char *sig, const void *value, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2, 3, 4); + +/** + * Get all properties. + * + * @param proxy The proxy object on which to do the query. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_get_all(Eldbus_Proxy *proxy, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Register a callback on "PropertiesChanged" signal. + * + * @param proxy The proxy object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "PropertiesChanged" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_proxy_properties_changed_callback_add(Eldbus_Proxy *proxy, Eldbus_Signal_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * Return the cached value of property. + * * This only work if you have enable eldbus_proxy_properties_monitor or * if you have call eldbus_proxy_event_callback_add of type * ELDBUS_PROXY_EVENT_PROPERTY_CHANGED and the property you want had changed. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @return Cached value of property. */ EAPI Eina_Value *eldbus_proxy_property_local_get(Eldbus_Proxy *proxy, const char *name) EINA_ARG_NONNULL(1, 2); /** - * Return a Eina_Hash with all cached properties. + * Get all cached properties. + * * This only work if you have enable eldbus_proxy_properties_monitor or * if you have call eldbus_proxy_event_callback_add of type * ELDBUS_PROXY_EVENT_PROPERTY_CHANGED. + * + * @param proxy The proxy object on which to do the query. + * @return A Eina_Hash with all cached properties */ EAPI const Eina_Hash *eldbus_proxy_property_local_get_all(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); @@ -137,10 +293,35 @@ EAPI const Eina_Hash *eldbus_proxy_property_local_get_all(Eldbus_Proxy *pro * @{ */ +/** + * Call the method "GetManagedObjects" on the eldbus object. + * + * @param obj A Eldbus object. + * @param cb The callback to call when receiving an answer. + * @param data The data to pass to the callback. + * + * @return A Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_managed_objects_get(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); +/** + * Register a callback on "InterfacesAdded" signal. + * + * @param obj The Eldbus object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param cb_data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "InterfacesAdded" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_object_manager_interfaces_added(Eldbus_Object *obj, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); +/** + * Register a callback on "InterfacesRemoved" signal. + * + * @param obj The Eldbus object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param cb_data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "InterfacesRemoved" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_object_manager_interfaces_removed(Eldbus_Object *obj, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); /** diff --git a/src/lib/eldbus/eldbus_message.h b/src/lib/eldbus/eldbus_message.h index 39bc41efa0..c3e3b8e5c9 100644 --- a/src/lib/eldbus/eldbus_message.h +++ b/src/lib/eldbus/eldbus_message.h @@ -10,6 +10,9 @@ /** * @brief Increase message reference. + * + * @param msg The Eldbus_Message object. + * @return The previous Eldbus_Message with incremented refcount. */ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); @@ -18,14 +21,57 @@ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NON * * When refcount reaches zero the message and all its resources will be * freed. + * + * @param msg The Eldbus_Message object. */ EAPI void eldbus_message_unref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); +/** + * Get the Eldbus message path. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message path. + */ EAPI const char *eldbus_message_path_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message interface. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message interface. + */ EAPI const char *eldbus_message_interface_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message member. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message member. + */ EAPI const char *eldbus_message_member_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message destination. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message destination. + */ EAPI const char *eldbus_message_destination_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message sender. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message sender. + */ EAPI const char *eldbus_message_sender_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message signature. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message signature. + */ EAPI const char *eldbus_message_signature_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -72,6 +118,7 @@ EAPI Eldbus_Message *eldbus_message_method_return_new(const Eldbus_Messag * desired. * @param text Variable in which to store the error text or @c NULL if it's not * desired. + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1); @@ -79,9 +126,9 @@ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, c * @brief Get the arguments from an Eldbus_Message * * Get the arguments of an Eldbus_Message storing them in the locations pointed - * to by the pointer arguments that follow @param signature. Each pointer + * to by the pointer arguments that follow param signature. Each pointer * argument must be of a type that is appropriate for the correspondent complete - * type in @param signature. For complex types such as arrays, structs, + * type in param signature. For complex types such as arrays, structs, * dictionaries or variants, a pointer to Eldbus_Message_Iter* must be provided. * * @param msg The message to get the arguments from. @@ -98,7 +145,7 @@ EAPI Eina_Bool eldbus_message_arguments_get(const Eldbus_Message *ms * @brief Get the arguments from an Eldbus_Message using a va_list. * * @param msg The message to get the arguments from. - * @param signature The signature user is expecting to read from @param msg. + * @param signature The signature user is expecting to read from param msg. * @param ap The va_list containing the pointer arguments. * * @see eldbus_message_arguments_get() @@ -111,8 +158,8 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m /** * @brief Append arguments into an Eldbus_Message * - * Append arguments into an Eldbus_Message according to the @param signature - * provided. For each complete type in @param signature, a value of the + * Append arguments into an Eldbus_Message according to the param signature + * provided. For each complete type in param signature, a value of the * corresponding type must be provided. * * This function supports only basic types. For complex types use @@ -120,7 +167,7 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m * * @param msg The message in which arguments are being appended. * @param signature Signature of the arguments that are being appended. - * @param ... Values of each argument to append in @param msg. + * @param ... Values of each argument to append in param msg. * * @return EINA_TRUE on success, EINA_FALSE otherwise. */ @@ -183,6 +230,7 @@ EAPI Eina_Bool eldbus_message_iter_basic_append(Eldbus_Message_Ite * @param iter iterator in which data will be appended * @param signature signature of the contained data * @param ... values for each complete type + * @return EINA_TRUE on success, else EINA_FALSE * * @see eldbus_message_iter_container_new() * @see eldbus_message_iter_container_close() @@ -206,6 +254,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_append(Eldbus_Message * @param iter iterator * @param signature of data * @param ap va_list with the values + * @return EINA_TRUE on success, else EINA_FALSE * * @note This function don't support variant, use instead * eldbus_message_iter_container_new() to create the variant fill @@ -221,6 +270,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_vappend(Eldbus_Messag * @param type basic type that will be appended * @param array data to append * @param size of array + * @return EINA_TRUE on success, else EINA_FALSE */ EAPI Eina_Bool eldbus_message_iter_fixed_array_append(Eldbus_Message_Iter *iter, int type, const void *array, unsigned int size) EINA_ARG_NONNULL(1, 3); @@ -247,6 +297,9 @@ EAPI void eldbus_message_iter_basic_get(Eldbus_Message_Iter * /** * @brief Returns the current signature of a message iterator. * + * @param iter The iterator on which to query the signature. + * @return A string containing the message iterator signature. + * * @note The returned string must be freed. */ EAPI char *eldbus_message_iter_signature_get(Eldbus_Message_Iter *iter) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -265,14 +318,14 @@ EAPI Eina_Bool eldbus_message_iter_next(Eldbus_Message_Iter *iter) * Useful to iterate over arrays. * * @param iter iterator - * @param type of the next completed type in Iterator + * @param signature of the next completed type in Iterator * @param ... pointer of where data will be stored * - * @param if iterator was reach to end or if type different of the type that + * @return if iterator was reach to end or if type different of the type that * iterator points return EINA_FALSE * */ -EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char type, ...) EINA_ARG_NONNULL(1, 2, 3); +EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char signature, ...) EINA_ARG_NONNULL(1, 2, 3); /** * @brief Reads a block of fixed-length values from the message iterator. @@ -290,6 +343,12 @@ EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Ite * * Because the array is not copied, this function runs in constant time and is * fast; it's much preferred over walking the entire array with an iterator. + * + * @param iter The message iterator + * @param signature + * @param value + * @param n_elements + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_iter_fixed_array_get(Eldbus_Message_Iter *iter, int signature, void *value, int *n_elements) EINA_ARG_NONNULL(1, 3, 4); diff --git a/src/lib/eldbus/eldbus_message_helper.h b/src/lib/eldbus/eldbus_message_helper.h index 3009bc1301..584318267f 100644 --- a/src/lib/eldbus/eldbus_message_helper.h +++ b/src/lib/eldbus/eldbus_message_helper.h @@ -5,6 +5,15 @@ * @{ */ +/** + * @typedef Eldbus_Dict_Cb_Get + * + * Callback used when iterating over a dictionary. It is called at each entry iteration. + * + * @param data Context data passed to the callback. + * @param key Key parameter. + * @param var A message iterator on the current entry. + */ typedef void (*Eldbus_Dict_Cb_Get)(void *data, const void *key, Eldbus_Message_Iter *var); /** diff --git a/src/lib/eldbus/eldbus_object.h b/src/lib/eldbus/eldbus_object.h index 514b40ec0b..297cb0b0f3 100644 --- a/src/lib/eldbus/eldbus_object.h +++ b/src/lib/eldbus/eldbus_object.h @@ -14,17 +14,23 @@ * @param conn connection where object belongs * @param bus name of bus or unique-id of who listens for calls of this object * @param path object path of this object + * @return The corresponding Eldbus_Object. */ EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /** * @brief Increase object reference. + * + * @param obj An Eldbus_Object. + * @return The same Eldbus_Object with an increased refcount. */ EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); /** * @brief Decrease object reference. * If reference == 0 object will be freed and all its children. + * + * @param obj An Eldbus_Object. */ EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); @@ -39,60 +45,128 @@ EAPI void eldbus_object_free_cb_add(Eldbus_Object *obj, Eldbus_Free_Cb /** * @brief Remove callback registered in eldbus_object_free_cb_add(). + * + * @param obj Object monitored. + * @param cb Callback that was registered. + * @param data Data that was passed to callback. */ EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Object_Event_Type + * + * An enumeration containing several Eldbus_Object event types. + */ typedef enum { ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */ ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */ - ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, - ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, + ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, /**< a property has changes */ + ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, /**< a property was removed */ ELDBUS_OBJECT_EVENT_DEL, ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Object_Event_Type; +/** + * @typedef Eldbus_Object_Event_Interface_Added + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_ADDED event. + */ typedef struct _Eldbus_Object_Event_Interface_Added { - const char *interface; - Eldbus_Proxy *proxy; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ } Eldbus_Object_Event_Interface_Added; +/** + * @typedef Eldbus_Object_Event_Interface_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Interface_Removed { - const char *interface; + const char *interface; /**< The interface name */ } Eldbus_Object_Event_Interface_Removed; +/** + * @typedef Eldbus_Object_Event_Property_Changed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED event. + */ typedef struct _Eldbus_Object_Event_Property_Changed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; - const Eina_Value *value; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ + const Eina_Value *value; /**< The value of the property */ } Eldbus_Object_Event_Property_Changed; +/** + * @typedef Eldbus_Object_Event_Property_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Property_Removed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ } Eldbus_Object_Event_Property_Removed; +/** + * @typedef Eldbus_Object_Event_Cb + * + * Callback that will be called when an Eldbus_Object event happens. + * + * @param data Context data. + * @param obj The Eldbus_Object. + * @param event_info Information about the event that triggered the callback. + */ typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info); /** * @brief Add a callback function to be called when an event of the specified * type occurs. + * + * @param obj The Eldbus_Object on which to register a callback. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_add(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); /** * @brief Remove callback registered in eldbus_object_event_callback_add(). + * + * @param obj The Eldbus_Object. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_del(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); +/** + * Get the Eldbus_Connection object associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return The corresponding Eldbus_Connection object. + */ EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the name associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object name. + */ EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the path associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object path. + */ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -105,6 +179,7 @@ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending object. */ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); @@ -116,9 +191,19 @@ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Messag * @param member name of the signal * @param cb callback that will be called when this signal is received * @param cb_data data that will be passed to callback + * @return A listener to the desired signal. */ EAPI Eldbus_Signal_Handler *eldbus_object_signal_handler_add(Eldbus_Object *obj, const char *interface, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 4); +/** + * @brief Call a dbus method on the Eldbus_Object. + * + * @param obj The Eldbus_Object on which to call the method. + * @param interface Interface name. + * @param member Name of the method to be called. + * + * @return a new Eldbus_Message, free with eldbus_message_unref() + */ EAPI Eldbus_Message *eldbus_object_method_call_new(Eldbus_Object *obj, const char *interface, const char *member) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /** diff --git a/src/lib/eldbus/eldbus_pending.h b/src/lib/eldbus/eldbus_pending.h index 98c0085657..8cb8e969ae 100644 --- a/src/lib/eldbus/eldbus_pending.h +++ b/src/lib/eldbus/eldbus_pending.h @@ -8,23 +8,86 @@ * @{ */ +/** + * @brief Set data to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + * @param data The data to set to the Eldbus_Pending object. + */ EAPI void eldbus_pending_data_set(Eldbus_Pending *pending, const char *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get the data set to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + * @return The data set to the Eldbus_Pending object. + */ EAPI void *eldbus_pending_data_get(const Eldbus_Pending *pending, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Delete the data set to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + */ EAPI void *eldbus_pending_data_del(Eldbus_Pending *pending, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Cancel the pending message. + * + * @param pending The Eldbus_Pending object corresponding to the pending message. + */ EAPI void eldbus_pending_cancel(Eldbus_Pending *pending) EINA_ARG_NONNULL(1); +/** + * @brief Get the destination of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the destination of the message. + */ EAPI const char *eldbus_pending_destination_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the path of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the path of the message. + */ EAPI const char *eldbus_pending_path_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the interface of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the interface of the message. + */ EAPI const char *eldbus_pending_interface_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the method of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the method of the message. + */ EAPI const char *eldbus_pending_method_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Add a callback function to be called when pending will be freed. + * + * @param pending The Eldbus_Pending object on which the callback is registered. + * @param cb The callback to register. + * @param data The data to pass to the callback. */ EAPI void eldbus_pending_free_cb_add(Eldbus_Pending *pending, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Remove callback registered in eldbus_pending_free_cb_add(). + * + * @param pending The Eldbus_Pending object on which the callback was registered. + * @param cb The callback that was registered. + * @param data The data passed to the callback. */ EAPI void eldbus_pending_free_cb_del(Eldbus_Pending *pending, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); diff --git a/src/lib/eldbus/eldbus_proxy.h b/src/lib/eldbus/eldbus_proxy.h index 5752001bd9..5993967439 100644 --- a/src/lib/eldbus/eldbus_proxy.h +++ b/src/lib/eldbus/eldbus_proxy.h @@ -10,40 +10,96 @@ /** * @brief Get a proxy of the following interface name in a Eldbus_Object. + * + * @param obj The Eldbus_Object on which to do the query. + * @param interface The interface name of the proxy. + * @return The corresponding Eldbus_Proxy object. */ EAPI Eldbus_Proxy *eldbus_proxy_get(Eldbus_Object *obj, const char *interface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** * @brief Increase proxy reference. + * + * @param proxy The Eldbus_Proxy on which to increase the refcount. + * @return The Eldbus_Proxy with an increased refcount. */ EAPI Eldbus_Proxy *eldbus_proxy_ref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); /** * @brief Decrease proxy reference. * If reference == 0 proxy will be freed and all your children. + * + * @param proxy The Eldbus_Proxy on which to decrease the refcount. */ EAPI void eldbus_proxy_unref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); +/** + * @brief Get the Eldbus_Object associated with a proxy object. + * + * @param proxy The Eldbus_Proxy on which to do the query. + * @return The corresponding Eldbus_Object. + */ EAPI Eldbus_Object *eldbus_proxy_object_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the interface name associated with a proxy object. + * + * @param proxy The Eldbus_Proxy on which to do the query. + * @return The string corresponding to the interface name. + */ EAPI const char *eldbus_proxy_interface_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; +/** + * @brief Set data to an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to set the data. + * @param key A string to which the data will be associated. + * @param data The data to set to the proxy object. + */ EAPI void eldbus_proxy_data_set(Eldbus_Proxy *proxy, const char *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get data of an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to get the data. + * @param key The string to which the data is associated. + * @return The data set to the proxy object associated with the provided key. + */ EAPI void *eldbus_proxy_data_get(const Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Delete data of an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to delete the data. + * @param key The string to which the data is associated. + */ EAPI void *eldbus_proxy_data_del(Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2); /** - * @brief Add a callback function to be called when occurs a event of the - * type passed. + * @brief Add a callback function to be called when an event of the + * type passed occurs. + * + * @param proxy The Eldbus_Proxy on which to add the callback. + * @param cb The callback to add. + * @param data The data to pass to the callback. */ EAPI void eldbus_proxy_free_cb_add(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Remove callback registered in eldbus_proxy_free_cb_add(). + * + * @param proxy The Eldbus_Proxy on which to delete the callback. + * @param cb The callback to delete. + * @param data The data passed to the callback. */ EAPI void eldbus_proxy_free_cb_del(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Constructs a new message to invoke a method on a remote interface. + * + * @param proxy The Eldbus_Proxy on which to call the method. + * @param member The name of the method to invoke. + * @return An Eldbus_Message object. */ EAPI Eldbus_Message *eldbus_proxy_method_call_new(Eldbus_Proxy *proxy, const char *member) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; @@ -56,6 +112,7 @@ EAPI Eldbus_Message *eldbus_proxy_method_call_new(Eldbus_Proxy *proxy, co * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending object on the sent message. */ EAPI Eldbus_Pending *eldbus_proxy_send(Eldbus_Proxy *proxy, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); @@ -72,6 +129,7 @@ EAPI Eldbus_Pending *eldbus_proxy_send(Eldbus_Proxy *proxy, Eldbus_Messag * ELDBUS_TIMEOUT_INFINITE for no timeout * @param signature of data that will be send * @param ... data value + * @return A Eldbus_Pending object on the sent message. * * @note This function only support basic type to complex types use * eldbus_message_iter_* functions. @@ -90,6 +148,7 @@ EAPI Eldbus_Pending *eldbus_proxy_call(Eldbus_Proxy *proxy, const char *m * ELDBUS_TIMEOUT_INFINITE for no timeout * @param signature of data that will be send * @param ap va_list of data value + * @return A Eldbus_Pending object on the sent message. * * @note This function only support basic type to complex types use * eldbus_message_iter_* functions. @@ -103,47 +162,86 @@ EAPI Eldbus_Pending *eldbus_proxy_vcall(Eldbus_Proxy *proxy, const char * * @param member name of the signal * @param cb callback that will be called when this signal is received * @param cb_data data that will be passed to callback + * @return A listener to the desired signal. */ EAPI Eldbus_Signal_Handler *eldbus_proxy_signal_handler_add(Eldbus_Proxy *proxy, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); +/** + * @typedef Eldbus_Proxy_Event_Type + * + * An enumeration containing proxy event types. + */ typedef enum { - ELDBUS_PROXY_EVENT_PROPERTY_CHANGED = 0, - ELDBUS_PROXY_EVENT_PROPERTY_REMOVED, + ELDBUS_PROXY_EVENT_PROPERTY_CHANGED = 0, /**< a property has changed */ + ELDBUS_PROXY_EVENT_PROPERTY_REMOVED, /**< a property was removed */ ELDBUS_PROXY_EVENT_DEL, ELDBUS_PROXY_EVENT_PROPERTY_LOADED, ELDBUS_PROXY_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Proxy_Event_Type; +/** + * @typedef Eldbus_Proxy_Event_Property_Changed + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_CHANGED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Changed { - const char *name; - const Eldbus_Proxy *proxy; - const Eina_Value *value; + const char *name; /**< the name of the property */ + const Eldbus_Proxy *proxy; /**< the proxy object */ + const Eina_Value *value; /**< the value of the property */ } Eldbus_Proxy_Event_Property_Changed; +/** + * @typedef Eldbus_Proxy_Event_Property_Loaded + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_LOADED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Loaded { - const Eldbus_Proxy *proxy; + const Eldbus_Proxy *proxy; /**< the proxy object */ } Eldbus_Proxy_Event_Property_Loaded; +/** + * @typedef Eldbus_Proxy_Event_Property_Removed + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_REMOVED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Removed { - const char *interface; - const Eldbus_Proxy *proxy; - const char *name; + const char *interface; /**< interface name */ + const Eldbus_Proxy *proxy; /**< the proxy object */ + const char *name; /**< the name of the property */ } Eldbus_Proxy_Event_Property_Removed; +/** + * @typedef Eldbus_Proxy_Event_Cb + * + * A callback called when an event occurs. + * @param data The data passed by the caller. + * @param proxy The Eldbus_Proxy object. + * @param event_info Information on the event that triggered the callback. + */ typedef void (*Eldbus_Proxy_Event_Cb)(void *data, Eldbus_Proxy *proxy, void *event_info); /** * @brief Add a callback function to be called when occurs a event of the * type passed. + * + * @param proxy The Eldbus_Proxy object. + * @param type The type of the event to register an callback on. + * @param cb The callback function to register. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_proxy_event_callback_add(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); /** * @brief Remove callback registered in eldbus_proxy_event_callback_add(). + * + * @param proxy The Eldbus_Proxy object. + * @param type The type of the event the callback was registered on. + * @param cb The callback function to delete. + * @param cb_data The data passed to the callback. */ EAPI void eldbus_proxy_event_callback_del(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); diff --git a/src/lib/embryo/Embryo.h b/src/lib/embryo/Embryo.h index 923afe73aa..413c38bf1a 100644 --- a/src/lib/embryo/Embryo.h +++ b/src/lib/embryo/Embryo.h @@ -370,13 +370,17 @@ extern "C" { #define EMBRYO_VERSION_MAJOR EFL_VERSION_MAJOR #define EMBRYO_VERSION_MINOR EFL_VERSION_MINOR - + + /** + * @typedef Embryo_Version + * Represents the current version of Embryo + */ typedef struct _Embryo_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Embryo is built from) */ } Embryo_Version; EAPI extern Embryo_Version *embryo_version; diff --git a/src/lib/emotion/Emotion.h b/src/lib/emotion/Emotion.h index b07cbd3062..a776084d38 100644 --- a/src/lib/emotion/Emotion.h +++ b/src/lib/emotion/Emotion.h @@ -272,13 +272,16 @@ extern "C" { #define EMOTION_VERSION_MAJOR EFL_VERSION_MAJOR #define EMOTION_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Emotion_Version + * Represents the current version of Emotion + */ typedef struct _Emotion_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Emotion is built from) */ } Emotion_Version; EAPI extern Emotion_Version *emotion_version; @@ -364,7 +367,19 @@ extern "C" { * @defgroup Emotion_Ressource Video ressource management */ +/** + * @brief Initialise Emotion library + * + * Initialise needed libraries like eina ecore eet + * Initialise needed modules like webcam + */ EAPI Eina_Bool emotion_init(void); + +/** + * @brief Shutdown Emotion library + * + * Proper shutdown of all loaded modules and initialised libraries. + */ EAPI Eina_Bool emotion_shutdown(void); /** @@ -851,6 +866,15 @@ EAPI void emotion_object_smooth_scale_set (Evas_Object *obj, Eina_B * @ingroup Emotion_Video */ EAPI Eina_Bool emotion_object_smooth_scale_get (const Evas_Object *obj); + +/** + * @brief Send an Emotion Event to an Evas object + * + * @param obj The object target of the event. + * @param ev The emotion event. + * + * @see Emotion_Event + */ EAPI void emotion_object_event_simple_send (Evas_Object *obj, Emotion_Event ev); /** @@ -1001,8 +1025,38 @@ EAPI const char *emotion_object_video_subtitle_file_get (const Evas_Object *ob * @ingroup Emotion_Video */ EAPI int emotion_object_video_channel_count (const Evas_Object *obj); + +/** + * @brief Get the name of a given video channel + * + * @param obj The object which we are retrieving the channel name from + * @param channel the channel number + * @return the channel name. + * + * @see emotion_object_video_channel_count() + * + * @ingroup Emotion_Video + */ EAPI const char *emotion_object_video_channel_name_get(const Evas_Object *obj, int channel); + +/** + * @brief Set the channel for a given video object + * + * @param obj The target object which we are setting the channel + * @param channel the channel number to be setted. + * + * @ingroup Emotion_Video + */ EAPI void emotion_object_video_channel_set (Evas_Object *obj, int channel); + +/** + * @brief Get the channel for a given video object + * + * @param obj The target object which we are getting the channel + * @return The current channel number. + * + * @ingroup Emotion_Video + */ EAPI int emotion_object_video_channel_get (const Evas_Object *obj); EAPI void emotion_object_spu_mute_set (Evas_Object *obj, Eina_Bool mute); EAPI Eina_Bool emotion_object_spu_mute_get (const Evas_Object *obj); diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 4f91433588..5d1fb0c31c 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -36,13 +36,16 @@ extern "C" { #define ETHUMB_VERSION_MAJOR EFL_VERSION_MAJOR #define ETHUMB_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Ethumb_Version + * Represents the current version of Ethumb + */ typedef struct _Ethumb_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ethumb is built from) */ } Ethumb_Version; EAPI extern Ethumb_Version *ethumb_version; @@ -141,10 +144,26 @@ typedef struct _Ethumb Ethumb; */ typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success); +/** + * @brief Initialize ethumb. + * @return 1 or greater on success, 0 otherwise. + */ EAPI int ethumb_init(void); +/** + * @brief Shutdown ethumb, unloading all currently-loaded modules. + * @return 0 if ethumb shuts down, an integer greater than 0 otherwise. + */ EAPI int ethumb_shutdown(void); +/** + * @brief Create a new ethumb object. + * return The newly-created ethumb object + */ EAPI Ethumb * ethumb_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; + +/** + * @brief Free an ethumb object. + */ EAPI void ethumb_free(Ethumb *e); /** @@ -160,13 +179,64 @@ EAPI void ethumb_free(Ethumb *e); * @{ */ +/** + * + * @brief Set the Ethumb Frame + * + * This can be used to simulate wood frames in the Thumbnails + * + * @param e handle of the current thumbnailer. + * @param theme_file the edje theme file + * @param group the edje group in theme + * @param swallow the edje swallow in theme + * + * @return EINA_TRUE on success and EINA_FALSE on failure + */ EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1); + +/** + * @brief Retreives the current ethumb frame of and Ethumb instance. + * + * @param e handle of the current thumbnailer. + * @param theme_file will be setted with the edje theme + * @param group will be setted with the edje group + * @param swallow will be setted with the edje swallow + */ EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1); +/** + * @brief Set the ethumb thumbnails path + * + * @param e handle of the current thumbnailer. + * @param path The thumbnails path + * + */ EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1); + +/** + * @brief Get the ethumb thumbnails path + * + * @param e handle of the current thumbnailer. + * + * @return The thumbnails path for the current thumbnailer + */ EAPI const char *ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @brief Set the thumbnails category + * + * @param e handle of the current thumbnailer. + * @param category the category to set + */ EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1); + +/** + * @brief Get the thumbnails category + * + * @param e handle of the current thumbnailer + * + * @return the current thumbnailer thumbnails category + */ EAPI const char *ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1); @@ -209,40 +279,213 @@ typedef enum _Ethumb_Thumb_Orientation EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1); +/** + * @brief Set the size of thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param tw Thumbnail width. + * @param th Thumbnail height. + */ EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1); +/** + * @brief Get the size of thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param[out] tw Pointer to an int to store the thumbnail width. + * @param[out] th Pointer to an int to store the thumbnail height. + */ EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1); +/** + * @brief Set the fileformat of the thumbnails + * + * Thumbnails are sent compressed; possible formats are PNG, JPEG and EET. + * + * @param e A pointer to an Ethumb object. + */ EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1); +/** + * @brief Get the fileformat of the thumbnails + * + * @param e A pointer to an Ethumb object. + * @return The thumbnail fileformat + * + * @see ethumb_thumb_format_set + */ EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect a) EINA_ARG_NONNULL(1); +/** + * @brief Set the aspect ratio policy. + * + * When the source and thumbnail aspect ratios don't match, this policy sets + * how to adapt from the former to the latter: resize keeping source aspect + * ratio, resize ignoring it or crop. + * + * @param e A pointer to an Ethumb object. + * @param aspect The new aspect ratio policy. + */ +EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect aspect) EINA_ARG_NONNULL(1); +/** + * @brief Get the aspect ratio policy. + * + * @param e A pointer to an Ethumb object. + * @return The aspect ratio policy. + */ EAPI Ethumb_Thumb_Aspect ethumb_thumb_aspect_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation o) EINA_ARG_NONNULL(1); +/** + * @brief Set the thumbnail rotation or flip. + * + * @param e A pointer to an Ethumb object. + * @param orientation The new orientation. + */ +EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation orientation) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail rotation. + * + * @param e A pointer to an Ethumb object. + * @return The current rotation. + */ EAPI Ethumb_Thumb_Orientation ethumb_thumb_orientation_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_crop_align_set(Ethumb *e, float x, float y) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_crop_align_get(const Ethumb *e, float *x, float *y) EINA_ARG_NONNULL(1); +/** + * @brief Set the thumbnail compression quality. + * + * @param e A pointer to an Ethumb object. + * @param quality Compression quality (from 0 to 100, 100 being the best; default is 80) + */ EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail compression quality. + * + * @param e A pointer to an Ethumb object. + * @return The current compression quality (from 0 to 100, 100 being the best) + */ EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; +/** + * @brief Set the compression rate + * + * @param e handle of the current thumbnailer. + * @param compress the compression rate (in percentage) + * + */ EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1); + +/** + * @brief Get the compression rate + * + * @param e handle of the current thumbnailer. + * + * @return the compression rate (in percentage) + */ EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; +/** + * @brief set the video play start point + * + * Set the start point of video thumbnail + * + * @param e handle of the current thumbnailer. + * @param start the start point (float from 0.0 to 1.0) + */ EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1); + +/** + * @brief get the video play start point + * + * Get the start point of video thumbnail + * + * @param e handle of the current thumbnailer. + * + * @return the start point (float from 0.0 to 1.0) + */ EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the video time (duration) in seconds. + * + * @param e handle of the current thumbnailer. + * @param time the video duration in seconds + */ EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1); + +/** + * @brief Get the video time (duration) in seconds. + * + * @param e handle of the current thumbnailer. + * @return the video duration in seconds + */ EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the video frame interval, in seconds + * + * This is useful for animated thumbnail and will define skip time + * before going to the next frame. Note that video backends might not + * be able to precisely skip that amount as it will depend on various + * factors, including video encoding. + * + * @param e handle of the current thumbnailer. + * @param interval the frame display interval in seconds + */ EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1); + +/** + * @brief Get the video frame interval, in seconds + * + * @param e handle of the current thumbnailer. + * @return the frame display interval in seconds + */ EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the number of times the video loops (if applicable). + * + * @param e A pointer to an Ethumb object. + * @param ntimes The number of times the video loops. + */ EAPI void ethumb_video_ntimes_set(Ethumb *e, unsigned int ntimes) EINA_ARG_NONNULL(1); +/** + * @brief Get the number of times the video loops (if applicable). + * + * @param e A pointer to an Ethumb object. + * @return The number of times the video loops. + */ EAPI unsigned int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the thumbnail framerate. + * + * @param e A pointer to an Ethumb object. + * @param fps New framerate of the thumbnail (default 10). + */ EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail framerate. + * + * @param e A pointer to an Ethumb object. + * @return Current framerate of the thumbnail. + */ EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - +/** + * @brief Set the page number to thumbnail in paged documents + * + * @param e handle of the current thumbnailer. + * @param page the page number. + */ EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1); + +/** + * @brief Get the page number thumbnailed in paged documents + * + * @param e handle of the current thumbnailer. + * @return the page number. + */ EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @} @@ -252,15 +495,74 @@ EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RES * @addtogroup Ethumb_Basics Ethumb Basics * @{ */ + +/** + * @brief Set the file for which to generate thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param path The file to use. + * @param key If @a path allows storing multiple resources in a single file + * (EET or Edje for instance), @a key is the key used to locate the + * right resource inside the file. NULL if not applicable. + */ EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2); +/** + * @brief Get the file for which to generate thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param[out] path The file being used. + * @param[out] key The key used to locate the right resource in case the file + * can store several of them. NULL if not applicable. + * @see ethumb_file_set + */ EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1); + +/** + * @brief Reset the source file information. + * + * @param e A pointer to an Ethumb object. + */ EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); +/** + * @brief Generate the thumbnail. + * + * @param e handle of the current thumbnailer. + * @param finished_cb The callback function to run on opertaion end + * @param free_data The callback function to run on free data. + * + * @return EINA_TRUE on success and EINA_FALSE on failure + */ EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief test if the thumbnailer exists + * + * @param e handle of the thumbnailer to test. + * + * @return EINA_TRUE if thumbnailer exists and EINA_FALSE otherwise. + */ EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @brief Duplicate an thumbnailer + * + * @param e Handle of the thumbnailer to duplicate + * + * @return a new allocated copy of the thumbnailer. + */ EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1); + +/** + * @brief Compare two thumbnailers. + * + * @param e1 First handle of thumbnailer to compare + * @param e2 Second handle of thumbnailer to compare + * + * @return EINA_TRUE if the thumbnailers are equal and EINA_FALSE otherwise + */ EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; + EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; EAPI int ethumb_key_cmp(const void *key1, int key1_length, const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE; diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 6826c79b72..e3cdc947a9 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -2,15 +2,46 @@ # error You shall not include this header directly #endif +/** + * @def EVAS_VERSION_MAJOR + * The major number of evas version + */ #define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR + +/** + * @def EVAS_VERSION_MINOR + * The minor number of eet version + */ #define EVAS_VERSION_MINOR EFL_VERSION_MINOR +/** + * @typedef Evas_Version + * + * This is the Evas version information structure that can be used at + * runtime to detect which version of evas is being used and adapt + * appropriately as follows for example: + * + * @code + * #if defined(EVAS_VERSION_MAJOR) && (EVAS_VERSION_MAJOR >= 1) && defined(EVAS_VERSION_MINOR) && (EVAS_VERSION_MINOR > 0) + * printf("Evas version: %i.%i.%i\n", + * evas_version->major, + * evas_version->minor, + * evas_version->micro); + * if (evas_version->revision > 0) + * { + * printf(" Built from Git revision # %i\n", evas_version->revision); + * } + * #endif + * @endcode + * + */ + typedef struct _Evas_Version { - int major; - int minor; - int micro; - int revision; + int major; /**< major (binary or source incompatible changes) */ + int minor; /**< minor (new features, bugfixes, major improvements version) */ + int micro; /**< micro (bugfix, internal improvements, no new features version) */ + int revision; /**< git revision (0 if a proper release or the git revision number Evas is built from) */ } Evas_Version; EAPI extern Evas_Version * evas_version; @@ -197,8 +228,8 @@ typedef struct _Evas_Point Evas_Point; /**< integer point */ typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */ typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */ -typedef struct _Evas_Coord_Size Evas_Coord_Size; /** <Evas_Coord size @since 1.8 */ -typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /** <Evas_Coord size with sub-pixel precision @since 1.8 */ +typedef struct _Evas_Coord_Size Evas_Coord_Size; /**< Evas_Coord size @since 1.8 */ +typedef struct _Evas_Coord_Precision_Size Evas_Coord_Precision_Size; /**< Evas_Coord size with sub-pixel precision @since 1.8 */ typedef struct _Evas_Position Evas_Position; /**< associates given point in Canvas and Output */ typedef struct _Evas_Precision_Position Evas_Precision_Position; /**< associates given point in Canvas and Output, with sub-pixel precision */ @@ -276,6 +307,7 @@ typedef struct _Evas_Public_Data Evas_Public_Data; */ typedef Eo Evas_Object; +/* This define is used in H files generated by Eolian */ #define _EVAS_OBJECT_EO_CLASS_TYPE typedef void Evas_Performance; /**< An Evas Performance handle */ @@ -296,11 +328,11 @@ typedef struct _Evas_Video_Surface Evas_Video_Surface; typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */ -typedef int Evas_Coord; -typedef int Evas_Font_Size; -typedef int Evas_Angle; +typedef int Evas_Coord;/**< A type for coordinates */; +typedef int Evas_Font_Size; /**< A type for font size */ +typedef int Evas_Angle; /**< A type for angle */ -struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */ +struct _Evas_Coord_Rectangle /** A rectangle in Evas_Coord */ { Evas_Coord x; /**< top-left x co-ordinate of rectangle */ Evas_Coord y; /**< top-left y co-ordinate of rectangle */ @@ -308,47 +340,51 @@ struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */ Evas_Coord h; /**< height of rectangle */ }; -struct _Evas_Coord_Point +struct _Evas_Coord_Point /** A Point in Evas_Coord */ { Evas_Coord x; /**< x co-ordinate */ Evas_Coord y; /**< y co-ordinate */ }; -struct _Evas_Coord_Size +struct _Evas_Coord_Size /** A size in Evas_Coord */ { Evas_Coord w; /**< width */ Evas_Coord h; /**< height */ }; -struct _Evas_Coord_Precision_Size + +struct _Evas_Coord_Precision_Size /** A size in Evas_Coord with subpixel precision*/ { - Evas_Coord w; /** < width */ - Evas_Coord h; /** < height */ - double wsub; /** < subpixel precision for width */ - double ysub; /** < subpixel precision for height */ + Evas_Coord w; /**< width */ + Evas_Coord h; /**< height */ + double wsub; /**< subpixel precision for width */ + double ysub; /**< subpixel precision for height */ }; -struct _Evas_Coord_Precision_Point +struct _Evas_Coord_Precision_Point /** A point in Evas_Coord with subpixel precision*/ { - Evas_Coord x, y; - double xsub, ysub; + Evas_Coord x; /**< x co-ordinate */ + Evas_Coord y; /**< y co-ordinate */ + double xsub; /**< subpixel precision for x */ + double ysub; /**< subpixel precision for y */ }; -struct _Evas_Point +struct _Evas_Point /** A point */ { - int x, y; + int x; /**< x co-ordinate */ + int y; /**< y co-ordinate */ }; -struct _Evas_Position +struct _Evas_Position /** A position */ { - Evas_Point output; + Evas_Point output; /**< position on the output */ Evas_Coord_Point canvas; /**< position on the canvas */ }; -struct _Evas_Precision_Position +struct _Evas_Precision_Position /** A position with precision*/ { - Evas_Point output; - Evas_Coord_Precision_Point canvas; + Evas_Point output; /**< position on the output */ + Evas_Coord_Precision_Point canvas; /**< position on the canvas */ }; typedef enum _Evas_Aspect_Control @@ -416,7 +452,11 @@ struct _Evas_Pixel_Import_Source void **rows; /**< an array of pointers (size depends on format) pointing to left edge of each scanline */ }; -/* magic version number to know what the native surf struct looks like */ +/** + * @def EVAS_NATIVE_SURFACE_VERSION + * Magic version number to know what the native surface struct looks like + */ + #define EVAS_NATIVE_SURFACE_VERSION 2 /** @@ -478,12 +518,13 @@ struct _Evas_Native_Surface */ #define EVAS_VIDEO_SURFACE_VERSION 1 -typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface); -typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b); + +typedef void (*Evas_Video_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface); /**< Evas video callback function signature */ +typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Video_Surface *surface, Evas_Coord a, Evas_Coord b); /**< Evas video coordinates callback function signature */ struct _Evas_Video_Surface { - int version; + int version; /**< The Evas Video surface version in use @see EVAS_VIDEO_SURFACE_VERSION*/ Evas_Video_Coord_Cb move; /**< Move the video surface to this position */ Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */ @@ -491,18 +532,24 @@ struct _Evas_Video_Surface Evas_Video_Cb hide; /**< Hide the video overlay surface */ Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */ - Evas_Object *parent; + Evas_Object *parent; /**< The parent object */ void *data; }; +/** + * Enum values for the Video surface capabilities + * @see evas_object_image_video_surface_caps_get() + * @see evas_object_image_video_surface_caps_set() + */ + typedef enum _Evas_Video_Surface_Caps { - EVAS_VIDEO_SURFACE_MOVE = 1, - EVAS_VIDEO_SURFACE_RESIZE = 2, - EVAS_VIDEO_SURFACE_CLIP = 4, - EVAS_VIDEO_SURFACE_BELOW = 8, - EVAS_VIDEO_SURFACE_STACKING_CHECK = 16, - EVAS_VIDEO_SURFACE_IGNORE_WINDOW = 32, + EVAS_VIDEO_SURFACE_MOVE = 1, /**< Move capability */ + EVAS_VIDEO_SURFACE_RESIZE = 2, /**< Resize capability */ + EVAS_VIDEO_SURFACE_CLIP = 4, /**< Clip capability */ + EVAS_VIDEO_SURFACE_BELOW = 8, /**< Below capability */ + EVAS_VIDEO_SURFACE_STACKING_CHECK = 16, /**< Stacking capability */ + EVAS_VIDEO_SURFACE_IGNORE_WINDOW = 32, /**< Ignore window capability */ } Evas_Video_Surface_Caps; #define EVAS_LAYER_MIN -32768 /**< bottom-most layer number */ @@ -549,9 +596,9 @@ typedef enum _Evas_Border_Fill_Mode typedef enum _Evas_Engine_Render_Mode { - EVAS_RENDER_MODE_BLOCKING = 0, - EVAS_RENDER_MODE_NONBLOCKING = 1, -} Evas_Engine_Render_Mode; + EVAS_RENDER_MODE_BLOCKING = 0, /**< The rendering is blocking mode*/ + EVAS_RENDER_MODE_NONBLOCKING = 1, /**< The rendering is non blocking mode*/ +} Evas_Engine_Render_Mode; /**< behaviour of the renderer*/ typedef enum _Evas_Image_Content_Hint { @@ -819,9 +866,9 @@ typedef enum _Evas_Object_Pointer_Mode typedef void (*Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */ typedef void (*Evas_Event_Cb)(void *data, Evas *e, void *event_info); /**< Evas event callback function signature */ -typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e); +typedef Eina_Bool (*Evas_Object_Event_Post_Cb)(void *data, Evas *e); /**< Evas object event (post) callback function signature */ typedef void (*Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */ -typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info); +typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info); /**< Evas async callback function signature */ /** * @defgroup Evas_Main_Group Top Level Functions @@ -1011,6 +1058,8 @@ EAPI int evas_async_events_process(void); * @param event_info Information about the event. * @param func The callback function pointer. * + * @return EINA_FALSE if an error occured, EINA_TRUE otherwise. + * * This is the way, for a routine running outside evas' main thread, * to report an asynchronous event. A callback function is informed, * whose call is to happen after evas_async_events_process() is @@ -1301,10 +1350,12 @@ EAPI void evas_render_updates_free(Eina_List *updates); * * @param e The canvas to create the device node for. * - * Adds a new device nod to the given canvas @p e. All devices created as + * Adds a new device node to the given canvas @p e. All devices created as * part of the canvas @p e will automatically be deleted when the canvas * is freed. * + * @return the device node created or NULL if an error occured. + * * @see evas_device_del * @since 1.8 */ @@ -1313,6 +1364,8 @@ EAPI Evas_Device *evas_device_add(Evas *e); /** * Delete a new device type * + * @param dev The device node you want to delete. + * * @see evas_device_add * @see evas_device_push * @see evas_device_pop @@ -2303,6 +2356,7 @@ EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled); * This gets the alpha flag for map rendering. * * @param m map to get the alpha from. Must not be NULL. + * @return EINA_FALSE if map is NULL EINA_TRUE otherwise. */ EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m); @@ -2514,18 +2568,173 @@ EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r * @{ */ +/** + * Function signature for the resize event of an evas object + * + * @param data is the pointer passed through the callback. + * @param obj the object being shown. + * + * @see evas_object_intercept_show_callback_add() + * @see evas_object_intercept_show_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the hide event of an evas object + * + * @param data is the pointer passed through the callback. + * @param obj the object being hidden. + * + * @see evas_object_intercept_hide_callback_add() + * @see evas_object_intercept_hide_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the move event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being moved. + * @param x move x position + * @param y move y position + * + * @see evas_object_intercept_move_callback_add() + * @see evas_object_intercept_move_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y); + +/** + * Function signature for the resize event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being resized. + * @param width of the object + * @param height of the object + * + * @see evas_object_intercept_resize_callback_add() + * @see evas_object_intercept_resize_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h); + +/** + * Function signature for the raise event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being raised. + * + * @see evas_object_intercept_raise_callback_add() + * @see evas_object_intercept_raise_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the lower event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being lowered. + * + * @see evas_object_intercept_lower_callback_add() + * @see evas_object_intercept_lower_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the stack above event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being stacked above. + * @param above the object above which the object is stacked + * + * @see evas_object_intercept_stack_above_callback_add() + * @see evas_object_intercept_stack_above_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above); + +/** + * Function signature for the stack below event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being stacked below. + * @param above the object below which the object is stacked + * + * @see evas_object_intercept_stack_below_callback_add() + * @see evas_object_intercept_stack_below_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above); + +/** + * Function signature for the layer event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being layered + * @param l the layer value + * + * @see evas_object_intercept_layer_callback_add() + * @see evas_object_intercept_layer_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l); + +/** + * Function signature for the focus set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being focused + * @param focus the focus value, EINA_TRUE if the object is focused, EINA_FALSE otherwise + * + * @see evas_object_intercept_focus_set_callback_add() + * @see evas_object_intercept_focus_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Focus_Set_Cb)(void *data, Evas_Object *obj, Eina_Bool focus); + +/** + * Function signature for the color set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object changing color + * @param r the red component of the color + * @param g the green component of the color + * @param b the blue component of the color + * @param a the alpha component of the color + * + * @see evas_object_intercept_color_set_callback_add() + * @see evas_object_intercept_color_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a); + +/** + * Function signature for the clip set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being clipped + * @param clip the evas object on which the object is clipped + * + * @see evas_object_intercept_clip_set_callback_add() + * @see evas_object_intercept_clip_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip); + +/** + * Function signature for the clip unset event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being unclipped + * + * @see evas_object_intercept_clip_unset_callback_add() + * @see evas_object_intercept_clip_unset_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj); /** @@ -2885,7 +3094,14 @@ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj * @{ */ - +/** + * Function signature for the evas object pixels get callback function + * @see evas_object_image_pixels_get() + * + * By @a data it will be passed the private data. By @a o it will be passed the + * Evas_Object image on which the pixels are requested. + * + */ typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o); /** @@ -2953,6 +3169,13 @@ EAPI Eina_Bool evas_object_image_extension_can_load_fast_get #define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \ do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0) +/** + * @typedef Evas_Text_Style_Type + * + * Types of styles to be applied on text objects. The @c + * EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others + * imposing shadow, to change shadow's direction + */ typedef enum _Evas_Text_Style_Type { EVAS_TEXT_STYLE_PLAIN, /**< plain, standard text */ @@ -2975,8 +3198,7 @@ typedef enum _Evas_Text_Style_Type EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< shadow growing to the top */ EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< shadow growing to top right */ EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< shadow growing to the right */ -} Evas_Text_Style_Type; /**< Types of styles to be applied on text objects. The @c EVAS_TEXT_STYLE_SHADOW_DIRECTION_* ones are to be ORed together with others imposing shadow, to change shadow's direction */ - +} Evas_Text_Style_Type; /** * @} */ @@ -3111,31 +3333,55 @@ typedef enum _Evas_Text_Style_Type * @{ */ +/** + * @typedef Evas_Textblock_Style + * + * A textblock style object. + * @see evas_textblock_style_new() + * @see evas_textblock_style_get() + * @see evas_textblock_style_set() + */ + typedef struct _Evas_Textblock_Style Evas_Textblock_Style; + +/** + * @typedef Evas_Textblock_Cursor + * + * A textblock cursor object, used to maipulate the cursor of an evas textblock + * @see evas_object_textblock_cursor_new + * + */ typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor; + /** * @typedef Evas_Object_Textblock_Node_Format * A format node. */ typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format; -typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle; +typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle; struct _Evas_Textblock_Rectangle { Evas_Coord x, y, w, h; }; +/** + * Text type for evas textblock. + */ typedef enum _Evas_Textblock_Text_Type { - EVAS_TEXTBLOCK_TEXT_RAW, - EVAS_TEXTBLOCK_TEXT_PLAIN, - EVAS_TEXTBLOCK_TEXT_MARKUP + EVAS_TEXTBLOCK_TEXT_RAW, /**< textblock text of type raw */ + EVAS_TEXTBLOCK_TEXT_PLAIN, /**< textblock text of type plain */ + EVAS_TEXTBLOCK_TEXT_MARKUP /**< textblock text of type markup */ } Evas_Textblock_Text_Type; +/** + * Cursor type for evas textblock. + */ typedef enum _Evas_Textblock_Cursor_Type { - EVAS_TEXTBLOCK_CURSOR_UNDER, - EVAS_TEXTBLOCK_CURSOR_BEFORE + EVAS_TEXTBLOCK_CURSOR_UNDER, /**< cursor type is under */ + EVAS_TEXTBLOCK_CURSOR_BEFORE /**< cursor type is before */ } Evas_Textblock_Cursor_Type; /** @@ -3694,6 +3940,13 @@ EAPI int evas_textblock_cursor_line_coord_s * @return a list of Rectangles representing the geometry of the range. */ EAPI Eina_List *evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2); + +/** + * Get the geometry of ? + * + * @param cur one side of the range. + * @param cur2 other side of the range. + */ EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1); /** diff --git a/src/lib/evas/Evas_GL.h b/src/lib/evas/Evas_GL.h index 5f2a8d1f71..99d9dd075a 100644 --- a/src/lib/evas/Evas_GL.h +++ b/src/lib/evas/Evas_GL.h @@ -402,10 +402,10 @@ typedef enum _Evas_GL_Color_Format typedef enum _Evas_GL_Depth_Bits { EVAS_GL_DEPTH_NONE = 0, - EVAS_GL_DEPTH_BIT_8 = 1, - EVAS_GL_DEPTH_BIT_16 = 2, - EVAS_GL_DEPTH_BIT_24 = 3, - EVAS_GL_DEPTH_BIT_32 = 4 + EVAS_GL_DEPTH_BIT_8 = 1, /**< 8 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_16 = 2, /**< 16 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_24 = 3, /**< 24 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_32 = 4 /**< 32 bits precision surface depth */ } Evas_GL_Depth_Bits; /** @@ -414,11 +414,11 @@ typedef enum _Evas_GL_Depth_Bits typedef enum _Evas_GL_Stencil_Bits { EVAS_GL_STENCIL_NONE = 0, - EVAS_GL_STENCIL_BIT_1 = 1, - EVAS_GL_STENCIL_BIT_2 = 2, - EVAS_GL_STENCIL_BIT_4 = 3, - EVAS_GL_STENCIL_BIT_8 = 4, - EVAS_GL_STENCIL_BIT_16 = 5 + EVAS_GL_STENCIL_BIT_1 = 1, /**< 1 bit precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_2 = 2, /**< 2 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_4 = 3, /**< 4 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_8 = 4, /**< 8 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_16 = 5 /**< 16 bits precision for stencil buffer */ } Evas_GL_Stencil_Bits; /** diff --git a/src/lib/evas/Evas_Legacy.h b/src/lib/evas/Evas_Legacy.h index 6c270f1aa8..b33b858f96 100644 --- a/src/lib/evas/Evas_Legacy.h +++ b/src/lib/evas/Evas_Legacy.h @@ -986,7 +986,7 @@ EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED */ /** - * Set the callback function that intercepts a show event of a object. + * Set the callback function that intercepts a show event of an object. * * @param obj The given canvas object pointer. * @param func The given function to be the callback function. @@ -1001,8 +1001,7 @@ EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED EAPI void evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a show event of a - * object. + * Unset the callback function that intercepts a show event of a object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1031,8 +1030,7 @@ EAPI void *evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a hide event of a - * object. + * Unset the callback function that intercepts a hide event of a object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1046,7 +1044,7 @@ EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2); /** - * Set the callback function that intercepts a move event of a object. + * Set the callback function that intercepts a move event of an object. * * @param obj The given canvas object pointer. * @param func The given function to be the callback function. @@ -1061,8 +1059,7 @@ EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a move event of a - * object. + * Unset the callback function that intercepts a move event of an object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1075,25 +1072,294 @@ EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object */ EAPI void *evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2); +/** + * Set the callback function that intercepts a resize event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a resize event + * of a canvas object. + * + * @see evas_object_intercept_resize_callback_del(). + * + */ EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a resize event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a resize event + * of a canvas object. + * + * @see evas_object_intercept_resize_callback_add(). + * + */ EAPI void *evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a raise event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a raise event + * of a canvas object. + * + * @see evas_object_intercept_raise_callback_del(). + * + */ EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a raise event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a raise event + * of a canvas object. + * + * @see evas_object_intercept_raise_callback_add(). + * + */ EAPI void *evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a lower event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a lower event + * of a canvas object. + * + * @see evas_object_intercept_lower_callback_del(). + * + */ EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a lower event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a lower event + * of a canvas object. + * + * @see evas_object_intercept_lower_callback_add(). + * + */ EAPI void *evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a stack above event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a stack above event + * of a canvas object. + * + * @see evas_object_intercept_stack_above_callback_del(). + * + */ EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a stack above event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a stack above event + * of a canvas object. + * + * @see evas_object_intercept_stack_above_callback_add(). + * + */ EAPI void *evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a stack below event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a stack below event + * of a canvas object. + * + * @see evas_object_intercept_stack_below_callback_del(). + * + */ EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a stack below event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a stack below event + * of a canvas object. + * + * @see evas_object_intercept_stack_below_callback_add(). + * + */ EAPI void *evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a layer set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a layer set event + * of a canvas object. + * + * @see evas_object_intercept_layer_set_callback_del(). + * + */ EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a layer set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a layer set event + * of a canvas object. + * + * @see evas_object_intercept_layer_set_callback_add(). + * + */ EAPI void *evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a color set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a color set event + * of a canvas object. + * + * @see evas_object_intercept_color_set_callback_del(). + * + */ EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a color set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a color set event + * of a canvas object. + * + * @see evas_object_intercept_color_set_callback_add(). + * + */ EAPI void *evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a clip set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a clip set event + * of a canvas object. + * + * @see evas_object_intercept_clip_set_callback_del(). + * + */ EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a clip set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a clip set event + * of a canvas object. + * + * @see evas_object_intercept_clip_set_callback_add(). + * + */ EAPI void *evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a clip unset event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a clip unset event + * of a canvas object. + * + * @see evas_object_intercept_clip_unset_callback_del(). + * + */ EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a clip unset event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a clip unset event + * of a canvas object. + * + * @see evas_object_intercept_clip_unset_callback_add(). + * + */ EAPI void *evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a focus set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a focus set event + * of a canvas object. + * + * @see evas_object_intercept_focus_set_callback_del(). + * + */ EAPI void evas_object_intercept_focus_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Focus_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a focus set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a focus set event + * of a canvas object. + * + * @see evas_object_intercept_focus_set_callback_add(). + * + */ EAPI void *evas_object_intercept_focus_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Focus_Set_Cb func) EINA_ARG_NONNULL(1, 2); /** @@ -2218,27 +2484,30 @@ EAPI Evas_Object *evas_object_grid_add(Evas *evas) EINA_WARN_UNUSED_RESULT EIN */ /** - * @since 1.8 * * Adds an output to the canvas - * + * * @parem e The canvas to add the output to * @return The output * * @see evas_out_engine_info_set * @see evas_output_viewport_set * @see evas_output_size_set + * + * @since 1.8 */ EAPI Evas_Out *evas_out_add(Evas *e); /** - * @since 1.8 * * Deletes an output - * + * * @parem evo The output object * * @see evas_out_add + * + * @since 1.8 + * */ EAPI void evas_output_del(Evas_Out *evo); |