aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib/ecore/Ecore.h3391
-rw-r--r--src/lib/ecore/Ecore_Getopt.h1004
-rw-r--r--src/lib/ecore_con/Ecore_Con.h1586
-rw-r--r--src/lib/ecore_con/Ecore_Con_Eet.h211
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_evas/Ecore_Evas.h2689
-rw-r--r--src/lib/ecore_fb/Ecore_Fb.h18
-rw-r--r--src/lib/ecore_file/Ecore_File.h39
-rw-r--r--src/lib/ecore_imf/Ecore_IMF.h1359
-rw-r--r--src/lib/ecore_imf_evas/Ecore_IMF_Evas.h75
-rw-r--r--src/lib/ecore_input/Ecore_Input.h433
-rw-r--r--src/lib/ecore_ipc/Ecore_Ipc.h125
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_x/Ecore_X.h828
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_x/Ecore_X_Atoms.h76
-rw-r--r--src/lib/ecore_x/Ecore_X_Cursor.h3
-rw-r--r--src/lib/edje/Edje.h5345
-rw-r--r--src/lib/edje/Edje_Edit.h5141
-rw-r--r--src/lib/eet/Eet.h4600
-rw-r--r--src/lib/efreet/Efreet.h95
-rw-r--r--src/lib/efreet/Efreet_Mime.h83
-rw-r--r--src/lib/efreet/Efreet_Trash.h67
-rw-r--r--src/lib/efreet/efreet_base.h202
-rw-r--r--src/lib/efreet/efreet_desktop.h189
-rw-r--r--src/lib/efreet/efreet_icon.h69
-rw-r--r--src/lib/efreet/efreet_ini.h125
-rw-r--r--src/lib/efreet/efreet_menu.h109
-rw-r--r--src/lib/efreet/efreet_uri.h20
-rw-r--r--src/lib/efreet/efreet_utils.h43
-rw-r--r--src/lib/eina/eina_array.h491
-rw-r--r--src/lib/eina/eina_benchmark.h436
-rw-r--r--src/lib/eina/eina_binbuf.h276
-rw-r--r--src/lib/eina/eina_convert.h253
-rw-r--r--src/lib/eina/eina_cpu.h100
-rw-r--r--src/lib/eina/eina_fp.h451
-rw-r--r--src/lib/eina/eina_hamster.h32
-rw-r--r--src/lib/eina/eina_hash.h1390
-rw-r--r--src/lib/eina/eina_inarray.h626
-rw-r--r--src/lib/eina/eina_inlist.h897
-rw-r--r--src/lib/eina/eina_iterator.h282
-rw-r--r--src/lib/eina/eina_lalloc.h67
-rw-r--r--src/lib/eina/eina_list.h1655
-rw-r--r--src/lib/eina/eina_log.h869
-rw-r--r--src/lib/eina/eina_main.h144
-rw-r--r--src/lib/eina/eina_matrixsparse.h406
-rw-r--r--src/lib/eina/eina_mmap.h69
-rw-r--r--src/lib/eina/eina_model.h281
-rw-r--r--src/lib/eina/eina_module.h412
-rw-r--r--src/lib/eina/eina_quadtree.h4
-rw-r--r--src/lib/eina/eina_rbtree.h203
-rw-r--r--src/lib/eina/eina_rectangle.h535
-rw-r--r--src/lib/eina/eina_refcount.h44
-rw-r--r--src/lib/eina/eina_safety_checks.h35
-rw-r--r--src/lib/eina/eina_sched.h10
-rw-r--r--src/lib/eina/eina_simple_xml_parser.h472
-rw-r--r--src/lib/eina/eina_str.h467
-rw-r--r--src/lib/eina/eina_strbuf.h746
-rw-r--r--src/lib/eina/eina_stringshare.h356
-rw-r--r--src/lib/eina/eina_tiler.h349
-rw-r--r--src/lib/eina/eina_tmpstr.h197
-rw-r--r--src/lib/eina/eina_types.h155
-rw-r--r--src/lib/eina/eina_unicode.h214
-rw-r--r--src/lib/eina/eina_ustrbuf.h504
-rw-r--r--src/lib/eina/eina_ustringshare.h201
-rw-r--r--src/lib/eina/eina_value.h2454
-rw-r--r--src/lib/eina/eina_xattr.h281
-rw-r--r--src/lib/eio/Eio.h678
-rw-r--r--src/lib/embryo/Embryo.h460
-rw-r--r--src/lib/ethumb/Ethumb.h453
-rw-r--r--src/lib/ethumb/Ethumb_Plugin.h6
-rw-r--r--src/lib/ethumb_client/Ethumb_Client.h65
-rwxr-xr-x[-rw-r--r--]src/lib/evas/Evas.h14734
-rwxr-xr-x[-rw-r--r--]src/lib/evas/Evas_GL.h130
-rw-r--r--src/modules/evas/engines/buffer/Evas_Engine_Buffer.h2
-rwxr-xr-x[-rw-r--r--]src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h33
-rw-r--r--src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h7
74 files changed, 38398 insertions, 22459 deletions
diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h
index a6ac338cab..efd2bf95f6 100644
--- a/src/lib/ecore/Ecore.h
+++ b/src/lib/ecore/Ecore.h
@@ -1,103 +1,60 @@
/**
- @brief Ecore Library Public API Calls
-
- These routines are used for Ecore Library interaction
- */
-
-/**
-
- @page ecore_main Ecore
-
- @date 2000 (created)
-
- @section toc Table of Contents
-
- @li @ref ecore_main_intro
- @li @ref ecore_main_compiling
- @li @ref ecore_main_next_steps
- @li @ref ecore_main_intro_example
-
- @section ecore_main_intro Introduction
-
- Ecore is a library of convenience functions. A brief explanation of how to use
- 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_IPC_Group
- @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
- @li @ref Ecore_Win32_Group
- @li @ref Ecore_Audio_Group
- @li @ref Ecore_Avahi_Group
- @li @ref Ecore_Drm_Group
- @li @ref Ecore_Wl_Group
-
-
-
- For more info on Ecore usage, there are these @ref ecore_examples.
-
- @section ecore_main_compiling How to compile
-
- Ecore is a library your application links to. The procedure for
- this is very simple. You simply have to compile your application
- with the appropriate compiler flags that the @p pkg-config script
- outputs. Note that each module is separate in pkg-config. For
- example using @ref Ecore_Evas_Group:
-
- Compiling C or C++ files into object files:
-
- @verbatim
- gcc -c -o main.o main.c `pkg-config --cflags ecore ecore-evas`
- @endverbatim
-
- Linking object files into a binary executable:
-
- @verbatim
- gcc -o my_application main.o `pkg-config --libs ecore ecore-evas`
- @endverbatim
-
- See @ref pkgconfig
-
- @section ecore_main_next_steps Next Steps
-
- After you understood what Ecore is and installed it in your system
- you should proceed understanding the programming interface. We'd
- recommend you to take a while to learn @ref Eina as it is very
- convenient and optimized, and Ecore uses it extensively.
-
- Recommended reading:
-
- @li @ref Ecore_Timer_Group
- @li @ref Ecore_Idle_Group
- @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
-
- @include ecore_timer_example.c
-
- More examples can be found at @ref ecore_examples.
-
-
+ * @defgroup Ecore_Group Ecore
+ * @ingroup EFL_Group
+ *
+ * @brief Ecore Library Public API Calls
+ *
+ * @remarks These routines are used for Ecore Library interaction.
+ *
+ * See @ref ecore_main for more details
+ *
+ * @page ecore_main Ecore
+ *
+ * @date 2000 (created)
+ *
+ * @section toc Table of Contents
+ *
+ * @li @ref ecore_main_intro
+ * @li @ref ecore_main_next_steps
+ *
+ * @section ecore_main_intro Introduction
+ *
+ * Ecore is a library of convenience functions. A brief explanation of how to use
+ * it can be found in @ref Ecore_Main_Loop_Page.
+ *
+ * The Ecore library provides the following modules:
+ * @li @ref Ecore_Main_Loop_Group
+ * @internal
+ * @li @ref Ecore_File_Group
+ * @li @ref Ecore_Con_Group
+ * @li @ref Ecore_Evas_Group
+ * @li @ref Ecore_FB_Group
+ * @li @ref Ecore_IMF_Group
+ * @li @ref Ecore_IMF_Context_Group
+ * @li @ref Ecore_IMF_Evas_Group
+ * @endinternal
+ * @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink
+ * @internal
+ * @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
+ * @endinternal
+ *
+ * @section ecore_main_next_steps Next Steps
+ *
+ * After you understood what Ecore is and installed it in your system
+ * you should proceed understanding the programming interface. We'd
+ * recommend you to take a while to learn @ref Eina_Group as it is very
+ * convenient and optimized, and Ecore uses it extensively.
+ *
+ * Recommended reading:
+ *
+ * @li @ref Ecore_Timer_Group
+ * @li @ref Ecore_Idle_Group
+ * @li @ref Ecore_FD_Handler_Group
+ * @li @ref Ecore_Event_Group
+ * @internal
+ * @li @ref Ecore_Exe_Group
+ * @endinternal
+ *
*/
/**
@@ -106,7 +63,7 @@
* @section Ecore_Main_Loop_Page_intro What is Ecore?
*
* Ecore is a clean and tiny event loop library with many modules to do lots of
- * convenient things for a programmer, to save time and effort. It's small and
+ * convenient things for a programmer as well as to save time and effort. It's small and
* lean, designed to work from embedded systems all the way up to large and
* powerful multi-cpu workstations. The main loop has a number of primitives to
* be used with its main loop. It serializes all the primitives and allows for
@@ -120,7 +77,7 @@
*
* @subsection pollers Pollers
*
- * Pollers allow for polling to be centralized into a single place therefore
+ * Pollers allow for polling to be centralized into a single place. Therefore,
* alleviating the need for different parts of the program to wake up at
* different times to do polling, thereby making the code simpler and more
* efficient.
@@ -128,30 +85,30 @@
*
* @subsection idler Idlers
*
- * There are three types of idlers, enterers, idlers(proper) and exiters, they
- * are called, respectively, when the program is about to enter an idle state,
- * when the program is idle and when the program is leaving an idle state. Idler
+ * There are three types of idlers: enterers, idlers(proper), and exiters, they
+ * are called respectively when the program is about to enter an idle state,
+ * when the program is idle, and when the program is leaving an idle state. Idler
* enterers are usually a good place to update the program state. Proper idlers
* are the appropriate place to do heavy computational tasks thereby using what
* would otherwise be wasted CPU cycles. Exiters are the perfect place to do
- * anything your program should do just before processing events (also timers,
- * pollers, file descriptor handlers and animators)
+ * anything that your program should do just before processing events(also timers,
+ * poolers, file descriptor handlers, and animators)
* @see Ecore_Idle_Group
*
* @subsection fd_handler File descriptor handlers
*
* File descriptor handlers allow you to monitor when there is data available to
- * read on file descriptors, when writing will not block or if there was an
- * error. Any valid file descriptor can be used with this API, regardless of if
- * was gotten with an OS specific API or from ecore.
+ * read on file descriptors, when writing is not blocked or when there is an
+ * error. Any valid file descriptor can be used with this API, regardless of whether
+ * it is obtained with an OS specific API or from ecore.
* @see Ecore_FD_Handler_Group
*
* @subsection animators Animators
*
* Ecore provides a facility called animators, so named since the intended use
- * was in animations, that facilitates knowing what percentage of a given
+ * is in animations, that facilitates knowing what percentage of a given
* interval has elapsed. This is perfect for performing animations, but is not
- * limited to that use, it can, for example, also be used to create a progress
+ * limited to that use. It can, for example, also be used to create a progress
* bar.
* @see Ecore_Animator_Group
*
@@ -159,25 +116,23 @@
*
* Event handlers are, arguably, the most important feature of the ecore main
* loop, they are what allows the programmer to easily handle user interaction.
- * Events however are not only things the user does, events can represent
+ * Events, however, are not the only things that the user does. Events can represent
* anything for which a type is created.
* @see Ecore_Event_Group
*
* All of these primitives are discussed in more detail in their respective
- * pages linked above.
+ * pages that are linked above.
*
* Here is a diagram of the main loop flow of a simple program:
*
* @image html prog_flow.png
- * @image latex prog_flow.eps width=\textwidth
- *
- *
+ * @image latex prog_flow.eps "prog flow" width=\textwidth
*
* @section Ecore_Main_Loop_Page_work How does Ecore work?
*
* Ecore is very easy to learn and use. All the function calls are designed to
* be easy to remember, explicit in describing what they do, and heavily
- * name-spaced. Ecore programs can start and be very simple.
+ * name-spaced. Ecore programs can start easily and are very simple.
*
* For example:
*
@@ -196,7 +151,7 @@
* @endcode
*
* This program is very simple and doesn't check for errors, but it does start up
- * and begin a main loop waiting for events or timers to tick off. This program
+ * and begin a main loop that is waiting for events or timers to tick off. This program
* doesn't set up any, but now we can expand on this simple program a little
* more by adding some event handlers and timers.
*
@@ -242,14 +197,14 @@
* @endcode
*
* In the previous example, we initialize our application and get the time at
- * which our program has started so we can calculate an offset. We set
- * up a timer to tick off in 0.5 seconds, and since it returns 1, will
- * keep ticking off every 0.5 seconds until it returns 0, or is deleted
+ * which our program has started so that we can calculate an offset. We set
+ * up a timer to tick off in @c 0.5 seconds, and since it returns @c 1, it
+ * keeps ticking off every @c 0.5 seconds until it returns @c 0, or is deleted
* by hand. An event handler is set up to call a function -
* exit_func(),
* whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
- * on the command line will cause such an event to happen). If this event
- * occurs it tells you what kind of exit signal was received, and asks
+ * on the command line causes such an event to happen). If this event
+ * occurs it tells you what kind of exit signal is received, and asks
* the main loop to quit when it is finished by calling
* ecore_main_loop_quit().
*
@@ -257,11 +212,11 @@
* ecore_event_handler_add() are
* only stored here as an example. If you don't need to address the timer or
* event handler again you don't need to store the result, so just call the
- * function, and don't assign the result to any variable.
+ * function and don't assign the result to any variable.
*
* This program looks slightly more complex than needed to do these simple
* things, but in principle, programs don't get any more complex. You add more
- * event handlers, for more events, will have more timers and such, BUT it all
+ * event handlers for more events, you have more timers, BUT it all
* follows the same principles as shown in this example.
*
*/
@@ -275,34 +230,19 @@
To use the library, you:
@li Set the default values of your properties.
- @li Load the configuration from a file. You must set the default values
+ @li Load the configuration from a file. You must set the default values
first, so that the library knows the correct type of each argument.
- The following examples show how to use the Enlightened Property Library:
- @li @link config_basic_example.c config_basic_example.c @endlink
- @li @link config_listener_example.c config_listener_example.c @endlink
-
- */
-
-/**
- @page X_Window_System_Page X Window System
-
- The Ecore library includes a wrapper for handling the X window system.
- This page briefly explains what the X window system is and various terms
- that are used.
*/
#ifndef _ECORE_H
#define _ECORE_H
-#include <Efl_Config.h>
-
#ifdef _MSC_VER
# include <Evil.h>
#endif
#include <Eina.h>
-#include <Eo.h>
#ifdef EAPI
# undef EAPI
@@ -350,13 +290,3172 @@
extern "C" {
#endif
-#include "Ecore_Common.h"
-#ifndef EFL_NOLEGACY_API_SUPPORT
-#include "Ecore_Legacy.h"
+/**
+ * @internal
+ * @defgroup Ecore_Init_Group Ecore initialization, shutdown functions and reset on fork.
+ * @ingroup Ecore_Group
+ *
+ * @{
+ */
+
+/**
+ * @brief Initialize the Ecore library.
+ *
+ * @details This function sets up connections, sockets, all singal handlers and
+ * the basic event loop, etc. If it succeeds, 1 or greater will be
+ * returned, otherwise 0 will be returned.
+ *
+ * @remarks This function initializes the Ecore library, making the proper calls
+ * to internal initialization functions. It will also initialize its
+ * @b dependencies, making calls to @c eina_init().
+ * So, there is no need to call those functions again, in your code.
+ * To shutdown Ecore, there is the function ecore_shutdown().
+ *
+ * @code
+ * #include <Ecore.h>
+ *
+ * int main(int argc, char **argv)
+ * {
+ * if (!ecore_init())
+ * {
+ * printf("ERROR: Cannot init Ecore!\n");
+ * return -1;
+ * }
+ * ecore_main_loop_begin();
+ * ecore_shutdown();
+ * }
+ * @endcode
+ *
+ * @return 1 or greater on success, 0 otherwise
+ *
+ * @see ecore_shutdown()
+ * @see eina_init()
+ */
+EAPI int ecore_init(void);
+
+/**
+ * @brief Shutdown the Ecore library.
+ *
+ * @details Shut down connections, signal handlers sockets etc.
+ *
+ * @remarks This function shuts down all things set up in ecore_init() and
+ * cleans up all event queues, handlers, filters, timers, idlers,
+ * idle enterers/exiters etc. set up after ecore_init() was called.
+ *
+ * @remarks Do not call this function from any callback that may be called
+ * from the main loop, as the main loop will then fall over and not
+ * function properly.
+ *
+ * @details This function shuts down the Edje library. It will also call the
+ * shutdown functions of its @b dependencies, which is @c
+ * eina_shutdown().
+ * so there is no need to call these functions again in your code.
+ * This returns The number of times the library has been initialised
+ * without being shutdown.
+ *
+ * @return 0 if ecore shuts down, greater than 0 otherwise.
+ *
+ * @see ecore_init()
+ * @see eina_shutdown()
+ */
+EAPI int ecore_shutdown(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Ecore_Application_Group Ecore Application
+ * @ingroup Ecore_Group
+ *
+ * @{
+ */
+
+EAPI void ecore_app_args_set(int argc, const char **argv);
+EAPI void ecore_app_args_get(int *argc, char ***argv);
+EAPI void ecore_app_restart(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Main_Loop_Group Ecore Main Loop
+ * @ingroup Ecore_Group
+ *
+ * @brief This group discusses functions that are acting on Ecore's main loop itself or
+ * on events and infrastructure directly linked to it. Most programs only need
+ * to start and end the main loop, the rest of the function discussed here is
+ * meant to be used in special situations, and with great care.
+ *
+ * For details on the usage of ecore's main loop and how it interacts with other
+ * ecore facilities see: @ref Ecore_Main_Loop_Page.
+ *
+ * @{
+ */
+
+#define ECORE_VERSION_MAJOR 1
+#define ECORE_VERSION_MINOR 8
+
+typedef struct _Ecore_Version
+{
+ int major;
+ int minor;
+ int micro;
+ int revision;
+} Ecore_Version;
+
+EAPI extern Ecore_Version *ecore_version;
+
+#define ECORE_CALLBACK_CANCEL EINA_FALSE /**< Return value to remove a callback */
+#define ECORE_CALLBACK_RENEW EINA_TRUE /**< Return value to keep a callback */
+
+#define ECORE_CALLBACK_PASS_ON EINA_TRUE /**< Return value to pass an event to the next handler */
+#define ECORE_CALLBACK_DONE EINA_FALSE /**< Return value to stop event handling */
+
+/**
+ * @typedef Ecore_Task_Cb Ecore_Task_Cb
+ * @brief The boolean type for a callback that is run for a task (timer, idler, poller, animator, and so on).
+ */
+typedef Eina_Bool (*Ecore_Task_Cb)(void *data);
+
+/**
+ * @typedef Ecore_Cb Ecore_Cb
+ * @brief Called as a hook when a certain point in the execution is reached.
+ */
+typedef void (*Ecore_Cb)(void *data);
+
+/**
+ * @typedef Ecore_Data_Cb Ecore_Data_Cb
+ * @brief Called to return data to the main function.
+ */
+typedef void *(*Ecore_Data_Cb)(void *data);
+
+/**
+ * @typedef Ecore_Select_Function
+ * @brief The integer type for a function that can be used to replace select() in the main loop.
+ */
+typedef int (*Ecore_Select_Function)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);
+
+/**
+ * @brief Adds a function to be called by ecore_fork_reset().
+ *
+ * @details This queues @a func to be called (and passes @a 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.
+ *
+ * @param[in] func The function to be called
+ * @param[in] data A data pointer to pass to the called function @a func
+ * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE.
+ *
+ * @since 1.7
+ * @since_tizen 2.3
+ */
+EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data);
+
+/**
+ * @brief Removes the specified callback.
+ *
+ * @details This deletes the callback added by ecore_fork_reset_callback_add() using
+ * the function and data pointer to specify which callback to remove.
+ *
+ * @param[in] func The function to be called
+ * @param[in] data A data pointer to pass to the called function @a func
+ * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE.
+ *
+ * @since 1.7
+ * @since_tizen 2.3
+ */
+EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data);
+
+/**
+ * @brief Resets the ecore's internal state after a fork.
+ *
+ * @since 1.7
+ * @since_tizen 2.3
+ *
+ * @remarks Ecore maintains the internal data that can be affected by the fork() system call,
+ * which creates a duplicate of the current process. This also duplicates
+ * file descriptors, which is problematic as these file descriptors still
+ * point to their original sources. This function makes ecore's reset internal
+ * state (e.g. pipes used for signalling between threads) so they function
+ * correctly afterwards.
+ *
+ * @remarks It is highly suggested that you call this function after any fork()
+ * system call inside the child process. If you intend to use ecore features
+ * after this point and not call exec() family functions. Not doing so
+ * causes a possible misbehaviour.
+ */
+EAPI void ecore_fork_reset(void);
+
+/**
+ * @brief Runs a single iteration of the main loop to process everything on the
+ * queue.
+ *
+ * @details It does everything that is already done inside an @c Ecore main loop,
+ * like checking for expired timers, idlers, etc. But it will do it
+ * only once and return, instead of keep watching for new events.
+ *
+ * @remarks DO NOT use this function unless you are the person God comes to ask
+ * for advice when He has trouble managing the Universe.
+ *
+ * @see ecore_main_loop_iterate_may_block()
+ */
+EAPI void ecore_main_loop_iterate(void);
+
+/**
+ * @brief Sets the function to use when monitoring multiple file descriptors,
+ * and waiting until one of more of the file descriptors before ready
+ * for some class of I/O operation.
+ *
+ * @remarks This function will be used instead of the system call select and
+ * could possible be used to integrate the Ecore event loop with an
+ * external event loop.
+ *
+ * @remarks you don't know how to use, don't even try to use it.
+ *
+ * @param func The function to be used.
+ *
+ * @see ecore_main_loop_select_func_get()
+ */
+EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func);
+
+/**
+ * @brief Gets the select function set by ecore_select_func_set(),
+ * or the native select function if none was set.
+ *
+ * @return The select function
+ *
+ * @see ecore_main_loop_select_func_get()
+ */
+EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void);
+
+/**
+ * @brief Request ecore to integrate GLib's main loop.
+ *
+ * @details This will add a small overhead during every main loop interaction
+ * by checking glib's default main context (used by its main loop). If
+ * it have events to be checked (timers, file descriptors or idlers),
+ * then these will be polled alongside with Ecore's own events, then
+ * dispatched before Ecore's. This is done by calling
+ * ecore_main_loop_select_func_set().
+ *
+ * @remarks This will cooperate with previously set
+ * ecore_main_loop_select_func_set() by calling the old function.
+ * Similarly, if you want to override
+ * ecore_main_loop_select_func_set() after main loop is integrated,
+ * call the new select function set by this call (get it by calling
+ * ecore_main_loop_select_func_get() right after
+ * ecore_main_loop_glib_integrate()).
+ *
+ * @remarks This is useful to use GMainLoop libraries, like GTK, GUPnP,
+ * LibSoup, GConf and more. Adobe Flash plugin and other plugins
+ * systems depend on this as well.
+ *
+ * @remarks Once initialized/integrated, it will be valid until Ecore is
+ * completely shut down.
+ *
+ * Example of use:
+ * @code
+ *
+ * int main(void)
+ * {
+ * ecore_init();
+ * ecore_main_loop_glib_integrate();
+ *
+ * // some code here
+ *
+ * ecore_main_loop_begin();
+ *
+ * ecore_shutdown();
+ *
+ * return 0;
+ * }
+ *
+ * @endcode
+ *
+ * @remarks This is only available if Ecore was compiled with GLib support.
+ * @remarks You don't need to call this function if Ecore was compiled with
+ * --with-glib=always.
+ *
+ * @return #EINA_TRUE on success of @c EINA_FALSE if it failed,
+ * likely no GLib support in Ecore.
+ */
+EAPI Eina_Bool ecore_main_loop_glib_integrate(void);
+
+/**
+ * @brief Disable always integrating glib
+ *
+ * @remarks If ecore is compiled with --with-glib=always (to always call
+ * ecore_main_loop_glib_integrate() when ecore_init() is called),
+ * then calling this before calling ecore_init() will disable the
+ * integration. This is for apps that explicitly do not want this
+ * to happen for whatever reasons they may have.
+ */
+EAPI void ecore_main_loop_glib_always_integrate_disable(void);
+
+/**
+ * @brief Runs the application main loop.
+ *
+ * @details This function will not return until @ref ecore_main_loop_quit is
+ * called. It will check for expired timers, idlers, file descriptors
+ * being watched by fd handlers, etc. Once everything is done, before
+ * entering again on idle state, any callback set as @c Idle_Enterer
+ * will be called.
+ *
+ * @remarks Each main loop iteration is done by calling
+ * ecore_main_loop_iterate() internally.
+ *
+ * @remarks The polling (select) function used can be changed with
+ * ecore_main_loop_select_func_set().
+ *
+ * @remarks The function used to check for file descriptors, events, and that
+ * has a timeout for the timers can be changed using
+ * ecore_main_loop_select_func_set().
+ */
+EAPI void ecore_main_loop_begin(void);
+
+/**
+ * @brief Quits the main loop once all the events currently on the queue have
+ * been processed.
+ *
+ * @details This function returns immediately, but will mark the
+ * ecore_main_loop_begin() function to return at the end of the
+ * current main loop iteration.
+ */
+EAPI void ecore_main_loop_quit(void);
+
+/**
+ * @brief Called asynchronously in the main loop.
+ *
+ * @since 1.1.0
+ *
+ * @remarks For all calls that need to happen in the main loop (most EFL functions do),
+ * this helper function provides the infrastructure needed to do it safely
+ * by avoiding a dead lock, race condition, and by properly waking up the main loop.
+ *
+ * @remarks Remember that after the function call, you should never touch the @a data
+ * in the thread again, it is owned by the main loop and your callback should take
+ * care of freeing it, if necessary.
+ *
+ * @param callback The callback to call in the main loop
+ * @param data The data to give to that call
+ */
+EAPI void ecore_main_loop_thread_safe_call_async(Ecore_Cb callback, void *data);
+
+/**
+ * @brief Called synchronously in the main loop.
+ *
+ * @since 1.1.0
+ *
+ * @remarks For all calls that need to happen in the main loop (most EFL functions do),
+ * this helper function provides the infrastructure needed to do it safely
+ * by avoiding a dead lock, race condition, and by properly waking up the main loop.
+ *
+ * @remarks Remember that this function blocks until the callback is executed in the
+ * main loop. It can take time and you have no guarantee about the timeline.
+ *
+ * @param callback The callback to call in the main loop
+ * @param data The data to give to that call
+ * @return The value returned by the callback in the main loop
+ */
+EAPI void *ecore_main_loop_thread_safe_call_sync(Ecore_Data_Cb callback, void *data);
+
+/**
+ * @brief Suspends the main loop in the know state.
+ *
+ * @details This function suspends the main loop in the know state. This lets you
+ * use any EFL call that you want after it returns. Be careful, the main loop
+ * is blocked until you call ecore_thread_main_loop_end(). This is
+ * the only way to achieve pseudo thread safety.
+ *
+ * @since 1.1.0
+ *
+ * @remarks Notice that till the main loop is blocked, the thread is blocked
+ * and there is no way around that.
+ *
+ * @remarks We still advise you, if possible, to use ecore_main_loop_thread_safe_call_async()
+ * as it does not block the thread or the main loop.
+ *
+ * @return The number of times ecore_thread_main_loop_begin() has been called
+ * in this thread, if the main loop is suspended correctly \n
+ * If not, it returns @c -1.
+ */
+EAPI int ecore_thread_main_loop_begin(void);
+
+/**
+ * @brief Unlocks the main loop.
+ *
+ * @since 1.1.0
+ *
+ * @remarks After a call to ecore_thread_main_loop_begin(), you need to absolutely
+ * call ecore_thread_main_loop_end(), or your application stays frozen.
+ *
+ * @return The number of times ecore_thread_main_loop_end() needs to be called before
+ * the main loop is unlocked again \n
+ * @c -1 is retured if you are trying to unlock
+ * when there aren't enough calls to ecore_thread_main_loop_begin().
+ *
+ */
+EAPI int ecore_thread_main_loop_end(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Event_Group Ecore Event
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief Ecore event are a helper to create events are being notified of events.
+ *
+ * Ecore events provide two main features that are of use to those using ecore:
+ * creating events and being notified of events. Those two are usually used
+ * in different contexts, creating events is mainly done by libraries wrapping
+ * some system functionality while being notified of events is mainly a
+ * necessity of applications.
+ *
+ * For a program to be notified of events it's interested in, it needs to have a
+ * function to process the event and to register that function as the callback
+ * to the event, that's all:
+ * @code
+ * ecore_event_handler_add(EVENT_TYPE, _my_event_handler, some_data);
+ * ...
+ * static Eina_Bool
+ * _my_event_handler(void *data, int type, void *event)
+ * {
+ * //Data is some_data
+ * //Event is provided by whoever created the event
+ * //Do really cool stuff with the event
+ * }
+ * @endcode
+ *
+ * One very important thing to note here is the @c EVENT_TYPE. To register a
+ * handler for an event, you must know its type before hand. Ecore provides
+ * the following events that are emitted in response to POSIX
+ * signals(https://en.wikipedia.org/wiki/Signal_%28computing%29):
+ * @li @b ECORE_EVENT_SIGNAL_USER
+ * @li @b ECORE_EVENT_SIGNAL_HUP
+ * @li @b ECORE_EVENT_SIGNAL_POWER
+ * @li @b ECORE_EVENT_SIGNAL_EXIT
+ *
+ * Don't override these using the @c signal or @c sigaction calls.
+ * These, however, aren't the only signals one can handle. Many
+ * libraries(including ecore modules) have their own signals that can be
+ * listened to and handled. To do that one only needs to know the type of the
+ * event. This information can be found on the documentation of the library
+ * emitting the signal.
+ * @internal
+ * So, for example, for events related to windowing one
+ * would use @ref Ecore_Evas_Group.
+ *
+ * Examples of libraries that integrate into ecore's main loop by providing
+ * events are @ref Ecore_Con_Group, @ref Ecore_Evas_Group, and @ref
+ * Ecore_Exe_Group, amongst others.
+ * @endinternal
+ *
+ * This usage can be divided into two parts,
+ * setup and adding events. The setup is very simple, all that needs to be done is
+ * getting a type ID for the event:
+ * @code
+ * int MY_EV_TYPE = ecore_event_type_new();
+ * @endcode
+ * This variable should be declared in the header since it is needed by
+ * anyone wishing to register a handler to your event.
+ *
+ * The complexity of adding an event to the queue depends on whether that
+ * event sends or uses @a event, if it doesn't it is a one-liner:
+ * @code
+ * ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL);
+ * @endcode
+ * The usage when an @c event is needed is not that complex and can be
+ * seen in @ref ecore_event_add.
+ *
+ * @{
+ */
+
+#define ECORE_EVENT_NONE 0
+#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 */
+#define ECORE_EVENT_SIGNAL_POWER 4 /**< Power signal event */
+#define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */
+#define ECORE_EVENT_COUNT 6
+
+typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< @internal @brief A handle for HANDLE handlers on Windows */
+typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< @brief A handle for an event handler */
+typedef struct _Ecore_Event_Filter Ecore_Event_Filter; /**< @brief A handle for an event filter */
+typedef struct _Ecore_Event Ecore_Event; /**< @brief A handle for an event */
+typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User; /**< @brief User signal event */
+typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup; /**< @brief Hup signal event */
+typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit; /**< @brief Exit signal event */
+typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power; /**< @brief Power signal event */
+typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime; /**< @brief Realtime signal event */
+
+/**
+ * @typedef Ecore_Filter_Cb
+ * @brief The boolean type for a callback used for filtering events from the main loop.
+ */
+typedef Eina_Bool (*Ecore_Filter_Cb)(void *data, void *loop_data, int type, void *event);
+
+/**
+ * @typedef Ecore_End_Cb Ecore_End_Cb
+ * @brief Called at the end of a function, usually for cleanup purposes.
+ */
+typedef void (*Ecore_End_Cb)(void *user_data, void *func_data);
+
+/**
+ * @typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb
+ * @brief The boolean type used by the main loop to handle events of a specified type.
+ */
+typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event);
+
+struct _Ecore_Event_Signal_User /** User signal event */
+{
+ int number; /**< The signal number. Either 1 or 2 */
+ void *ext_data; /**< Extension data - not used */
+
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
+#endif
+};
+
+struct _Ecore_Event_Signal_Hup /** Hup signal event */
+{
+ void *ext_data; /**< Extension data - not used */
+
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
+#endif
+};
+
+struct _Ecore_Event_Signal_Exit /** Exit request event */
+{
+ Eina_Bool interrupt : 1; /**< Set if the exit request is an interrupt signal*/
+ Eina_Bool quit : 1; /**< Set if the exit request is a quit signal */
+ Eina_Bool terminate : 1; /**< Set if the exit request is a terminate signal */
+ void *ext_data; /**< Extension data - not used */
+
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
#endif
-#ifdef EFL_EO_API_SUPPORT
-#include "Ecore_Eo.h"
+};
+
+struct _Ecore_Event_Signal_Power /** Power event */
+{
+ void *ext_data; /**< Extension data - not used */
+
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
+#endif
+};
+
+struct _Ecore_Event_Signal_Realtime /** Realtime event */
+{
+ int num; /**< The realtime signal's number */
+
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
+#endif
+};
+
+/**
+ * @brief Adds an event handler.
+ *
+ * @details This adds an event handler to the list of handlers. This, on success, returns
+ * a handle to the event handler object that is created, that can be used
+ * later to remove the handler using ecore_event_handler_del(). The @a type
+ * parameter is the integer of the event type that triggers this callback
+ * to be called. The callback @a func is called when this event is processed
+ * and is passed the event type, a pointer to the private event
+ * structure that is specific to that event type, and a data pointer that is
+ * provided in this call as the @a data parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When the callback @a func is called, it must return @c 1 or @c 0. If it returns
+ * @c 1 (or @c ECORE_CALLBACK_PASS_ON), it keeps being called as per normal, for
+ * each handler set up for that event type. If it returns @c 0 (or
+ * @c ECORE_CALLBACK_DONE), it ceases processing handlers for that particular
+ * event, so all handlers set to handle that event type that have not already
+ * been called, are not called.
+ *
+ * @param[in] type The type of the event that this handler gets called for
+ * @param[in] func The function to call when the event is found in the queue
+ * @param[in] data A data pointer to pass to the called function @a func
+ * @return A new Event handler,
+ * otherwise @c NULL on failure
+ */
+EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data);
+
+/**
+ * @brief Deletes an event handler.
+ *
+ * @details This deletes a specified event handler from the handler list. On success, this
+ * deletes the event handler and returns the pointer passed as @a data when the
+ * handler is added by ecore_event_handler_add(). On failure, @c NULL is
+ * returned. Once a handler is deleted it is no longer called.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] event_handler The event handler handle to delete
+ * @return The data passed to the handler
+ */
+EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler);
+
+/**
+ * @brief Adds an event to the event queue.
+ *
+ * @remarks If it succeeds, an event of type @a type is added to the queue for
+ * processing by event handlers added by ecore_event_handler_add(). The @a ev
+ * parameter is passed as the @a event parameter of the handler. When the
+ * event is no longer needed, @a func_free is called and it passes @a ev for
+ * cleaning up. If @a func_free is @c NULL, free() is called with the private
+ * structure pointer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] type The event type to add to the end of the event queue
+ * @param[in] ev The data structure passed as @a event to event handlers
+ * @param[in] func_free The function to be called to free @a ev
+ * @param[in] data The data pointer to be passed to the free function
+ * @return A Handle for that event on success,
+ * otherwise @c NULL on failure
+ */
+EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data);
+
+/**
+ * @brief Deletes an event from the queue.
+ *
+ * @details This deletes the event @a event from the event queue, and returns the
+ * @a data parameter originally set when adding it using ecore_event_add(). This
+ * does not immediately call the free function, and it may be called later for
+ * cleanup, and so if the free function depends on the data pointer to work,
+ * you should defer cleaning of this till the free function is called later.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] event The event handle to delete
+ * @return The data pointer originally set for the event free function
+ */
+EAPI void *ecore_event_del(Ecore_Event *event);
+
+/**
+ * @brief Gets the data associated with an #Ecore_Event_Handler.
+ *
+ * @details This function returns the data previously associated with @a eh by
+ * ecore_event_handler_add().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] eh The event handler
+ * @return The data
+ */
+EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh);
+
+/**
+ * @brief Sets the data associated with an #Ecore_Event_Handler.
+ *
+ * @details This function sets @a data to @a eh and returns the old data pointer
+ * that had been previously associated with @a eh by ecore_event_handler_add().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] eh The event handler
+ * @param[in] data The data to associate
+ * @return The previous data
+ */
+EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data);
+
+/**
+ * @brief Allocates a new event type ID sensibly and returns the new ID.
+ *
+ * @details This function allocates a new event type ID and returns it. Once an event
+ * type has been allocated it can never be de-allocated during the life of
+ * the program. There is no guarantee of the contents of this event ID, or how
+ * it is calculated, except that the ID is unique to the current instance
+ * of the process.
+ *
+ * @since_tizen 2.3
+ *
+ * @return A new event type ID
+ *
+ */
+EAPI int ecore_event_type_new(void);
+
+/**
+ * @brief Adds a filter to the current event queue.
+ *
+ * @details This adds a callback to filter events from the event queue. Filters are called on
+ * the queue just before Event handler processing to try and remove redundant
+ * events. Just when processing is about to start @a func_start is called and
+ * passed the @a data pointer. The return value of this function is passed to
+ * @a func_filter as loop_data. @a func_filter is also passed @a data, the
+ * event type, and the event structure. If this @a func_filter returns
+ * @c EINA_FALSE, the event is removed from the queue. If it returns
+ * #EINA_TRUE, the event is kept. When processing is finished @a func_end is
+ * called and is passed the loop_data(returned by @a func_start) and @a data
+ * pointer to clean up.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] func_start The function to call just before filtering and returning data
+ * @param[in] func_filter The function to call on each event
+ * @param[in] func_end The function to call after the queue has been filtered
+ * @param[in] data The data to pass to the filter functions
+ * @return A filter handle on success,
+ * otherwise @c NULL on failure
+ *
+ */
+EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data);
+
+/**
+ * @brief Deletes an event filter.
+ *
+ * @details This deletes a filter that has been added by its @a ef handle.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] ef The event filter handle
+ * @return The data set for the filter on success,
+ * otherwise @c NULL
+ */
+EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef);
+
+/**
+ * @brief Returns the current event type being handled.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the program is currently inside an Ecore event handler callback this
+ * returns the type of the current event being processed.
+ *
+ * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
+ * events and not all the original information is passed on. In special cases,
+ * this extra information may be useful or needed and using this call can let
+ * the program know if the event type being handled is the one about which it wants to get more
+ * information.
+ *
+ * @return The current event type being handled if inside a handler callback,
+ * otherwise @c ECORE_EVENT_NONE
+ */
+EAPI int ecore_event_current_type_get(void);
+/**
+ * @brief Returns the current event type pointer handled.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the program is currently inside an Ecore event handler callback this
+ * returns the pointer of the current event being processed.
+ *
+ * @remarks This is useful when certain Ecore modules such as Ecore_Evas "swallow"
+ * events and not all the original information is passed on. In special cases,
+ * this extra information may be useful or needed and using this call can let
+ * the program access the event data if the type of the event is handled by
+ * the program.
+ *
+ * @return The current event pointer being handled if inside a handler callback,
+ * otherwise @c NULL
+ */
+EAPI void *ecore_event_current_event_get(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Ecore_Exe_Group Process Spawning
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * This module is responsible for managing portable processes using Ecore.
+ * With this module you're able to spawn processes and you can also pause and
+ * quit your spawned processes.
+ * An interaction between your process and those spawned is possible
+ * using pipes or signals.
+ *
+ * @{
+ */
+
+/** Inherit priority from the parent process */
+#define ECORE_EXE_PRIORITY_INHERIT 9999
+
+EAPI extern int ECORE_EXE_EVENT_ADD; /**< @brief A child process has been added */
+EAPI extern int ECORE_EXE_EVENT_DEL; /**< @brief A child process has been deleted (it exited, naming is consistent with the rest of ecore) */
+EAPI extern int ECORE_EXE_EVENT_DATA; /**< @brief Data from a child process */
+EAPI extern int ECORE_EXE_EVENT_ERROR; /**< @brief Errors from a child process */
+
+/**
+ * @internal
+ * @enum _Ecore_Exe_Flags
+ * @brief Enumeration that defines the flags for executing a child with its stdin and/or stdout piped back.
+ */
+enum _Ecore_Exe_Flags /* Flags for executing a child with its stdin and/or stdout piped back */
+{
+ ECORE_EXE_NONE = 0, /**< No exe flags at all */
+ ECORE_EXE_PIPE_READ = 1, /**< Exe Pipe Read mask */
+ ECORE_EXE_PIPE_WRITE = 2, /**< Exe Pipe Write mask */
+ ECORE_EXE_PIPE_ERROR = 4, /**< Exe Pipe error mask */
+ ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8, /**< Reads are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */
+ ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, /**< Errors are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */
+ ECORE_EXE_PIPE_AUTO = 32, /**< stdout and stderr are buffered automatically */
+ ECORE_EXE_RESPAWN = 64, /**< FIXME: Exe is restarted if it dies */
+ ECORE_EXE_USE_SH = 128, /**< Use /bin/sh to run the command */
+ ECORE_EXE_NOT_LEADER = 256, /**< Do not use setsid() to make the executed process its own session leader */
+ ECORE_EXE_TERM_WITH_PARENT = 512 /**< Makes a child receive SIGTERM when the parent dies */
+};
+typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags;
+
+/**
+ * @internal
+ * @enum _Ecore_Exe_Win32_Priority
+ * @brief Enumeration that defines the priority of the proccess.
+ */
+enum _Ecore_Exe_Win32_Priority
+{
+ ECORE_EXE_WIN32_PRIORITY_IDLE, /**< Idle priority, for monitoring the system */
+ ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL, /**< Below default priority */
+ ECORE_EXE_WIN32_PRIORITY_NORMAL, /**< Default priority */
+ ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL, /**< Above default priority */
+ ECORE_EXE_WIN32_PRIORITY_HIGH, /**< High priority, use with care as other threads in the system do not get processor time */
+ ECORE_EXE_WIN32_PRIORITY_REALTIME /**< Realtime priority, should be almost never used as it can interrupt system threads that manage mouse input, keyboard input, and background disk flushing */
+};
+typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority;
+
+typedef struct _Ecore_Exe Ecore_Exe; /**< @brief A handle for spawned processes */
+
+/**
+ * @typedef Ecore_Exe_Cb Ecore_Exe_Cb
+ * @brief Called to run with the associated @ref Ecore_Exe, usually
+ * for cleanup purposes.
+ */
+typedef void (*Ecore_Exe_Cb)(void *data, const Ecore_Exe *exe);
+
+typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add; /**< @brief Spawned Exe add event */
+typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< @brief Spawned Exe exit event */
+typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< @brief Lines from a child process */
+typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< @brief Data from a child process */
+
+/**
+* @internal
+* @brief Structure of Ecore Exe Event Add
+*/
+struct _Ecore_Exe_Event_Add /** Process add event */
+{
+ Ecore_Exe *exe; /**< The handle to the added process */
+ void *ext_data; /**< Extension data - not used */
+};
+
+struct _Ecore_Exe_Event_Del /** Process exit event */
+{
+ pid_t pid; /**< The process ID of the process that exited */
+ int exit_code; /**< The exit code of the process */
+ Ecore_Exe *exe; /**< The handle to the exited process, otherwise @c NULL if not found */
+ int exit_signal; /** < The signal that caused the process to exit */
+ Eina_Bool exited : 1; /** < Set to @c 1 if the process exited on its own */
+ Eina_Bool signalled : 1; /** < Set to @c 1 if the process exited due to an uncaught signal */
+ void *ext_data; /**< Extension data - not used */
+#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
+ siginfo_t data; /**< Signal info */
+#endif
+};
+
+struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */
+{
+ 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 */
+{
+ Ecore_Exe *exe; /**< The handle to the process */
+ void *data; /**< The raw binary data from the child process that is received */
+ int size; /**< The size of this data in bytes */
+ Ecore_Exe_Event_Data_Line *lines; /**< An array of line data if line buffered, the last one has its line member set to @c NULL */
+};
+
+EAPI void ecore_exe_run_priority_set(int pri);
+EAPI int ecore_exe_run_priority_get(void);
+EAPI Ecore_Exe *ecore_exe_run(const char *exe_cmd, const void *data);
+EAPI Ecore_Exe *ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, const void *data);
+EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func);
+EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, int size);
+EAPI void ecore_exe_close_stdin(Ecore_Exe *exe);
+EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines);
+EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags);
+EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data);
+EAPI void *ecore_exe_free(Ecore_Exe *exe);
+EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe);
+EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag);
+EAPI const char *ecore_exe_tag_get(const Ecore_Exe *exe);
+EAPI const char *ecore_exe_cmd_get(const Ecore_Exe *exe);
+EAPI void *ecore_exe_data_get(const Ecore_Exe *exe);
+EAPI void *ecore_exe_data_set(Ecore_Exe *exe, void *data);
+EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe);
+EAPI void ecore_exe_pause(Ecore_Exe *exe);
+EAPI void ecore_exe_continue(Ecore_Exe *exe);
+EAPI void ecore_exe_interrupt(Ecore_Exe *exe);
+EAPI void ecore_exe_quit(Ecore_Exe *exe);
+EAPI void ecore_exe_terminate(Ecore_Exe *exe);
+EAPI void ecore_exe_kill(Ecore_Exe *exe);
+EAPI void ecore_exe_signal(Ecore_Exe *exe, int num);
+EAPI void ecore_exe_hup(Ecore_Exe *exe);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_FD_Handler_Group Ecore File Descriptor Handling
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief This group discusses functions that deal with file descriptor handlers.
+ *
+ * File descriptor handlers facilitate reading, writing, and checking for errors
+ * without blocking the program or doing expensive pooling. This can be used to
+ * monitor a socket, pipe, or some other stream for which an FD can be present.
+ *
+ * File descriptor handlers can't be used to monitor file creation,
+ * modification, or deletion,
+ * @internal
+ * see @ref Ecore_File_Group for this.
+ * @endinternal
+ *
+ * One common FD to be monitored is the standard input(stdin), monitoring it for
+ * reading requires a single call:
+ * @code
+ * static Eina_Bool
+ * _my_cb_func(void *data, Ecore_Fd_Handler *handler)
+ * {
+ * char c;
+ * scanf("%c", &c); //Guaranteed not to block
+ * ... do stuff with c ...
+ * }
+ * ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL);
+ * @endcode
+ *
+ * When using a socket, pipe, or some other stream it's important to remember that
+ * errors may occur and we must monitor not only for reading/writing, but also
+ * for errors using the @ref ECORE_FD_ERROR flag.
+ *
+ * @{
+ */
+
+/**
+ * @brief typedef to struct _Ecore_Fd_Handler
+ */
+typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for FD handlers */
+
+/**
+ * @enum _Ecore_Fd_Handler_Flags
+ * @brief Enumeration that defines the handler flags to monitor the file descriptor for: reading, writing, or error.
+ */
+enum _Ecore_Fd_Handler_Flags
+{
+ ECORE_FD_READ = 1, /**< FD Read mask */
+ ECORE_FD_WRITE = 2, /**< FD Write mask */
+ ECORE_FD_ERROR = 4 /**< FD Error mask */
+};
+
+/**
+ * @brief typedef to enum _Ecore_Fd_Handler_Flags
+ */
+typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags;
+
+/**
+ * @typedef Ecore_Fd_Cb Ecore_Fd_Cb
+ * @brief The boolean type for a callback used by an @ref Ecore_Fd_Handler.
+ */
+typedef Eina_Bool (*Ecore_Fd_Cb)(void *data, Ecore_Fd_Handler *fd_handler);
+
+/**
+ * @typedef Ecore_Fd_Prep_Cb Ecore_Fd_Prep_Cb
+ * @brief Called to be used by an @ref Ecore_Fd_Handler.
+ */
+typedef void (*Ecore_Fd_Prep_Cb)(void *data, Ecore_Fd_Handler *fd_handler);
+
+/**
+ * @internal
+ * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb
+ * @brief The boolean type for a callback used by an @ref Ecore_Win32_Handler.
+ */
+typedef Eina_Bool (*Ecore_Win32_Handle_Cb)(void *data, Ecore_Win32_Handler *wh);
+
+/**
+ * @brief Adds a callback for activity on the given file descriptor.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a func is called during the execution of @ref Ecore_Main_Loop_Page
+ * when the file descriptor is available for reading, writing, or there has been
+ * an error(depending on the given @a flags).
+ *
+ * @remarks When @a func returns @c ECORE_CALLBACK_CANCEL, it indicates that the
+ * handler should be marked for deletion (identical to calling @ref
+ * ecore_main_fd_handler_del).
+ *
+ * @remarks @a buf_func is meant for @b internal use only and should be @b
+ * avoided.
+ *
+ * @remarks The return value of @a buf_func has a different meaning, when it returns
+ * @c ECORE_CALLBACK_CANCEL, it indicates that @a func @b shouldn't be called, and
+ * when it returns @c ECORE_CALLBACK_RENEW it indicates @a func should be called.
+ * The return value of @a buf_func does not cause the FD handler to get deleted.
+ *
+ * @remarks @a buf_func is called during event loop handling to check if data that has
+ * been read from the file descriptor is in a buffer and is available to read.
+ * Some systems, notably xlib, handle their own buffering, and would otherwise
+ * not work with select(). These systems should use a @a buf_func. This is the
+ * most annoying hack, only ecore_x uses it, so refer to that for an example.
+ *
+ * @remarks This function should @b not be used for monitoring "normal" files, like text files.
+ *
+ * @param[in] fd The file descriptor to watch
+ * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c
+ * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n
+ * Values by |(ored).
+ * @param[in] func The callback function
+ * @param[in] data The data to pass to the callback
+ * @param[in] buf_func The function to call to check if any data has been buffered
+ * and already read from the fd \n
+ * May be @c NULL.
+ * @param[in] buf_data The data to pass to the @a buf_func function
+ * @return An fd handler handle on success,
+ * otherwise @c NULL on failure
+ *
+ */
+EAPI Ecore_Fd_Handler *ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data);
+
+/**
+ * @brief Adds a callback for activity on the given file descriptor.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is identical to ecore_main_fd_handler_add, except that it supports regular files.
+ *
+ * @remarks This function should ONLY be called with @c ECORE_FD_ERROR, otherwise it calls the fd
+ * handler constantly.
+ * @remarks Do not use this function unless you know what you are doing.
+ *
+ * @param[in] fd The file descriptor to watch
+ * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c
+ * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n
+ * Values by |(ored).
+ * @param[in] func The callback function
+ * @param[in] data The data to pass to the callback
+ * @param[in] buf_func The function to call to check if any data has been buffered
+ * and already read from the fd \n
+ * May be @c NULL.
+ * @param[in] buf_data The data to pass to the @a buf_func function.
+ * @return An fd handler handle on success,
+ * otherwise @c NULL on failure
+ */
+EAPI Ecore_Fd_Handler *ecore_main_fd_handler_file_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data);
+
+/**
+ * @brief Sets the prepare callback with data for a given #Ecore_Fd_Handler.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is called prior to any fd handler's callback function
+ * (even the other fd handlers), before entering the main loop select function.
+ *
+ * @remarks Once a prepare callback is set for an fd handler, it cannot be changed.
+ * You need to delete the fd handler and create a new one, to set another
+ * callback.
+ *
+ * @remarks You probably don't need this function. It is only necessary for very
+ * uncommon cases that need special behavior.
+ *
+ * @param[in] fd_handler The fd handler
+ * @param[in] func The prep function
+ * @param[in] data The data to pass to the prep function
+ */
+EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data);
+
+/**
+ * @brief Marks an FD handler for deletion.
+ *
+ * @since_tizen 2.3
+ *
+ * @details This function marks an fd handler to be deleted during an iteration of the
+ * main loop. It does NOT close the associated fd.
+ *
+ * @remarks If the underlying fd is already closed ecore may complain if the
+ * main loop is using epoll internally, and also in some rare cases this may
+ * cause crashes and instability. Remember to delete your fd handlers before the
+ * fds they listen to are closed.
+ *
+ * @param[in] fd_handler The fd handler
+ * @return The data pointer set using @ref ecore_main_fd_handler_add, for
+ * @a fd_handler on success,
+ * otherwise @c NULL on failure
+ */
+EAPI void *ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler);
+
+/**
+ * @brief Retrieves the file descriptor that the given handler is handling.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] fd_handler The given fd handler
+ * @return The file descriptor that the handler is watching
+ */
+EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler);
+
+/**
+ * @brief Gets which flags are active on an FD handler.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] fd_handler The given fd handler
+ * @param[in] flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE, or
+ * @c ECORE_FD_ERROR to query
+ * @return #EINA_TRUE if any of the given flags are active,
+ * otherwise @c EINA_FALSE
+ */
+EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags);
+
+/**
+ * @brief Sets what active streams the given FD handler should be monitoring.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] fd_handler The given fd handler
+ * @param[in] flags The flags to be watching
+ */
+EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags);
+
+/**
+ * @internal
+ */
+EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data);
+
+/**
+ * @internal
+ */
+EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Time_Group Ecore Time
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief This group discusses the functions to retrieve time in a given format.
+ *
+ * @{
+ */
+
+/**
+ * @brief Retrieves the current system time as a floating point value in seconds.
+ *
+ * @details This uses a monotonic clock and thus never goes back in time while
+ * machine is live (even if user changes time or timezone changes,
+ * however it may be reset whenever the machine is restarted).
+ *
+ * @since_tizen 2.3
+ *
+ * @return The number of seconds. Start time is not defined (it may be
+ * when the machine was booted, unix time, etc), all it is
+ * defined is that it never goes backwards (unless you got big critical
+ * messages when the application started).
+ *
+ * @see ecore_loop_time_get().
+ * @see ecore_time_unix_get().
+ */
+EAPI double ecore_time_get(void);
+
+/**
+ * @brief Retrieves the current UNIX time as a floating point value in seconds.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The number of seconds since 12.00AM 1st January 1970.
+ *
+ * @see ecore_time_get().
+ * @see ecore_loop_time_get().
+ */
+EAPI double ecore_time_unix_get(void);
+
+/**
+ * @brief Retrieves the time at which the last loop stopped waiting for
+ * timeouts or events.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This gets the time that the main loop ceased waiting for timouts
+ * and/or events to come in or for signals or any other interrupt
+ * source. This should be considered a reference point for all time
+ * based activity that should calculate its timepoint from the return
+ * of ecore_loop_time_get(). Use this UNLESS you absolutely must get
+ * the current actual timepoint - then use ecore_time_get().
+ * Note that this time is meant to be used as relative to other times
+ * obtained on this run. If you need absolute time references, use
+ * ecore_time_unix_get() instead.
+ *
+ * @remarks This function can be called before any loop has ever been run, but
+ * either ecore_init() or ecore_time_get() must have been called once.
+ *
+ * @return The number of seconds. Start time is not defined (it may be
+ * when the machine was booted, unix time, etc), all it is
+ * defined is that it never goes backwards (unless you got big critical
+ * messages when the application started).
+ */
+EAPI double ecore_loop_time_get(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Thread_Group Ecore Thread
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief Facilities to run heavy tasks in different threads to avoid blocking
+ * the main loop.
+ *
+ * The EFL is, for the most part, not thread safe. This means that if you
+ * have some task running in another thread and you have, for example, an
+ * Evas object to show the status progress of this task, you cannot update
+ * the object from within the thread. This can only be done from the main
+ * thread, the one running the main loop. This problem can be solved
+ * by running a thread that sends messages to the main one using an
+ * @ref Ecore_Pipe_Group "Ecore_Pipe", but when you need to handle other
+ * things like cancelling the thread, your code grows in complexity and gets
+ * much harder to maintain.
+ *
+ * Ecore Thread is here to solve that problem. It is not a simple wrapper
+ * around standard POSIX threads (or an equivalent in other systems) and
+ * it's not meant to be used to run parallel tasks throughout the entire
+ * duration of the program, especially when these tasks are performance
+ * critical, as Ecore manages these tasks using a pool of threads based on
+ * system configuration.
+ *
+ * What Ecore Thread does is it makes it a lot easier to dispatch a worker
+ * function to perform some heavy tasks and then get the result once it
+ * completes, without blocking the application's UI. In addition, cancelling
+ * and rescheduling comes practically for free and the developer need not
+ * worry about how many threads are launched, since Ecore schedules
+ * them according to the number of processors the system has and the maximum
+ * amount of concurrent threads set for the application.
+ *
+ * At the system level, Ecore starts a new thread on an as-needed basis
+ * until the maximum set is reached. When no more threads can be launched,
+ * new worker functions are queued in a waiting list until a thread
+ * becomes available. This way, system threads are shared throughout
+ * different worker functions, but running only one at a time. At the same
+ * time, a worker function that is rescheduled may be run on a different
+ * thread the next time.
+ *
+ * The ::Ecore_Thread handler has two meanings, depending on what context
+ * it is on. The one returned when starting a worker with any of the
+ * functions ecore_thread_run() or ecore_thread_feedback_run() is an
+ * identifier of that specific instance of the function and can be used from
+ * the main loop with the ecore_thread_cancel() and ecore_thread_check()
+ * functions. This handler must not be shared with the worker function
+ * running in the thread. This same handler is the one received
+ * on the @c end, @c cancel, and @c feedback callbacks.
+ *
+ * The worker function, that's the one running in the thread, also receives
+ * an ::Ecore_Thread handler that can be used with ecore_thread_cancel() and
+ * ecore_thread_check(), sharing the flag with the main loop. But this
+ * handler is also associated with the thread where the function is running.
+ * This has strong implications when working with thread local data.
+ *
+ * There are two kinds of worker threads that Ecore handles: simple or short,
+ * workers, and feedback workers.
+ *
+ * The first kind is for simple functions that perform a
+ * usually small but time consuming task. Ecore runs this function in
+ * a thread as soon as one becomes available and notifies the calling user of
+ * its completion once the task is done.
+ *
+ * The following image shows the flow of a program running four tasks on
+ * a pool of two threads.
+ *
+ * @image html ecore_thread.png
+ * @image rtf ecore_thread.png
+ * @image latex ecore_thread.eps "ecore thread" width=\textwidth
+ *
+ * For larger tasks that may require continuous communication with the main
+ * program, the feedback workers provide the same functionality plus a way
+ * for the function running in the thread to send messages to the main
+ * thread.
+ *
+ * The next diagram omits some details shown in the previous one regarding
+ * how threads are spawned and tasks are queued, but illustrates how feedback
+ * jobs communicate with the main loop and the special case of threads
+ * running out of the pool.
+ *
+ * @image html ecore_thread_feedback.png
+ * @image rtf ecore_thread_feedback.png
+ * @image latex ecore_thread_feedback.eps "ecore thread feedback" width=\textwidth
+ *
+ * @{
+ */
+
+typedef struct _Ecore_Thread Ecore_Thread; /**< @brief A handle for threaded jobs */
+
+/**
+ * @typedef Ecore_Thread_Cb Ecore_Thread_Cb
+ * @brief Called to be used by Ecore_Thread helper.
+ */
+typedef void (*Ecore_Thread_Cb)(void *data, Ecore_Thread *thread);
+/**
+ * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb
+ * @brief Called to be used by the main loop to receive data sent by an
+ * @ref Ecore_Thread_Group.
+ */
+typedef void (*Ecore_Thread_Notify_Cb)(void *data, Ecore_Thread *thread, void *msg_data);
+
+/**
+ * @brief Schedules a task to run in a parallel thread to avoid locking the main loop.
+ *
+ * @details This function tries to create a new thread to run @a func_blocking in,
+ * or if the maximum number of concurrent threads has been reached it
+ * adds it to the pending list, where it waits until a thread becomes
+ * available. The return value is an ::Ecore_Thread handle that can
+ * be used to cancel the thread before its completion.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function should always return immediately, but in the rare
+ * case that Ecore is built with no thread support, @a func_blocking is
+ * be called here, actually blocking the main loop.
+ *
+ * @remarks Once a thread becomes available, @a func_blocking is run in it until
+ * it finishes, then @a func_end is called from the thread containing the
+ * main loop to inform the user of its completion. While in @a func_blocking,
+ * no functions from the EFL can be used, except for those from Eina that are
+ * marked to be thread-safe. Even for the latter, caution needs to be taken
+ * if the data is shared across several threads.
+ *
+ * @remarks @a func_end is called from the main thread when @a func_blocking ends,
+ * so here it's safe to use anything from the EFL freely.
+ *
+ * @remarks The thread can also be cancelled before its completion by calling
+ * ecore_thread_cancel(), either from the main thread or @a func_blocking.
+ * In this case, @a func_cancel is called, also from the main thread
+ * to inform of this happening. If the thread could not be created, this
+ * function is called and its @c thread parameter is @c NULL. It's
+ * also safe to call any EFL function here, as it is running in the
+ * main thread.
+ *
+ * @remarks Inside @a func_blocking, it's possible to call ecore_thread_reschedule()
+ * to tell Ecore that this function should be called again.
+ *
+ * @remarks Be aware that no assumptions can be made about the order in which the
+ * @a func_end callbacks for each task are called. Once the function is
+ * running in a different thread, it's the OS that handles its running
+ * schedule, and different functions may take longer to finish than others.
+ * Also remember that just starting several tasks together doesn't mean they
+ * are going to run at the same time. Ecore schedules them based on the
+ * number of threads available for the particular system it's running in,
+ * so some of the jobs started may be waiting until another one finishes
+ * before it can execute its own @a func_blocking.
+ *
+ * @param[in] func_blocking The function that should run in another thread
+ * @param[in] func_end The function to call from the main loop when @a func_blocking
+ * completes its task successfully (may be @c NULL)
+ * @param[in] func_cancel The function to call from the main loop if the thread running
+ * @a func_blocking is cancelled or fails to start (may be @c NULL)
+ * @param[in] data The user context data to pass to all callbacks
+ * @return A new thread handler,
+ * otherwise @c NULL on failure
+ *
+ * @see ecore_thread_feedback_run()
+ * @see ecore_thread_cancel()
+ * @see ecore_thread_reschedule()
+ * @see ecore_thread_max_set()
+ */
+EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data);
+
+/**
+ * @brief Launches a thread to run a task that can talk back to the main thread.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The difference in the above is that ecore_thread_run() is meant for
+ * tasks that don't need to communicate anything until they finish, while
+ * this function is provided with a new callback, @a func_notify, that is
+ * called from the main thread for every message sent from @a func_heavy
+ * with ecore_thread_feedback().
+ *
+ * @remarks Like with ecore_thread_run(), a new thread is launched to run
+ * @a func_heavy unless the maximum number of simultaneous threads has been
+ * reached, in which case the function is scheduled to run whenever a
+ * running task ends and a thread becomes free. But if @a try_no_queue is
+ * set, Ecore first tries to launch a thread outside of the pool to run
+ * the task. If it fails, it reverts to the normal behaviour of using a
+ * thread from the pool as if @a try_no_queue had not been set.
+ *
+ * @remarks Keep in mind that Ecore handles the thread pool based on the number of
+ * CPUs available, but running a thread outside of the pool doesn't count for
+ * this, so having too many of them may have drastic effects over the
+ * program's performance.
+ *
+ * @remarks See ecore_thread_run() for a general description of this function.
+ *
+ * @param[in] func_heavy The function that should run in another thread
+ * @param[in] func_notify the function that receives the data sent from the thread
+ * @param[in] func_end The function to call from the main loop when @a func_heavy
+ * completes its task successfully
+ * @param[in] func_cancel The function to call from the main loop if the thread running
+ * @a func_heavy is cancelled or fails to start
+ * @param[in] data The user context data to pass to all callbacks
+ * @param[in] try_no_queue The boolean value that indicates whether to run outside the thread pool
+ * @return A new thread handler,
+ * otherwise @c NULL on failure
+ *
+ * @see ecore_thread_feedback()
+ * @see ecore_thread_run()
+ * @see ecore_thread_cancel()
+ * @see ecore_thread_reschedule()
+ * @see ecore_thread_max_set()
+ */
+EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify,
+ Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel,
+ const void *data, Eina_Bool try_no_queue);
+
+/**
+ * @brief Cancels a running thread.
+ *
+ * @details This function cancels a running thread. If @a thread can be immediately
+ * cancelled (its still pending execution after creation or rescheduling),
+ * then the @a cancel callback is called, @a thread is freed and
+ * the function returns #EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the thread is already running, then this function returns @c EINA_FALSE
+ * after marking the @a thread as pending cancellation. For the thread to
+ * actually be terminated, it needs to return from the user function back
+ * into Ecore control. This can happen in several ways:
+ * @li The function ends and returns normally. If it hadn't been cancelled,
+ * @a func_end would be called here, but instead @a func_cancel happens.
+ * @li The function returns after requesting to be rescheduled with
+ * ecore_thread_reschedule().
+ * @li The function is prepared to leave early by checking if
+ * ecore_thread_check() returns #EINA_TRUE.
+ *
+ * @remarks The user function can cancel itself by calling ecore_thread_cancel(), but
+ * it should always use the ::Ecore_Thread handle passed to it and never
+ * share it with the main loop thread by means of shared user data or in any
+ * other way.
+ *
+ * @remarks @a thread is freed and should not be used again if this function
+ * returns #EINA_TRUE or after the @a func_cancel callback returns.
+ *
+ * @remarks This function can be called both in the main loop and in the running thread.
+ *
+ * @param[in] thread The thread to cancel
+ * @return #EINA_TRUE if the thread has been cancelled,
+ * otherwise @c EINA_FALSE if it is pending
+ *
+ * @see ecore_thread_check()
+ */
+EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread);
+
+/**
+ * @brief Checks whether a thread is in pending cancellation.
+ *
+ * @details This function can be called both in the main loop and in the running thread.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When ecore_thread_cancel() is called on an already running task, the
+ * thread is marked as pending cancellation. This function returns #EINA_TRUE
+ * if this mark is set for the given @a thread and can be used from the
+ * main loop thread to check if a still active thread has been cancelled,
+ * or from the user function running in the thread to check if it should
+ * stop doing what it's doing and return early, effectively cancelling the
+ * task.
+ *
+ * @param[in] thread The thread to test
+ * @return #EINA_TRUE if the thread is in pending cancellation,
+ * otherwise @c EINA_FALSE if it is not
+ *
+ * @see ecore_thread_cancel()
+ */
+EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread);
+
+/**
+ * @brief Sends data from the worker thread to the main loop.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks You should use this function only in the @a func_heavy call.
+ *
+ * @remarks Only the address to @a msg_data is sent and once this function
+ * returns #EINA_TRUE, the job running in the thread should never touch the
+ * contents of it again. The data sent should be malloc()'ed or something
+ * similar, as long as it's not the memory that is local to the thread that risks being
+ * overwritten or deleted once it goes out of scope or the thread finishes.
+ *
+ * @remarks Care must be taken that @a msg_data is properly freed in the @a func_notify
+ * callback set when creating the thread.
+ *
+ * @param[in] thread The current ::Ecore_Thread context to send data from
+ * @param[in] msg_data The data to be transmitted to the main loop
+ * @return #EINA_TRUE if @a msg_data is successfully sent to the main loop,
+ * otherwise @c EINA_FALSE if anything goes wrong
+ *
+ * @see ecore_thread_feedback_run()
+ */
+EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data);
+
+/**
+ * @brief Asks for the function in the thread to be called again at a later period.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function should be called only from the function represented
+ * by @a thread.
+ *
+ * Calling this function marks the thread for a reschedule, so as soon
+ * as it returns, it is added to the end of the list of pending tasks.
+ * If no other tasks are waiting or there are sufficient threads available,
+ * the rescheduled task is launched again immediately.
+ *
+ * This should never return @c EINA_FALSE, unless it is called from the wrong
+ * thread or with the wrong arguments.
+ *
+ * @remarks The @a func_end callback set when the thread is created is not
+ * called until the function in the thread returns without being rescheduled.
+ * Similarly, if the @a thread is cancelled, the reschedule does not take
+ * effect.
+ *
+ * @param[in] thread The current ::Ecore_Thread context to reschedule
+ * @return #EINA_TRUE if the task is successfully rescheduled,
+ * otherwise @c EINA_FALSE if anything goes wrong
+ *
+ */
+EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread);
+
+/**
+ * @brief Gets the number of active threads running jobs.
+ *
+ * @details This returns the number of threads currently running jobs of any type
+ * through the Ecore_Thread API.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Jobs started through the ecore_thread_feedback_run() function with
+ * the @a try_no_queue parameter set to #EINA_TRUE are not accounted for
+ * in the return of this function unless the thread creation fails and it
+ * falls back to using one from the pool.
+ *
+ * @return The number of active threads running jobs
+ *
+ */
+EAPI int ecore_thread_active_get(void);
+
+/**
+ * @brief Gets the number of short jobs waiting for a thread to run.
+ *
+ * @details This returns the number of tasks started with ecore_thread_run() that are
+ * pending and waiting for a thread to become available to run them.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The number of pending threads running "short" jobs
+ *
+ */
+EAPI int ecore_thread_pending_get(void);
+
+/**
+ * @brief Gets the number of feedback jobs waiting for a thread to run.
+ *
+ * @details This returns the number of tasks started with ecore_thread_feedback_run()
+ * that are pending and waiting for a thread to become available to run them.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The number of pending threads running "feedback" jobs
+ *
+ */
+EAPI int ecore_thread_pending_feedback_get(void);
+
+/**
+ * @brief Gets the total number of pending jobs.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is same as the sum of ecore_thread_pending_get() and
+ * ecore_thread_pending_feedback_get().
+ *
+ * @return The number of pending threads running jobs
+ *
+ */
+EAPI int ecore_thread_pending_total_get(void);
+
+/**
+ * @brief Gets the maximum number of threads that can run simultaneously.
+ *
+ * @details This returns the maximum number of Ecore_Thread's that may be running at
+ * the same time. If this number is reached, new jobs started by either
+ * ecore_thread_run() or ecore_thread_feedback_run() are added to the
+ * respective pending queues until one of the running threads finishes its
+ * task and becomes available to run a new one.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks By default, this is the number of available CPUs for the
+ * running program (as returned by eina_cpu_count()), or @c 1 if this value
+ * could not be fetched.
+ *
+ * @return The maximum possible number of Ecore_Thread's running concurrently
+ *
+ * @see ecore_thread_max_set()
+ * @see ecore_thread_max_reset()
+ */
+EAPI int ecore_thread_max_get(void);
+
+/**
+ * @brief Sets the maximum number of threads allowed to run simultaneously.
+ *
+ * @details This sets a new value for the maximum number of concurrently running
+ * Ecore_Thread's. It @b must be an integer between @c 1 and (@c 16 * @c x), where @c x
+ * is the number for CPUs available.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] num The new maximum
+ *
+ * @see ecore_thread_max_get()
+ * @see ecore_thread_max_reset()
+ */
+EAPI void ecore_thread_max_set(int num);
+
+/**
+ * @brief Resets the maximum number of concurrently running threads to the default.
+ *
+ * @details This resets the value returned by ecore_thread_max_get() back to its
+ * default.
+ *
+ * @since_tizen 2.3
+ *
+ * @see ecore_thread_max_get()
+ * @see ecore_thread_max_set()
+ */
+EAPI void ecore_thread_max_reset(void);
+
+/**
+ * @brief Gets the number of threads available for running tasks.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is same as doing ecore_thread_max_get() - ecore_thread_active_get().
+ *
+ * @remarks This function may return a negative number only in the case when the user
+ * changes the maximum number of running threads while other tasks are
+ * running.
+ *
+ * @return The number of available threads
+ *
+ */
+EAPI int ecore_thread_available_get(void);
+
+/**
+ * @brief Adds some data present in the hash local to the thread.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Ecore Thread has a mechanism to share data across several worker functions
+ * that run on the same system thread. That is, the data is stored per
+ * thread and for a worker function to have access to it, it must be run
+ * by the same thread that stored the data.
+ *
+ * @remarks When there are no more workers pending, the thread is destroyed
+ * along with the internal hash and any data left in it is freed with
+ * the given @a cb function.
+ *
+ * @ This set of functions is useful to share things around several instances
+ * of a function when that thing is costly to create and can be reused, but
+ * may only be used by one function at a time.
+ *
+ * For example, if you have a program doing requisitions to a database,
+ * these requisitions can be done in threads so that waiting for the
+ * database to respond doesn't block the UI. Each of these threads
+ * run a function, and each function is dependent on a connection to
+ * the database, which may not be able to handle more than one request at
+ * a time so for each running function you need one connection handle.
+ *
+ * The options then are:
+ * @li Each function opens a connection when it's called, does the work and
+ * closes the connection when it finishes. This may be costly, wasting a lot
+ * of time on resolving hostnames, negotiating permissions, and allocating
+ * memory.
+ * @li Open the connections in the main loop and pass it to the threads
+ * using the data pointer. Even worse, it's just as costly as before and now
+ * it may even be kept with connections open doing nothing until a thread
+ * becomes available to run the function.
+ * @li Have a way to share connection handles, so that each instance of the
+ * function can check if an available connection exists, and if it doesn't,
+ * create one and add it to the pool. When no more connections are needed,
+ * they are all closed.
+ *
+ * The last option is the most efficient, but it requires a lot of work to
+ * be implemented properly. Using thread local data helps to achieve the same
+ * result while avoiding all the tracking work on your code. The way
+ * to use it would be at the worker function, to ask for the connection
+ * using ecore_thread_local_data_find() and if it doesn't exist, then open
+ * a new one and save it with ecore_thread_local_data_add(). Complete the work and
+ * forget about the connection handle, when everything is done the function
+ * just ends. The next worker to run on that thread checks if a
+ * connection exists and finds that it does, so the process of opening a
+ * new one has been spared. When no more workers exist, the thread is
+ * destroyed and the callback used when saving the connection is called
+ * to close it.
+ *
+ * @remarks This function adds the data @a value to the thread data under the given
+ * @a key. No other value in the hash may have the same @a key. If you need to
+ * change the value under a @a key, or you don't know if one exists already,
+ * you can use ecore_thread_local_data_set().
+ *
+ * Neither @a key nor @a value may be @c NULL and @a key gets copied in the
+ * hash, unless @a direct is set, in which case the string used should not
+ * be freed until the data is removed from the hash.
+ *
+ * @remarks The @a cb function is called when the data in the hash needs to be
+ * freed, be it because it got deleted by ecore_thread_local_data_del() or
+ * because @a thread got terminated and the hash got destroyed. This parameter
+ * may be @c NULL, in which case @a value needs to be manually freed after
+ * removing it from the hash with either ecore_thread_local_data_del() or
+ * ecore_thread_local_data_set(), but it's very unlikely that this is what
+ * you want.
+ *
+ * This function, and all of the others in the @a ecore_thread_local_data
+ * family of functions, can only be called within the worker function running
+ * in the thread. Do not call them from the main loop or from a thread
+ * other than the one represented by @a thread.
+ *
+ * @param[in] thread The thread context the data belongs to
+ * @param[in] key The name under which the data is stored
+ * @param[in] value The data to add
+ * @param[in] cb The function to free the data when removed from the hash
+ * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()),
+ * otherwise @c false
+ * @return #EINA_TRUE on success,
+ * otherwise @c EINA_FALSE on failure
+ *
+ * @see ecore_thread_local_data_set()
+ * @see ecore_thread_local_data_find()
+ * @see ecore_thread_local_data_del()
+ */
+EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key, void *value,
+ Eina_Free_Cb cb, Eina_Bool direct);
+
+/**
+ * @brief Sets some data present in the hash local to the given thread.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If no data exists in the hash under the @a key, this function adds
+ * @a value in the hash under the given @a key and returns @c NULL.
+ * The key itself is copied.
+ *
+ * If the hash already contains something under @a key, the data is
+ * replaced by @a value and the old value is returned.
+ *
+ * @c NULL is also returned if either @a key or @a value are @c NULL, or
+ * if an error occurs.
+ *
+ * @remarks This function, and all of the others in the @a ecore_thread_local_data
+ * family of functions, can only be called within the worker function running
+ * in the thread. Do not call them from the main loop or from a thread
+ * other than the one represented by @a thread.
+ *
+ * @param[in] thread The thread context the data belongs to
+ * @param[in] key The name under which the data is stored
+ * @param[in] value The data to add
+ * @param[in] cb The function to free the data when removed from the hash
+ *
+ * @see ecore_thread_local_data_add()
+ * @see ecore_thread_local_data_del()
+ * @see ecore_thread_local_data_find()
+ */
+EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb);
+
+/**
+ * @brief Gets data stored in the hash local to the given thread.
+ *
+ * @since_tizen 2.3
+ *
+ * @details This finds and returns the data stored in the shared hash under the key @a key.
+ *
+ * @remarks This function, and all the others in the @a ecore_thread_local_data
+ * family of functions, can only be called within the worker function running
+ * in the thread. Do not call them from the main loop or from a thread
+ * other than the one represented by @a thread.
+ *
+ * @param[in] thread The thread context the data belongs to
+ * @param[in] key The name under which the data is stored
+ * @return The value under the given key,
+ * otherwise @c NULL on an error
+ *
+ * @see ecore_thread_local_data_add()
+ * @see ecore_thread_local_data_wait()
+ */
+EAPI void *ecore_thread_local_data_find(Ecore_Thread *thread, const char *key);
+
+/**
+ * @brief Deletes the data corresponding to the given key from the thread's hash.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If there's any data associated with @a key that is stored in the global hash,
+ * this function removes it from the hash and returns #EINA_TRUE. If no data
+ * exists or an error occurs, it returns @c EINA_FALSE.
+ *
+ * @remarks If the data is added to the hash with a free function, then it is
+ * also freed after removing it from the hash, otherwise it requires
+ * to be manually freed by the user, which means that if no other reference
+ * to it exists before calling this function, it results in a memory
+ * leak.
+ *
+ * @remarks This function, and all the others in the @a ecore_thread_local_data
+ * family of functions, can only be called within the worker function running
+ * in the thread. Do not call them from the main loop or from a thread
+ * other than the one represented by @a thread.
+ *
+ * @param[in] thread The thread context the data belongs to
+ * @param[in] key The name under which the data is stored
+ * @return #EINA_TRUE on success,
+ * otherwise @c EINA_FALSE on failure
+ *
+ * @see ecore_thread_local_data_add()
+ */
+EAPI Eina_Bool ecore_thread_local_data_del(Ecore_Thread *thread, const char *key);
+
+/**
+ * @brief Adds some data to a hash shared by all threads.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Ecore Thread keeps a hash that can be used to share data across several
+ * threads, including the main loop thread, without having to manually handle
+ * mutexes to do it safely.
+ *
+ * @remarks This function adds the data @a value to this hash under the given @a key.
+ * No other value in the hash may have the same @a key. If you need to
+ * change the value under a @a key, or you don't know if one exists already,
+ * you can use ecore_thread_global_data_set().
+ *
+ * Neither @a key nor @a value may be @c NULL and @a key gets copied in the
+ * hash, unless @a direct is set, in which case the string used should not
+ * be freed until the data is removed from the hash.
+ *
+ * @remarks The @a cb function is called when the data in the hash needs to be
+ * freed, be it because it got deleted with ecore_thread_global_data_del() or
+ * because Ecore Thread got shut down and the hash got destroyed. This parameter
+ * may be @c NULL, in which case @a value needs to be manually freed after
+ * removing it from the hash with either by ecore_thread_global_data_del() or
+ * ecore_thread_global_data_set().
+ *
+ * Manually freeing any data that is added to the hash with the @a cb function
+ * is likely to produce a segmentation fault, or any other strange
+ * happening at a later stage in the program.
+ *
+ * @param[in] key The name under which the data is stored
+ * @param[in] value The data to add
+ * @param[in] cb The function to free the data when removed from the hash
+ * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()),
+ * otherwise @c false
+ * @return #EINA_TRUE on success,
+ * otherwise @c EINA_FALSE on failure
+ *
+ * @see ecore_thread_global_data_del()
+ * @see ecore_thread_global_data_set()
+ * @see ecore_thread_global_data_find()
+ */
+EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct);
+
+/**
+ * @brief Sets some data in the hash shared by all threads.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If no data exists in the hash under the @a key, this function adds
+ * @a value in the hash under the given @a key and returns @c NULL.
+ * The key itself is copied.
+ *
+ * If the hash already contains something under @a key, the data is
+ * replaced by @a value and the old value is returned.
+ *
+ * @c NULL is also returned if either @a key or @a value is @c NULL, or
+ * if an error occurs.
+ *
+ *
+ * @param[in] key The name under which the data is stored
+ * @param[in] value The data to add
+ * @param[in] cb The function to free the data when removed from the hash
+ *
+ * @see ecore_thread_global_data_add()
+ * @see ecore_thread_global_data_del()
+ * @see ecore_thread_global_data_find()
+ */
+EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_Cb cb);
+
+/**
+ * @brief Gets data stored in the hash shared by all threads.
+ *
+ * @since_tizen 2.3
+ *
+ * @details This finds and returns the data stored in the shared hash under the key @a key.
+ *
+ * @remarks Keep in mind that the data returned may be used by more than one thread
+ * at the same time and no reference counting is done on it by Ecore.
+ * Freeing the data or modifying its contents may require additional
+ * precautions to be considered, depending on the application's design.
+ *
+ * @param[in] key The name under which the data is stored
+ * @return The value under the given key,
+ * otherwise @c NULL on an error
+ *
+ * @see ecore_thread_global_data_add()
+ * @see ecore_thread_global_data_wait()
+ */
+EAPI void *ecore_thread_global_data_find(const char *key);
+
+/**
+ * @brief Deletes the data corresponding to the given key from the shared hash.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If there's any data associated with @p key that is stored in the global hash,
+ * this function removes it from the hash and returns #EINA_TRUE. If no data
+ * exists or an error occurs, it returns @c EINA_FALSE.
+ *
+ * @remarks If the data is added to the hash with a free function, then it is
+ * also freed after removing it from the hash, otherwise it requires
+ * to be manually freed by the user, which means that if no other reference
+ * to it exists before calling this function, it results in a memory
+ * leak.
+ *
+ * Note, also, that freeing data that other threads may be using results
+ * in a crash, so appropriate care must be taken by the application when
+ * that possibility exists.
+ *
+ * @param[in] key The name under which the data is stored
+ * @return #EINA_TRUE on success,
+ * otherwise @c EINA_FALSE on failure
+ *
+ * @see ecore_thread_global_data_add()
+ */
+EAPI Eina_Bool ecore_thread_global_data_del(const char *key);
+
+/**
+ * @brief Gets data stored in the shared hash or waits for it if it doesn't exist.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This finds and returns the data stored in the shared hash under the key @a key.
+ *
+ * If there's nothing in the hash under the given @a key, the function
+ * blocks and waits for @a seconds seconds for some other thread to
+ * add it with either ecore_thread_global_data_add() or
+ * ecore_thread_global_data_set(). If after waiting there's still no data
+ * to obtain, @c NULL is returned.
+ *
+ * If @a seconds is @c 0, then no waiting happens and this function works
+ * like ecore_thread_global_data_find(). If @a seconds is less than @c 0, then
+ * the function waits indefinitely.
+ *
+ * @remarks Keep in mind that the data returned may be used by more than one thread
+ * at the same time and no reference counting is done on it by Ecore.
+ * Freeing the data or modifying its contents may require additional
+ * precautions to be considered, depending on the application's design.
+ *
+ * @param[in] key The name under which the data is stored
+ * @param[in] seconds The amount of time in seconds to wait for the data
+ * @return The value under the given key,
+ * otherwise @c NULL on an error
+ *
+ * @see ecore_thread_global_data_add()
+ * @see ecore_thread_global_data_find()
+ */
+EAPI void *ecore_thread_global_data_wait(const char *key, double seconds);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Timer_Group Ecore Timer
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief Ecore provides very flexible timer functionality.
+ *
+ * The basic usage of timers is to call a certain function at a certain
+ * interval, which can be achieved with a single line:
+ * @code
+ * Eina_Bool my_func(void *data) {
+ * do_funky_stuff_with_data(data);
+ * return ECORE_CALLBACK_RENEW;
+ * }
+ * ecore_timer_add(interval_in_seconds, my_func, data_given_to_function);
+ * @endcode
+ * If the function is to be executed only once simply return
+ * @c CORE_CALLBACK_CANCEL instead.
+ *
+ * @{
+ */
+
+typedef struct _Ecore_Timer Ecore_Timer; /**< @brief A handle for timers */
+
+/**
+ * @brief Creates a timer to call the given function in the given period of time.
+ *
+ * @details This function adds a timer and returns its handle on success and NULL on
+ * failure. The function @p func will be called every @p in seconds. The
+ * function will be passed the @p data pointer as its parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When the timer @p func is called, it must return a value of either 1
+ * (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL).
+ * If it returns 1, it will be called again at the next tick, or if it returns
+ * 0 it will be deleted automatically making any references/handles for it
+ * invalid.
+ *
+ * @param[in] in The interval in seconds.
+ * @param[in] func The given function. If @p func returns 1, the timer is
+ * rescheduled for the next interval @p in.
+ * @param[in] data Data to pass to @p func when it is called.
+ * @return A timer object on success. @c NULL on failure.
+ */
+EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Creates a timer to call the given function in the given period of time.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is same as ecore_timer_add(), but "now" is the time from
+ * ecore_loop_time_get(), not ecore_time_get(), as ecore_timer_add() uses it. See
+ * ecore_timer_add() for more details.
+ *
+ * @param[in] in The interval in seconds from the current loop time
+ * @param[in] func The given function \n
+ * If @a func returns @c 1, the timer is
+ * rescheduled for the next interval @a in.
+ * @param[in] data The data to pass to @a func when it is called
+ * @return A timer object on success,
+ * otherwise @c NULL on failure
+ */
+EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Deletes the specified timer from the timer list.
+ *
+ * @details This deletes the specified @a timer from the set of timer that are
+ * executed during main loop execution. This function returns the data
+ * parameter that is being passed to the callback on success, otherwise @c NULL on
+ * failure.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] timer The timer to delete
+ * @return The data pointer set for the timer on add
+ *
+ */
+EAPI void *ecore_timer_del(Ecore_Timer *timer);
+
+/**
+ * @brief Change the interval the timer ticks off.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] timer The timer to change.
+ * @param[in] in The interval in seconds.
+ */
+EAPI void ecore_timer_interval_set(Ecore_Timer *timer, double in);
+
+/**
+ * @brief Get the interval the timer ticks on.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] timer The timer to retrieve the interval from
+ * @return The interval on success. -1 on failure.
+ */
+EAPI double ecore_timer_interval_get(Ecore_Timer *timer);
+
+/**
+ * @brief Pauses a running timer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The timer callback won't be called while the timer is paused. The remaining
+ * time until the timer expires will be saved, so the timer can be resumed with
+ * that same remaining time to expire, instead of expiring instantly. Use
+ * ecore_timer_thaw() to resume it.
+ *
+ * @remarks Nothing happens if the timer was already paused.
+ *
+ * @param[in] timer The timer to be paused.
+ *
+ * @see ecore_timer_thaw()
+ */
+EAPI void ecore_timer_freeze(Ecore_Timer *timer);
+
+/**
+ * @brief Resumes a frozen (paused) timer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The timer will be resumed from its previous relative position in time. That
+ * means, if it had X seconds remaining until expire when it was paused, it will
+ * be started now with those same X seconds remaining to expire again. But
+ * notice that the interval time won't be touched by this call or by
+ * ecore_timer_freeze().
+ *
+ * @param[in] timer The timer to be resumed.
+ *
+ * @see ecore_timer_freeze()
+ */
+EAPI void ecore_timer_thaw(Ecore_Timer *timer);
+
+/**
+ * @brief Add some delay for the next occurrence of a timer.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This doesn't affect the interval of a timer.
+ *
+ * @param[in] timer The timer to change.
+ * @param[in] add The delay to add to the next iteration.
+ */
+EAPI void ecore_timer_delay(Ecore_Timer *timer, double add);
+
+/**
+ * @brief Reset a timer to its full interval. This effectively makes
+ * the timer start ticking off from zero now.
+ *
+ * @param[in] timer The timer
+ *
+ * @since_tizen 2.3
+ */
+EAPI void ecore_timer_reset(Ecore_Timer *timer);
+
+/**
+ * @brief Get the pending time regarding a timer.
+ *
+ * @param[in] timer The timer
+ * @return The pending time
+ *
+ * @since_tizen 2.3
+ */
+EAPI double ecore_timer_pending_get(Ecore_Timer *timer);
+
+/**
+ * @brief Retrieves the current precision used by timer infrastructure.
+ *
+ * @since_tizen 2.3
+ *
+ * @return Current precision.
+ *
+ * @see ecore_timer_precision_set()
+ */
+EAPI double ecore_timer_precision_get(void);
+
+/**
+ * @brief Sets the precision to be used by timer infrastructure.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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
+ * to use this function is to @b increase the allowed timeout and thus @b
+ * decrease precision of the timers, this is because less precise the timers
+ * result in the system waking up less often and thus consuming less resources.
+ *
+ * @remarks Be aware that kernel may delay delivery even further, these delays
+ * are always possible due other tasks having higher priorities or
+ * other scheduler policies.
+ *
+ * @remarks Example:
+ * We have 2 timers, one that expires in a 2.0s and another that
+ * expires in 2.1s, if precision is 0.1s, then the Ecore will request
+ * for the next expire to happen in 2.1s and not 2.0s and another one
+ * of 0.1 as it would before.
+ *
+ * @remarks Ecore is smart enough to see if there are timers in the
+ * precision range, if it does not, in our example if no second timer
+ * in (T + precision) existed, then it would use the minimum timeout.
+
+ * @param[in] precision difference from the requested internval.
+ */
+EAPI void ecore_timer_precision_set(double precision);
+
+/**
+ * @brief Dump the all timers.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The information of all timers
+ */
+EAPI char *ecore_timer_dump(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Idle_Group Ecore Idle
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief The idler functionality in Ecore allows for callbacks to be called when the
+ * program isn't handling @ref Ecore_Event_Group "events", @ref Ecore_Timer_Group
+ * "timers", or @ref Ecore_FD_Handler_Group "fd handlers".
+ *
+ * There are three types of idlers: Enterers, Idlers(proper), and Exiters. They
+ * are called respectively when the program is about to enter an idle state,
+ * when the program is in an idle state and when the program has just left an
+ * idle state and begins processing @ref Ecore_Event_Group "events", @ref
+ * Ecore_Timer_Group "timers", or @ref Ecore_FD_Handler_Group "fd handlers".
+ *
+ * Enterer callbacks are good for updating your program's state, if
+ * it has a state engine. Once all of the enterer handlers are
+ * called, the program enters a "sleeping" state.
+ *
+ * Idler callbacks are called when the main loop has called all
+ * enterer handlers. They are useful for interfaces that require
+ * polling and timers without which they would be too slow to use.
+ *
+ * Exiter callbacks are called when the main loop wakes up from an idle state.
+ *
+ * If no idler callbacks are specified, then the process literally
+ * goes to sleep. Otherwise, the idler callbacks are called
+ * continuously while the loop is "idle", using as much CPU as is
+ * available to the process.
+ *
+ * Idle state doesn't mean that the @b program is idle, but
+ * that the <b>main loop</b> is idle. It doesn't have any timers,
+ * events, fd handlers, or anything else to process (which in most
+ * <em>event driven</em> programs also means that the @b program is
+ * idle too, but it's not a rule). The program itself may be doing
+ * a lot of processing in the idler, or in another thread, for
+ * example.
+ *
+ * @{
+ */
+
+typedef struct _Ecore_Idler Ecore_Idler; /**< @brief A handle for idlers */
+typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer; /**< @brief A handle for idle enterers */
+typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter; /**< @brief A handle for idle exiters */
+
+/**
+ * @brief Adds an idler handler.
+ *
+ * @details This adds an idler handle to the event loop, returning a handle on
+ * success and @c NULL otherwise. The function @a func is called
+ * repeatedly while no other events are ready to be processed, as
+ * long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0
+ * (or @c ECORE_CALLBACK_CANCEL) deletes the idler.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Idlers are useful for progressively processing data without blocking.
+ *
+ * @param[in] func The function to call when idling
+ * @param[in] data The data to be passed to this @a func call
+ * @return A idler handle if successfully added,
+ * otherwise @c NULL
+ *
+ */
+EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Deletes an idler callback from the list to be executed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] idler The handle of the idler callback to delete
+ * @return The data pointer passed to the idler callback on success,
+ * otherwise @c NULL
+ */
+EAPI void *ecore_idler_del(Ecore_Idler *idler);
+
+/**
+ * @brief Add an idle enterer handler.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The function func will be called every time the main loop is entering
+ * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
+ * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer.
+ *
+ * @param[in] func The function to call when entering an idle state.
+ * @param[in] data The data to be passed to the @p func call
+ * @return A handle to the idle enterer callback if successful. Otherwise,
+ * NULL is returned.
+ */
+EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Add an idle enterer handler at the start of the list so it gets called earlier than others.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The function func will be called every time the main loop is entering
+ * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
+ * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer.
+ *
+ * @param[in] func The function to call when entering an idle state.
+ * @param[in] data The data to be passed to the @p func call
+ * @return A handle to the idle enterer callback if successful. Otherwise,
+ * NULL is returned.
+ */
+EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Delete an idle enterer callback.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] idle_enterer The idle enterer to delete
+ * @return The data pointer passed to the idler enterer callback on success.
+ * NULL otherwise.
+ */
+EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer);
+
+/**
+ * @brief Add an idle exiter handler.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The function func will be called every time the main loop is exiting
+ * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
+ * (or ECORE_CALLBACK_CANCEL) deletes the idle exiter.
+ *
+ * @param[in] func The function to call when exiting an idle state.
+ * @param[in] data The data to be passed to the @p func call
+ * @return A handle to the idle exiter callback on success. NULL otherwise.
+ */
+EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Delete an idle exiter handler from the list to be run on exiting idle state.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] idle_exiter The idle exiter to delete
+ * @return The data pointer that was being being passed to the handler if
+ * successful. NULL otherwise.
+ */
+EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Pipe_Group Ecore Pipe Wrapper
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief This group discusses the functions that wrap the write / read functions of the pipe to easily
+ * integrate its use into ecore's main loop.
+ *
+ * @remarks The ecore_pipe_add() function creates file descriptors (sockets
+ * on Windows) and attaches a handle to the ecore main loop. That
+ * handle is called when data is read in the pipe. To write data in
+ * the pipe, just call ecore_pipe_write(). When you are done, just
+ * call ecore_pipe_del().
+ *
+ * @{
+ */
+
+typedef struct _Ecore_Pipe Ecore_Pipe; /**< @brief A handle for pipes */
+
+/**
+ * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb
+ * @brief Called to send data written to the pipe.
+ */
+typedef void (*Ecore_Pipe_Cb)(void *data, void *buffer, unsigned int nbyte);
+
+/**
+ * @brief Create two file descriptors (sockets on Windows).
+ *
+ * @details Add a callback that will be called when the file descriptor that
+ * is listened receives data. An event is also put in the event
+ * queue when data is received.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] handler The handler called when data is received.
+ * @param[in] data Data to pass to @p handler when it is called.
+ * @return A newly created Ecore_Pipe object if successful.
+ * @c NULL otherwise.
+ */
+EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data);
+
+/**
+ * @brief Free an Ecore_Pipe object created with ecore_pipe_add().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object to be freed.
+ * @return The pointer to the private data
+ */
+EAPI void *ecore_pipe_del(Ecore_Pipe *p);
+
+/**
+ * @brief Write on the file descriptor the data passed as parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object.
+ * @param[in] buffer The data to write into the pipe.
+ * @param[in] nbytes The size of the @p buffer in bytes
+ * @return #EINA_TRUE on a successful write, @c EINA_FALSE on error.
+ */
+EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes);
+
+/**
+ * @brief Close the write end of an Ecore_Pipe object created with ecore_pipe_add().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object.
+ */
+EAPI void ecore_pipe_write_close(Ecore_Pipe *p);
+
+/**
+ * @brief Close the read end of an Ecore_Pipe object created with
+ * ecore_pipe_add().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object.
+ */
+EAPI void ecore_pipe_read_close(Ecore_Pipe *p);
+
+/**
+ * @brief Start monitoring again the pipe for reading. See ecore_pipe_freeze()
+ * for stopping the monitoring activity. This will not work if
+ * ecore_pipe_read_close() was previously called on the same pipe.
+ *
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object.
+ */
+EAPI void ecore_pipe_thaw(Ecore_Pipe *p);
+
+/**
+ * @brief Stop monitoring if necessary the pipe for reading.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] p The Ecore_Pipe object.
+ *
+ * @see ecore_pipe_thaw() for monitoring it again.
+ *
+ */
+EAPI void ecore_pipe_freeze(Ecore_Pipe *p);
+
+/**
+ * @brief Wait from another thread on the read side of a pipe.
+ * @since 1.1
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Negative value for @p wait means infite wait.
+ *
+ * @param[in] p The pipe to watch on.
+ * @param[in] message_count The minimal number of message to wait before exiting.
+ * @param[in] wait The amount of time in second to wait before exiting.
+ * @return the number of message catched during that wait call.
+ *
+ */
+EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait);
+
+/**
+ * @}
+ */
+
+/**
+ * @internal
+ * @defgroup Ecore_Throttle_Group Ecore Throttle
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @{
+ */
+
+/**
+ * @brief Increase throttle amount
+ *
+ * @details This will increase or decrease (if @p amount is positive or negative) the
+ * amount of "voluntary throttling" ecore will do to its main loop while
+ * running. This is intended to be used to limit animations and wakeups when
+ * in a strict power management state. The higher the current throttle value
+ * (which can be retrieved by ecore_throttle_get() ), the more throttling
+ * takes place. If the current throttle value is 0, then no throttling takes
+ * place at all.
+ *
+ * @remarks The value represents how long the ecore main loop will sleep (in seconds)
+ * before it goes into a fully idle state waiting for events, input or
+ * timing events to wake it up. For example, if the current throttle level
+ * is 0.5, then after every time the main loop cycles and goes into idle
+ * affter processing all events, the main loop will explicitly sleep for 0.5
+ * seconds before sitting and waiting for incoming events or timeouts, thus
+ * preventing animation, async IO and network handling etc. for that period
+ * of time. Of course these events, data and timeouts will be buffered,
+ * thus not losing anything, simply delaying when they get handled by the
+ * throttle value.
+ *
+ * Example:
+ * @code
+ * void enter_powersave(void) {
+ * ecore_throttle_adjust(0.2);
+ * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
+ * }
+ *
+ * void enter_deep_powersave(void) {
+ * ecore_throttle_adjust(0.5);
+ * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
+ * }
+ *
+ * void exit_powersave(void) {
+ * ecore_throttle_adjust(-0.2);
+ * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
+ * }
+ *
+ * void exit_deep_powersave(void) {
+ * ecore_throttle_adjust(-0.5);
+ * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
+ * }
+ * @endcode
+ *
+ * @param[in] amount Amount (in seconds) to adjust by
+ */
+
+EAPI void ecore_throttle_adjust(double amount);
+
+/**
+ * @brief Get current throttle level
+ *
+ * @remarks This gets the current throttling level, which can be adjusted by
+ * ecore_throttle_adjust(). The value is in seconds.
+ *
+ * @return The current throttle level
+ *
+ * @see ecore_throttle_adjust() for more information.
+ *
+ */
+EAPI double ecore_throttle_get(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Poller_Group Ecore Poller
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief Ecore poller provides infrastructure for the creation of pollers.
+ *
+ * Pollers are, in essence, callbacks that share a single timer per type. Because not
+ * all pollers need to be called at the same frequency the user may specify the
+ * frequency in ticks(each expiration of the shared timer is called a tick, in
+ * ecore poller parlance) for each added poller. Ecore pollers should only be
+ * used when the poller doesn't have specific requirements on the exact times
+ * to poll.
+ *
+ * This architecture means that the main loop is only woken up once to handle
+ * all pollers of that type, this saves power as the CPU has more of a
+ * chance to go into a low power state the longer it is asleep, so this
+ * should be used in situations where power usage is a concern.
+ *
+ * For now only 1 core poller type is supported: @c ECORE_POLLER_CORE.
+ * The default interval for @c ECORE_POLLER_CORE is @c 0.125(or 1/8th) second.
+ *
+ * The creation of a poller is extremely simple and only requires one line:
+ * @code
+ * ecore_poller_add(ECORE_POLLER_CORE, 1, my_poller_function, NULL);
+ * @endcode
+ * This sample creates a poller to call @a my_poller_function at every tick with
+ * @c NULL as data.
+ *
+ * @{
+ */
+
+/**
+ * @enum _Ecore_Poller_Type
+ * @brief Enumeration that defines the frequency of ticks for the poller.
+ */
+enum _Ecore_Poller_Type /* Poller types */
+{
+ ECORE_POLLER_CORE = 0, /**< The core poller interval */
+#ifdef __linux
+ ECORE_POLLER_LAZY = 1, /**< Core poller based on timerfd,
+ timer is deferrable in case the kernel supports it (no fire at IDLE time) */
#endif
+ ECORE_POLLER_TYPE_MAX
+};
+
+/**
+ * @brief typedef to enum _Ecore_Poller_Type
+ */
+typedef enum _Ecore_Poller_Type Ecore_Poller_Type;
+
+typedef struct _Ecore_Poller Ecore_Poller; /**< @brief A handle for pollers */
+
+/**
+ * @brief Sets the time(in seconds) between ticks for the given poller type.
+ *
+ * @details This adjusts the time between ticks of the given timer type defined by
+ * @a type to the time period defined by @a poll_time.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] type The poller type to adjust
+ * @param[in] poll_time The time(in seconds) between ticks of the timer
+ *
+ */
+EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time);
+
+/**
+ * @brief Gets the time(in seconds) between ticks for the given poller type.
+ *
+ * @details This gets the time between ticks of the specified poller timer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] type The poller type to query
+ * @return The time in seconds between ticks of the poller timer
+ *
+ */
+EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type);
+
+/**
+ * @brief Changes the polling interval rate of @a poller.
+ *
+ * @details This allows the changing of a poller's polling interval. It is useful when
+ * you want to alter a poll rate without deleting and re-creating a poller.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] poller The Ecore_Poller to change the interval of
+ * @param[in] interval The tick interval to set, must be a power of 2 and <= 32768
+ * @return @c true on success, otherwise @c false on failure
+ *
+ */
+EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *poller, int interval);
+
+/**
+ * @brief Gets the polling interval rate of @a poller.
+ *
+ * @details This returns a poller's polling interval, otherwise @c 0 on error.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] poller The Ecore_Poller to change the interval of
+ * @return The interval, in ticks, that @a poller polls at
+ *
+ */
+EAPI int ecore_poller_poller_interval_get(Ecore_Poller *poller);
+
+/**
+ * @brief Creates a poller to call the given function at a particular tick interval.
+ *
+ * @details This function adds @a func as a poller callback that is called every @a
+ * interval ticks together with other pollers of type @a type. @a func is
+ * passed the @a data pointer as a parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The @a interval must be between @c 1 and @c 32768 inclusive, and must be a power of
+ * @c 2 (i.e. 1, 2, 4, 8, 16, ... 16384, 32768). The exact tick in which @a func
+ * is called is undefined, as only the interval between calls can be
+ * defined. Ecore endeavors to keep pollers synchronized and calls as
+ * many in 1 wakeup event as possible. If @a interval is not a power of @c 2, the
+ * closest power of @c 2 greater than @a interval is used.
+ *
+ * @remarks When the poller @a func is called, it must return a value of either
+ * @c ECORE_CALLBACK_RENEW(or @c 1) or @c ECORE_CALLBACK_CANCEL(or @c 0). If it
+ * returns @c 1, it is called again at the next tick, or if it returns
+ * @c 0 it is deleted automatically making any references/handles for it
+ * invalid.
+ *
+ * @param[in] type The ticker type to attach the poller to \n
+ * Must be @c ECORE_POLLER_CORE.
+ * @param[in] interval The poll interval
+ * @param[in] func The poller function
+ * @param[in] data The data to pass to @a func when it is called
+ * @return A poller object on success,
+ * otherwise @c NULL on failure
+ *
+ */
+EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Deletes the specified poller from the timer list.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a poller must be a valid handle. If the poller function has already
+ * returned @c 0, the handle is no longer valid (and does not need to be deleted).
+ *
+ * @param[in] poller The poller to delete
+ * @return The data pointer set for the timer when @ref ecore_poller_add is called on success,
+ * otherwise @c NULL on failure
+ */
+EAPI void *ecore_poller_del(Ecore_Poller *poller);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Animator_Group Ecore Animator
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief Ecore animators are a helper to simplify creating animations.
+ *
+ * Creating an animation is as simple as saying for how long it
+ * should be run and having a callback that does the animation,
+ * something like this:
+ * @code
+ * static Eina_Bool
+ * _do_animation(void *data, double pos)
+ * {
+ * evas_object_move(data, 100 * pos, 100 * pos);
+ * ... do some more animating ...
+ * }
+ * ...
+ * ecore_animator_timeline_add(2, _do_animation, my_evas_object);
+ * @endcode
+ *
+ * In the sample above we create an animation to move
+ * @c my_evas_object from position (0,0) to (100,100) in @c 2 seconds.
+ *
+ * If your animation runs for an unspecified amount of time you
+ * can use ecore_animator_add(), which is like using
+ * ecore_timer_add() with the interval being the
+ * @ref ecore_animator_frametime_set "framerate". Note that this has
+ * tangible benefits of creating a timer for each animation in terms
+ * of performance.
+ *
+ * @{
+ */
+
+/**
+ * @brief handle for ecore animator.
+ */
+typedef struct _Ecore_Animator Ecore_Animator;
+
+/**
+ * @enum _Ecore_Pos_Map
+ * @brief Enumeration that defines the position mappings for the animation.
+ */
+enum _Ecore_Pos_Map /* Position mappings */
+{
+ ECORE_POS_MAP_LINEAR, /**< Linear 0.0 -> 1.0 */
+ ECORE_POS_MAP_ACCELERATE, /**< Start slow then speed up */
+ ECORE_POS_MAP_DECELERATE, /**< Start fast then slow down */
+ ECORE_POS_MAP_SINUSOIDAL, /**< Start slow, speed up then slow down at the end */
+ ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal accelerate, @c 2.0 being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on */
+ ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal decelerate, @c 2.0 being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on */
+ ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal sinusoidal, @c 2.0 being much more pronounced sinusoidal (squared), @c 3.0 being cubed, and so on */
+ ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via power of v2 curve */
+ ECORE_POS_MAP_BOUNCE, /**< Start at @c 0.0 then "drop" like a ball bouncing to the ground at @c 1.0, and bounce v2 times, with decay factor of v1 */
+ ECORE_POS_MAP_SPRING /**< Start at @c 0.0 then "wobble" like a spring with rest position @c 1.0, and wobble v2 times, with decay factor of v1 */
+};
+
+/**
+ * @brief typedef to enum _Ecore_Pos_Map
+ */
+typedef enum _Ecore_Pos_Map Ecore_Pos_Map;
+
+/**
+ * @enum _Ecore_Animator_Source
+ * @brief Enumeration that defines the timing sources for animators.
+ */
+enum _Ecore_Animator_Source /* Timing sources for animators */
+{
+ ECORE_ANIMATOR_SOURCE_TIMER, /**< The default system clock/timer based animator that ticks every "frametime" seconds */
+ ECORE_ANIMATOR_SOURCE_CUSTOM /**< A custom animator trigger which ticks when you call ecore_animator_trigger() */
+};
+
+/**
+ * @brief typedef to enum _Ecore_Animator_Source
+ */
+typedef enum _Ecore_Animator_Source Ecore_Animator_Source;
+
+/**
+ * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb
+ * @brief The boolean type for a callback run for a task (animators with runtimes)
+ */
+typedef Eina_Bool (*Ecore_Timeline_Cb)(void *data, double pos);
+
+/**
+ * @brief Adds an animator to call @a func at every animation tick during main
+ * loop execution.
+ *
+ * @details This function adds an animator and returns its handle on success, and @c NULL
+ * on failure. The function @a func is called every N seconds where N is
+ * the @a frametime interval set by ecore_animator_frametime_set(). The
+ * function is passed the @a data pointer as its parameter.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When the animator @a func is called, it must return a value of either @c 1 or
+ * @c 0. If it returns @c 1 (or @c ECORE_CALLBACK_RENEW), it is called again at
+ * the next tick, or if it returns @c 0 (or @c ECORE_CALLBACK_CANCEL) it is
+ * deleted automatically making any references/handles for it invalid.
+ *
+ * @remarks The default @a frametime value is 1/30th of a second.
+ *
+ * @param[in] func The function to call when it ticks off
+ * @param[in] data The data to pass to the function
+ * @return A handle to the new animator
+ *
+ * @see ecore_animator_timeline_add()
+ * @see ecore_animator_frametime_set()
+ */
+EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data);
+
+/**
+ * @brief Adds an animator that runs for a limited time.
+ *
+ * @details This function is just like ecore_animator_add() except that the animator only
+ * runs for a limited time specified in seconds by @a runtime. Once the
+ * runtime of the animator has elapsed (animator finished) it is automatically
+ * deleted. The callback function @a func can return @c ECORE_CALLBACK_RENEW
+ * to keep the animator running or @c ECORE_CALLBACK_CANCEL to stop it and have
+ * it deleted automatically at any time.
+ *
+ * @since 1.1.0
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The @a func is ALSO passed a position parameter that has a value
+ * from @c 0.0 to @c 1.0 to indicate where along the timeline (@c 0.0 for start, @c 1.0 for end)
+ * is the animator run at. If the callback wishes not to have a linear
+ * transition it can "map" this value to one of the several curves and mappings
+ * via ecore_animator_pos_map().
+ *
+ * @remarks The default @a frametime value is 1/30th of a second.
+ *
+ * @param[in] runtime The time to run in seconds
+ * @param[in] func The function to call when it ticks off
+ * @param[in] data The data to pass to the function
+ * @return A handle to the new animator
+ *
+ * @see ecore_animator_add()
+ * @see ecore_animator_pos_map()
+ */
+EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data);
+
+/**
+ * @brief Deletes the specified animator from the animator list.
+ *
+ * @details This deletes the specified @a animator from the set of animators that are
+ * executed during main loop execution. This function returns the data
+ * parameter that is being passed to the callback on success, otherwise @c NULL on
+ * failure. After this call returns the specified animator object @a animator
+ * is invalid and should not be used again. It does not get called again after
+ * deletion.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] animator The animator to delete
+ * @return The data pointer set for the animator on add
+ *
+ */
+EAPI void *ecore_animator_del(Ecore_Animator *animator);
+
+/**
+ * @brief Suspends the specified animator.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The specified @a animator is temporarily removed from the set of
+ * animators that are executed during the main loop.
+ *
+ * @remarks Freezing an animator doesn't freeze accounting of how long that
+ * animator has been running. Therefore if the animator is created with
+ * ecore_animator_timeline_add() the @a pos argument given to the callback
+ * increases as if the animator hadn't been frozen and the animator may
+ * have its execution halted if @a runtime elapses.
+ *
+ * @param[in] animator The animator to delete
+ *
+ */
+EAPI void ecore_animator_freeze(Ecore_Animator *animator);
+
+/**
+ * @brief Restores execution of the specified animator.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The specified @a animator is put back in the set of animators that are
+ * executed during the main loop.
+ *
+ * @param[in] animator The animator to delete
+ *
+ */
+EAPI void ecore_animator_thaw(Ecore_Animator *animator);
+
+/**
+ * @brief Sets the animator call interval in seconds.
+ *
+ * @details This function sets the time interval (in seconds) between animator ticks.
+ * At every tick the callback of every existing animator is called.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Too small a value may cause performance issues and too high a
+ * value may cause your animation to look "jerky".
+ *
+ * @remarks The default @a frametime value is 1/30th of a second.
+ *
+ * @param[in] frametime The time in seconds between animator ticks
+ *
+ */
+EAPI void ecore_animator_frametime_set(double frametime);
+
+/**
+ * @brief Gets the animator call interval in seconds.
+ *
+ * @details This function retrieves the time in seconds between animator ticks.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The time in seconds between animator ticks
+ *
+ * @see ecore_animator_frametime_set()
+ */
+EAPI double ecore_animator_frametime_get(void);
+
+/**
+ * @brief Maps an input position from @c 0.0 to @c 1.0 along a timeline to a
+ * position in a different curve.
+ *
+ * @details This takes an input position (@c 0.0 to @c 1.0) and maps it to a new position (normally
+ * between @c 0.0 and @c 1.0, but it may go above/below @c 0.0 or @c 1.0 to show that it
+ * has "overshot" the mark) using some interpolation (mapping) algorithm.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is useful to create non-linear animations. It offers a variety
+ * of possible animation curves to be used:
+ * @li ECORE_POS_MAP_LINEAR - Linear, returns @a pos.
+ * @li ECORE_POS_MAP_ACCELERATE - Start slow then speed up.
+ * @li ECORE_POS_MAP_DECELERATE - Start fast then slow down.
+ * @li ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at the end.
+ * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a
+ * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_ACCELERATE, @c 2.0
+ * being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on.
+ * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a
+ * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_DECELERATE, @c 2.0
+ * being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on.
+ * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down
+ * at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being
+ * @c ECORE_POS_MAP_SINUSOIDAL, @c 2.0 being much more pronounced sinusoidal
+ * (squared), @c 3.0 being cubed, and so on.
+ * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via
+ * power of v2 curve.
+ * @li ECORE_POS_MAP_BOUNCE - Start at @c 0.0 then "drop" like a ball bouncing to
+ * the ground at @c 1.0, and bounce v2 times, with decay factor of v1.
+ * @li ECORE_POS_MAP_SPRING - Start at @c 0.0 then "wobble" like a spring with rest
+ * position @c 1.0, and wobble v2 times, with decay factor of v1
+ * @remarks When not listed v1 and v2 have no effect.
+ *
+ * @image html ecore-pos-map.png
+ * @image latex ecore-pos-map.eps "ecore pos map" width=\textwidth
+ *
+ * @remarks One way to use this would be:
+ * @code
+ * double pos; // input position in a timeline from 0.0 to 1.0
+ * double out; // output position after mapping
+ * int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position
+ * int x, y; // x & y are the calculated position
+ *
+ * out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
+ * x = (x1 * out) + (x2 * (1.0 - out));
+ * y = (y1 * out) + (y2 * (1.0 - out));
+ * move_my_object_to(myobject, x, y);
+ * @endcode
+ * This makes an animation that bounces @c 7 diminish each time by a
+ * factor of @c 1.8.
+ *
+ * @param[in] pos The input position to map
+ * @param[in] map The mapping to use
+ * @param[in] v1 A parameter used by the mapping (pass @c 0.0 if not used)
+ * @param[in] v2 A parameter used by the mapping (pass @c 0.0 if not used)
+ * @return The mapped value
+ *
+ * @see _Ecore_Pos_Map
+ *
+ * @since 1.1.0
+ */
+EAPI double ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2);
+
+/**
+ * @brief Sets the source of the animator ticks for the mainloop.
+ *
+ * @details This sets the source of the animator ticks. When an animator is active the
+ * mainloop will "tick" over frame by frame calling all animators that are
+ * registered until none are left. The mainloop ticks at a given rate based
+ * on the animator source. The default source is the system clock timer
+ * source - @c ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock
+ * to tick over every N seconds (specified by ecore_animator_frametime_set(),
+ * with the default being 1/30th of a second unless set otherwise). You can
+ * set a custom tick source by setting the source to
+ * @c ECORE_ANIMATOR_SOURCE_CUSTOM and then driving it yourself based on some input
+ * tick source (like another application via ipc, some vertical blanking
+ * interrupt and so on) using ecore_animator_custom_source_tick_begin_callback_set() and
+ * ecore_animator_custom_source_tick_end_callback_set() to set the functions
+ * that are called to start and stop the ticking source, which when
+ * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over @c 1
+ * frame.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] source The source of the animator ticks to use
+ *
+ */
+EAPI void ecore_animator_source_set(Ecore_Animator_Source source);
+
+/**
+ * @brief Gets the animator source currently set.
+ *
+ * @details This gets the current animator source.
+ *
+ * @since_tizen 2.3
+ *
+ * @return The current animator source
+ *
+ * @see ecore_animator_source_set()
+ */
+EAPI Ecore_Animator_Source ecore_animator_source_get(void);
+
+/**
+ * @brief Sets the function that begins a custom animator tick source.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The Ecore Animator infrastructure handles tracking of whether animators are needed
+ * and which ones need to be called and when, but when the tick source
+ * is custom, you have to provide a tick source by calling
+ * ecore_animator_custom_tick() to indicate that a frame tick happened. In order
+ * to allow the source of ticks to be dynamically enabled or disabled as
+ * needed, @a func when set is called to enable the tick source to
+ * produce tick events that call ecore_animator_custom_tick(). If @a func
+ * is @c NULL then no function is called to begin custom ticking.
+ *
+ * @param[in] func The function to call when ticking is to begin
+ * @param[in] data The data passed to the tick begin function as its parameter
+ *
+ * @see ecore_animator_source_set()
+ * @see ecore_animator_custom_source_tick_end_callback_set()
+ * @see ecore_animator_custom_tick()
+ */
+EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data);
+
+/**
+ * @brief Sets the function that ends a custom animator tick source.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is a matching pair to the function set by
+ * ecore_animator_custom_source_tick_begin_callback_set() and is called
+ * when ticking is to stop. If @a func is @c NULL then no function is
+ * called to stop ticking. For more information see
+ * ecore_animator_custom_source_tick_begin_callback_set().
+ *
+ * @param[in] func The function to call when ticking is to end
+ * @param[in] data The data passed to the tick end function as its parameter
+ *
+ * @see ecore_animator_source_set()
+ * @see ecore_animator_custom_source_tick_begin_callback_set()
+ * @see ecore_animator_custom_tick()
+ */
+EAPI void ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data);
+
+/**
+ * @brief Triggers a custom animator tick.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When animator source is set to @c ECORE_ANIMATOR_SOURCE_CUSTOM, then calling
+ * this function triggers a run of all animators currently registered with
+ * Ecore as this indicates that a "frame tick" happened. This does nothing if
+ * the animator source(set by ecore_animator_source_set()) is not set to
+ * @c ECORE_ANIMATOR_SOURCE_CUSTOM.
+ *
+ * @see ecore_animator_source_set()
+ * @see ecore_animator_custom_source_tick_begin_callback_set
+ * @see ecore_animator_custom_source_tick_end_callback_set()()
+ */
+EAPI void ecore_animator_custom_tick(void);
+
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ecore_Job_Group Ecore Job
+ * @ingroup Ecore_Main_Loop_Group
+ *
+ * @brief You can queue jobs that are to be done by the main loop when the
+ * current event is dealt with.
+ *
+ * Jobs are processed by the main loop in a manner which is similar to events. They
+ * are also executed in the order in which they are added.
+ *
+ * A good use for them is when you don't want to execute an action
+ * immediately, but want to give the control back to the main loop
+ * so that it calls your job callback when jobs start being
+ * processed (and if there are other jobs added before yours, they
+ * are processed first). This also gives a chance to other
+ * actions in your program to cancel the job before it is started.
+ *
+ * @{
+ */
+
+typedef struct _Ecore_Job Ecore_Job; /**< @brief A job handle */
+
+/**
+ * @brief Add a job to the event queue.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Once the job has been executed, the job handle is invalid.
+ *
+ * @param[in] func The function to call when the job gets handled.
+ * @param[in] data Data pointer to be passed to the job function when the job is
+ * handled.
+ * @return The handle of the job. @c NULL is returned if the job could not be
+ * added to the queue.
+ */
+EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data);
+
+/**
+ * @brief Delete a queued job that has not yet been executed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] job Handle of the job to delete.
+ * @return The data pointer that was to be passed to the job.
+ */
+EAPI void *ecore_job_del(Ecore_Job *job);
+
+/**
+ * @}
+ */
#ifdef __cplusplus
}
diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h
index a20cc98e02..33661e4e90 100644
--- a/src/lib/ecore/Ecore_Getopt.h
+++ b/src/lib/ecore/Ecore_Getopt.h
@@ -31,168 +31,121 @@
#endif /* ! _WIN32 */
/**
- * @defgroup Ecore_Getopt_Group Ecore Getopt
- * @ingroup Ecore
- *
- * This group contains powerful getopt replacement.
+ * @internal
+ * @file Ecore_Getopt.h
+ * @brief Contains powerful getopt replacement.
*
* This replacement handles both short (-X) or long options (--ABC)
* options, with various actions supported, like storing one value and
* already converting to required type, counting number of
- * occurrences, setting true or false values, show help, license,
- * copyright and even support user-defined callbacks.
+ * occurrences, setting true or false values, showing help, license,
+ * copyright, and even supporting user-defined callbacks.
*
- * It is provided a set of C Pre Processor macros so definition is
+ * It is provided a set of C Pre Processor macros. So definition is
* straightforward.
*
- * Values will be stored elsewhere indicated by an array of pointers
- * to values, it is given in separate to parser description so you can
+ * Values are stored elsewhere indicated by an array of pointers
+ * to values. It is given separately 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, /**< 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_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;
-/**
- * @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, /**< 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_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;
-/**
- * @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, /**< 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_NO = 0,
+ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1,
+ ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3
} Ecore_Getopt_Desc_Arg_Requirement;
+typedef union _Ecore_Getopt_Value Ecore_Getopt_Value;
+
typedef struct _Ecore_Getopt_Desc_Store Ecore_Getopt_Desc_Store;
typedef struct _Ecore_Getopt_Desc_Callback Ecore_Getopt_Desc_Callback;
+typedef struct _Ecore_Getopt_Desc Ecore_Getopt_Desc;
+typedef struct _Ecore_Getopt Ecore_Getopt;
-#ifndef _ECORE_GETOPT_PREDEF
-typedef struct _Ecore_Getopt Ecore_Getopt;
-#define _ECORE_GETOPT_PREDEF 1
-#endif
-#ifndef _ECORE_GETOPT_DESC_PREDEF
-typedef struct _Ecore_Getopt_Desc Ecore_Getopt_Desc;
-#define _ECORE_GETOPT_DESC_PREDEF 1
-#endif
-#ifndef _ECORE_GETOPT_VALUE_PREDEF
-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; /**< 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 */
+ 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;
};
-/**
- * @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; /**< option argument requirement */
+ Ecore_Getopt_Type type; /**< Type of data being handled */
+ Ecore_Getopt_Desc_Arg_Requirement arg_req;
union
{
- 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 */
+ const char *strv;
+ Eina_Bool boolv;
+ short shortv;
+ int intv;
+ long longv;
+ unsigned short ushortv;
+ unsigned int uintv;
+ unsigned long ulongv;
+ double doublev;
+ } def;
};
-/**
- * @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); /**< 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 */
+ Ecore_Getopt_Value *storage);
+ const void *data;
+ Ecore_Getopt_Desc_Arg_Requirement arg_req;
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 */
- const char *longname; /**< used with double dashes */
- const char *help; /**< used by --help/ecore_getopt_help() */
- const char *metavar; /**< used by ecore_getopt_help() with nargs > 0 */
+ char shortname; /**< Used with a single dash */
+ const char *longname; /**< Used with double dashes */
+ const char *help; /**< Used by -- help/ecore_getopt_help() */
+ const char *metavar; /**< Used by ecore_getopt_help() with nargs > 0 */
- Ecore_Getopt_Action action; /**< define how to handle it */
+ Ecore_Getopt_Action action; /**< Define how to handle it */
union
{
const Ecore_Getopt_Desc_Store store;
@@ -201,1018 +154,267 @@ struct _Ecore_Getopt_Desc
const Ecore_Getopt_Type append_type;
const Ecore_Getopt_Desc_Callback callback;
const void *dummy;
- } action_param; /**< Action parameter */
+ } action_param;
};
-/**
- * @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 */
- const char *usage; /**< usage example, %prog is replaced */
- const char *version; /**< if exists, --version will work */
- const char *copyright; /**< if exists, --copyright will work */
- 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[]; /**< A table that contains the description of all the other options (NULL terminated).*/
-
+ const char *prog; /**< To be used when ecore_app_args_get() fails */
+ const char *usage; /**< Usage example, %prog is replaced */
+ const char *version; /**< If exists, --version works */
+ const char *copyright; /**< If exists, --copyright works */
+ const char *license; /**< If exists, --license works */
+ const char *description; /**< Long description, possible multiline */
+ Eina_Bool strict : 1; /**< Fail on errors */
+ const Ecore_Getopt_Desc descs[]; /**< @c 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, \
+#define ECORE_GETOPT_HELP(shortname, longname) \
+ {shortname, longname, "show this message.", NULL, \
+ 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, \
- {.dummy = NULL}}
-
-#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 info The structure containing information about command line options.
- *
- * @see ecore_getopt_help_category()
- */
-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 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.
- *
- * @see ecore_getopt_help()
- */
-EAPI Eina_Bool ecore_getopt_help_category(FILE *fp, const Ecore_Getopt *info, const char *category);
-
-/**
- * Check parser for duplicate entries, print them out.
- *
- * @return @c EINA_TRUE if there are duplicates, @c EINA_FALSE otherwise.
- * @param parser The parser to be checked.
- */
-EAPI Eina_Bool ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser);
-
-/**
- * Parse command line parameters.
- *
- * Walks the command line parameters and parse them based on @a parser
- * description, doing actions based on @c parser->descs->action, like
- * showing help text, license, copyright, storing values in values and
- * so on.
- *
- * It is expected that values is of the same size than @c parser->descs,
- * options that do not need a value it will be left untouched.
- *
- * All values are expected to be initialized before use. Options with
- * action @c ECORE_GETOPT_ACTION_STORE and non required arguments
- * (others than @c ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES), are expected
- * to provide a value in @c def to be used.
- *
- * The following actions will store @c 1 on value as a boolean
- * (@c value->boolp) if it's not @c NULL to indicate these actions were
- * executed:
- * - @c ECORE_GETOPT_ACTION_HELP
- * - @c ECORE_GETOPT_ACTION_VERSION
- * - @c ECORE_GETOPT_ACTION_COPYRIGHT
- * - @c ECORE_GETOPT_ACTION_LICENSE
- *
- * Just @c ECORE_GETOPT_ACTION_APPEND will allocate memory and thus
- * need to be freed. For consistency between all of appended subtypes,
- * @c eina_list->data will contain an allocated memory with the value,
- * that is, for @c ECORE_GETOPT_TYPE_STR it will contain a copy of the
- * argument, @c ECORE_GETOPT_TYPE_INT a pointer to an allocated
- * integer and so on.
- *
- * If parser is in strict mode (see @c Ecore_Getopt->strict), then any
- * error will abort parsing and @c -1 is returned. Otherwise it will try
- * to continue as far as possible.
- *
- * This function may reorder @a argv elements.
- *
- * Translation of help strings (description), metavar, usage, license
- * and copyright may be translated, standard/global gettext() call
- * will be applied on them if ecore was compiled with such support.
- *
- * This function will @b not parse positional arguments! If these are
- * declared (metavar is defined with both shortname and longname being
- * empty), then you must call ecore_getopt_parse_positional() with the
- * last argument (@c start) being the result of this function. This is
- * done so you can have "quit options", those that once called you
- * want to exit without doing further parsing, as is the case with
- * help, license, copyright, version and eventually others you may
- * define.
- *
- * @param parser description of how to work.
- * @param values where to store values, it is assumed that this is a vector
- * of the same size as @c parser->descs. Values should be previously
- * initialized.
- * @param argc how many elements in @a argv. If not provided it will be
- * retrieved with ecore_app_args_get().
- * @param argv command line parameters.
- *
- * @return index of first non-option parameter or -1 on error.
- *
- * @see ecore_getopt_parse_positional()
- */
-EAPI int ecore_getopt_parse(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv);
-
-/**
- * Parse command line positional parameters.
- *
- * Walks the command line positional parameters (those that do not
- * start with "-" or "--") and parse them based on @a parser
- * description, doing actions based on @c parser->descs->action, like
- * storing values of some type.
- *
- * It is expected that @a values is of the same size than @c
- * parser->descs, same as with ecore_getopt_parse().
- *
- * All values are expected to be initialized before use.
- *
- * Unlike the ecore_getopt_parse(), only the following options are
- * supported:
- * - @c ECORE_GETOPT_ACTION_STORE
- * - @c ECORE_GETOPT_ACTION_CHOICE
- * - @c ECORE_GETOPT_ACTION_APPEND
- * - @c ECORE_GETOPT_ACTION_CALLBACK
- *
- * There is a special case for @c ECORE_GETOPT_ACTION_APPEND as it
- * will consume all remaining elements. It is also special in the
- * sense that it will allocate memory and thus need to be freed. For
- * consistency between all of appended subtypes, @c eina_list->data
- * will contain an allocated memory with the value, that is, for @c
- * ECORE_GETOPT_TYPE_STR it will contain a copy of the argument, @c
- * ECORE_GETOPT_TYPE_INT a pointer to an allocated integer and so on.
- *
- * If parser is in strict mode (see @c Ecore_Getopt->strict), then any
- * error will abort parsing and @c -1 is returned. Otherwise it will try
- * to continue as far as possible.
- *
- * Translation of help strings (description) and metavar may be done,
- * standard/global gettext() call will be applied on them if ecore was
- * compiled with such support.
- *
- * @param parser description of how to work.
- * @param values where to store values, it is assumed that this is a vector
- * of the same size as @c parser->descs. Values should be previously
- * initialized.
- * @param argc how many elements in @a argv. If not provided it will be
- * retrieved with ecore_app_args_get().
- * @param argv command line parameters.
- * @param start the initial position argument to look at, usually the
- * return of ecore_getopt_parse(). If less than 1, will try to
- * find it automatically.
- *
- * @return index of first non-option parameter or -1 on error. If the
- * last positional argument is of action @c
- * ECORE_GETOPT_ACTION_APPEND then it will be the same as @a argc.
- */
-EAPI int ecore_getopt_parse_positional(const Ecore_Getopt *parser, Ecore_Getopt_Value *values, int argc, char **argv, int start);
+EAPI void
+ecore_getopt_help(FILE *fp,
+ const Ecore_Getopt *info);
+EAPI Eina_Bool
+ ecore_getopt_parser_has_duplicates(const Ecore_Getopt *parser);
+EAPI int
+ ecore_getopt_parse(const Ecore_Getopt *parser,
+ Ecore_Getopt_Value *values,
+ int argc,
+ char **argv);
-/**
- * Utility to free list and nodes allocated by @a ECORE_GETOPT_ACTION_APPEND.
- *
- * @param list pointer to list to be freed.
- * @return always @c NULL, so you can easily make your list head @c NULL.
- */
EAPI Eina_List *ecore_getopt_list_free(Eina_List *list);
-/**
- * Helper ecore_getopt callback to parse geometry (x:y:w:h).
- *
- * @param parser This parameter isn't in use.
- * @param desc This parameter isn't in use.
- * @param str Geometry value
- * @param data This parameter isn't in use.
- * @param storage must be a pointer to @c Eina_Rectangle and will be used to
- * store the four values passed in the given string.
- * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect geometry value.
- *
- * This is a helper functions to be used with ECORE_GETOPT_CALLBACK_*().
- *
- * @c callback_data value is ignored, you can safely use @c NULL.
- */
-EAPI Eina_Bool ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage);
-
-/**
- * Helper ecore_getopt callback to parse geometry size (WxH).
- *
- * @param parser This parameter isn't in use.
- * @param desc This parameter isn't in use.
- * @param str size value
- * @param data This parameter isn't in use.
- * @param storage must be a pointer to @c Eina_Rectangle and will be used to
- * store the two values passed in the given string and @c 0 in the x and y
- * fields.
- * @return @c EINA_TRUE on success, @c EINA_FALSE on incorrect size value.
- *
- * @c callback_data value is ignored, you can safely use @c NULL.
- */
-EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage);
+/* Helper functions to be used with ECORE_GETOPT_CALLBACK_*() */
+EAPI Eina_Bool
+ecore_getopt_callback_geometry_parse(const Ecore_Getopt *parser,
+ const Ecore_Getopt_Desc *desc,
+ const char *str,
+ void *data,
+ Ecore_Getopt_Value *storage);
+EAPI Eina_Bool
+ecore_getopt_callback_size_parse(const Ecore_Getopt *parser,
+ const Ecore_Getopt_Desc *desc,
+ const char *str,
+ void *data,
+ Ecore_Getopt_Value *storage);
#ifdef __cplusplus
}
#endif
-
-/**
- * @}
- */
-
#endif /* _ECORE_GETOPT_H */
diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h
index 6cfea2eff3..a299c033a4 100644
--- a/src/lib/ecore_con/Ecore_Con.h
+++ b/src/lib/ecore_con/Ecore_Con.h
@@ -9,7 +9,6 @@
# include <netdb.h>
#endif
#include <Eina.h>
-#include <Eo.h>
#ifdef EAPI
# undef EAPI
@@ -38,12 +37,13 @@
#endif
/**
+ * @internal
* @defgroup Ecore_Con_Group Ecore_Con - Connection functions
- * @ingroup Ecore
+ * @ingroup Ecore_Group
*
* The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
- * for communications between programs using reliable sockets. It saves
- * the programmer from having to worry about file descriptors and waiting
+ * for communications between programs using reliable sockets. It saves
+ * you from having to worry about file descriptors and waiting
* for incoming connections.
*
* There are two main objects in the @c Ecore_Con library: the @c
@@ -70,138 +70,140 @@
/**
+ * @internal
* @defgroup Ecore_Con_Events_Group Ecore Connection Events Functions
* @ingroup Ecore_Con_Group
*
* @li ECORE_CON_CLIENT_ADD: Whenever a client connection is made to an
* @c Ecore_Con_Server, an event of this type is emitted, allowing the
- * retrieval of the client's ip with @ref ecore_con_client_ip_get and
+ * retrieval of the client's IP with @ref ecore_con_client_ip_get and
* associating data with the client using ecore_con_client_data_set.
* @li ECORE_CON_EVENT_CLIENT_DEL: Whenever a client connection to an
- * @c Ecore_Con_Server, an event of this type is emitted. The contents of
+ * @c Ecore_Con_Server, an event of this type is emitted. The contents of
* the data with this event are variable, but if the client object in the data
* is non-null, it must be freed with @ref ecore_con_client_del.
* @li ECORE_CON_EVENT_SERVER_ADD: Whenever a server object is created
* with @ref ecore_con_server_connect, an event of this type is emitted,
* allowing for data to be serialized and sent to the server using
- * @ref ecore_con_server_send. At this point, the http handshake has
+ * @ref ecore_con_server_send. At this point, the HTTP handshake has
* occurred.
* @li ECORE_CON_EVENT_SERVER_DEL: Whenever a server object is destroyed,
* usually by the server connection being refused or dropped, an event of this
- * type is emitted. The contents of the data with this event are variable,
+ * type is emitted. The contents of the data with this event are variable,
* but if the server object in the data is non-null, it must be freed
* with @ref ecore_con_server_del.
* @li ECORE_CON_EVENT_CLIENT_DATA: Whenever a client connects to your server
- * object and sends data, an event of this type is emitted. The data will contain both
- * the size and contents of the message sent by the client. It should be noted that
+ * object and sends data, an event of this type is emitted. The data contains both
+ * the size and contents of the message sent by the client. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
- * retained. This event will continue to occur until the client has stopped sending its
- * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
+ * retained. This event continues to occur until the client has stopped sending its
+ * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the client object must be freed with ecore_con_client_free.
* @li ECORE_CON_EVENT_SERVER_DATA: Whenever your server object connects to its destination
- * and receives data, an event of this type is emitted. The data will contain both
- * the size and contents of the message sent by the server. It should be noted that
+ * and receives data, an event of this type is emitted. The data contains both
+ * the size and contents of the message sent by the server. It should be noted that
* data within this object is transient, so it must be duplicated in order to be
- * retained. This event will continue to occur until the server has stopped sending its
- * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
+ * retained. This event continues to occur until the server has stopped sending its
+ * message, so a good option for storing this data is an Eina_Strbuf. Once the message has
* been received in full, the server object must be freed with ecore_con_server_free.
*
*/
/**
+ * @internal
* @defgroup Ecore_Con_Buffer Ecore Connection Buffering
* @ingroup Ecore_Con_Group
- *
- * As Ecore_Con works on an event driven design, as data arrives, events will
- * be produced containing the data that arrived. It is up to the user of
+ *
+ * As Ecore_Con works on an event driven design, as data arrives, events are
+ * produced containing the data that arrived. It is up to the user of
* Ecore_Con to either parse as they go, append to a file to later parse the
- * whole file in one go, or append to memory to parse or handle later.
- *
- * To help with this Eina has some handy API's. The Eina_Binbuf and
- * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
- * to handle buffers at runtime, without having to manage them. Eina_Binbuf
- * makes it possible to create, expand, reset and slice a blob of memory -
- * all via API. No system calls, no pointer manipulations and no size
+ * whole file in one go, or append to memory to parse or handle leter.
+ *
+ * To help with this, Eina has some handy API's. The Eina_Binbuf and
+ * Eina_Strbuf APIs, abstract dynamic buffer management and make it trivial
+ * to handle buffers at runtime, without having to manage them. Eina_Binbuf
+ * makes it possible to create, expand, reset and slice a blob of memory -
+ * all via API. No system calls, no pointer manipulations and no size
* calculation.
- *
- * Additional functions include adding content at specified byte positions in
- * the buffer, escaping the inputs, find and replace strings. This provides
+ *
+ * Additional functions include adding content at specified byte positions in
+ * the buffer, escaping the inputs, find and replace strings. This provides
* extreme flexibility to play around, with a dynamic blob of memory.
- *
+ *
* It is good to free it (using eina_binbuf_free()) after using it.
- *
+ *
* Eina_Binbuf compliments Ecore_Con use cases, where dynamic sizes of data
* arrive from the network (think http download in chunks). Using
* Eina_Binbuf provides enough flexibility to handle data as it arrives and
* to defer its processing until desired, without having to think about
* where to store the temporary data and how to manage its size.
- *
+ *
* An example of how to use these with Ecore_Con follows.
- *
+ *
* @code
* #include <Eina.h>
* #include <Ecore.h>
* #include <Ecore_Con.h>
- *
+ *
* static Eina_Bool
* data_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Data *url_data = event;
* if ( url_data->size > 0)
* {
- * // append data as it arrives - don't worry where or how it gets stored.
- * // Also don't worry about size, expanding, reallocing etc.
- * // just keep appending - size is automatically handled.
- *
+ * // Append data as it arrives - do not worry where or how it gets stored.
+ * // Also do not worry about size, expanding, reallocing etc.
+ * // Just keep appending - size is automatically handled.
+ *
* eina_binbuf_append_length(data, url_data->data, url_data->size);
- *
+ *
* fprintf(stderr, "Appended %d \n", url_data->size);
* }
* return EINA_TRUE;
* }
- *
- *
- *
+ *
+ *
+ *
* static Eina_Bool
* completion_callback(void *data, int type, void *event)
* {
* Ecore_Con_Event_Url_Complete *url_complete = event;
* printf("download completed with status code: %d\n", url_complete->status);
- *
- * // get the data back from Eina_Binbuf
+ *
+ * // Get the data back from Eina_Binbuf
* char *ptr = eina_binbuf_string_get(data);
* size_t size = eina_binbuf_length_get(data);
- *
- * // process data as required (write to file)
+ *
+ * // Process data as required (write to file)
* fprintf(stderr, "Size of data = %d bytes\n", size);
* int fd = open("./elm.png", O_CREAT);
* write(fd, ptr, size);
* close(fd);
- *
- * // free it when done.
+ *
+ * // Free it when done.
* eina_binbuf_free(data);
- *
+ *
* ecore_main_loop_quit();
- *
+ *
* return EINA_TRUE;
* }
- *
- *
+ *
+ *
* int
* main(int argc, char **argv)
* {
- *
+ *
* const char *url = "http://www.enlightenment.org/p/index/d/logo.png";
- *
+ *
* ecore_init();
* ecore_con_init();
* ecore_con_url_init();
- *
- *
+ *
+ *
* // This is single additional line to manage dynamic network data.
* Eina_Binbuf *data = eina_binbuf_new();
* Ecore_Con_Url *url_con = ecore_con_url_new(url);
- *
+ *
* ecore_event_handler_add(ECORE_CON_EVENT_URL_COMPLETE,
* completion_callback,
* data);
@@ -209,7 +211,7 @@
* data_callback,
* data);
* ecore_con_url_get(url_con);
- *
+ *
* ecore_main_loop_begin();
* return 0;
* }
@@ -222,376 +224,341 @@ extern "C" {
#define ECORE_CON_USE_SSL ECORE_CON_USE_SSL2
#define ECORE_CON_REMOTE_SYSTEM ECORE_CON_REMOTE_TCP
-typedef Eo Ecore_Con;
/**
- * @typedef Ecore_Con_Socks
- * An object representing a SOCKS proxy
- * @ingroup Ecore_Con_Socks_Group
- * @since 1.2
+ * @typedef Ecore_Con_Server
+ * @brief The structure type containing a connection handle to a server.
+ * @ingroup Ecore_Con_Server_Group
*/
-typedef struct Ecore_Con_Socks Ecore_Con_Socks;
+typedef struct _Ecore_Con_Server Ecore_Con_Server;
/**
- * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
- * @ingroup Ecore_Con_Group
- *
- * Utility functions that set up and shut down the Ecore Connection
- * library.
- *
- * There's also ecore_con_lookup() that can be used to make simple asynchronous
- * DNS lookups.
+ * @typedef Ecore_Con_Client
+ * @brief The structure type containing a connection handle to a client.
+ * @ingroup Ecore_Con_Client_Group
+ */
+typedef struct _Ecore_Con_Client Ecore_Con_Client;
+
+/**
+ * @typedef Ecore_Con_Socks
+ * @brief The structure type containing an object representing a SOCKS proxy.
*
- * A simple example of how to use these functions:
- * @li @ref ecore_con_lookup_example_c
+ * @since 1.2
*
- * @{
+ * @ingroup Ecore_Con_Socks_Group
*/
+typedef struct Ecore_Con_Socks Ecore_Con_Socks;
/**
- * @typedef Ecore_Con_Type
- * @enum _Ecore_Con_Type
- * Types for an ecore_con client/server object. A correct way to set this type is
- * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
- * and LOAD_CERT if the previously loaded certificate should be used.
- * @code
- * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
- * @endcode
- * @ingroup Ecore_Con_Server_Group
+ * @typedef Ecore_Con_Url
+ * @brief The structure type containing a handle to an HTTP upload/download object.
+ * @ingroup Ecore_Con_Url_Group
*/
-typedef enum _Ecore_Con_Type
-{
- /** Socket in ~/.ecore */
- ECORE_CON_LOCAL_USER = 0,
- /** Socket in /tmp */
- ECORE_CON_LOCAL_SYSTEM = 1,
- /** Abstract socket */
- ECORE_CON_LOCAL_ABSTRACT = 2,
- /** Remote server using TCP */
- ECORE_CON_REMOTE_TCP = 3,
- /** Remote multicast server */
- ECORE_CON_REMOTE_MCAST = 4,
- /** Remote server using UDP */
- ECORE_CON_REMOTE_UDP = 5,
- /** Remote broadcast using UDP */
- ECORE_CON_REMOTE_BROADCAST = 6,
- /** Remote connection sending packets immediately */
- ECORE_CON_REMOTE_NODELAY = 7,
- /** Remote connection sending data in large chunks
- * @note Only available on Linux
- * @since 1.2
- */
- ECORE_CON_REMOTE_CORK = 8,
- /** Use SSL2: UNSUPPORTED. **/
- ECORE_CON_USE_SSL2 = (1 << 4),
- /** Use SSL3 */
- ECORE_CON_USE_SSL3 = (1 << 5),
- /** Use TLS */
- ECORE_CON_USE_TLS = (1 << 6),
- /** Use both TLS and SSL3 */
- ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
- /** Attempt to use the loaded certificate */
- ECORE_CON_LOAD_CERT = (1 << 7),
- /** Disable all types of proxy on the server
- * @note Only functional for clients
- * @since 1.2
- */
- ECORE_CON_NO_PROXY = (1 << 8),
- ECORE_CON_SOCKET_ACTIVATE = (1 << 9)
-} Ecore_Con_Type;
-
-/** @} */
+typedef struct _Ecore_Con_Url Ecore_Con_Url;
-#ifndef EFL_NOLEGACY_API_SUPPORT
-#include "Ecore_Con_Legacy.h"
-#endif
-#ifdef EFL_EO_API_SUPPORT
-#include "Ecore_Con_Eo.h"
-#endif
/**
+ * @internal
* @addtogroup Ecore_Con_Events_Group
+ *
* @{
*/
/**
* @typedef Ecore_Con_Event_Client_Add
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event
*/
typedef struct _Ecore_Con_Event_Client_Add Ecore_Con_Event_Client_Add;
/**
* @typedef Ecore_Con_Event_Client_Upgrade
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Upgrade Ecore_Con_Event_Client_Upgrade;
/**
* @typedef Ecore_Con_Event_Client_Del
- * Used as the @p data param for the corresponding event
+ * @brief The structure type containing a connection used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Del Ecore_Con_Event_Client_Del;
/**
* @typedef Ecore_Con_Event_Client_Error
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Error Ecore_Con_Event_Client_Error;
/**
* @typedef Ecore_Con_Event_Server_Add
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Add Ecore_Con_Event_Server_Add;
/**
* @typedef Ecore_Con_Event_Server_Upgrade
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Upgrade Ecore_Con_Event_Server_Upgrade;
/**
* @typedef Ecore_Con_Event_Server_Del
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Del Ecore_Con_Event_Server_Del;
/**
* @typedef Ecore_Con_Event_Server_Error
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Error Ecore_Con_Event_Server_Error;
/**
* @typedef Ecore_Con_Event_Client_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Client_Data Ecore_Con_Event_Client_Data;
/**
* @typedef Ecore_Con_Event_Server_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
*/
typedef struct _Ecore_Con_Event_Server_Data Ecore_Con_Event_Server_Data;
/**
* @typedef Ecore_Con_Event_Client_Write
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Client_Write Ecore_Con_Event_Client_Write;
/**
* @typedef Ecore_Con_Event_Server_Write
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.1
*/
typedef struct _Ecore_Con_Event_Server_Write Ecore_Con_Event_Server_Write;
/**
* @typedef Ecore_Con_Event_Proxy_Bind
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @since 1.2
*/
typedef struct _Ecore_Con_Event_Proxy_Bind Ecore_Con_Event_Proxy_Bind;
/**
* @typedef Ecore_Con_Event_Url_Data
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Data Ecore_Con_Event_Url_Data;
/**
* @typedef Ecore_Con_Event_Url_Complete
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Complete Ecore_Con_Event_Url_Complete;
/**
* @typedef Ecore_Con_Event_Url_Progress
- * Used as the @p data param for the corresponding event
+ * @brief The structure type used as the @a data param for the corresponding event.
* @ingroup Ecore_Con_Url_Group
*/
typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress;
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Add
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ADD event.
*/
struct _Ecore_Con_Event_Client_Add
{
- Ecore_Con_Client *client; /**< the client that connected */
+ Ecore_Con_Client *client; /** the client that connected */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Upgrade
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Client_Upgrade
{
- Ecore_Con_Client *client; /**< the client that completed handshake */
+ Ecore_Con_Client *client; /** The client that completed handshake */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Del
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DEL event.
*/
struct _Ecore_Con_Event_Client_Del
{
- Ecore_Con_Client *client; /**< the client that was lost */
+ Ecore_Con_Client *client; /** The client that was lost */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Error
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_ERROR event.
*/
struct _Ecore_Con_Event_Client_Error
{
- Ecore_Con_Client *client; /**< the client for which an error occurred */
- char *error; /**< the error string describing what happened */
+ Ecore_Con_Client *client; /** The client for which an error occurred */
+ char *error; /**< The error string describing what happened */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Add
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ADD event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ADD event.
*/
struct _Ecore_Con_Event_Server_Add
{
- Ecore_Con_Server *server; /**< the server that was connected to */
+ Ecore_Con_Server *server; /** The server that is connected to */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Upgrade
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_UPGRADE event.
* @since 1.1
*/
struct _Ecore_Con_Event_Server_Upgrade
{
- Ecore_Con_Server *server; /**< the server that was connected to */
+ Ecore_Con_Server *server; /** The server that is connected to */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Del
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DEL event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DEL event.
*/
struct _Ecore_Con_Event_Server_Del
{
- Ecore_Con_Server *server; /**< the client that was lost */
+ Ecore_Con_Server *server; /** The client that is lost */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Error
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_ERROR event.
*/
struct _Ecore_Con_Event_Server_Error
{
- Ecore_Con_Server *server; /**< the server for which an error occurred */
- char *error; /**< the error string describing what happened */
+ Ecore_Con_Server *server; /** The server for which an error occurred */
+ char *error; /**< The error string describing what happened */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_DATA event.
*/
struct _Ecore_Con_Event_Client_Data
{
- Ecore_Con_Client *client; /**< the client that connected */
- void *data; /**< the data that the client sent */
- int size; /**< the length of the data sent */
+ Ecore_Con_Client *client; /**< The client that connected */
+ void *data; /**< The data that the client sent */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_DATA event.
*/
struct _Ecore_Con_Event_Server_Data
{
- Ecore_Con_Server *server; /**< the server that was connected to */
- void *data; /**< the data that the server sent */
- int size; /**< the length of the data sent */
+ Ecore_Con_Server *server; /**< The server that is connected to */
+ void *data; /**< The data that the server sent */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Client_Write
- * Used as the @p data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_CLIENT_WRITE event.
*/
struct _Ecore_Con_Event_Client_Write
{
- Ecore_Con_Client *client; /**< the client that connected */
- int size; /**< the length of the data sent */
+ Ecore_Con_Client *client; /**< The client that connected */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Server_Write
- * Used as the @p data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_SERVER_WRITE event.
*/
struct _Ecore_Con_Event_Server_Write
{
- Ecore_Con_Server *server; /**< the server that was connected to */
- int size; /**< the length of the data sent */
+ Ecore_Con_Server *server; /**< The server that is connected to */
+ int size; /**< The length of the data sent */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Proxy_Bind
- * Used as the @p data param for the @ref ECORE_CON_EVENT_PROXY_BIND event
- * @ingroup Ecore_Con_Socks_Group
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_PROXY_BIND event.
+ *
* @since 1.2
+ * @ingroup Ecore_Con_Socks_Group
*/
struct _Ecore_Con_Event_Proxy_Bind
{
- Ecore_Con_Server *server; /**< the server object connected to the proxy */
- const char *ip; /**< the proxy-bound ip address */
- int port; /**< the proxy-bound port */
+ Ecore_Con_Server *server; /**< The server object connected to the proxy */
+ const char *ip; /**< The proxy-bound ip address */
+ int port; /**< The proxy-bound port */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Data
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_DATA event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_DATA event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Data
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
- int size; /**< the size of the current received data (in bytes) */
- unsigned char data[1]; /**< the data received on this event */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
+ int size; /**< The size of the current received data (in bytes) */
+ unsigned char data[1]; /**< The data received on this event */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Complete
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_COMPLETE event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Complete
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
int status; /**< HTTP status code of the operation (200, 404, 401, etc.) */
};
/**
+ * @internal
* @struct _Ecore_Con_Event_Url_Progress
- * Used as the @p data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event
+ * @brief The structure type used as the @a data param for the @ref ECORE_CON_EVENT_URL_PROGRESS event.
* @ingroup Ecore_Con_Url_Group
*/
struct _Ecore_Con_Event_Url_Progress
{
- Ecore_Con_Url *url_con; /**< a pointer to the connection object */
+ Ecore_Con_Url *url_con; /**< A pointer to the connection object */
struct
{
- double total; /**< total size of the downloading data (in bytes) */
- double now; /**< current size of the downloading data (in bytes) */
- } down; /**< download info */
+ double total; /**< Total size of the downloading data (in bytes) */
+ double now; /**< Current size of the downloading data (in bytes) */
+ } down; /**< Download info */
struct
{
- double total; /**< total size of the uploading data (in bytes) */
- double now; /**< current size of the uploading data (in bytes) */
- } up; /**< upload info */
+ double total; /**< Total size of the uploading data (in bytes) */
+ double now; /**< Current size of the uploading data (in bytes) */
+ } up; /**< Upload info */
};
/** A client has connected to the server */
@@ -606,9 +573,9 @@ EAPI extern int ECORE_CON_EVENT_CLIENT_ERROR;
* @since 1.1
*/
EAPI extern int ECORE_CON_EVENT_CLIENT_UPGRADE;
-/** A server was created */
+/** A server is created */
EAPI extern int ECORE_CON_EVENT_SERVER_ADD;
-/** A server connection was lost */
+/** A server connection is lost */
EAPI extern int ECORE_CON_EVENT_SERVER_DEL;
/** A server experienced an error
* @since 1.1
@@ -646,36 +613,127 @@ EAPI extern int ECORE_CON_EVENT_URL_PROGRESS;
*/
/**
- * @addtogroup Ecore_Con_Events_Group Ecore_Con_Lib_Group
+ * @internal
+ * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
* @ingroup Ecore_Con_Group
*
+ * @brief This group provides utility functions that set up and shut down the Ecore Connection
+ * library.
+ *
+ * There is also ecore_con_lookup() that can be used to make simple asynchronous
+ * DNS lookups.
+ *
* @{
*/
/**
- * Initialises the Ecore_Con library.
- * @return Number of times the library has been initialised without being
- * shut down.
+ * @typedef Ecore_Con_Dns_Cb
+ * A callback type for use with @ref ecore_con_lookup.
+ */
+typedef void (*Ecore_Con_Dns_Cb)(const char *canonname,
+ const char *ip,
+ struct sockaddr *addr,
+ int addrlen,
+ void *data);
+
+/**
+ * @typedef Ecore_Con_Type
+ * @enum _Ecore_Con_Type
+ * @brief Enumeration of the types for an ecore_con client/server object. A correct way to set this type is
+ * with an ECORE_CON_$TYPE, optionally OR'ed with an ECORE_CON_$USE if encryption is desired,
+ * and LOAD_CERT if the previously loaded certificate should be used.
+ * @code
+ * ECORE_CON_REMOTE_TCP | ECORE_CON_USE_TLS | ECORE_CON_LOAD_CERT
+ * @endcode
+ * @ingroup Ecore_Con_Server_Group
+ */
+typedef enum _Ecore_Con_Type
+{
+ /** Socket in ~/.ecore */
+ ECORE_CON_LOCAL_USER = 0,
+ /** Socket in /tmp */
+ ECORE_CON_LOCAL_SYSTEM = 1,
+ /** Abstract socket */
+ ECORE_CON_LOCAL_ABSTRACT = 2,
+ /** Remote server using TCP */
+ ECORE_CON_REMOTE_TCP = 3,
+ /** Remote multicast server */
+ ECORE_CON_REMOTE_MCAST = 4,
+ /** Remote server using UDP */
+ ECORE_CON_REMOTE_UDP = 5,
+ /** Remote broadcast using UDP */
+ ECORE_CON_REMOTE_BROADCAST = 6,
+ /** Remote connection sending packets immediately */
+ ECORE_CON_REMOTE_NODELAY = 7,
+ /** Remote connection sending data in large chunks
+ * @note Only available on Linux
+ * @since 1.2
+ */
+ ECORE_CON_REMOTE_CORK = 8,
+ /** Use SSL2: UNSUPPORTED. **/
+ ECORE_CON_USE_SSL2 = (1 << 4),
+ /** Use SSL3 */
+ ECORE_CON_USE_SSL3 = (1 << 5),
+ /** Use TLS */
+ ECORE_CON_USE_TLS = (1 << 6),
+ /** Use both TLS and SSL3 */
+ ECORE_CON_USE_MIXED = ECORE_CON_USE_SSL3 | ECORE_CON_USE_TLS,
+ /** Attempt to use the loaded certificate */
+ ECORE_CON_LOAD_CERT = (1 << 7),
+ /** Disable all types of proxy on the server
+ * @note Only functional for clients
+ * @since 1.2
+ */
+ ECORE_CON_NO_PROXY = (1 << 8)
+} Ecore_Con_Type;
+
+/**
+ * @brief Initialises the Ecore_Con library.
*
- * @note This function already calls ecore_init() internally, so you don't need
- * to call it explicitly.
+ * @remarks This function already calls ecore_init() internally. So you do not need
+ * to call it explicitly.
+ * @return The number of times the library has been initialised without being shut down
*/
EAPI int ecore_con_init(void);
/**
- * Shuts down the Ecore_Con library.
- * @return Number of times the library has been initialised without being
- * shut down.
- * @note This function already calls ecore_shutdown() internally, so you don't
- * need to call it explicitly unless you called ecore_init() explicitly too.
+ * @brief Shuts down the Ecore_Con library.
+ *
+ * @remarks This function already calls ecore_shutdown() internally. So you do not
+ * need to call it explicitly unless you called ecore_init() explicitly too.
+ *
+ * @return The number of times the library has been initialised without being shut down
*/
EAPI int ecore_con_shutdown(void);
/**
+ * @brief Does an asynchronous DNS lookup.
+ *
+ * @details This function performs a DNS lookup on the hostname specified by @a name,
+ * then calls @a done_cb with the result and the @a data given as parameter.
+ * The result is given to the @a done_cb as follows:
+ * @li @c canonname - the canonical name of the address
+ * @li @c ip - the resolved IP address
+ * @li @c addr - a pointer to the socket address
+ * @li @c addrlen - the length of the socket address, in bytes
+ * @li @c data - the data pointer given as parameter to ecore_con_lookup()
+ *
+ * @param[in] name The IP address or server name to translate
+ * @param[in] done_cb The callback to notify when done
+ * @param[in] data The user data to be given to done_cb
+ * @return @c EINA_TRUE if the request did not fail to be set up, \n
+ * otherwise @c EINA_FALSE if it failed
+ */
+EAPI Eina_Bool ecore_con_lookup(const char *name,
+ Ecore_Con_Dns_Cb done_cb,
+ const void *data);
+
+/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_SSL_Group Ecore Connection SSL Functions
* @ingroup Ecore_Con_Group
*
@@ -713,18 +771,19 @@ EAPI void ecore_con_socks_apply_once(Ecore_Con_Socks *ecs);
EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
/**
+ * @internal
* @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
* @ingroup Ecore_Con_Group
*
- * This group of functions is applied to an @ref Ecore_Con_Server object. It
- * doesn't mean that they should be used in the server application, but on the
- * server object. In fact, most of them should be used in the client
- * application, when retrieving information or sending data.
+ * @brief This group of functions is applied to an @ref Ecore_Con_Server object. It
+ * does not mean that they should be used in the server application, but on the
+ * server object. In fact, most of them should be used in the client
+ * application, when retrieving information or sending data.
*
* Setting up a server is very simple: you just need to start it with
* ecore_con_server_add() and setup some callbacks to the events
* @ref ECORE_CON_EVENT_CLIENT_ADD, @ref ECORE_CON_EVENT_CLIENT_DEL and
- * @ref ECORE_CON_EVENT_CLIENT_DATA, that will be called when a client is
+ * @ref ECORE_CON_EVENT_CLIENT_DATA, that is called when a client is
* communicating with the server:
*
* @code
@@ -739,7 +798,7 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
* @endcode
*
* The function ecore_con_server_connect() can be used to write a client that
- * connects to a server. The resulting code will be very similar to the server
+ * connects to a server. The resulting code is very similar to the server
* code:
*
* @code
@@ -754,180 +813,194 @@ EAPI void ecore_con_socks_apply_always(Ecore_Con_Socks *ecs);
* @endcode
*
* After these two pieces of code are executed, respectively, in the server and
- * client code, the server will be up and running and the client will try to
+ * client code, the server is up and running and the client tries to
* connect to it. The connection, with its subsequent messages being sent from
* server to client and client to server, can be represented in the following
* sequence diagram:
*
* @htmlonly
- * <img src="ecore_con-client-server.png" style="max-width: 400px"/>
* <a href="ecore_con-client-server.png">Full size</a>
* @endhtmlonly
*
+ * @image html ecore_con-client-server.png
* @image rtf ecore_con-client-server.png
- * @image latex ecore_con-client-server.eps width=\textwidth
+ * @image latex ecore_con-client-server.eps "ecore con client server" width=\textwidth
*
- * Please notice the important difference between these two codes: the first is
+ * Note the important difference between these two codes: the first is
* used for writing a @b server, while the second should be used for writing a
* @b client.
*
* A reference for the @c client functions can be found at @ref
* Ecore_Con_Client_Group.
*
- * Examples of usage for this API can be found here:
- * @li @ref ecore_con_server_simple_example_c
- * @li @ref ecore_con_client_simple_example_c
- *
* @{
*/
/**
- * Creates a server to listen for connections.
+ * @brief Creates a server to listen for connections.
*
- * @param type The connection type.
- * @param name Name to associate with the socket. It is used when
- * generating the socket name of a Unix socket, or for
- * determining what host to listen on for TCP sockets.
- * @c NULL will not be accepted.
- * @param port Number to identify socket. When a Unix socket is used,
- * it becomes part of the socket name. When a TCP socket
- * is used, it is used as the TCP port.
- * @param data Data to associate with the created Ecore_Con_Server
- * object.
- * @return A new Ecore_Con_Server.
+ * @remarks The socket on which the server listens depends on the connection type:
+ * @li If @a type is @c ECORE_CON_LOCAL_USER, the server listens on
+ * the Unix socket "~/.ecore/[name]/[port]".
+ * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server listens
+ * on Unix socket "/tmp/.ecore_service|[name]|[port]".
+ * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server listens
+ * on TCP port @c port.
*
- * The socket on which the server listens depends on the connection
- * type:
- * @li If @a type is @c ECORE_CON_LOCAL_USER, the server will listen on
- * the Unix socket "~/.ecore/[name]/[port]".
- * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the server will listen
- * on Unix socket "/tmp/.ecore_service|[name]|[port]".
- * @li If @a type is @c ECORE_CON_REMOTE_TCP, the server will listen
- * on TCP port @c port.
+ * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type.
*
- * More information about the @p type can be found at @ref _Ecore_Con_Type.
+ * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get()
+ * or changed with ecore_con_server_data_set().
*
- * The @p data parameter can be fetched later using ecore_con_server_data_get()
- * or changed with ecore_con_server_data_set().
+ * @param[in] type The connection type
+ * @param[in] name The name to associate with the socket \n
+ * It is used when generating the socket name of a Unix socket, or for
+ * determining what host to listen on for TCP sockets.
+ * @c NULL is not accepted.
+ * @param[in] port The number to identify socket \n
+ * When a Unix socket is used, it becomes part of the socket name.
+ * When a TCP socket is used, it is used as the TCP port.
+ * @param[in] data The data to associate with the created Ecore_Con_Server object
+ * @return A new Ecore_Con_Server
*/
EAPI Ecore_Con_Server *ecore_con_server_add(Ecore_Con_Type type,
const char *name, int port,
const void *data);
/**
- * Creates a connection to the specified server and returns an associated object.
+ * @brief Creates a connection to the specified server and returns an associated object.
*
- * @param type The connection type.
- * @param name Name used when determining what socket to connect to.
- * It is used to generate the socket name when the socket
- * is a Unix socket. It is used as the hostname when
- * connecting with a TCP socket.
- * @param port Number to identify the socket to connect to. Used when
- * generating the socket name for a Unix socket, or as the
- * TCP port when connecting to a TCP socket.
- * @param data Data to associate with the created Ecore_Con_Server
- * object.
- * @return A new Ecore_Con_Server.
+ * @remarks The socket to which the connection is made depends on the connection type:
+ * @li If @a type is @c ECORE_CON_LOCAL_USER, the function
+ * connects to the server at the Unix socket
+ * "~/.ecore/[name]/[port]".
+ * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function
+ * connects to the server at the Unix socket
+ * "/tmp/.ecore_service|[name]|[port]".
+ * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function
+ * connects to the server at the TCP port "[name]:[port]".
*
- * The socket to which the connection is made depends on the connection type:
- * @li If @a type is @c ECORE_CON_LOCAL_USER, the function will
- * connect to the server at the Unix socket
- * "~/.ecore/[name]/[port]".
- * @li If @a type is @c ECORE_CON_LOCAL_SYSTEM, the function will
- * connect to the server at the Unix socket
- * "/tmp/.ecore_service|[name]|[port]".
- * @li If @a type is @c ECORE_CON_REMOTE_TCP, the function will
- * connect to the server at the TCP port "[name]:[port]".
+ * @remarks More information about the @a type can be found at @ref _Ecore_Con_Type.
*
- * More information about the @p type can be found at @ref _Ecore_Con_Type.
+ * @remarks This function does not block. It either succeeds, or fails due to invalid
+ * parameters, failed memory allocation, etc., returning @c NULL in that case.
*
- * This function won't block. It will either succeed, or fail due to invalid
- * parameters, failed memory allocation, etc., returning @c NULL on that case.
+ * @remarks However, even if this call returns a valid @ref Ecore_Con_Server, the
+ * connection is only successfully completed if an event of type
+ * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
+ * @ref ECORE_CON_EVENT_SERVER_DEL is received.
*
- * However, even if this call returns a valid @ref Ecore_Con_Server, the
- * connection will only be successfully completed if an event of type
- * @ref ECORE_CON_EVENT_SERVER_ADD is received. If it fails to complete, an
- * @ref ECORE_CON_EVENT_SERVER_DEL will be received.
+ * @remarks The @a data parameter can be fetched later using ecore_con_server_data_get()
+ * or changed with ecore_con_server_data_set().
*
- * The @p data parameter can be fetched later using ecore_con_server_data_get()
- * or changed with ecore_con_server_data_set().
+ * @param[in] type The connection type
+ * @param[in] name The name used when determining what socket to connect to \n
+ * It is used to generate the socket name when the socket
+ * is a Unix socket. It is used as the hostname when
+ * connecting with a TCP socket.
+ * @param[in] port The number to identify the socket to connect to \n
+ * It is used when generating the socket name for a Unix socket,
+ * or as the TCP port when connecting to a TCP socket.
+ * @param[in] data The data to associate with the created Ecore_Con_Server object
+ * @return A new Ecore_Con_Server
*/
EAPI Ecore_Con_Server *ecore_con_server_connect(Ecore_Con_Type type,
const char *name, int port,
const void *data);
/**
- * Closes the connection and frees the given server.
+ * @brief Closes the connection and frees the given server.
*
- * @param svr The given server.
- * @return Data associated with the server when it was created.
+ * @remarks All the clients connected to this server is disconnected.
*
- * All the clients connected to this server will be disconnected.
+ * @param[in] svr The given server
+ * @return The data associated with the server when it is created
*
* @see ecore_con_server_add, ecore_con_server_connect
*/
EAPI void * ecore_con_server_del(Ecore_Con_Server *svr);
/**
- * Retrieves the data associated with the given server.
+ * @brief Gets the data associated with the given server.
*
- * @param svr The given server.
- * @return The associated data.
+ * @param[in] svr The given server
+ * @return The associated data
*
* @see ecore_con_server_data_set()
*/
EAPI void * ecore_con_server_data_get(Ecore_Con_Server *svr);
/**
- * Sets the data associated with the given server.
+ * @brief Sets the data associated with the given server.
*
- * @param svr The given server.
- * @param data The data to associate with @p svr
- * @return The previously associated data, if any.
+ * @param[in] svr The given server
+ * @param[in] data The data to associate with @a svr
+ * @return The previously associated data, if any
*
* @see ecore_con_server_data_get()
*/
EAPI void * ecore_con_server_data_set(Ecore_Con_Server *svr,
void *data);
/**
- * Retrieves whether the given server is currently connected.
+ * @brief Checks whether the given server is currently connected.
+ *
+ * @param[in] svr The given server
+ * @return @c EINA_TRUE if the server is connected, \n
+ * otherwise @c EINA_FALSE if the server is not connected
+ */
+EAPI Eina_Bool ecore_con_server_connected_get(Ecore_Con_Server *svr);
+/**
+ * @brief Gets the current list of clients.
+ *
+ * @remarks Each node in the returned list points to an @ref Ecore_Con_Client. This list
+ * cannot be modified or freed. It can also change if new clients are connected
+ * or disconnected, and becomes invalid when the server is deleted or freed.
+ *
+ * @param[in] svr The given server
+ * @return The list of clients on this server
+ */
+EAPI const Eina_List * ecore_con_server_clients_get(Ecore_Con_Server *svr);
+
+/**
+ * @brief Gets the name of server.
+ *
+ * @remarks The name returned is the name used to connect on this server.
*
- * @param svr The given server.
- * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise.
+ * @param[in] svr The given server
+ * @return The name of the server
*/
-EAPI Eina_Bool ecore_con_server_connected_get(const Ecore_Con_Server *svr);
+EAPI const char * ecore_con_server_name_get(Ecore_Con_Server *svr);
/**
- * Retrieves the server port in use.
+ * @brief Gets the server port in use.
*
- * @param svr The given server.
- * @return The server port in use.
+ * @remarks The port where the server is listening for connections.
*
- * The port where the server is listening for connections.
+ * @param[in] svr The given server
+ * @return The server port in use
*/
-EAPI int ecore_con_server_port_get(const Ecore_Con_Server *svr);
+EAPI int ecore_con_server_port_get(Ecore_Con_Server *svr);
/**
- * @brief Check how long a server has been connected
+ * @brief Checks how long a server has been connected.
*
- * @param svr The server to check
- * @return The total time, in seconds, that the server has been
- * connected/running
+ * @details This function is used to find out the time that has been elapsed since
+ * ecore_con_server_add() succeeded.
*
- * This function is used to find out the time that has been elapsed since
- * ecore_con_server_add() succeeded.
+ * @param[in] svr The server to check
+ * @return The total time, in seconds, that the server has been connected or running
*/
-EAPI double ecore_con_server_uptime_get(const Ecore_Con_Server *svr);
+EAPI double ecore_con_server_uptime_get(Ecore_Con_Server *svr);
/**
- * Sends the given data to the given server.
+ * @brief Sends the given data to the given server.
*
- * @param svr The given server.
- * @param data The given data.
- * @param size Length of the data, in bytes, to send.
- * @return The number of bytes sent. @c 0 will be returned if there is an
- * error.
+ * @details This function sends the given data to the server as soon as the program
+ * is back to the main loop. Thus, this function returns immediately
+ * (non-blocking). If the data needs to be sent @b now, call
+ * ecore_con_server_flush() after this one.
*
- * This function will send the given data to the server as soon as the program
- * is back to the main loop. Thus, this function returns immediately
- * (non-blocking). If the data needs to be sent @b now, call
- * ecore_con_server_flush() after this one.
+ * @param[in] svr The given server
+ * @param[in] data The given data
+ * @param[in] size The length of the data, in bytes, to send
+ * @return The number of bytes sent, \n
+ * otherwise @c 0 if there is an error
*
* @see ecore_con_client_send()
* @see ecore_con_server_flush()
@@ -936,120 +1009,121 @@ EAPI int ecore_con_server_send(Ecore_Con_Server *svr,
const void *data,
int size);
/**
- * Sets a limit on the number of clients that can be handled concurrently
- * by the given server, and a policy on what to do if excess clients try to
- * connect.
- *
- * @param svr The given server.
- * @param client_limit The maximum number of clients to handle
- * concurrently. -1 means unlimited (default). 0
- * effectively disables the server.
- * @param reject_excess_clients Set to 1 to automatically disconnect
- * excess clients as soon as they connect if you are
- * already handling client_limit clients. Set to 0
- * (default) to just hold off on the "accept()"
- * system call until the number of active clients
- * drops. This causes the kernel to queue up to 4096
- * connections (or your kernel's limit, whichever is
- * lower).
- *
- * Beware that if you set this once ecore is already running, you may
- * already have pending CLIENT_ADD events in your event queue. Those
- * clients have already connected and will not be affected by this call.
- * Only clients subsequently trying to connect will be affected.
+ * @brief Sets a limit on the number of clients that can be handled concurrently
+ * by the given server, and a policy on what to do if excess clients try to
+ * connect.
+ *
+ * @remarks Beware that if you set this once, ecore is already running. You may
+ * already have pending CLIENT_ADD events in your event queue. Those
+ * clients have already connected and is not affected by this call.
+ * Only clients subsequently trying to connect is affected.
+ *
+ * @param[in] svr The given server
+ * @param[in] client_limit The maximum number of clients to handle concurrently \n
+ * @c -1 means unlimited (default), @c 0 effectively disables the server.
+ * @param[in] reject_excess_clients Set to @c 1 to automatically disconnect excess clients
+ * as soon as they connect if you are already handling client_limit clients \n
+ * otherwise set to @c 0 (default) to just hold off on the "accept()"
+ * system call until the number of active clients drops \n
+ * This causes the kernel to queue up to 4096
+ * connections (or your kernel's limit, whichever is lower).
*/
EAPI void ecore_con_server_client_limit_set(Ecore_Con_Server *svr,
int client_limit,
char reject_excess_clients);
/**
- * Gets the IP address of a server that has been connected to.
+ * @brief Gets the IP address of a server that has been connected to.
*
- * @param svr The given server.
+ * @param[in] svr The given server
* @return A pointer to an internal string that contains the IP address of
- * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
+ * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation \n
* This string should not be modified or trusted to stay valid after
- * deletion for the @p svr object. If no IP is known @c NULL is
- * returned.
+ * deletion for the @a svr object. If no IP is known, @c NULL is returned.
*/
-EAPI const char * ecore_con_server_ip_get(const Ecore_Con_Server *svr);
+EAPI const char * ecore_con_server_ip_get(Ecore_Con_Server *svr);
/**
- * Flushes all pending data to the given server.
+ * @brief Flushes all pending data to the given server.
*
- * @param svr The given server.
+ * @details This function blocks until all data is sent to the server.
*
- * This function will block until all data is sent to the server.
+ * @param[in] svr The given server
*
* @see ecore_con_server_send()
* @see ecore_con_client_flush()
*/
EAPI void ecore_con_server_flush(Ecore_Con_Server *svr);
/**
- * Set the default time after which an inactive client will be disconnected
+ * @brief Sets the default time after which an inactive client is disconnected.
*
- * @param svr The server object
- * @param timeout The timeout, in seconds, to disconnect after
+ * @details This function is used by the server to set the default idle timeout on
+ * clients. If the any of the clients becomes idle for a time higher than this
+ * value, it is disconnected. A value of < @c 1 disables the idle timeout.
*
- * This function is used by the server to set the default idle timeout on
- * clients. If the any of the clients becomes idle for a time higher than this
- * value, it will be disconnected. A value of < 1 disables the idle timeout.
+ * @remarks This timeout is not affected by the one set by
+ * ecore_con_client_timeout_set(). A client is disconnected whenever the
+ * client or the server timeout is reached. That means, the lower timeout value
+ * is used for that client if ecore_con_client_timeout_set() is used on it.
*
- * This timeout is not affected by the one set by
- * ecore_con_client_timeout_set(). A client will be disconnected whenever the
- * client or the server timeout is reached. That means, the lower timeout value
- * will be used for that client if ecore_con_client_timeout_set() is used on it.
+ * @param[in] svr The server object
+ * @param[in] timeout The timeout, in seconds, to disconnect after
*
* @see ecore_con_server_timeout_get()
* @see ecore_con_client_timeout_set()
*/
EAPI void ecore_con_server_timeout_set(Ecore_Con_Server *svr, double timeout);
/**
- * Get the default time after which an inactive client will be disconnected
+ * @brief Gets the default time after which an inactive client is disconnected.
*
- * @param svr The server object
- * @return The timeout, in seconds, to disconnect after
+ * @details This function is used to get the idle timeout for clients. A value of < @c 1
+ * means the idle timeout is disabled.
*
- * This function is used to get the idle timeout for clients. A value of < 1
- * means the idle timeout is disabled.
+ * @param[in] svr The server object
+ * @return The timeout, in seconds, to disconnect after
*
* @see ecore_con_server_timeout_set()
* @see ecore_con_client_timeout_get()
*/
-EAPI double ecore_con_server_timeout_get(const Ecore_Con_Server *svr);
+EAPI double ecore_con_server_timeout_get(Ecore_Con_Server *svr);
/**
- * Get the fd that the server is connected to
+ * @brief Get the fd that the server is connected to.
*
- * @param svr The server object
- * @return The fd, or -1 on failure
+ * @details This function returns the fd which is used by the underlying server connection.
+ * It should not be tampered with unless you REALLY know what you are doing.
+ * @since 1.1
*
- * This function returns the fd which is used by the underlying server connection.
- * It should not be tampered with unless you REALLY know what you are doing.
- * @note This function is only valid for servers created with ecore_con_server_connect()
- * @warning Seriously. Don't use this unless you know what you are doing.
- * @since 1.1
+ * @remarks This function is only valid for servers created with ecore_con_server_connect()
+ * @remarks Do not use this unless you know what you are doing.
+ *
+ * @param[in] svr The server object
+ * @return The fd, \n
+ * otherwise @c -1 on failure
*/
-EAPI int ecore_con_server_fd_get(const Ecore_Con_Server *svr);
+EAPI int ecore_con_server_fd_get(Ecore_Con_Server *svr);
/**
- * Get the fd that the client is connected to
+ * @brief Gets the fd that the client is connected to.
*
- * @param cl The client object
- * @return The fd, or -1 on failure
+ * @details This function returns the fd which is used by the underlying client connection.
+ * It should not be tampered with unless you REALLY know what you are doing.
+ *
+ * @since 1.1
*
- * This function returns the fd which is used by the underlying client connection.
- * It should not be tampered with unless you REALLY know what you are doing.
- * @since 1.1
+ * @param[in] cl The client object
+ * @return The fd, \n
+ * otherwise @c -1 on failure
*/
-EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl);
+EAPI int ecore_con_client_fd_get(Ecore_Con_Client *cl);
/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
* @ingroup Ecore_Con_Group
*
- * Functions to communicate with and/or set options on a client.
+ * @brief This group provides functions to communicate with and/or set options on a client.
*
* This set of functions, as explained in @ref Ecore_Con_Server_Group, is used
* to send data to a client, or to set options and get information about this
@@ -1059,25 +1133,22 @@ EAPI int ecore_con_client_fd_get(const Ecore_Con_Client *cl);
* If you need to implement a client, the way to connect to a server is
* described in @ref Ecore_Con_Server_Group.
*
- * An example of usage of these functions can be found at:
- * @li @ref ecore_con_client_simple_example_c
- *
* @{
*/
/**
- * Sends the given data to the given client.
+ * @brief Sends the given data to the given client.
*
- * @param cl The given client.
- * @param data The given data.
- * @param size Length of the data, in bytes, to send.
- * @return The number of bytes sent. @c 0 will be returned if there is an
- * error.
+ * @details This function sends the given data to the client as soon as the program
+ * is back to the main loop. Thus, this function returns immediately
+ * (non-blocking). If the data needs to be sent @b now, call
+ * ecore_con_client_flush() after this one.
*
- * This function will send the given data to the client as soon as the program
- * is back to the main loop. Thus, this function returns immediately
- * (non-blocking). If the data needs to be sent @b now, call
- * ecore_con_client_flush() after this one.
+ * @param[in] cl The given client
+ * @param[in] data The given data
+ * @param[in] size The length of the data, in bytes, to send
+ * @return The number of bytes sent, \n
+ * otherwise @c 0 if there is an error
*
* @see ecore_con_server_send()
* @see ecore_con_client_flush()
@@ -1086,126 +1157,139 @@ EAPI int ecore_con_client_send(Ecore_Con_Client *cl,
const void *data,
int size);
/**
- * Closes the connection and frees memory allocated to the given client.
+ * @brief Gets the server representing the socket the client has connected to.
*
- * @param cl The given client.
- * @return Data associated with the client.
+ * @param[in] cl The given client
+ * @return The server that the client connected to
+ */
+EAPI Ecore_Con_Server *ecore_con_client_server_get(Ecore_Con_Client *cl);
+
+/**
+ * @brief Closes the connection and frees the memory allocated to the given client.
+ *
+ * @param[in] cl The given client
+ * @return The data associated with the client
*/
EAPI void * ecore_con_client_del(Ecore_Con_Client *cl);
+
/**
- * Sets the data associated with the given client to @p data.
+ * @brief Sets the data associated with the given client to @a data.
*
- * @param cl The given client.
- * @param data What to set the data to.
+ * @param[in] cl The given client
+ * @param[in] data The data to set
*/
EAPI void ecore_con_client_data_set(Ecore_Con_Client *cl,
const void *data);
/**
- * Retrieves the data associated with the given client.
+ * @brief Gets the data associated with the given client.
*
- * @param cl The given client.
- * @return The data associated with @p cl.
+ * @param[in] cl The given client
+ * @return The data associated with @a cl
*/
EAPI void * ecore_con_client_data_get(Ecore_Con_Client *cl);
/**
- * Gets the IP address of a client that has connected.
+ * @brief Gets the IP address of a client that has connected.
*
- * @param cl The given client.
- * @return A pointer to an internal string that contains the IP address of
- * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation.
+ * @remarks The returned string should not be modified, freed or trusted to stay valid
+ * after deletion for the @a cl object. If no IP is known @c NULL is returned.
*
- * The returned string should not be modified, freed or trusted to stay valid
- * after deletion for the @p cl object. If no IP is known @c NULL is returned.
+ * @param[in] cl The given client
+ * @return A pointer to an internal string that contains the IP address of
+ * the connected client in the form "XXX.YYY.ZZZ.AAA" IP notation
*/
-EAPI const char * ecore_con_client_ip_get(const Ecore_Con_Client *cl);
+EAPI const char * ecore_con_client_ip_get(Ecore_Con_Client *cl);
+
/**
- * Flushes all pending data to the given client.
+ * @brief Flushes all pending data to the given client.
*
- * @param cl The given client.
+ * @details This function blocks until all data is sent to the server.
*
- * This function will block until all data is sent to the server.
+ * @param[in] cl The given client
*
* @see ecore_con_client_send()
* @see ecore_con_server_flush()
*/
EAPI void ecore_con_client_flush(Ecore_Con_Client *cl);
+
/**
- * @brief Check how long a client has been connected
+ * @brief Checks how long a client has been connected.
*
- * @param cl The client to check
- * @return The total time, in seconds, that the client has been connected to
- * the server
+ * @details This function is used to find out how long a client has been connected for.
*
- * This function is used to find out how long a client has been connected for.
+ * @param[in] cl The client to check
+ * @return The total time, in seconds, that the client has been connected to the server
*/
-EAPI double ecore_con_client_uptime_get(const Ecore_Con_Client *cl);
+EAPI double ecore_con_client_uptime_get(Ecore_Con_Client *cl);
+
/**
- * Get the default time after which the client will be disconnected when
- * inactive
+ * @brief Gets the default time after which the client is disconnected when inactive.
*
- * @param cl The client object
- * @return The timeout, in seconds, to disconnect after
+ * @details This function is used to get the idle timeout for a client. A value of < @c 1
+ * means the idle timeout is disabled.
*
- * This function is used to get the idle timeout for a client. A value of < 1
- * means the idle timeout is disabled.
+ * @param[in] cl The client object
+ * @return The timeout, in seconds, to disconnect after
*
* @see ecore_con_client_timeout_set()
*/
-EAPI double ecore_con_client_timeout_get(const Ecore_Con_Client *cl);
+EAPI double ecore_con_client_timeout_get(Ecore_Con_Client *cl);
+
/**
- * Set the time after which the client will be disconnected when inactive
+ * @brief Sets the time after which the client is disconnected when inactive.
*
- * @param cl The client object
- * @param timeout The timeout, in seconds, to disconnect after
+ * @details This function is used by the server to set the idle timeout on a specific
+ * client. If the client becomes idle for a time higher than this value, it is
+ * disconnected. A value of < @c 1 disables the idle timeout.
*
- * This function is used by the server to set the idle timeout on a specific
- * client. If the client becomes idle for a time higher than this value, it will
- * be disconnected. A value of < 1 disables the idle timeout.
+ * @details This timeout is not affected by the one set by
+ * ecore_con_server_timeout_set(). A client is disconnected whenever the
+ * client or the server timeout is reached. That means, the lower timeout value
+ * is used for that client if ecore_con_server_timeout_set() is used on the server.
*
- * This timeout is not affected by the one set by
- * ecore_con_server_timeout_set(). A client will be disconnected whenever the
- * client or the server timeout is reached. That means, the lower timeout value
- * will be used for that client if ecore_con_server_timeout_set() is used on the
- * server.
+ * @param[in] cl The client object
+ * @param[in] timeout The timeout, in seconds, to disconnect after
*
* @see ecore_con_client_timeout_get()
* @see ecore_con_server_timeout_set()
*/
EAPI void ecore_con_client_timeout_set(Ecore_Con_Client *cl, double timeout);
+
/**
- * Returns whether the client is still connected
+ * @brief Checks whether the client is still connected.
*
- * @param cl The given client.
- * @return @c EINA_TRUE if connected, @c EINA_FALSE otherwise.
+ * @param[in] cl The given client
+ * @return @c EINA_TRUE if connected, \n
+ * otherwise @c EINA_FALSE if it is not connected
*/
-EAPI Eina_Bool ecore_con_client_connected_get(const Ecore_Con_Client *cl);
+EAPI Eina_Bool ecore_con_client_connected_get(Ecore_Con_Client *cl);
/**
- * @brief Return the port that the client has connected to
+ * @brief Gets the port that the client has connected to.
*
- * @param cl The client
- * @return The port that @p cl has connected to, or -1 on error
- * Use this function to return the port on which a given client has connected.
+ * @remarks Use this function to return the port on which a given client has connected.
+ *
+ * @param[in] cl The client
+ * @return The port that @a cl has connected to, \n
+ * otherwise @c -1 on error
*/
-EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
-
-
+EAPI int ecore_con_client_port_get(Ecore_Con_Client *cl);
/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Con_Url_Group Ecore URL Connection Functions
* @ingroup Ecore_Con_Group
*
- * Utility functions that set up, use and shut down the Ecore URL
- * Connection library.
+ * @brief This group provides utility functions that set up, use and shut down the Ecore URL
+ * Connection library.
*
- * These functions are a shortcut to make it easy to perform http requests
+ * These functions are shortcuts to make it easy to perform HTTP requests
* (POST, GET, etc).
*
- * Brief usage:
+ * Brief usage details:
* 1. Create an Ecore_Con_Url object with ecore_con_url_new(url);
* 2. Register to receive the #ECORE_CON_EVENT_URL_COMPLETE event
* (and optionally the #ECORE_CON_EVENT_URL_DATA and
@@ -1218,7 +1302,7 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
* need to wait for the #ECORE_CON_EVENT_URL_COMPLETE event before re-using or
* destroying the object.
*
- * If it's necessary to change the @ref Ecore_Con_Url object url, use
+ * If it is necessary to change the @ref Ecore_Con_Url object url, use
* ecore_con_url_url_set().
*
* Simple Usage 1 (HTTP GET):
@@ -1253,18 +1337,14 @@ EAPI int ecore_con_client_port_get(const Ecore_Con_Client *cl);
* ecore_con_url_ftp_upload(url_con, "/tmp/file", "user", "pass","dir");
* @endcode
*
- * These are complete examples for the API:
- * @li @ref ecore_con_url_download_example.c "Downloading a file"
- * @li @ref ecore_con_url_headers_example.c "Setting many options for the connection"
- *
* @{
*/
/**
* @typedef Ecore_Con_Url_Time
* @enum _Ecore_Con_Url_Time
- * The type of condition to use when making an HTTP request dependent on time,
- * so that headers such as "If-Modified-Since" are used.
+ * @brief Enumeration for the type of condition to use when making an HTTP request dependent on time,
+ * so that headers such as "If-Modified-Since" are used.
*/
typedef enum _Ecore_Con_Url_Time
{
@@ -1289,7 +1369,7 @@ typedef enum _Ecore_Con_Url_Time
/**
* @typedef Ecore_Con_Url_Http_Version
* @enum _Ecore_Con_Url_Http_Version
- * The http version to use
+ * @brief Enumeration of the HTTP version to use.
* @since 1.2
*/
typedef enum _Ecore_Con_Url_Http_Version
@@ -1307,84 +1387,87 @@ typedef enum _Ecore_Con_Url_Http_Version
} Ecore_Con_Url_Http_Version;
/**
- * Change the HTTP version used for the request
- * @param url_con Connection object through which the request will be sent.
- * @param version The version to be used
- * @return @c EINA_TRUE on success, @c EINA_FALSE on failure to change version.
- * @since 1.2
+ * @brief Changes the HTTP version used for the request.
+ * @since 1.2
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @param[in] version The version to be used
+ * @return @c EINA_TRUE if the version is changed successfully, \n
+ * otherwise @c EINA_FALSE on failure to change version
* @see ecore_con_url_pipeline_get()
*/
EAPI Eina_Bool ecore_con_url_http_version_set(Ecore_Con_Url *url_con, Ecore_Con_Url_Http_Version version);
-
+
/**
- * Initialises the Ecore_Con_Url library.
- * @return Number of times the library has been initialised without being
- * shut down.
+ * @brief Initialises the Ecore_Con_Url library.
*
- * @note This function doesn't call ecore_con_init(). You still need to call it
- * explicitly before calling this one.
+ * @remarks This function does not call ecore_con_init(). You still need to call it
+ * explicitly before calling this one.
+ * @return The number of times the library has been initialised without being shut down
*/
EAPI int ecore_con_url_init(void);
/**
- * Shuts down the Ecore_Con_Url library.
- * @return Number of calls that still uses Ecore_Con_Url
+ * @brief Shuts down the Ecore_Con_Url library.
*
- * @note This function doesn't call ecore_con_shutdown(). You still need to call
- * it explicitly after calling this one.
+ * @remarks This function does not call ecore_con_shutdown(). You still need to call
+ * it explicitly after calling this one.
+ * @return The number of calls that still uses Ecore_Con_Url
*/
EAPI int ecore_con_url_shutdown(void);
/**
- * Enable or disable HTTP 1.1 pipelining.
- * @param enable @c EINA_TRUE will turn it on, @c EINA_FALSE will disable it.
+ * @brief Enables or disables HTTP 1.1 pipelining.
*
- * Pipelining allows to send one request after another one, without having to
- * wait for the reply of the first request. The respective replies are received
- * in the order that the requests were sent.
+ * @remarks Pipelining allows to send one request after another one, without having to
+ * wait for the reply of the first request. The respective replies are received
+ * in the order that the requests were sent.
*
- * Enabling this feature will be valid for all requests done using @c
- * ecore_con_url.
+ * @remarks Enabling this feature is valid for all requests done using @c ecore_con_url.
*
- * See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
+ * @remarks See http://en.wikipedia.org/wiki/HTTP_pipelining for more info.
*
+ * @param[in] enable Set @c EINA_TRUE to turn it on, \n
+ * otherwise @c EINA_FALSE to disable it
* @see ecore_con_url_pipeline_get()
*/
EAPI void ecore_con_url_pipeline_set(Eina_Bool enable);
/**
- * Is HTTP 1.1 pipelining enable ?
- * @return @c EINA_TRUE if it is enable.
+ * @brief Checks whether HTTP 1.1 pipelining is enabled.
+ *
+ * @return @c EINA_TRUE if it is enabled, \n
+ * otherwise @c EINA_FALSE if it is not enabled
*
* @see ecore_con_url_pipeline_set()
*/
EAPI Eina_Bool ecore_con_url_pipeline_get(void);
/**
- * Creates and initializes a new Ecore_Con_Url connection object.
+ * @brief Creates and initializes a new Ecore_Con_Url connection object.
*
- * @param url URL that will receive requests. Can be changed using
- * ecore_con_url_url_set.
+ * @details This function creates and initializes a new Ecore_Con_Url connection object that can be
+ * used for sending requests.
*
- * @return @c NULL on error, a new Ecore_Con_Url on success.
- *
- * Creates and initializes a new Ecore_Con_Url connection object that can be
- * used for sending requests.
+ * @param[in] url The URL that receives requests \n
+ * This can be changed using ecore_con_url_url_set.
+ * @return A new Ecore_Con_Url, \n
+ * otherwise @c NULL on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_url_set()
*/
EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
/**
- * Creates a custom connection object.
- *
- * @param url URL that will receive requests
- * @param custom_request Custom request (e.g. GET, POST, HEAD, PUT, etc)
+ * @brief Creates a custom connection object.
*
- * @return @c NULL on error, a new Ecore_Con_Url on success.
+ * @details This function creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
+ * SUBSCRIBE and other obscure HTTP requests). This object should be used like
+ * the one created with ecore_con_url_new().
*
- * Creates and initializes a new Ecore_Con_Url for a custom request (e.g. HEAD,
- * SUBSCRIBE and other obscure HTTP requests). This object should be used like
- * one created with ecore_con_url_new().
+ * @param[in] url The URL that receives requests
+ * @param[in] custom_request The custom request (e.g. GET, POST, HEAD, PUT, etc)
+ * @return A new Ecore_Con_Url, \n
+ * otherwise @c NULL on error
*
* @see ecore_con_url_new()
* @see ecore_con_url_url_set()
@@ -1392,52 +1475,74 @@ EAPI Ecore_Con_Url * ecore_con_url_new(const char *url);
EAPI Ecore_Con_Url * ecore_con_url_custom_new(const char *url,
const char *custom_request);
/**
- * Destroys a Ecore_Con_Url connection object.
+ * @brief Destroys an Ecore_Con_Url connection object.
*
- * @param url_con Connection object to free.
+ * @param[in] url_con The connection object to free
*
* @see ecore_con_url_new()
*/
EAPI void ecore_con_url_free(Ecore_Con_Url *url_con);
/**
- * Associates data with a connection object.
+ * @brief Sets the URL to send the request to.
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @param[in] url The URL that receives the request
+ *
+ * @return @c EINA_TRUE if the URL is set successfully, \n
+ * otherwise @c EINA_FALSE on error
+ */
+EAPI Eina_Bool ecore_con_url_url_set(Ecore_Con_Url *url_con,
+ const char *url);
+/**
+ * @brief Gets the URL to send the request to.
+ * @since 1.1
+ *
+ * @param[in] url_con The connection object through which the request is sent
+ * @return The URL that receives the request, \n
+ * otherwise @c NULL on failure \n
+ * URL is stringshared.
+ */
+EAPI const char *ecore_con_url_url_get(Ecore_Con_Url *url_con);
+
+/**
+ * @brief Associates data with a connection object.
*
- * @param url_con Connection object to associate data.
- * @param data Data to be set.
+ * @remarks Associates data with a connection object, which can be retrieved later with
+ * ecore_con_url_data_get()).
*
- * Associates data with a connection object, which can be retrieved later with
- * ecore_con_url_data_get()).
+ * @param[in] url_con The connection object to associate data
+ * @param[in] data The data to be set
*
* @see ecore_con_url_data_get()
*/
EAPI void ecore_con_url_data_set(Ecore_Con_Url *url_con,
void *data);
/**
- * Retrieves data associated with a Ecore_Con_Url connection object.
+ * @brief Gets data associated with a Ecore_Con_Url connection object.
*
- * @param url_con Connection object to retrieve data from.
+ * @details This function gets data associated with a Ecore_Con_Url connection object (previously
+ * set with ecore_con_url_data_set()).
*
- * @return Data associated with the given object.
- *
- * Retrieves data associated with a Ecore_Con_Url connection object (previously
- * set with ecore_con_url_data_set()).
+ * @param[in] url_con The connection object to retrieve data from
+ * @return The data associated with the given object
*
* @see ecore_con_url_data_set()
*/
EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
+
/**
- * Adds an additional header to the request connection object.
+ * @brief Adds an additional header to the request connection object.
*
- * @param url_con Connection object
- * @param key Header key
- * @param value Header value
+ * @details This function adds an additional header (User-Agent, Content-Type, etc.) to the request
+ * connection object. This addition is valid for only one
+ * ecore_con_url_get() or ecore_con_url_post() call.
*
- * Adds an additional header (User-Agent, Content-Type, etc.) to the request
- * connection object. This addition will be valid for only one
- * ecore_con_url_get() or ecore_con_url_post() call.
+ * @remarks Some functions like ecore_con_url_time() also add headers to the request.
*
- * Some functions like ecore_con_url_time() also add headers to the request.
+ * @param[in] url_con The connection object
+ * @param[in] key The header key
+ * @param[in] value The header value
*
* @see ecore_con_url_get()
* @see ecore_con_url_post()
@@ -1446,88 +1551,92 @@ EAPI void * ecore_con_url_data_get(Ecore_Con_Url *url_con);
EAPI void ecore_con_url_additional_header_add(Ecore_Con_Url *url_con,
const char *key,
const char *value);
+
/**
- * Cleans additional headers.
+ * @brief Cleans additional headers.
*
- * @param url_con Connection object to clean additional headers.
+ * @details This function cleans additional headers associated with a connection object (previously
+ * added with ecore_con_url_additional_header_add()).
*
- * Cleans additional headers associated with a connection object (previously
- * added with ecore_con_url_additional_header_add()).
+ * @param[in] url_con The connection object to clean additional headers
*
* @see ecore_con_url_additional_header_add()
* @see ecore_con_url_get()
* @see ecore_con_url_post()
*/
EAPI void ecore_con_url_additional_headers_clear(Ecore_Con_Url *url_con);
+
/**
- * Retrieves headers from last request sent.
+ * @brief Gets headers from last request sent.
*
- * @param url_con Connection object to retrieve response headers from.
+ * @details This function retrieves a list containing the response headers. This function should be
+ * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
+ * ready at that time).
*
- * Retrieves a list containing the response headers. This function should be
- * used after an ECORE_CON_EVENT_URL_COMPLETE event (headers should normally be
- * ready at that time).
- *
- * @return List of response headers. This list must not be modified by the user.
+ * @param[in] url_con The connection object to retrieve response headers from
+ * @return The list of response headers \n
+ * This list must not be modified by the user.
*/
EAPI const Eina_List * ecore_con_url_response_headers_get(Ecore_Con_Url *url_con);
+
/**
- * Setup a file for receiving response data.
+ * @brief Sets up a file for receiving response data.
*
- * @param url_con Connection object to set file
- * @param fd File descriptor associated with the file. A negative value will
- * unset any previously set fd.
+ * @details This function sets up a file to have response data written into. Note that
+ * ECORE_CON_EVENT_URL_DATA events are not emitted if a file has been set to
+ * receive the response data.
*
- * Sets up a file to have response data written into. Note that
- * ECORE_CON_EVENT_URL_DATA events will not be emitted if a file has been set to
- * receive the response data.
+ * @remarks This function can be used to easily setup a file where the downloaded data
+ * is saved.
*
- * This call can be used to easily setup a file where the downloaded data will
- * be saved.
+ * @param[in] url_con The connection object to set file
+ * @param[in] fd The file descriptor associated with the file \n
+ * A negative value unsets any previously set @a fd.
*/
EAPI void ecore_con_url_fd_set(Ecore_Con_Url *url_con, int fd);
+
/**
- * Retrieves the number of bytes received.
- *
- * Retrieves the number of bytes received on the last request of the given
- * connection object.
+ * @brief Gets the number of bytes received.
*
- * @param url_con Connection object which the request was sent on.
+ * @details This function retrieves the number of bytes received on the last request of the given
+ * connection object.
*
- * @return Number of bytes received on request.
+ * @param[in] url_con The connection object which the request is sent on
+ * @return The number of bytes received on request
*
* @see ecore_con_url_get()
* @see ecore_con_url_post()
*/
EAPI int ecore_con_url_received_bytes_get(Ecore_Con_Url *url_con);
+
/**
- * Sets url_con to use http auth, with given username and password, "safely" or not.
- *
- * @param url_con Connection object to perform a request on, previously created
- * with ecore_con_url_new() or ecore_con_url_custom_new().
- * @param username Username to use in authentication
- * @param password Password to use in authentication
- * @param safe Whether to use "safer" methods (eg, NOT http basic auth)
+ * @brief Sets @a url_con to use http auth, with the given @a username and @a password, "safely" or not.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @remarks This function requires libcurl >= 7.19.1 to work. Otherwise it always returns @c 0.
*
- * @attention Requires libcurl >= 7.19.1 to work, otherwise will always return
- * @c 0.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * with ecore_con_url_new() or ecore_con_url_custom_new().
+ * @param[in] username The username to use in authentication
+ * @param[in] password The password to use in authentication
+ * @param[in] safe Set @c EINA_TRUE to use "safer" methods (eg, NOT http basic auth), \n
+ * otherwise set @c EINA_FALSE to not use it
+ * @return @c EINA_TRUE if it is set successfully,
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
const char *username,
const char *password,
Eina_Bool safe);
/**
- * Sends a get request.
+ * @brief Sends a get request.
*
- * @param url_con Connection object to perform a request on, previously created
+ * @remarks The request is performed immediately, but you need to setup event handlers
+ * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
+ * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
- *
- * The request is performed immediately, but you need to setup event handlers
- * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
- * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * @return @c EINA_TRUE if the request is sent successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_additional_headers_clear()
@@ -1539,24 +1648,27 @@ EAPI Eina_Bool ecore_con_url_httpauth_set(Ecore_Con_Url *url_con,
* @see ecore_con_url_post()
*/
EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
+
/**
- * Sends a post request.
+ * @brief Sends a post request.
*
- * @param url_con Connection object to perform a request on, previously created
- * with ecore_con_url_new() or ecore_con_url_custom_new().
- * @param data Payload (data sent on the request). Can be @c NULL.
- * @param length Payload length. If @c -1, rely on automatic length
- * calculation via @c strlen() on @p data.
- * @param content_type Content type of the payload (e.g. text/xml). Can be @c
- * NULL.
+ * @remarks The request starts immediately, but you need to setup event handlers
+ * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
+ * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @remarks This call does not block your main loop.
*
- * The request starts immediately, but you need to setup event handlers
- * for #ECORE_CON_EVENT_URL_DATA, #ECORE_CON_EVENT_URL_COMPLETE or
- * #ECORE_CON_EVENT_URL_PROGRESS to get more information about its result.
- *
- * This call won't block your main loop.
+ * @param[in] url_con The connection object to perform a request on, previously created
+ * with ecore_con_url_new() or ecore_con_url_custom_new().
+ * @param[in] data The payload (data sent on the request) \n
+ * This can be @c NULL.
+ * @param[in] length The payload length \n
+ * If this is @c -1, it relies on automatic length
+ * calculation via @c strlen() on @a data.
+ * @param[in] content_type The content type of the payload (e.g. text/xml) \n
+ * This can be @c NULL.
+ * @return @c EINA_TRUE if the request is sent successfully,
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_custom_new()
* @see ecore_con_url_additional_headers_clear()
@@ -1570,37 +1682,39 @@ EAPI Eina_Bool ecore_con_url_get(Ecore_Con_Url *url_con);
EAPI Eina_Bool ecore_con_url_post(Ecore_Con_Url *url_con,
const void *data, long length,
const char *content_type);
+
/**
- * Sets whether HTTP requests should be conditional, dependent on
- * modification time.
+ * @brief Sets whether HTTP requests should be conditional, dependent on
+ * modification time.
*
- * @param url_con Ecore_Con_Url to act upon.
- * @param time_condition Condition to use for HTTP requests.
- * @param timestamp Time since 1 Jan 1970 to use in the condition.
+ * @details This function may set the header "If-Modified-Since" or
+ * "If-Unmodified-Since", depending on the value of @a time_condition, with the
+ * value @a timestamp.
*
- * This function may set the header "If-Modified-Since" or
- * "If-Unmodified-Since", depending on the value of @p time_condition, with the
- * value @p timestamp.
+ * @param[in] url_con The Ecore_Con_Url to act upon
+ * @param[in] time_condition The condition to use for HTTP requests
+ * @param[in] timestamp The time since 1 Jan 1970 to use in the condition
*
- * @sa ecore_con_url_get()
- * @sa ecore_con_url_post()
+ * @see ecore_con_url_get()
+ * @see ecore_con_url_post()
*/
EAPI void ecore_con_url_time(Ecore_Con_Url *url_con,
Ecore_Con_Url_Time time_condition,
double timestamp);
/**
- * @brief Uploads a file to an ftp site.
+ * @brief Uploads a file to an FTP site.
*
- * @param url_con The Ecore_Con_Url object to send with
- * @param filename The path to the file to send
- * @param user The username to log in with
- * @param pass The password to log in with
- * @param upload_dir The directory to which the file should be uploaded
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
+ * @remarks Upload @a filename to an FTP server set in @a url_con using @a user
+ * and @a pass to directory @a upload_dir
*
- * Upload @p filename to an ftp server set in @p url_con using @p user
- * and @p pass to directory @p upload_dir
+ * @param[in] url_con The Ecore_Con_Url object to send with
+ * @param[in] filename The path to the file to send
+ * @param[in] user The username to log in with
+ * @param[in] pass The password to log in with
+ * @param[in] upload_dir The directory to which the file should be uploaded
+ * @return @c EINA_TRUE if the file is uploaded successfully, \n
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
const char *filename,
@@ -1608,173 +1722,178 @@ EAPI Eina_Bool ecore_con_url_ftp_upload(Ecore_Con_Url *url_con,
const char *pass,
const char *upload_dir);
/**
- * Toggle libcurl's verbose output.
+ * @brief Toggles libcurl's verbose output.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param verbose Whether or not to enable libcurl's verbose output.
+ * @remarks If @a verbose is @c EINA_TRUE, libcurl outputs a lot of verbose
+ * information about its operations, which is useful for
+ * debugging. The verbose information is sent to stderr.
*
- * If @p verbose is @c EINA_TRUE, libcurl will output a lot of verbose
- * information about its operations, which is useful for
- * debugging. The verbose information will be sent to stderr.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] verbose Set @c EINA_TRUE to enable libcurl's verbose output, \n
+ * otherwise @c EINA_FALSE to disable verbose output
*/
EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con,
Eina_Bool verbose);
+
/**
- * Enable or disable EPSV extension
- * @param url_con The Ecore_Con_Url instance which will be acted upon.
- * @param use_epsv Boolean to enable/disable the EPSV extension.
+ * @brief Enables or disables EPSV extension.
+ *
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] use_epsv Set @c EINA_TRUE to enable the EPSV extension, \n
+ * otherwise @c EINA_FALSE to disable it
*/
EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con,
Eina_Bool use_epsv);
/**
- * Enables the cookie engine for subsequent HTTP requests.
+ * @brief Enables the cookie engine for subsequent HTTP requests.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks After this function is called, cookies set by the server in HTTP responses
+ * are parsed and stored, as well as sent back to the server in new HTTP requests.
*
- * After this function is called, cookies set by the server in HTTP responses
- * will be parsed and stored, as well as sent back to the server in new HTTP
- * requests.
+ * @remarks Even though this function is called @c ecore_con_url_cookies_init(),
+ * there is no symmetrical shutdown operation.
*
- * @note Even though this function is called @c ecore_con_url_cookies_init(),
- * there is no symmetrical shutdown operation.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
*/
EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con);
+
/**
- * Controls whether session cookies from previous sessions shall be loaded.
+ * @brief Sets whether session cookies from previous sessions shall be loaded.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies
- * from files. If @c EINA_FALSE, all cookies will be loaded.
+ * @remarks Session cookies are cookies with no expire date set, which usually means
+ * they are removed after the current session is closed.
*
- * Session cookies are cookies with no expire date set, which usually means
- * they are removed after the current session is closed.
+ * @remarks By default, when Ecore_Con_Url loads cookies from a file, all cookies are
+ * loaded, including session cookies, which, most of the time, were supposed
+ * to be loaded and valid only for that session.
*
- * By default, when Ecore_Con_Url loads cookies from a file, all cookies are
- * loaded, including session cookies, which, most of the time, were supposed
- * to be loaded and valid only for that session.
+ * @remarks If @a ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
+ * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
+ * are not loaded.
*
- * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from
- * the files passed to @c ecore_con_url_cookies_file_add(), session cookies
- * will not be loaded.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] ignore Set @c EINA_TRUE to ignore session cookies when loading cookies from files, \n
+ * otherwise set @c EINA_FALSE to load all cookies
*
* @see ecore_con_url_cookies_file_add()
*/
EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con,
Eina_Bool ignore);
+
/**
- * Clears currently loaded cookies.
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @brief Clears currently loaded cookies.
*
- * The cleared cookies are removed and will not be sent in subsequent HTTP
- * requests, nor will they be written to the cookiejar file set via
- * @c ecore_con_url_cookies_jar_file_set().
+ * @remarks The cleared cookies are removed and not sent in subsequent HTTP
+ * requests, nor are they written to the cookiejar file set using
+ * @c ecore_con_url_cookies_jar_file_set().
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
- * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
- * immediately, just when the request is started. Thus, if you ask to
- * clear the cookies, but has a file already set by that function, the
- * cookies will then be loaded and you will have old cookies set. In order
- * to don't have any old cookie set, you need to don't call
- * ecore_con_url_cookies_file_add() ever on the @p url_con handler, and
- * call this function to clear any cookie set by a previous request on
- * this handler.
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
+ * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded
+ * immediately, just when the request is started. Thus, if you ask to
+ * clear the cookies, but has a file already set by that function, the
+ * cookies are then loaded and you have old cookies set. In order
+ * to not have any old cookie set, you need to not call
+ * ecore_con_url_cookies_file_add() ever on the @a url_con handler, and
+ * call this function to clear any cookie set by a previous request on
+ * this handler.
+ *
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
*
* @see ecore_con_url_cookies_session_clear()
* @see ecore_con_url_cookies_ignore_old_session_set()
*/
EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con);
+
/**
- * Clears currently loaded session cookies.
+ * @brief Clears currently loaded session cookies.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks Session cookies are cookies with no expire date set, which usually means
+ * they are removed after the current session is closed.
*
- * Session cookies are cookies with no expire date set, which usually means
- * they are removed after the current session is closed.
+ * @remarks The cleared cookies are removed and not sent in subsequent HTTP
+ * requests, nor are they be written to the cookiejar file set using
+ * @c ecore_con_url_cookies_jar_file_set().
*
- * The cleared cookies are removed and will not be sent in subsequent HTTP
- * requests, nor will they be written to the cookiejar file set via
- * @c ecore_con_url_cookies_jar_file_set().
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
+ * @remarks The cookie files set by ecore_con_url_cookies_file_add() are not loaded
+ * immediately, just when the request is started. Thus, if you ask to
+ * clear the session cookies, but has a file already set by that function,
+ * the session cookies are then loaded and you have old cookies
+ * set. In order to not have any old session cookie set, you need to
+ * not call ecore_con_url_cookies_file_add() ever on the @a url_con
+ * handler, and call this function to clear any session cookie set by a
+ * previous request on this handler. An easier way to not use old
+ * session cookies is by using the function
+ * ecore_con_url_cookies_ignore_old_session_set().
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
- * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded
- * immediately, just when the request is started. Thus, if you ask to
- * clear the session cookies, but has a file already set by that function,
- * the session cookies will then be loaded and you will have old cookies
- * set. In order to don't have any old session cookie set, you need to
- * don't call ecore_con_url_cookies_file_add() ever on the @p url_con
- * handler, and call this function to clear any session cookie set by a
- * previous request on this handler. An easier way to don't use old
- * session cookies is by using the function
- * ecore_con_url_cookies_ignore_old_session_set().
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
*
* @see ecore_con_url_cookies_clear()
* @see ecore_con_url_cookies_ignore_old_session_set()
*/
EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con);
+
/**
- * Adds a file to the list of files from which to load cookies.
- *
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param file_name Name of the file that will be added to the list.
+ * @brief Adds a file to the list of files from which to load cookies.
*
- * Files must contain cookies defined according to two possible formats:
+ * @remarks The files must contain cookies defined according to two possible formats:
+ * @li HTTP-style header ("Set-Cookie: ...").
+ * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
*
- * @li HTTP-style header ("Set-Cookie: ...").
- * @li <a href="http://www.cookiecentral.com/faq/#3.5">Netscape/Mozilla cookie data format.</a>
+ * @remarks Cookies are only @b read from this file. If you want to save cookies to a
+ * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
+ * function supports the both types of cookie file cited above, while
+ * ecore_con_url_cookies_jar_file_set() saves only in the Netscape/Mozilla's format.
*
- * Cookies will only be @b read from this file. If you want to save cookies to a
- * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this
- * function supports the both types of cookie file cited above, while
- * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's
- * format.
+ * @remarks Please notice that the file is not read immediately, but rather added
+ * to a list of files that is loaded and parsed at a later time.
*
- * Please notice that the file will not be read immediately, but rather added
- * to a list of files that will be loaded and parsed at a later time.
+ * @remarks This function initializes the cookie engine if it has not been
+ * initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
+ * @param[in] file_name The name of the file that is added to the list
*
* @see ecore_con_url_cookies_ignore_old_session_set()
* @see ecore_con_url_cookies_jar_file_set()
*/
EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con,
const char * const file_name);
+
/**
- * Sets the name of the file to which all current cookies will be written when
- * either cookies are flushed or Ecore_Con is shut down.
- *
- * @param url_con Ecore_Con_Url instance which will be acted upon.
- * @param cookiejar_file File to which the cookies will be written.
+ * @brief Sets the name of the file to which all current cookies are written when
+ * either cookies are flushed or Ecore_Con is shut down.
*
- * @return @c EINA_TRUE is the file name has been set successfully,
- * @c EINA_FALSE otherwise.
+ * @remarks Cookies are written following Netscape/Mozilla's data format, also known as
+ * cookie-jar.
*
- * Cookies are written following Netscape/Mozilla's data format, also known as
- * cookie-jar.
+ * @remarks Cookies are only @b saved to this file. If you need to read cookies from
+ * a file, use ecore_con_url_cookies_file_add() instead.
*
- * Cookies will only be @b saved to this file. If you need to read cookies from
- * a file, use ecore_con_url_cookies_file_add() instead.
+ * @remarks This function initializes the cookie engine if it has not been initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which are acted upon
+ * @param[in] cookiejar_file The file to which the cookies are written
+ * @return @c EINA_TRUE is the file name has been set successfully, \n
+ * otherwise @c EINA_FALSE on failure
*
* @see ecore_con_url_cookies_jar_write()
*/
EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con,
const char * const cookiejar_file);
+
/**
- * Writes all current cookies to the cookie jar immediately.
+ * @brief Writes all current cookies to the cookie jar immediately.
*
- * @param url_con Ecore_Con_Url instance which will be acted upon.
+ * @remarks A cookie-jar file must have been previously set by
+ * ecore_con_url_jar_file_set(), otherwise nothing is done.
*
- * A cookie-jar file must have been previously set by
- * @c ecore_con_url_jar_file_set, otherwise nothing will be done.
+ * @remarks This function initializes the cookie engine if it has not been initialized yet.
*
- * @note This function will initialize the cookie engine if it has not been
- * initialized yet.
+ * @param[in] url_con The Ecore_Con_Url instance which is acted upon
*
* @see ecore_con_url_cookies_jar_file_set()
*/
@@ -1786,81 +1905,86 @@ EAPI int ecore_con_url_ssl_ca_set(Ecore_Con_Url *url_con,
const char *ca_path);
/**
- * Set HTTP proxy to use.
- *
- * The parameter should be a char * to a zero terminated string holding
- * the host name or dotted IP address. To specify port number in this string,
- * append :[port] to the end of the host name.
- * The proxy string may be prefixed with [protocol]:// since any such prefix
- * will be ignored.
- * The proxy's port number may optionally be specified with the separate option.
- * If not specified, libcurl will default to using port 1080 for proxies.
+ * @brief Sets the HTTP proxy to use.
+ * @since 1.2
*
- * @param url_con Connection object that will use the proxy.
- * @param proxy Porxy string or @c NULL to disable
+ * @remarks The parameter should be a char * to a zero terminated string holding
+ * the host name or dotted IP address. To specify port number in this string,
+ * append :[port] to the end of the host name.
+ * The proxy string may be prefixed with [protocol]:// since any such prefix
+ * is ignored.
+ * The proxy's port number may optionally be specified with the separate option.
+ * If not specified, libcurl defaults to using port 1080 for proxies.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
- * @since 1.2
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] proxy The proxy string, \n
+ * otherwise set @c NULL to disable
+ * @return @c EINA_TRUE if the proxy is set successfully,
+ * otherwise @c EINA_FALSE on error
*/
EAPI Eina_Bool ecore_con_url_proxy_set(Ecore_Con_Url *url_con, const char *proxy);
/**
- * Set zero terminated username to use for proxy.
+ * @brief Sets zero terminated username to use for proxy.
+ * @since 1.2
*
- * if socks protocol is used for proxy, protocol should be socks5 and above.
+ * @remarks If socks protocol is used for proxy, protocol should be socks5 and above.
*
- * @param url_con Connection object that will use the proxy.
- * @param username Username string.
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] username The username string
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @return @c EINA_TRUE if the username is set successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_proxy_set()
*
- * @since 1.2
*/
EAPI Eina_Bool ecore_con_url_proxy_username_set(Ecore_Con_Url *url_con, const char *username);
/**
- * Set zero terminated password to use for proxy.
+ * @brief Sets zero terminated password to use for proxy.
+ * @since 1.2
*
- * if socks protocol is used for proxy, protocol should be socks5 and above.
+ * @remarks If socks protocol is used for proxy, protocol should be socks5 and above.
*
- * @param url_con Connection object that will use the proxy.
- * @param password Password string.
+ * @param[in] url_con The connection object that uses the proxy
+ * @param[in] password The password string
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE on error.
+ * @return @c EINA_TRUE if the password is set successfully, \n
+ * otherwise @c EINA_FALSE on error
*
* @see ecore_con_url_proxy_set()
*
- * @since 1.2
*/
EAPI Eina_Bool ecore_con_url_proxy_password_set(Ecore_Con_Url *url_con, const char *password);
/**
- * Set timeout in seconds.
+ * @brief Sets timeout in seconds.
*
- * the maximum time in seconds that you allow the ecore con url transfer
- * operation to take. Normally, name lookups can take a considerable time
- * and limiting operations to less than a few minutes risk aborting perfectly
- * normal operations.
+ * @since 1.2
*
- * @param url_con Connection object that will use the timeout.
- * @param timeout time in seconds.
+ * @remarks The maximum time in seconds that you allow the ecore_con_url_transfer
+ * operation to take. Normally, name lookups can take a considerable time
+ * and limiting operations to less than a few minutes risk aborting perfectly
+ * normal operations.
*
- * @see ecore_con_url_cookies_jar_file_set()
+ * @param[in] url_con The connection object that uses the timeout
+ * @param[in] timeout The time in seconds
*
- * @since 1.2
+ * @see ecore_con_url_cookies_jar_file_set()
*/
EAPI void ecore_con_url_timeout_set(Ecore_Con_Url *url_con, double timeout);
/**
- * Get the returned HTTP STATUS code
+ * @brief Gets the returned HTTP STATUS code.
+ * @since 1.2
*
- * This is used to, at any time, try to return the status code for a transmission.
- * @param url_con Connection object
- * @return A valid HTTP STATUS code, or 0 on failure
+ * @remarks This is used to try to return the status code for a transmission.
+ *
+ * @param[in] url_con The connection object
+ * @return A valid HTTP STATUS code, \n
+ * otherwise @c 0 on failure
*
- * @since 1.2
*/
EAPI int ecore_con_url_status_code_get(Ecore_Con_Url *url_con);
/**
diff --git a/src/lib/ecore_con/Ecore_Con_Eet.h b/src/lib/ecore_con/Ecore_Con_Eet.h
index a6c52bd328..bdf0d2d605 100644
--- a/src/lib/ecore_con/Ecore_Con_Eet.h
+++ b/src/lib/ecore_con/Ecore_Con_Eet.h
@@ -31,254 +31,43 @@
# 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_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h
index 82186e3035..d933203c92 100644..100755
--- a/src/lib/ecore_evas/Ecore_Evas.h
+++ b/src/lib/ecore_evas/Ecore_Evas.h
@@ -2,7 +2,8 @@
#define _ECORE_EVAS_H
#include <Evas.h>
-#include <Ecore_Evas_Types.h>
+#include <Ecore_Getopt.h>
+#include <Ecore_Input.h>
#ifdef EAPI
# undef EAPI
@@ -31,16 +32,9 @@
#endif /* ! _WIN32 */
/**
+ * @internal
* @file Ecore_Evas.h
* @brief Evas wrapper functions
- *
- * The following is a list of example that partially exemplify Ecore_Evas's API:
- * @li @ref ecore_evas_callbacks_example_c
- * @li @ref ecore_evas_object_example_c
- * @li @ref ecore_evas_basics_example_c
- * @li @ref Ecore_Evas_Window_Sizes_Example_c
- * @li @ref Ecore_Evas_Buffer_Example_01_c
- * @li @ref Ecore_Evas_Buffer_Example_02_c
*/
/* FIXME:
@@ -60,13 +54,14 @@ extern "C" {
#endif
/**
+ * @internal
* @defgroup Ecore_Evas_Group Ecore_Evas wrapper/helper set of functions
- * @ingroup Ecore
+ * @ingroup Ecore_Group
*
* Ecore evas is a set of functions that makes it easy to tie together ecore's
- * main loop and input handling to evas. As such it's a natural base for EFL
+ * main loop and input handling to evas. As such it is a natural base for EFL
* applications. While this combination makes it easy to create the basic
- * aspects all applications need, for normal applications(ones with buttons,
+ * aspects all applications need, for normal applications (ones with buttons,
* checkboxes and layouts) one should consider using Elementary.
*
* Ecore evas is extremely well suited for applications that are not based on
@@ -75,35 +70,25 @@ extern "C" {
* in conjunction with Edje or if doing custom drawing as, for example, is done
* in games.
*
- * This is a list of examples of these functions:
- * @li @ref ecore_evas_basics_example_c
- * @li @ref ecore_evas_object_example_c
- * @li @ref ecore_evas_callbacks_example_c
- * @li @ref Ecore_Evas_Window_Sizes_Example_c
- * @li @ref Ecore_Evas_Buffer_Example_01_c
- * @li @ref Ecore_Evas_Buffer_Example_02_c
- *
* @{
*/
-/* these are dummy and just tell u what API levels ecore_evas supports - not if
+/* These are dummy and just tells you what API levels ecore_evas supports - not
* the actual support is compiled in. You need to query for that separately.
*/
#define HAVE_ECORE_EVAS_X 1
#define HAVE_ECORE_EVAS_FB 1
#define HAVE_ECORE_EVAS_X11_GL 1
-//#define HAVE_ECORE_EVAS_X11_16 1
-//#define HAVE_ECORE_EVAS_DIRECTFB 1
+#define HAVE_ECORE_EVAS_X11_16 1
+#define HAVE_ECORE_EVAS_DIRECTFB 1
#define HAVE_ECORE_EVAS_WIN32 1
#define HAVE_ECORE_EVAS_COCOA 1
#define HAVE_ECORE_EVAS_SDL 1
-//#define HAVE_ECORE_EVAS_WINCE 1
+#define HAVE_ECORE_EVAS_WINCE 1
#define HAVE_ECORE_EVAS_EWS 1
#define HAVE_ECORE_EVAS_PSL1GHT 1
#define HAVE_ECORE_EVAS_WAYLAND_SHM 1
#define HAVE_ECORE_EVAS_WAYLAND_EGL 1
-#define HAVE_ECORE_EVAS_DRM 1
-#define HAVE_ECORE_EVAS_DRM_GL 1
typedef enum _Ecore_Evas_Engine_Type
{
@@ -129,9 +114,7 @@ typedef enum _Ecore_Evas_Engine_Type
ECORE_EVAS_ENGINE_EWS,
ECORE_EVAS_ENGINE_PSL1GHT,
ECORE_EVAS_ENGINE_WAYLAND_SHM,
- ECORE_EVAS_ENGINE_WAYLAND_EGL,
- ECORE_EVAS_ENGINE_DRM,
- ECORE_EVAS_ENGINE_OPENGL_DRM
+ ECORE_EVAS_ENGINE_WAYLAND_EGL
} Ecore_Evas_Engine_Type;
typedef enum _Ecore_Evas_Avoid_Damage_Type
@@ -149,26 +132,63 @@ typedef enum _Ecore_Evas_Object_Associate_Flags
ECORE_EVAS_OBJECT_ASSOCIATE_DEL = 1 << 2
} Ecore_Evas_Object_Associate_Flags;
+#ifndef _ECORE_X_H
+#define _ECORE_X_WINDOW_PREDEF
+typedef unsigned int Ecore_X_Window;
+typedef unsigned int Ecore_X_Pixmap;
+#endif
+
+#ifndef _ECORE_DIRECTFB_H
+#define _ECORE_DIRECTFB_WINDOW_PREDEF
+typedef struct _Ecore_DirectFB_Window Ecore_DirectFB_Window;
+#endif
+
+#ifndef __ECORE_WIN32_H__
+typedef struct _Ecore_Win32_Window Ecore_Win32_Window;
+#endif
+
+#ifndef __ECORE_WINCE_H__
+typedef struct _Ecore_WinCE_Window Ecore_WinCE_Window;
+#endif
+
+#ifndef __ECORE_COCOA_H__
+typedef struct _Ecore_Cocoa_Window Ecore_Cocoa_Window;
+#endif
+
+#ifndef _ECORE_EVAS_PRIVATE_H
+/* Basic data types */
+typedef struct _Ecore_Evas Ecore_Evas;
+typedef void (*Ecore_Evas_Event_Cb) (Ecore_Evas *ee); /**< Callback used for several ecore evas events @since 1.2 */
+#endif
+
+#ifndef _ECORE_WAYLAND_H_
+#define _ECORE_WAYLAND_WINDOW_PREDEF
+typedef struct _Ecore_Wl_Window Ecore_Wl_Window;
+#endif
+
/* module setup/shutdown calls */
EAPI int ecore_evas_engine_type_supported_get(Ecore_Evas_Engine_Type engine);
/**
- * @brief Init the Ecore_Evas system.
+ * @brief Initializes the Ecore_Evas system.
*
- * @return How many times the lib has been initialized, 0 indicates failure.
+ * @details This function sets up the Evas wrapper system - initializes Evas and Ecore libraries.
*
- * Set up the Evas wrapper system. Init Evas and Ecore libraries.
+ * @return The number of time the lib has been initialized, \n
+ * otherwise @c 0 on failure
*
* @see ecore_evas_shutdown()
*/
EAPI int ecore_evas_init(void);
+
/**
- * @brief Shut down the Ecore_Evas system.
+ * @brief Shuts down the Ecore_Evas system.
*
- * @return 0 if ecore evas is fully shut down, or > 0 if it still being used.
+ * @details This function closes the Evas wrapper system down - shuts down Evas and Ecore libraries.
*
- * This closes the Evas wrapper system down. Shut down Evas and Ecore libraries.
+ * @return @c 0 if ecore evas is fully shut down, \n
+ * otherwise > @c 0 if it still being used
*
* @see ecore_evas_init()
*/
@@ -178,723 +198,716 @@ EAPI void ecore_evas_app_comp_sync_set(Eina_Bool do_sync);
EAPI Eina_Bool ecore_evas_app_comp_sync_get(void);
/**
- * @brief Returns a list of supported engines names.
+ * @brief Gets a list of supported engines names.
*
- * @return Newly allocated list with engines names. Engines names
- * strings are internal and should be considered constants, do not
- * free or modify them, to free the list use ecore_evas_engines_free().
+ * @return The newly allocated list with engines names \n
+ * Engines names strings are internal and should be
+ * considered constants, do not free or modify them,
+ * to free the list use ecore_evas_engines_free().
*/
EAPI Eina_List *ecore_evas_engines_get(void);
+
/**
- * @brief Free list returned by ecore_evas_engines_get()
+ * @brief Frees the list returned by ecore_evas_engines_get().
*
- * @param engines list with engines names
+ * @param[in] engines The list with engines names
*/
EAPI void ecore_evas_engines_free(Eina_List *engines);
+
/**
- * @brief Creates a new Ecore_Evas based on engine name and common parameters.
- *
- * @param engine_name engine name as returned by
- * ecore_evas_engines_get() or @c NULL to use environment variable
- * ECORE_EVAS_ENGINE, that can be undefined and in this case
- * this call will try to find the first working engine.
- * @param x horizontal position of window (not supported in all engines)
- * @param y vertical position of window (not supported in all engines)
- * @param w width of window
- * @param h height of window
- * @param extra_options string with extra parameter, dependent on engines
- * or @ NULL. String is usually in the form: 'key1=value1;key2=value2'.
- * Pay attention that when getting that from shell commands, most
- * consider ';' as the command terminator, so you need to escape
- * it or use quotes.
- *
- * @return Ecore_Evas instance or @c NULL if creation failed.
+ * @brief Creates a new Ecore_Evas based on engine name and common parameters.
+ *
+ * @param[in] engine_name The engine name as returned by ecore_evas_engines_get(), \n
+ * otherwise set @c NULL to use environment variable @a ECORE_EVAS_ENGINE \n
+ * This can be undefined and in this case this call tries
+ * to find the first working engine.
+ * @param[in] x The horizontal position of window (not supported in all engines)
+ * @param[in] y The vertical position of window (not supported in all engines)
+ * @param[in] w The width of window
+ * @param[in] h The height of window
+ * @param[in] extra_options The string with extra parameter, dependent on engines or @ NULL \n
+ * The string is usually in the form: 'key1=value1;key2=value2'.
+ * Pay attention that when getting that from shell commands, most
+ * consider ';' as the command terminator, so you need to escape
+ * it or use quotes.
+ * @return The Ecore_Evas instance, \n
+ * otherwise @c NULL on failure
*/
EAPI Ecore_Evas *ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options);
+
/**
- * @brief Set whether an Ecore_Evas has an alpha channel or not.
+ * @brief Sets whether an Ecore_Evas has an alpha channel or not.
*
- * @param ee The Ecore_Evas to shape
- * @param alpha @c EINA_TRUE to enable the alpha channel, @c EINA_FALSE to
- * disable it
+ * @details This function allows you to make an Ecore_Evas translucent using an
+ * alpha channel. See ecore_evas_shaped_set() for details. The difference
+ * between a shaped window and a window with an alpha channel is that an
+ * alpha channel supports multiple levels of transparency, as opposed to
+ * the @c 1 bit transparency of a shaped window (a pixel is either opaque, or
+ * it is transparent).
*
- * This function allows you to make an Ecore_Evas translucent using an
- * alpha channel. See ecore_evas_shaped_set() for details. The difference
- * between a shaped window and a window with an alpha channel is that an
- * alpha channel supports multiple levels of transparency, as opposed to
- * the 1 bit transparency of a shaped window (a pixel is either opaque, or
- * it's transparent).
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to shape
+ * @param[in] alpha Set @c EINA_TRUE to enable the alpha channel, \n
+ * otherwise @c EINA_FALSE to disable it
*/
EAPI void ecore_evas_alpha_set(Ecore_Evas *ee, Eina_Bool alpha);
+
/**
- * @brief Query whether an Ecore_Evas has an alpha channel.
- * @param ee The Ecore_Evas to query.
- * @return @c EINA_TRUE if ee has an alpha channel, @c EINA_FALSE if it does
- * not.
+ * @brief Checks whether an Ecore_Evas has an alpha channel.
*
- * This function returns @c EINA_TRUE if @p ee has an alpha channel, and
- * @c EINA_FALSE if it does not.
+ * @remarks This function returns @c EINA_TRUE if @a ee has an alpha channel, and
+ * @c EINA_FALSE if it does not.
+ *
+ * @param[in] ee The Ecore_Evas to query
+ * @return @c EINA_TRUE if @a ee has an alpha channel, \n
+ * otherwise @c EINA_FALSE if it does not
*
* @see ecore_evas_alpha_set()
*/
EAPI Eina_Bool ecore_evas_alpha_get(const Ecore_Evas *ee);
+
/**
- * @brief Set whether an Ecore_Evas has an transparent window or not.
+ * @brief Sets whether an Ecore_Evas has an transparent window or not.
*
- * @param ee The Ecore_Evas to shape
- * @param transparent @c EINA_TRUE to enable the transparent window,
- * @c EINA_FALSE to disable it
+ * @details This function sets some translucency options.
*
- * This function sets some translucency options, for more complete support see
- * ecore_evas_alpha_set().
+ * @remarks For more complete support see ecore_evas_alpha_set().
*
- * @warning Support for this depends on the underlying windowing system.
+ * @remarks Support for this depends on the underlying windowing system.
+ *
+ * @param[in] ee The Ecore_Evas to shape
+ * @param[in] transparent @c EINA_TRUE to enable the transparent window, \n
+ * otherwise @c EINA_FALSE to disable it
*
* @see ecore_evas_alpha_set()
*/
EAPI void ecore_evas_transparent_set(Ecore_Evas *ee, Eina_Bool transparent);
+
/**
- * @brief Query whether an Ecore_Evas is transparent.
+ * @brief Checks whether an Ecore_Evas is transparent.
*
- * @param ee The Ecore_Evas to query.
- * @return @c EINA_TRUE if ee is transparent, @c EINA_FALSE if it isn't.
+ * @param[in] ee The Ecore_Evas to query
+ * @return @c EINA_TRUE if ee is transparent, \n
+ * otherwise @c EINA_FALSE if it is not
*
* @see ecore_evas_transparent_set()
*/
EAPI Eina_Bool ecore_evas_transparent_get(const Ecore_Evas *ee);
+
/**
- * @brief Get the geometry of an Ecore_Evas.
+ * @brief Gets the geometry of an Ecore_Evas.
*
- * @param ee The Ecore_Evas whose geometry y
- * @param x A pointer to an int to place the x coordinate in
- * @param y A pointer to an int to place the y coordinate in
- * @param w A pointer to an int to place the w size in
- * @param h A pointer to an int to place the h size in
- *
- * This function takes four pointers to (already allocated) ints, and places
- * the geometry of @p ee in them. If any of the parameters is not desired you
- * may pass @c NULL on them.
+ * @details This function takes four pointers to (already allocated) int, and places
+ * the geometry of @a ee in them. If any of the parameters is not desired, you
+ * may pass @c NULL on them.
*
* @code
* int x, y, w, h;
* ecore_evas_geometry_get(ee, &x, &y, &w, &h);
* @endcode
*
+ * @param[in] ee The Ecore_Evas whose geometry y
+ * @param[out] x A pointer to an int to place the x coordinate in
+ * @param[out] y A pointer to an int to place the y coordinate in
+ * @param[out] w A pointer to an int to place the w size in
+ * @param[out] h A pointer to an int to place the h size in
+ *
* @see ecore_evas_new()
* @see ecore_evas_resize()
* @see ecore_evas_move()
* @see ecore_evas_move_resize()
*/
EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h);
+
/**
- * @brief Get the geometry which an Ecore_Evas was latest recently requested.
+ * @brief Gets the geometry recently requested by an Ecore_Evas.
*
- * @param ee The Ecore_Evas whose geometry y
- * @param x A pointer to an int to place the x coordinate in
- * @param y A pointer to an int to place the y coordinate in
- * @param w A pointer to an int to place the w size in
- * @param h A pointer to an int to place the h size in
- *
- * This function takes four pointers to (already allocated) ints, and places
- * the geometry which @p ee was latest recently requested . If any of the
- * parameters is not desired you may pass @c NULL on them.
- * This function can represent recently requested geometry.
- * ecore_evas_geometry_get function returns the value is updated after engine
- * finished request. By comparison, ecore_evas_request_geometry_get returns
- * recently requested value.
+ * @details This function takes four pointers to (already allocated) ints, and places
+ * the geometry which @a ee recently requested. If any of the
+ * parameters is not desired, you may pass @c NULL on them.
+ * This function can represent the recently requested geometry.
+ * The ecore_evas_geometry_get function returns the value that is updated after engine
+ * finished the request. By comparison, ecore_evas_request_geometry_get returns
+ * the recently requested value.
+ * @since 1.1
*
* @code
* int x, y, w, h;
* ecore_evas_request_geometry_get(ee, &x, &y, &w, &h);
* @endcode
*
- * @since 1.1
+ * @param[in] ee The Ecore_Evas whose geometry y
+ * @param[out] x A pointer to an int to place the x coordinate in
+ * @param[out] y A pointer to an int to place the y coordinate in
+ * @param[out] w A pointer to an int to place the w size in
+ * @param[out] h A pointer to an int to place the h size in
*/
EAPI void ecore_evas_request_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h);
+
/**
- * @brief Set the focus of an Ecore_Evas' window.
+ * @brief Sets the focus of an Ecore_Evas' window.
*
- * @param ee The Ecore_Evas
- * @param on @c EINA_TRUE for focus, @c EINA_FALSE to defocus.
+ * @details This function focuses @a ee if @a on is @c EINA_TRUE,
+ * or unfocuses @a ee if @a on is @c EINA_FALSE.
*
- * This function focuses @p ee if @p on is @c EINA_TRUE, or unfocuses @p ee if
- * @p on is @c EINA_FALSE.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE for focus, \n
+ * otherwise set @c EINA_FALSE to defocus
*/
EAPI void ecore_evas_focus_set(Ecore_Evas *ee, Eina_Bool on);
+
/**
- * @brief Query whether an Ecore_Evas' window is focused or not.
+ * @brief Checks whether an Ecore_Evas' window is focused.
*
- * @param ee The Ecore_Evas to set
- * @return @c EINA_TRUE if @p ee if focused, @c EINA_FALSE if not.
+ * @param[in] ee The Ecore_Evas to check
+ * @return @c EINA_TRUE if @a ee is focused, \n
+ * otherwise @c EINA_FALSE if it is not focused.
*
* @see ecore_evas_focus_set()
*/
EAPI Eina_Bool ecore_evas_focus_get(const Ecore_Evas *ee);
+
/**
- * @brief Iconify or uniconify an Ecore_Evas' window.
+ * @brief Iconifies or uniconifies an Ecore_Evas' window.
*
- * @param ee The Ecore_Evas
- * @param on @c EINA_TRUE to iconify, @c EINA_FALSE to uniconify.
+ * @details This function iconifies @a ee if @a on is @c EINA_TRUE, or uniconifies @a ee
+ * if @a on is @c EINA_FALSE.
*
- * This function iconifies @p ee if @p on is @c EINA_TRUE, or uniconifies @p ee
- * if @p on is @c EINA_FALSE.
+ * @remarks Iconify and minimize are synonyms.
*
- * @note Iconify and minimize are synonyms.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE to iconify, \n
+ * otherwise set @c EINA_FALSE to uniconify
*/
EAPI void ecore_evas_iconified_set(Ecore_Evas *ee, Eina_Bool on);
+
/**
- * @brief Query whether an Ecore_Evas' window is iconified or not.
+ * @brief Checks whether an Ecore_Evas' window is iconified.
*
- * @param ee The Ecore_Evas to set
- * @return @c EINA_TRUE if @p ee is iconified, @c EINA_FALSE if not.
+ * @remarks Iconify and minimize are synonyms.
*
- * @note Iconify and minimize are synonyms.
+ * @param[in] ee The Ecore_Evas to check
+ * @return @c EINA_TRUE if @a ee is iconified, \n
+ * otherwise @c EINA_FALSE if it is not iconified
*
* @see ecore_evas_iconified_set()
*/
EAPI Eina_Bool ecore_evas_iconified_get(const Ecore_Evas *ee);
+
/**
- * @brief Set whether an Ecore_Evas' window is borderless or not.
+ * @brief Sets whether an Ecore_Evas' window is borderless or not.
*
- * @param ee The Ecore_Evas
- * @param on @c EINA_TRUE for borderless, @c EINA_FALSE for bordered.
+ * @details This function makes @a ee borderless if @a on is @c EINA_TRUE, or bordered
+ * if @a on is @c EINA_FALSE.
*
- * This function makes @p ee borderless if @p on is @c EINA_TRUE, or bordered
- * if @p on is @c EINA_FALSE.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE for borderless, \n
+ * otherwise set @c EINA_FALSE for bordered
*/
EAPI void ecore_evas_borderless_set(Ecore_Evas *ee, Eina_Bool on);
+
/**
- * @brief Query whether an Ecore_Evas' window is borderless or not.
+ * @brief Checks whether an Ecore_Evas' window is borderless.
*
- * @param ee The Ecore_Evas to set
- * @return @c EINA_TRUE if @p ee is borderless, @c EINA_FALSE if not.
+ * @param[in] ee The Ecore_Evas to check
+ * @return @c EINA_TRUE if @a ee is borderless, \n
+ * otherwise @c EINA_FALSE if it is not borderless
*
* @see ecore_evas_borderless_set()
*/
EAPI Eina_Bool ecore_evas_borderless_get(const Ecore_Evas *ee);
+
/**
- * @brief Set whether or not an Ecore_Evas' window is fullscreen.
+ * @brief Sets whether or not an Ecore_Evas' window is fullscreen.
*
- * @param ee The Ecore_Evas
- * @param on @c EINA_TRUE fullscreen, @c EINA_FALSE not.
+ * @details This function causes @a ee to be fullscreen if @a on is @c EINA_TRUE, and
+ * not to be fullscreen if @a on is @c EINA_FALSE.
*
- * This function causes @p ee to be fullscreen if @p on is @c EINA_TRUE, or
- * not if @p on is @c EINA_FALSE.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE for fullscreen, \n
+ * otherwise set @c EINA_FALSE
*/
EAPI void ecore_evas_fullscreen_set(Ecore_Evas *ee, Eina_Bool on);
+
/**
- * @brief Query whether an Ecore_Evas' window is fullscreen or not.
+ * @brief Checks whether an Ecore_Evas' window is fullscreen.
*
- * @param ee The Ecore_Evas to set
- * @return @c EINA_TRUE if @p ee is fullscreen, @c EINA_FALSE if not.
+ * @param[in] ee The Ecore_Evas to check
+ * @return @c EINA_TRUE if @a ee is fullscreen, \n
+ * otherwise @c EINA_FALSE if it is not fullscreen
*
* @see ecore_evas_fullscreen_set()
*/
EAPI Eina_Bool ecore_evas_fullscreen_get(const Ecore_Evas *ee);
+
/**
- * @brief Set another window that this window is a group member of
+ * @brief Sets another window that this window is a group member of.
+ * @since 1.2
*
- * @param ee The Ecore_Evas
- * @param ee_group The other group member
+ * @remarks If @a ee_group is @c NULL, @a ee is removed from the group, otherwise it is
+ * added. Note that if you free the @a ee_group canvas before @a ee, then
+ * getting the group canvas with ecore_evas_window_group_get() returns
+ * an invalid handle.
*
- * If @p ee_group is @c NULL, @p ee is removed from the group, otherwise it is
- * added. Note that if you free the @p ee_group canvas before @p ee, then
- * getting the group canvas with ecore_evas_window_group_get() will return
- * an invalid handle.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] ee_group The other group member
*/
EAPI void ecore_evas_window_group_set(Ecore_Evas *ee, const Ecore_Evas *ee_group);
+
/**
- * @brief Get the canvas group set.
+ * @brief Gets the canvas group that is set.
+ * @details This returns the handle set by ecore_evas_window_group_set().
*
- * This returns the handle set by ecore_evas_window_group_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The Canvas group handle
+ * @param[in] ee The Ecore_Evas
+ * @return The Canvas group handle
*
* @see ecore_evas_window_group_set()
- * @since 1.2
*/
EAPI const Ecore_Evas *ecore_evas_window_group_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the aspect ratio of a canvas window
+ * @brief Sets the aspect ratio of a canvas window.
*
- * @param ee The Ecore_Evas
- * @param aspect The aspect ratio (width divided by height), or 0 to disable
+ * @details This function sets the desired aspect ratio of a canvas window.
+ * @since 1.2
*
- * This sets the desired aspect ratio of a canvas window
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] aspect The aspect ratio (width divided by height), \n
+ * otherwise set @c 0 to disable
*/
EAPI void ecore_evas_aspect_set(Ecore_Evas *ee, double aspect);
+
/**
- * @brief Get the aspect ratio of a canvas window
+ * @brief Gets the aspect ratio of a canvas window.
*
- * This returns the value set by ecore_evas_aspect_set().
+ * @details This function returns the value set by ecore_evas_aspect_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The aspect ratio
+ * @param[in] ee The Ecore_Evas to set
+ * @return The aspect ratio
*
* @see ecore_evas_aspect_set()
- * @since 1.2
*/
EAPI double ecore_evas_aspect_get(const Ecore_Evas *ee);
+
/**
- * @brief Set The urgent hint flag
+ * @brief Sets the urgent hint flag.
*
- * @param ee The Ecore_Evas
- * @param urgent The urgent state flag
+ * @details This function sets the "urgent" state hint on a window so that the desktop environment
+ * can highlight it somehow.
+ * @since 1.2
*
- * This sets the "urgent" state hint on a window so the desktop environment
- * can highlight it somehow.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] urgent Set @c EINA_TRUE to set the urgent state flag, \n
+ * otherwise set @c EINA_FALSE to not set it
*/
EAPI void ecore_evas_urgent_set(Ecore_Evas *ee, Eina_Bool urgent);
+
/**
- * @brief Get the urgent state on the cavas window
+ * @brief Gets the urgent state on the canvas window.
*
- * This returns the value set by ecore_evas_urgent_set()
+ * @details This returns the value set by ecore_evas_urgent_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The urgent state set
+ * @param[in] ee The Ecore_Evas to set
+ * @return @c EINA_TRUE if the urgent state is set, \n
+ * otherwise @c EINA_FALSE if it is not set
*
* @see ecore_evas_urgent_set()
- * @since 1.2
*/
EAPI Eina_Bool ecore_evas_urgent_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the modal state flag on the canvas window
+ * @brief Sets the modal state flag on the canvas window.
*
- * @param ee The Ecore_Evas
- * @param modal The modal hint flag
+ * @details This function hints if the window should be modal (for example, if it is also transient
+ * for another window, the other window maybe be denied focus by
+ * the desktop window manager).
+ * @since 1.2
*
- * This hints if the window should be modal (eg if it is also transient
- * for another window, the other window will maybe be denied focus by
- * the desktop window manager).
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] modal Set @c EINA_TRUE to set the window as modal, \n
+ * otherwise set @c EINA_FALSE to set the window as not modal
*/
EAPI void ecore_evas_modal_set(Ecore_Evas *ee, Eina_Bool modal);
+
/**
- * @brief Get The modal flag
+ * @brief Checks whether the modal flag is set.
*
- * This returns the value set by ecore_evas_modal_set().
+ * @details This returns the value set by ecore_evas_modal_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The modal flag
+ * @param[in] ee The Ecore_Evas
+ * @return @c EINA_TRUE if the window is modal, \n
+ * otherwise @c EINA_FALSE if the window is not modal
*
* @see ecore_evas_modal_set()
- * @since 1.2
*/
EAPI Eina_Bool ecore_evas_modal_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the "i demand attention" flag on a canvas window
+ * @brief Sets the "i demand attention" flag on a canvas window.
+ * @since 1.2
*
- * @param ee The Ecore_Evas
- * @param demand The flag state to set
+ * @remarks A window may demand attention (for example, you must enter a password before
+ * continuing), and so you may flag a window with this function.
*
- * A window may demand attention now (eg you must enter a password before
- * continuing), and so it may flag a window with this.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] demand Set @c EINA_TRUE to set the flag, \n
+ * otherwise set @c EINA_FALSE to not set the flag
*/
EAPI void ecore_evas_demand_attention_set(Ecore_Evas *ee, Eina_Bool demand);
+
/**
- * @brief Get the "i demand attention" flag
+ * @brief Checks whether the "i demand attention" flag is set.
*
- * This returns the value set by ecore_evas_demand_attention_set().
+ * @details This function returns the value set by ecore_evas_demand_attention_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The "i demand attention" flag.
+ * @param[in] ee The Ecore_Evas
+ * @return @c EINA_TRUE if the "i demand attention" flag is set, \n
+ * otherwise @c EINA_FALSE if the flag is not set
*
* @see ecore_evas_demand_attention_set()
- * @since 1.2
*/
EAPI Eina_Bool ecore_evas_demand_attention_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the "focus skip" flag
+ * @brief Sets the "focus skip" flag.
+ * @since 1.2
*
- * @param ee The Ecore_Evas
- * @param skip The "focus skip" state to set.
+ * @remarks A window may not want to accept focus, be in the taskbar or pager
+ * sometimes (example for a small notification window that hovers around
+ * a taskbar or panel, or hovers around a window until some activity
+ * dismisses it).
*
- * A window may not want to accept focus, be in the taskbar, pager etc.
- * sometimes (example for a small notification window that hovers around
- * a taskbar or panel, or hovers around a window until some activity
- * dismisses it).
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.2
+ * @param[in] ee The Ecore_Evas
+ * @param[in] skip Set @c EINA_TRUE to set the "focus skip", \n
+ * otherwise @c EINA_FALSE to not set the flag
*/
EAPI void ecore_evas_focus_skip_set(Ecore_Evas *ee, Eina_Bool skip);
+
/**
- * @brief Get the "focus skip" flag
+ * @brief Checks whether the "focus skip" flag is set.
*
- * This returns the value set by ecore_evas_focus_skip_set().
+ * @details This returns the value set by ecore_evas_focus_skip_set().
+ * @since 1.2
*
- * @param ee The Ecore_Evas to set
- * @return The "focus skip" flag.
+ * @param[in] ee The Ecore_Evas to set
+ * @return @c EINA_TRUE if the "focus skip" flag is set, \n
+ * otherwise @c EINA_FALSE if the flag is not set
*
* @see ecore_evas_focus_skip_set()
- * @since 1.2
*/
EAPI Eina_Bool ecore_evas_focus_skip_get(const Ecore_Evas *ee);
/**
- * @brief Set if this evas should ignore @b all events.
+ * @brief Sets whether this evas should ignore @b all events.
*
- * @param ee The Ecore_Evas whose window's to ignore events.
- * @param ignore The Ecore_Evas new ignore state.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] ignore Set @c EINA_TRUE for Ecore_Evas to ignore events, \n
+ * otherwise @c EINA_FALSE to not ignore the events
*/
EAPI void ecore_evas_ignore_events_set(Ecore_Evas *ee, Eina_Bool ignore);
+
/**
- * @brief Returns the ignore state of an Ecore_Evas' window.
+ * @brief Checks whether the ignore state of the Ecore_Evas window is set.
*
- * @param ee The Ecore_Evas whose window's ignore events state is returned.
- * @return The Ecore_Evas window's ignore state.
+ * @param[in] ee The Ecore_Evas
+ * @return @c EINA_TRUE if ignore state is set, \n
+ * otherwise @c EINA_FALSE if the ignore state is not set
*
* @see ecore_evas_ignore_events_set()
*/
EAPI Eina_Bool ecore_evas_ignore_events_get(const Ecore_Evas *ee);
+
/**
- * @brief Query whether an Ecore_Evas' window is visible or not.
+ * @brief Checks whether an Ecore_Evas window is visible.
*
- * @param ee The Ecore_Evas to query.
- * @return 1 if visible, 0 if not.
+ * @details This function queries @a ee and returns @c 1 if it is visible,
+ * and @c 0 if it is not visible.
*
- * This function queries @p ee and returns 1 if it is visible, and 0 if not.
+ * @param[in] ee The Ecore_Evas to query
+ * @return @c 1 if the window visible, \n
+ * otherwise @c 0 if it is not visible
*
* @see ecore_evas_show()
* @see ecore_evas_hide()
*/
EAPI int ecore_evas_visibility_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the layer of an Ecore_Evas' window.
+ * @brief Sets the layer of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas
- * @param layer The layer to put @p ee on.
+ * @details This function moves @a ee to the layer @a layer.
*
- * This function moves @p ee to the layer @p layer.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] layer The layer to put @a ee on
*
* @see ecore_evas_lower()
* @see ecore_evas_raise()
*/
EAPI void ecore_evas_layer_set(Ecore_Evas *ee, int layer);
+
/**
- * @brief Get the layer of an Ecore_Evas' window.
+ * @brief Gets the layer of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas to set
- * @return the layer @p ee's window is on.
+ * @param[in] ee The Ecore_Evas to set
+ * @return The layer @a ee's window is on
*
* @see ecore_evas_layer_set()
* @see ecore_evas_lower()
* @see ecore_evas_raise()
*/
EAPI int ecore_evas_layer_get(const Ecore_Evas *ee);
+
/**
- * @brief Maximize (or unmaximize) an Ecore_Evas' window.
+ * @brief Maximizes (or unmaximizes) an Ecore_Evas window.
*
- * @param ee The Ecore_Evas
- * @param on @c EINA_TRUE to maximize, @c EINA_FALSE to unmaximize.
+ * @details This function maximizes @a ee if @a on is @c EINA_TRUE,
+ * or unmaximizes @a ee if @a on is @c EINA_FALSE.
*
- * This function maximizes @p ee if @p on is @c EINA_TRUE, or unmaximizes @p ee
- * if @p on is @c EINA_FALSE.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE to maximize, \n
+ * otherwise set @c EINA_FALSE to unmaximize
*/
EAPI void ecore_evas_maximized_set(Ecore_Evas *ee, Eina_Bool on);
+
/**
- * @brief Query whether an Ecore_Evas' window is maximized or not.
+ * @brief Checks whether an Ecore_Evas window is maximized.
*
- * @param ee The Ecore_Evas to set
- * @return @c EINA_TRUE if @p ee is maximized, @c EINA_FALSE if not.
+ * @param[in] ee The Ecore_Evas to set
+ * @return @c EINA_TRUE if @a ee is maximized, \n
+ * otherwise @c EINA_FALSE if is not maximized
*
* @see ecore_evas_maximized_set()
*/
EAPI Eina_Bool ecore_evas_maximized_get(const Ecore_Evas *ee);
+
/**
- * @brief Query if the underlying windowing system supports the window profile.
- *
- * @param ee The Ecore_Evas
- * @return @c EINA_TRUE if the window profile is supported, @c EINA_FALSE otherwise.
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
- */
-EAPI Eina_Bool ecore_evas_window_profile_supported_get(const Ecore_Evas *ee);
-/**
- * @brief Set the window profile
- *
- * @param ee The Ecore_Evas to set
- * @param profile The string value of the window profile
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
- */
-EAPI void ecore_evas_window_profile_set(Ecore_Evas *ee, const char *profile);
-/**
- * @brief Get the window profile
- *
- * @param ee The Ecore_Evas to get the window profile from.
- * @return The string value of the window profile, or NULL if none exists
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
- */
-EAPI const char *ecore_evas_window_profile_get(const Ecore_Evas *ee);
-/**
- * @brief Set the array of available window profiles
- *
- * @param ee The Ecore_Evas to set
- * @param profiles The string array of available window profiels
- * @param count The number of members in profiles
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
- */
-EAPI void ecore_evas_window_available_profiles_set(Ecore_Evas *ee, const char **profiles, const unsigned int count);
-/**
- * @brief Get the array of available window profiles
- *
- * @param ee The Ecore_Evas to get available window profiles from.
- * @param profiles Where to return the string array of available window profiles
- * @param count Where to return the number of members in profiles
- * @return EINA_TRUE if available window profiles exist, EINA_FALSE otherwise
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
- */
-EAPI Eina_Bool ecore_evas_window_available_profiles_get(Ecore_Evas *ee, char ***profiles, unsigned int *count);
-/**
- * @brief Query if the underlying windowing system supports the window manager rotation.
- *
- * @param ee The Ecore_Evas
- * @return @c EINA_TRUE if the window manager rotation is supported, @c EINA_FALSE otherwise.
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.9.0
- */
-EAPI Eina_Bool ecore_evas_wm_rotation_supported_get(const Ecore_Evas *ee);
-/**
- * @brief Set the preferred rotation hint.
- *
- * @param ee The Ecore_Evas to set
- * @param rotation Value to set the preferred rotation hint
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.9.0
- */
-EAPI void ecore_evas_wm_rotation_preferred_rotation_set(Ecore_Evas *ee, int rotation);
-/**
- * @brief Get the preferred rotation hint.
- *
- * @param ee The Ecore_Evas to get the preferred rotation hint from.
- * @return The preferred rotation hint, -1 on failure.
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.9.0
- */
-EAPI int ecore_evas_wm_rotation_preferred_rotation_get(const Ecore_Evas *ee);
-/**
- * @brief Set the array of available window rotations.
+ * @brief Sets the Ecore_Evas window profile list.
+ * @since 1.7.0
*
- * @param ee The Ecore_Evas to set
- * @param rotations The integer array of available window rotations
- * @param count The number of members in rotations
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.9.0
+ * @param[in] ee The Ecore_Evas
+ * @param[in] profiles The profile name list
+ * @param[in] num_profiles The number of profile names
*/
-EAPI void ecore_evas_wm_rotation_available_rotations_set(Ecore_Evas *ee, const int *rotations, unsigned int count);
+EAPI void ecore_evas_profiles_set(Ecore_Evas *ee, const char **profiles, unsigned int num_profiles);
+
/**
- * @brief Get the array of available window rotations.
+ * @brief Gets the Ecore_Evas window profile name.
+ * @since 1.7.0
*
- * @param ee The Ecore_Evas to get available window rotations from.
- * @param rotations Where to return the integer array of available window rotations
- * @param count Where to return the number of members in rotations
- * @return EINA_TRUE if available window rotations exist, EINA_FALSE otherwise
- *
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.9.0
+ * @param[in] ee The Ecore_Evas
+ * @return The profile name
*/
-EAPI Eina_Bool ecore_evas_wm_rotation_available_rotations_get(const Ecore_Evas *ee, int **rotations, unsigned int *count);
+EAPI const char *ecore_evas_profile_get(const Ecore_Evas *ee);
+
+EAPI Eina_Bool ecore_evas_wm_rotation_supported_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_wm_rotation_preferred_rotation_set(Ecore_Evas *ee, int rotation);
+EAPI int ecore_evas_wm_rotation_preferred_rotation_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_wm_rotation_available_rotations_set(Ecore_Evas *ee, const int *rotations, unsigned int count);
+EAPI Eina_Bool ecore_evas_wm_rotation_available_rotations_get(const Ecore_Evas *ee, int **rotations, unsigned int *count);
+
/**
- * @brief Set manual rotation done mode of Ecore_Evas's window
+ * @brief Sets manual rotation done mode for Ecore_Evas window.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas
- * @param set If true, the window manager will not rotate the Ecore_Evas's window until
- * the rotation done event is received by ecore_evas_wm_rotation_manual_rotation_done.
- * If false, the manual rotation mode is disabled.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] set Set @c EINA_TRUE if the window manager should not rotate the Ecore_Evas's window until
+ * the rotation done event is received by ecore_evas_wm_rotation_manual_rotation_done, \n
+ * otherwise set @c EINA_FALSE if the manual rotation mode should be disabled
*
- * @since 1.9.0
*/
-EAPI void ecore_evas_wm_rotation_manual_rotation_done_set(Ecore_Evas *ee, Eina_Bool set);
+EAPI void ecore_evas_wm_rotation_manual_rotation_done_set(Ecore_Evas *ee, Eina_Bool set);
/**
- * @brief Get manual rotation done mode of Ecore_Evas's window
- *
- * @param ee The Ecore_Evas
- * @return If true, the manual rotation done mode is enabled
+ * @brief Gets manual rotation done mode of Ecore_Evas's window.
+ * @since 1.8.0
*
- * @since 1.9.0
+ * @param[in] ee The Ecore_Evas
+ * @return @c EINA_TRUE if the manual rotation done mode is enabled, \n
+ * otherwise @c EINA_FALSE if it is not enabled
*/
-EAPI Eina_Bool ecore_evas_wm_rotation_manual_rotation_done_get(const Ecore_Evas *ee);
+EAPI Eina_Bool ecore_evas_wm_rotation_manual_rotation_done_get(const Ecore_Evas *ee);
/**
- * @brief Set rotation finish manually
+ * @brief Sets the rotation finish manually.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas
+ * @param[in] ee The Ecore_Evas
*
- * @since 1.9.0
*/
-EAPI void ecore_evas_wm_rotation_manual_rotation_done(Ecore_Evas *ee);
+EAPI void ecore_evas_wm_rotation_manual_rotation_done(Ecore_Evas *ee);
+
/**
- * @brief Get the list of supported auxiliary hint strings.
+ * @brief Gets the list of supported auxiliary hint strings.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas
- * @return List of supported auxiliary hint strings.
- * @note Do not change the returned list of its contents. Auxiliary hint
- * strings are internal and should be considered constants, do not free or
- * modify them.
- * @warning Support for this depends on the underlying windowing system.
+ * @remarks Do not change the returned list of its contents. Auxiliary hint
+ * strings are internal and should be considered constants, do not free or
+ * modify them.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * The window auxiliary hint is the value which is used to decide which actions should
- * be made available to the user by the window manager. If you want to set specific hint
- * to your window, then you should check whether it exists in the supported auxiliary
- * hints that are registered in the root window by the window manager. Once you've added
- * an auxiliary hint, you can get a new ID which is used to change value and delete hint.
- * The window manager sends the response message to the application on receiving auxiliary
- * hint change event. A list of auxiliary hint within the Ecore_Evas has this format:
- * ID:HINT:VALUE,ID:HINT:VALUE,...
+ * @remarks The window auxiliary hint is the value which is used to decide which actions should
+ * be made available to the user by the window manager. If you want to set specific hint
+ * to your window, then you should check whether it exists in the supported auxiliary
+ * hints that are registered in the root window by the window manager. Once you have added
+ * an auxiliary hint, you can get a new ID which is used to change value and delete hint.
+ * The window manager sends the response message to the application on receiving auxiliary
+ * hint change event. A list of auxiliary hint within the Ecore_Evas has this format:
+ * ID:HINT:VALUE,ID:HINT:VALUE,...
*
- * @since 1.10.0
+ * @param[in] ee The Ecore_Evas
+ * @return The list of supported auxiliary hint strings
*/
EAPI const Eina_List *ecore_evas_aux_hints_supported_get(const Ecore_Evas *ee);
+
/**
- * @brief Get the list of allowed auxiliary hint ID.
+ * @brief Gets the list of allowed auxiliary hint ID.
*
- * @param ee The Ecore_Evas
- * @return List of allowed auxiliary hint ID.
- * @note This function is low level. Instead of using it directly, consider
- * using the callback mechanism in Elementary such as "aux,hint,allowed".
- * @warning Support for this depends on the underlying windowing system.
+ * @since 1.8.0
*
- * @since 1.10.0
+ * @remarks This function is low level. Instead of using it directly, consider
+ * using the callback mechanism in Elementary such as "aux,hint,allowed".
+ * @remarks Support for this depends on the underlying windowing system.
+ *
+ * @param[in] ee The Ecore_Evas
+ * @return The list of allowed auxiliary hint ID
*/
EAPI Eina_List *ecore_evas_aux_hints_allowed_get(const Ecore_Evas *ee);
+
/**
- * @brief Create an auxiliary hint of the Ecore_Evas.
+ * @brief Creates an auxiliary hint of the Ecore_Evas.
*
- * @param ee The Ecore_Evas
- * @param hint The auxiliary hint string.
- * @param val The value string.
- * @return The ID of created auxiliary hint, or -1 on failure.
- * @warning Support for this depends on the underlying windowing system.
+ * @since 1.8.0
*
- * @since 1.10.0
+ * @remarks Support for this depends on the underlying windowing system.
+ *
+ * @param[in] ee The Ecore_Evas
+ * @param[in] hint The auxiliary hint string
+ * @param[in] val The value string
+ * @return The ID of created auxiliary hint, \n
+ * otherwise @c -1 on failure
*/
EAPI int ecore_evas_aux_hint_add(Ecore_Evas *ee, const char *hint, const char *val);
+
/**
- * @brief Delete an auxiliary hint of the Ecore_Evas.
+ * @brief Deletes an auxiliary hint of the Ecore_Evas.
*
- * @param ee The Ecore_Evas
- * @param id The ID of the auxiliary hint.
- * @return EINA_TRUE if no error occurred, EINA_FALSE otherwise.
- * @warning Support for this depends on the underlying windowing system.
+ * @since 1.8.0
*
- * @since 1.10.0
+ * @remarks Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] id The ID of the auxiliary hint.
+ * @return @c EINA_TRUE if the hint is deleted successfully, \n
+ * otherwise @c EINA_FALSE in case of errors
*/
EAPI Eina_Bool ecore_evas_aux_hint_del(Ecore_Evas *ee, const int id);
+
/**
- * @brief Change a value of the auxiliary hint.
+ * @brief Changes a value of the auxiliary hint.
*
- * @param ee The Ecore_Evas
- * @param id The auxiliary hint ID.
- * @param val The value string to be set.
- * @return EINA_TRUE if no error occurred, EINA_FALSE otherwise.
- * @warning Support for this depends on the underlying windowing system.
+ * @since 1.8.0
+ *
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @since 1.10.0
+ * @param[in] ee The Ecore_Evas
+ * @param[in] id The auxiliary hint ID
+ * @param[in] val The value string to be set
+ * @return @c EINA_TRUE if the value is changed successfully, \n
+ * otherwise @c EINA_FALSE in case of errors
*/
EAPI Eina_Bool ecore_evas_aux_hint_val_set(Ecore_Evas *ee, const int id, const char *val);
+
/**
- * @brief Send message to parent ecore
+ * @brief Sends message to parent ecore.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas to set
- * @param msg_domain The domain of message
- * @param msg_id The id of message
- * @param data The data of message
- * @param size The size of message data
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
+ * @param[in] ee The Ecore_Evas to set
+ * @param[in] msg_domain The domain of message
+ * @param[in] msg_id The ID of message
+ * @param[in] data The data of message
+ * @param[in] size The size of message data
*
* @see ecore_evas_msg_send()
* @see ecore_evas_callback_msg_parent_handle_set()
* @see eecore_evas_callback_msg_handle_set()
- *
- * This is a list of examples of these functions:
- * @li @ref ecore_evas_extn_socket_example
- * @li @ref ecore_evas_extn_plug_example
*/
EAPI void ecore_evas_msg_parent_send(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size);
+
/**
- * @brief Send message to child ecore
+ * @brief Sends message to child ecore.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas to set
- * @param msg_domain The domain of message
- * @param msg_id The id of message
- * @param data The data of message
- * @param size The size of message data
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
+ * @param[in] ee The Ecore_Evas to set
+ * @param[in] msg_domain The domain of message
+ * @param[in] msg_id The ID of message
+ * @param[in] data The data of message
+ * @param[in] size The size of message data
*
* @see ecore_evas_msg_parent_send()
* @see ecore_evas_callback_msg_parent_handle_set()
* @see eecore_evas_callback_msg_handle_set()
*/
EAPI void ecore_evas_msg_send(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size);
+
/**
- * Set a callback for parent Ecore_Evas message.
+ * @brief Sets a callback for parent Ecore_Evas message.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas to set callbacks on
- * @param func_parent_handle The handle to be called when message arive.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func_parent_handle The handle to be called when message arrives
*
* @see ecore_evas_msg_parent_send()
* @see ecore_evas_msg_send()
* @see eecore_evas_callback_msg_handle_set()
*/
EAPI void ecore_evas_callback_msg_parent_handle_set(Ecore_Evas *ee, void (*func_parent_handle)(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size));
+
/**
- * Set a callback for child Ecore_Evas message.
+ * @brief Sets a callback for child Ecore_Evas message.
+ * @since 1.8.0
*
- * @param ee The Ecore_Evas to set callbacks on
- * @param func_handle The handle to be called when message arive
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
- * @since 1.8.0
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func_handle The handle to be called when message arrives
*
* @see ecore_evas_msg_parent_send()
* @see ecore_evas_msg_send()
@@ -903,15 +916,15 @@ EAPI void ecore_evas_callback_msg_parent_handle_set(Ecore_Evas *ee, void (*func_
EAPI void ecore_evas_callback_msg_handle_set(Ecore_Evas *ee, void (*func_handle)(Ecore_Evas *ee, int msg_domain, int msg_id, void *data, int size));
/**
- * @brief Move an Ecore_Evas.
+ * @brief Moves an Ecore_Evas.
*
- * @param ee The Ecore_Evas to move
- * @param x The x coordinate to move to
- * @param y The y coordinate to move to
+ * @details This function moves @a ee to the screen coordinates (@a x, @a y).
*
- * This moves @p ee to the screen coordinates (@p x, @p y)
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to move
+ * @param[in] x The x coordinate to move to
+ * @param[in] y The y coordinate to move to
*
* @see ecore_evas_new()
* @see ecore_evas_resize()
@@ -919,162 +932,173 @@ EAPI void ecore_evas_callback_msg_handle_set(Ecore_Evas *ee, void (*func_handle)
*/
EAPI void ecore_evas_move(Ecore_Evas *ee, int x, int y);
/**
- * @brief Resize an Ecore_Evas.
+ * @brief Resizes an Ecore_Evas.
*
- * @param ee The Ecore_Evas to move
- * @param w The w coordinate to resize to
- * @param h The h coordinate to resize to
+ * @details This function resizes @a ee to @a w x @a h.
*
- * This resizes @p ee to @p w x @p h.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to move
+ * @param[in] w The w coordinate to resize to
+ * @param[in] h The h coordinate to resize to
*
* @see ecore_evas_new()
* @see ecore_evas_move()
* @see ecore_evas_move_resize()
*/
EAPI void ecore_evas_resize(Ecore_Evas *ee, int w, int h);
+
/**
- * @brief Move and resize an Ecore_Evas
+ * @brief Moves and resizes an Ecore_Evas.
*
- * @param ee The Ecore_Evas to move and resize
- * @param x The x coordinate to move to
- * @param y The y coordinate to move to
- * @param w The w coordinate to resize to
- * @param h The h coordinate to resize to
+ * @details This moves @a ee to the screen coordinates (@a x, @a y) and resizes
+ * it to @a w x @a h.
*
- * This moves @p ee to the screen coordinates (@p x, @p y) and resizes
- * it to @p w x @p h.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to move and resize
+ * @param[in] x The x coordinate to move to
+ * @param[in] y The y coordinate to move to
+ * @param[in] w The w coordinate to resize to
+ * @param[in] h The h coordinate to resize to
*
* @see ecore_evas_new()
* @see ecore_evas_move()
* @see ecore_evas_resize()
*/
EAPI void ecore_evas_move_resize(Ecore_Evas *ee, int x, int y, int w, int h);
+
/**
- * @brief Set the rotation of an Ecore_Evas' window.
+ * @brief Sets the rotation of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas
- * @param rot the angle (in degrees) of rotation.
+ * @remarks The allowed values of @a rot depend on the engine being used. Most only
+ * allow multiples of @c 90.
*
- * The allowed values of @p rot depend on the engine being used. Most only
- * allow multiples of 90.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] rot The angle (in degrees) of rotation
*
* @see ecore_evas_rotation_with_resize_set()
*/
EAPI void ecore_evas_rotation_set(Ecore_Evas *ee, int rot);
+
/**
- * @brief Set the rotation of an Ecore_Evas' window
+ * @brief Sets the rotation of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas
- * @param rot the angle (in degrees) of rotation.
+ * @remarks Like ecore_evas_rotation_set(), but it also resizes the window's contents so
+ * that they fit inside the current window geometry.
*
- * Like ecore_evas_rotation_set(), but it also resizes the window's contents so
- * that they fit inside the current window geometry.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] rot The angle (in degrees) of rotation
*
* @see ecore_evas_rotation_set()
*/
EAPI void ecore_evas_rotation_with_resize_set(Ecore_Evas *ee, int rot);
+
/**
- * @brief Get the rotation of an Ecore_Evas' window
+ * @brief Gets the rotation of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas
- * @return the angle (in degrees) of rotation.
+ * @param[in] ee The Ecore_Evas
+ * @return The angle (in degrees) of rotation
*
* @see ecore_evas_rotation_set()
* @see ecore_evas_rotation_with_resize_set()
*/
EAPI int ecore_evas_rotation_get(const Ecore_Evas *ee);
+
/**
- * @brief Raise an Ecore_Evas' window.
+ * @brief Raises an Ecore_Evas window.
*
- * @param ee The Ecore_Evas to raise.
+ * @details This functions raises the Ecore_Evas to the front.
*
- * This functions raises the Ecore_Evas to the front.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to raise
*
* @see ecore_evas_lower()
* @see ecore_evas_layer_set()
*/
EAPI void ecore_evas_raise(Ecore_Evas *ee);
+
/**
- * @brief Lower an Ecore_Evas' window.
+ * @brief Lowers an Ecore_Evas window.
*
- * @param ee The Ecore_Evas to raise.
+ * @details This functions lowers the Ecore_Evas to the back.
*
- * This functions lowers the Ecore_Evas to the back.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to raise
*
* @see ecore_evas_raise()
* @see ecore_evas_layer_set()
*/
EAPI void ecore_evas_lower(Ecore_Evas *ee);
+
/**
- * @brief Set the title of an Ecore_Evas' window.
+ * @brief Sets the title of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas whose title you wish to set.
- * @param t The title
+ * @details This function sets the title of @a ee to @a t.
*
- * This function sets the title of @p ee to @p t.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas whose title you wish to set
+ * @param[in] t The title
*/
EAPI void ecore_evas_title_set(Ecore_Evas *ee, const char *t);
+
/**
- * @brief Get the title of an Ecore_Evas' window.
+ * @brief Gets the title of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas whose title you wish to get.
- * @return The title of @p ee.
+ * @details This function returns the title of @a ee.
*
- * This function returns the title of @p ee.
+ * @param[in] ee The Ecore_Evas whose title you wish to get
+ * @return The title of @a ee
*
* @see ecore_evas_title_set()
*/
EAPI const char *ecore_evas_title_get(const Ecore_Evas *ee);
+
/**
- * @brief Set the name and class of an Ecore_Evas' window.
+ * @brief Sets the name and class of an Ecore_Evas window.
*
- * @param ee the Ecore_Evas
- * @param n the name
- * @param c the class
+ * @details This function sets the name of @a ee to @a n, and its class to @a c. The
+ * meaning of @a name and @a class depends on the underlying windowing system.
*
- * This function sets the name of @p ee to @p n, and its class to @p c. The
- * meaning of @p name and @p class depends on the underlying windowing system.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] n The name
+ * @param[in] c The class
*/
EAPI void ecore_evas_name_class_set(Ecore_Evas *ee, const char *n, const char *c);
+
/**
- * @brief Get the name and class of an Ecore_Evas' window
+ * @brief Gets the name and class of an Ecore_Evas window.
*
- * This function gets the name of @p ee into @p n, and its class into
- * @p c.
+ * @details This function gets the name of @a ee into @a n, and its class into @a c.
*
- * @param ee The Ecore_Evas to query.
- * @param n A pointer to a string to place the name in.
- * @param c A pointer to a string to place the class in.
+ * @param[in] ee The Ecore_Evas to query
+ * @param[out] n A pointer to a string to place the name in
+ * @param[out] c A pointer to a string to place the class in
* @see ecore_evas_name_class_set()
*/
EAPI void ecore_evas_name_class_get(const Ecore_Evas *ee, const char **n, const char **c);
+
/**
- * @brief Returns a pointer to the underlying window.
+ * @brief Gets a pointer to the underlying window.
*
- * @param ee The Ecore_Evas whose window is desired.
- * @return A pointer to the underlying window.
+ * @remarks Support for this depends on the underlying windowing system.
*
- * @warning Support for this depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas
+ * @return A pointer to the underlying window
*/
EAPI Ecore_Window ecore_evas_window_get(const Ecore_Evas *ee);
-/* engine/target specific init calls */
+
+/* Engine/target specific init calls */
EAPI Ecore_Evas *ecore_evas_software_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
EAPI Ecore_X_Window ecore_evas_software_x11_window_get(const Ecore_Evas *ee);
EAPI void ecore_evas_software_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on);
@@ -1096,7 +1120,12 @@ EAPI Ecore_Evas *ecore_evas_software_x11_pixmap_new(const char *disp_name, E
/**
* @brief Returns the underlying Ecore_X_Pixmap used in the Ecore_Evas
*
- * @param ee The Ecore_Evas whose pixmap is desired.
+ * @param[in] disp_name Display name.
+ * @param[in] parent X11 parent window.
+ * @param[in] x X cooridnate.
+ * @param[in] y Y coordinate.
+ * @param[in] w Width.
+ * @param[in] h Height.
* @return The underlying Ecore_X_Pixmap
*
* @warning Support for this depends on the underlying windowing system.
@@ -1107,12 +1136,13 @@ EAPI Ecore_Evas *ecore_evas_software_x11_pixmap_new(const char *disp_name, E
*
* @since 1.8
*/
+EAPI Ecore_Evas * ecore_evas_software_x11_pixmap_new_internal(const char *disp_name, Ecore_X_Window parent,int x, int y, int w, int h);
EAPI Ecore_X_Pixmap ecore_evas_software_x11_pixmap_get(const Ecore_Evas *ee);
#define ECORE_EVAS_GL_X11_OPT_NONE 0
#define ECORE_EVAS_GL_X11_OPT_INDIRECT 1
#define ECORE_EVAS_GL_X11_OPT_VSYNC 2
-#define ECORE_EVAS_GL_X11_OPT_SWAP_MODE 3
+#define ECORE_EVAS_GL_X11_OPT_SWAP_MODE 3
#define ECORE_EVAS_GL_X11_OPT_LAST 4
#define ECORE_EVAS_GL_X11_SWAP_MODE_AUTO 0
@@ -1120,7 +1150,7 @@ EAPI Ecore_X_Pixmap ecore_evas_software_x11_pixmap_get(const Ecore_Evas *ee);
#define ECORE_EVAS_GL_X11_SWAP_MODE_COPY 2
#define ECORE_EVAS_GL_X11_SWAP_MODE_DOUBLE 3
#define ECORE_EVAS_GL_X11_SWAP_MODE_TRIPLE 4
-
+
EAPI Ecore_Evas *ecore_evas_gl_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
EAPI Ecore_Evas *ecore_evas_gl_x11_options_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h, const int *opt);
EAPI Ecore_X_Window ecore_evas_gl_x11_window_get(const Ecore_Evas *ee);
@@ -1133,18 +1163,31 @@ EAPI void ecore_evas_gl_x11_pre_post_swap_callback_set(const Ecore_Ev
* @brief Create a new Ecore_Evas which does not contain an XWindow. It will
* only contain an XPixmap to render to
*
+ * @since 1.8
+ *
* @warning The XPixmap ID can change with every frame after it is rendered,
* so you should ALWAYS call ecore_evas_software_x11_pixmap_get when you
* need the current pixmap id.
*
- * @since 1.8
+ * @param[in] disp_name Display name.
+ * @param[in] parent X11 parent window.
+ * @param[in] x X cooridnate.
+ * @param[in] y Y coordinate.
+ * @param[in] w Width.
+ * @param[in] h Height.
+ * @return The underlying Ecore_X_Pixmap
*/
EAPI Ecore_Evas *ecore_evas_gl_x11_pixmap_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
/**
* @brief Returns the underlying Ecore_X_Pixmap used in the Ecore_Evas
*
- * @param ee The Ecore_Evas whose pixmap is desired.
+ * @param[in] disp_name Display name.
+ * @param[in] parent X11 parent window.
+ * @param[in] x X cooridnate.
+ * @param[in] y Y coordinate.
+ * @param[in] w Width.
+ * @param[in] h Height.
* @return The underlying Ecore_X_Pixmap
*
* @warning Support for this depends on the underlying windowing system.
@@ -1155,31 +1198,32 @@ EAPI Ecore_Evas *ecore_evas_gl_x11_pixmap_new(const char *disp_name, Ecore_X
*
* @since 1.8
*/
+EAPI Ecore_Evas * ecore_evas_gl_x11_pixmap_new_internal(const char *disp_name, Ecore_X_Window parent,int x, int y, int w, int h);
EAPI Ecore_X_Pixmap ecore_evas_gl_x11_pixmap_get(const Ecore_Evas *ee);
-EAPI Ecore_Evas *ecore_evas_xrender_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED;
-EAPI Ecore_X_Window ecore_evas_xrender_x11_window_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_xrender_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED;
-EAPI Eina_Bool ecore_evas_xrender_x11_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_xrender_x11_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED;
-
-EAPI Ecore_Evas *ecore_evas_software_x11_8_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED;
-EAPI Ecore_X_Window ecore_evas_software_x11_8_window_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI Ecore_X_Window ecore_evas_software_x11_8_subwindow_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_software_x11_8_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED;
-EAPI Eina_Bool ecore_evas_software_x11_8_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_software_x11_8_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED;
-
-EAPI Ecore_Evas *ecore_evas_software_x11_16_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h) EINA_DEPRECATED;
-EAPI Ecore_X_Window ecore_evas_software_x11_16_window_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_software_x11_16_direct_resize_set(Ecore_Evas *ee, Eina_Bool on) EINA_DEPRECATED;
-EAPI Eina_Bool ecore_evas_software_x11_16_direct_resize_get(const Ecore_Evas *ee) EINA_DEPRECATED;
-EAPI void ecore_evas_software_x11_16_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win) EINA_DEPRECATED;
+EAPI Ecore_Evas *ecore_evas_xrender_x11_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
+EAPI Ecore_X_Window ecore_evas_xrender_x11_window_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_xrender_x11_direct_resize_set(Ecore_Evas *ee, Eina_Bool on);
+EAPI Eina_Bool ecore_evas_xrender_x11_direct_resize_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_xrender_x11_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win);
+
+EAPI Ecore_Evas *ecore_evas_software_x11_8_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
+EAPI Ecore_X_Window ecore_evas_software_x11_8_window_get(const Ecore_Evas *ee);
+EAPI Ecore_X_Window ecore_evas_software_x11_8_subwindow_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_software_x11_8_direct_resize_set(Ecore_Evas *ee, Eina_Bool on);
+EAPI Eina_Bool ecore_evas_software_x11_8_direct_resize_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_software_x11_8_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win);
+
+EAPI Ecore_Evas *ecore_evas_software_x11_16_new(const char *disp_name, Ecore_X_Window parent, int x, int y, int w, int h);
+EAPI Ecore_X_Window ecore_evas_software_x11_16_window_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_software_x11_16_direct_resize_set(Ecore_Evas *ee, Eina_Bool on);
+EAPI Eina_Bool ecore_evas_software_x11_16_direct_resize_get(const Ecore_Evas *ee);
+EAPI void ecore_evas_software_x11_16_extra_event_window_add(Ecore_Evas *ee, Ecore_X_Window win);
EAPI Ecore_Evas *ecore_evas_fb_new(const char *disp_name, int rotation, int w, int h);
-EAPI Ecore_Evas *ecore_evas_directfb_new(const char *disp_name, int windowed, int x, int y, int w, int h) EINA_DEPRECATED;
-EAPI Ecore_DirectFB_Window *ecore_evas_directfb_window_get(const Ecore_Evas *ee) EINA_DEPRECATED;
+EAPI Ecore_Evas *ecore_evas_directfb_new(const char *disp_name, int windowed, int x, int y, int w, int h);
+EAPI Ecore_DirectFB_Window *ecore_evas_directfb_window_get(const Ecore_Evas *ee);
EAPI Ecore_Evas *ecore_evas_wayland_shm_new(const char *disp_name, unsigned int parent, int x, int y, int w, int h, Eina_Bool frame);
@@ -1191,201 +1235,195 @@ EAPI void ecore_evas_wayland_pointer_set(Ecore_Evas *ee, int hot_x, i
EAPI void ecore_evas_wayland_type_set(Ecore_Evas *ee, int type);
EAPI Ecore_Wl_Window *ecore_evas_wayland_window_get(const Ecore_Evas *ee);
-EAPI Ecore_Evas *ecore_evas_drm_new(const char *device, unsigned int parent, int x, int y, int w, int h);
-EAPI Ecore_Evas *ecore_evas_gl_drm_new(const char *device, unsigned int parent, int x, int y, int w, int h); /** @since 1.12 */
-
/**
- * @brief Create a new @c Ecore_Evas canvas bound to the Evas
- * @b buffer engine
+ * @brief Creates a new @c Ecore_Evas canvas bound to the Evas @b buffer engine.
*
- * @param w The width of the canvas, in pixels
- * @param h The height of the canvas, in pixels
- * @return A new @c Ecore_Evas instance or @c NULL, on failure
+ * @details This function creates a new buffer canvas wrapper, with image data array
+ * @b bound to the ARGB format, 8 bits per pixel.
*
- * This creates a new buffer canvas wrapper, with image data array
- * @b bound to the ARGB format, 8 bits per pixel.
+ * @remarks This function allocates the needed pixels array with canonical
+ * @c malloc(). If you wish a custom function to allocate it, consider
+ * using ecore_evas_buffer_allocfunc_new(), instead.
*
- * This function will allocate the needed pixels array with canonical
- * @c malloc(). If you wish a custom function to allocate it, consider
- * using ecore_evas_buffer_allocfunc_new(), instead.
+ * @remarks This function actually is a wrapper on
+ * ecore_evas_buffer_allocfunc_new(), using the same @a w and @a h
+ * arguments and canonical @c malloc() and @c free() to the memory
+ * allocation and freeing functions. See the function's documentation
+ * for more details.
*
- * @note This function actually is a wrapper on
- * ecore_evas_buffer_allocfunc_new(), using the same @a w and @a h
- * arguments and canonical @c malloc() and @c free() to the memory
- * allocation and freeing functions. See that function's documentation
- * for more details.
+ * @param[in] w The width of the canvas, in pixels
+ * @param[in] h The height of the canvas, in pixels
+ * @return A new @c Ecore_Evas instance, \n
+ * otherwise @c NULL on failure
*/
EAPI Ecore_Evas *ecore_evas_buffer_new(int w, int h);
/**
- * @brief Create a new @c Ecore_Evas canvas bound to the Evas
- * @b buffer engine, giving custom allocation and freeing functions for
- * the canvas memory region
+ * @brief Creates a new @c Ecore_Evas canvas bound to the Evas
+ * @b buffer engine, giving custom allocation and freeing functions for
+ * the canvas memory region.
*
- * @param w The width of the canvas, in canvas units
- * @param h The height of the canvas, in canvas units
- * @param alloc_func Function to be called to allocate the memory
- * needed for the new buffer canvas. @a data will be passed the same
- * value as the @p data of this function, while @a size will be passed
- * @p w times @p h times @c sizeof(int).
- * @param free_func Function to be called to free the memory used by
- * the new buffer canvas. @a data will be passed the same value as the
- * @p data of this function, while @a pix will be passed the canvas
- * memory pointer.
- * @param data Custom data to be passed to the allocation and freeing
- * functions
- * @return A new @c Ecore_Evas instance or @c NULL, on failure
+ * @details This function creates a new buffer canvas wrapper, with image data array
+ * @b bound to the ARGB format, 8 bits per pixel.
*
- * This creates a new buffer canvas wrapper, with image data array
- * @b bound to the ARGB format, 8 bits per pixel.
+ * @remarks This function is useful when one wants an @c Ecore_Evas buffer
+ * canvas with a custom allocation function, like one getting memory
+ * chunks from a memory pool, for example.
*
- * This function is useful when one wants an @c Ecore_Evas buffer
- * canvas with a custom allocation function, like one getting memory
- * chunks from a memory pool, for example.
+ * @remarks On any resizing of this @c Ecore_Evas buffer canvas, its image data
+ * is @b freed, to be allocated again with the new size.
*
- * On any resizing of this @c Ecore_Evas buffer canvas, its image data
- * will be @b freed, to be allocated again with the new size.
+ * @remarks @a w and @a h sizes have to greater or equal to @c 1. Otherwise,
+ * they are interpreted as @c 1, exactly.
*
- * @note @p w and @p h sizes have to greater or equal to 1. Otherwise,
- * they'll be interpreted as 1, exactly.
+ * @param[in] w The width of the canvas, in canvas units
+ * @param[in] h The height of the canvas, in canvas units
+ * @param[in] alloc_func The function to be called to allocate the memory
+ * needed for the new buffer canvas \n
+ * @a data is passed the same value as the @a data of this function,
+ * while @a size is passed @a w times @a h times @c sizeof(int).
+ * @param[in] free_func The function to be called to free the memory used by
+ * the new buffer canvas \n
+ * @a data is passed the same value as the @a data of this function,
+ * while @a pix is passed the canvas memory pointer.
+ * @param[in] data The custom data to be passed to the allocation and freeing functions
+ * @return A new @c Ecore_Evas instance, \n
+ * otherwise @c NULL on failure
*
* @see ecore_evas_buffer_new()
*/
EAPI Ecore_Evas *ecore_evas_buffer_allocfunc_new(int w, int h, void *(*alloc_func) (void *data, int size), void (*free_func) (void *data, void *pix), const void *data);
/**
- * @brief Grab a pointer to the actual pixels array of a given
- * @c Ecore_Evas @b buffer canvas/window.
+ * @brief Grabs a pointer to the actual pixels array of a given
+ * @c Ecore_Evas @b buffer canvas/window.
*
- * @param ee An @c Ecore_Evas handle
- * @return A pointer to the internal pixels array of @p ee
+ * @remarks Besides returning a pointer to the actual pixel array of the given
+ * canvas, this call forces a <b>rendering update on @a ee</b>, first.
*
- * Besides returning a pointer to the actual pixel array of the given
- * canvas, this call will force a <b>rendering update on @p ee</b>,
- * first.
+ * @remarks A common use case for this call is to create an image object, from
+ * @b another canvas, to have as data @a ee's contents, thus taking a
+ * snapshot of the canvas. For that case, one can also use the
+ * ecore_evas_object_image_new() helper function.
*
- * A common use case for this call is to create an image object, from
- * @b another canvas, to have as data @p ee's contents, thus
- * snapshoting the canvas. For that case, one can also use the
- * ecore_evas_object_image_new() helper function.
+ * @param[in] ee An @c Ecore_Evas handle
+ * @return A pointer to the internal pixels array of @a ee
*/
EAPI const void *ecore_evas_buffer_pixels_get(Ecore_Evas *ee);
/**
- * @brief Create a new @c Ecore_Evas canvas bound to the Evas
- * @b ews (Ecore + Evas Single Process Windowing System) engine
+ * @brief Creates a new @c Ecore_Evas canvas bound to the Evas
+ * @b ews (Ecore + Evas Single Process Windowing System) engine.
+ *
+ * @since 1.1
*
- * EWS is a simple single process windowing system. The backing store
- * is also an @c Ecore_Evas that can be setup with
- * ecore_evas_ews_setup() and retrieved with
- * ecore_evas_ews_ecore_evas_get(). It will allow window management
- * using events prefixed with @c ECORE_EVAS_EVENT_EWS_.
+ * @remarks EWS is a simple single process windowing system. The backing store
+ * is also an @c Ecore_Evas that can be setup with
+ * ecore_evas_ews_setup() and retrieved with
+ * ecore_evas_ews_ecore_evas_get(). It allows window management
+ * using events prefixed with @c ECORE_EVAS_EVENT_EWS_.
*
- * The EWS windows (returned by this function or
- * ecore_evas_new("ews"...)) will all be software buffer windows
- * automatic rendered to the backing store.
+ * @remarks The EWS windows (returned by this function or
+ * ecore_evas_new("ews"...)) is all software buffer windows
+ * automatic rendered to the backing store.
*
- * @param x horizontal position of window, in pixels
- * @param y vertical position of window, in pixels
- * @param w The width of the canvas, in pixels
- * @param h The height of the canvas, in pixels
- * @return A new @c Ecore_Evas instance or @c NULL, on failure
+ * @param[in] x The horizontal position of window, in pixels
+ * @param[in] y The vertical position of window, in pixels
+ * @param[in] w The width of the canvas, in pixels
+ * @param[in] h The height of the canvas, in pixels
+ * @return A new @c Ecore_Evas instance, \n
+ * otherwise @c NULL on failure
*
* @see ecore_evas_ews_setup()
* @see ecore_evas_ews_ecore_evas_get()
- *
- * @since 1.1
*/
EAPI Ecore_Evas *ecore_evas_ews_new(int x, int y, int w, int h);
-
/**
- * Returns the backing store image object that represents the given
- * window in EWS.
- * @return The evas object of EWS backing store.
+ * @brief Gets the backing store image object that represents the given
+ * window in EWS.
+ * @since 1.1
+ *
+ * @remarks This should not be modified anyhow, but may be helpful to
+ * determine stacking and geometry of it for window managers
+ * that decorate windows.
*
- * @note This should not be modified anyhow, but may be helpful to
- * determine stacking and geometry of it for window managers
- * that decorate windows.
+ * @param[in] ee The Ecore_Evas from which to get the backing store
+ * @return The evas object of EWS backing store
*
- * @param ee The Ecore_Evas from which to get the backing store.
* @see ecore_evas_ews_manager_set()
* @see ecore_evas_ews_evas_get()
- * @since 1.1
*/
EAPI Evas_Object *ecore_evas_ews_backing_store_get(const Ecore_Evas *ee);
/**
- * Calls the window to be deleted (freed), but can let user decide to
- * forbid it by using ecore_evas_callback_delete_request_set()
+ * @brief Calls the window to be deleted (freed), but can let user decide to
+ * forbid it by using ecore_evas_callback_delete_request_set()
+ * @since 1.1
*
- * @param ee The Ecore_Evas for which window will be deleted.
- * @since 1.1
+ * @param[in] ee The Ecore_Evas for which window is deleted
*/
EAPI void ecore_evas_ews_delete_request(Ecore_Evas *ee);
/**
- * @brief Create an Evas image object with image data <b>bound to an
- * own, internal @c Ecore_Evas canvas wrapper</b>
- *
- * @param ee_target @c Ecore_Evas to have the canvas receiving the new
- * image object
- * @return A handle to the new image object
- *
- * This will create a @b special Evas image object. The image's pixel
- * array will get bound to the same image data array of an @b internal
- * @b buffer @c Ecore_Evas canvas. The user of this function is, then,
- * supposed to grab that @c Ecore_Evas handle, with
- * ecore_evas_object_ecore_evas_get(), and use its canvas to render
- * whichever contents he/she wants, @b independently of the contents
- * of the canvas owned by @p ee_target. Those contents will reflect on
- * the canvas of @p ee, though, being exactly the image data of the
- * object returned by this function.
- *
- * This is a helper function for the scenario of one wanting to grab a
- * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be
- * used on another canvas, for whichever reason. The most common goal
- * of this setup is to @b save an image file with a whole canvas as
- * contents, which could not be achieved by using an image file within
- * the target canvas.
- *
- * @warning Always resize the returned image and its underlying
- * @c Ecore_Evas handle accordingly. They must be kept with same sizes
- * for things to work as expected. Also, you @b must issue
- * @c evas_object_image_size_set() on the image with that same size. If
- * the image is to be shown in a canvas bound to an engine different
- * than the buffer one, then you must also set this image's @b fill
- * properties accordingly.
- *
- * @note The image returned will always be bound to the
- * @c EVAS_COLORSPACE_ARGB8888 colorspace, always.
- *
- * @note Use ecore_evas_object_evas_get() to grab the image's internal
- * own canvas directly.
- *
- * @note If snapshoting this image's internal canvas, remember to
- * flush its internal @c Ecore_Evas firstly, with
- * ecore_evas_manual_render().
+ * @brief Creates an Evas image object with image data <b>bound to an
+ * own, internal @c Ecore_Evas canvas wrapper</b>.
+ *
+ * @remarks This creates a @b special Evas image object. The image's pixel
+ * array gets bound to the same image data array of an @b internal
+ * @b buffer @c Ecore_Evas canvas. The user of this function is, then,
+ * supposed to grab that @c Ecore_Evas handle, with
+ * ecore_evas_object_ecore_evas_get(), and use its canvas to render
+ * whichever contents he/she wants, @b independently of the contents
+ * of the canvas owned by @a ee_target. Those contents reflect on
+ * the canvas of @a ee, though, being exactly the image data of the
+ * object returned by this function.
+ *
+ * This is a helper function for the scenario of one wanting to grab a
+ * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be
+ * used on another canvas, for whichever reason. The most common goal
+ * of this setup is to @b save an image file with a whole canvas as
+ * contents, which could not be achieved by using an image file within
+ * the target canvas.
+ *
+ * @remarks Always resize the returned image and its underlying
+ * @c Ecore_Evas handle accordingly. They must be kept with same sizes
+ * for things to work as expected. Also, you @b must issue
+ * @c evas_object_image_size_set() on the image with that same size. If
+ * the image is to be shown in a canvas bound to an engine different
+ * than the buffer one, then you must also set this image's @b fill
+ * properties accordingly.
+ *
+ * @remarks The image returned is always bound to the
+ * @c EVAS_COLORSPACE_ARGB8888 colorspace, always.
+ *
+ * @remarks Use ecore_evas_object_evas_get() to grab the image's internal
+ * own canvas directly.
+ *
+ * @remarks If you are taking a snapshot of this image's internal canvas, remember to
+ * flush its internal @c Ecore_Evas firstly, with
+ * ecore_evas_manual_render().
+ *
+ * @param[in] ee_target The Ecore_Evas to have the canvas receiving the new image object
+ * @return A handle to the new image object
*/
EAPI Evas_Object *ecore_evas_object_image_new(Ecore_Evas *ee_target);
/**
- * @brief Retrieve the internal @c Ecore_Evas handle of an image
- * object created via ecore_evas_object_image_new()
+ * @brief Gets the internal @c Ecore_Evas handle of an image
+ * object created using ecore_evas_object_image_new().
*
- * @param obj A handle to an image object created via
- * ecore_evas_object_image_new()
- * @return The underlying @c Ecore_Evas handle in @p obj
+ * @param[in] obj A handle to an image object created using ecore_evas_object_image_new()
+ * @return The underlying @c Ecore_Evas handle in @a obj
*/
EAPI Ecore_Evas *ecore_evas_object_ecore_evas_get(Evas_Object *obj);
/**
- * @brief Retrieve the canvas bound to the internal @c Ecore_Evas
- * handle of an image object created via ecore_evas_object_image_new()
+ * @brief Gets the canvas bound to the internal @c Ecore_Evas
+ * handle of an image object created using ecore_evas_object_image_new().
*
- * @param obj A handle to an image object created via
- * ecore_evas_object_image_new()
- * @return A handle to @p obj's underlying @c Ecore_Evas's canvas
+ * @param[in] obj A handle to an image object created using ecore_evas_object_image_new()
+ * @return A handle to @a obj's underlying @c Ecore_Evas's canvas
*/
EAPI Evas *ecore_evas_object_evas_get(Evas_Object *obj);
@@ -1429,97 +1467,98 @@ EAPI Ecore_Evas *ecore_evas_software_wince_new(Ecore_WinCE_Window *parent,
int x,
int y,
int width,
- int height) EINA_DEPRECATED;
+ int height);
EAPI Ecore_Evas *ecore_evas_software_wince_fb_new(Ecore_WinCE_Window *parent,
int x,
int y,
int width,
- int height) EINA_DEPRECATED;
+ int height);
EAPI Ecore_Evas *ecore_evas_software_wince_gapi_new(Ecore_WinCE_Window *parent,
int x,
int y,
int width,
- int height) EINA_DEPRECATED;
+ int height);
EAPI Ecore_Evas *ecore_evas_software_wince_ddraw_new(Ecore_WinCE_Window *parent,
int x,
int y,
int width,
- int height) EINA_DEPRECATED;
+ int height);
EAPI Ecore_Evas *ecore_evas_software_wince_gdi_new(Ecore_WinCE_Window *parent,
int x,
int y,
int width,
- int height) EINA_DEPRECATED;
+ int height);
-EAPI Ecore_WinCE_Window *ecore_evas_software_wince_window_get(const Ecore_Evas *ee) EINA_DEPRECATED;
+EAPI Ecore_WinCE_Window *ecore_evas_software_wince_window_get(const Ecore_Evas *ee);
EAPI Ecore_Evas *ecore_evas_cocoa_new(Ecore_Cocoa_Window *parent,
- int x,
- int y,
- int w,
- int h);
+ int x,
+ int y,
+ int w,
+ int h);
EAPI Ecore_Evas *ecore_evas_psl1ght_new(const char* name, int w, int h);
-/* generic manipulation calls */
+/* Generic manipulation calls */
/**
- * @brief Get the engine name used by this Ecore_Evas(window).
+ * @brief Gets the engine name used by this Ecore_Evas(window).
*
- * @param ee Ecore_Evas whose engine's name is desired.
- * @return A string that can(usually) be used in ecore_evas_new()
+ * @param[in] ee The Ecore_Evas whose engine's name is desired
+ * @return A string that can(usually) be used in ecore_evas_new()
*
* @see ecore_evas_free()
*/
EAPI const char *ecore_evas_engine_name_get(const Ecore_Evas *ee);
/**
- * @brief Return the Ecore_Evas for this Evas
+ * @brief Gets the Ecore_Evas for this Evas.
*
- * @param e The Evas to get the Ecore_Evas from
- * @return The Ecore_Evas that holds this Evas, or @c NULL if not held by one.
+ * @remarks Use this only on Evas created with ecore evas.
*
- * @warning Only use on Evas' created with ecore evas!
+ * @param[in] e The Evas to get the Ecore_Evas from
+ * @return The Ecore_Evas that holds this Evas, \n
+ * otherwise @c NULL if not held by one
*/
EAPI Ecore_Evas *ecore_evas_ecore_evas_get(const Evas *e);
/**
- * @brief Free an Ecore_Evas
+ * @brief Frees an Ecore_Evas.
*
- * @param ee The Ecore_Evas to free
+ * @details This function frees up any memory used by the Ecore_Evas.
*
- * This frees up any memory used by the Ecore_Evas.
+ * @param[in] ee The Ecore_Evas to free.
*/
EAPI void ecore_evas_free(Ecore_Evas *ee);
/**
- * @brief Retrieve user data associated with an Ecore_Evas.
+ * @brief Gets user data associated with an Ecore_Evas.
*
- * @param ee The Ecore_Evas to retrieve the user data from.
- * @param key The key which the user data to be retrieved is associated with.
+ * @details This function retrieves user specific data that has been stored within an
+ * Ecore_Evas structure with ecore_evas_data_set().
*
- * This function retrieves user specific data that has been stored within an
- * Ecore_Evas structure with ecore_evas_data_set().
+ * @return A pointer to the user data on success, \n
+ * otherwise @c NULL on error
*
- * @returns @c NULL on error or no data found, A pointer to the user data on
- * success.
+ * @param[in] ee The Ecore_Evas to retrieve the user data from
+ * @param[in] key The key which the user data to be retrieved is associated with
*
* @see ecore_evas_data_set()
*/
EAPI void *ecore_evas_data_get(const Ecore_Evas *ee, const char *key);
/**
- * @brief Store user data in an Ecore_Evas structure.
+ * @brief Stores user data in an Ecore_Evas structure.
*
- * @param ee The Ecore_Evas to store the user data in.
- * @param key A unique string to associate the user data against. Cannot
- * be NULL.
- * @param data A pointer to the user data to store.
+ * @details This function associates the @a data with a @a key which is stored by
+ * the Ecore_Evas @a ee. Be aware that a call to ecore_evas_free() does
+ * not free any memory for the associated user data. This is the responsibility
+ * of the caller.
*
- * This function associates the @p data with a @p key which is stored by
- * the Ecore_Evas @p ee. Be aware that a call to ecore_evas_free() will
- * not free any memory for the associated user data, this is the responsibility
- * of the caller.
+ * @param[in] ee The Ecore_Evas to store the user data in
+ * @param[in] key A unique string to associate the user data against \n
+ * This must not be @c NULL.
+ * @param[in] data A pointer to the user data to store
*
* @see ecore_evas_callback_pre_free_set()
* @see ecore_evas_free()
@@ -1527,563 +1566,505 @@ EAPI void *ecore_evas_data_get(const Ecore_Evas *ee, const char *key);
*/
EAPI void ecore_evas_data_set(Ecore_Evas *ee, const char *key, const void *data);
/**
- * Set a callback for Ecore_Evas resize events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee is resized.
+ * @brief Sets a callback for Ecore_Evas resize events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee is resized.
+ *
+ * @remarks If and when this function is called depends on the underlying
+ * windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_resize_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas move events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee is moved.
+ * @brief Sets a callback for Ecore_Evas move events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee is moved.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_move_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas show events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee is shown.
+ * @brief Sets a callback for Ecore_Evas show events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee is shown.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_show_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas hide events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee is hidden.
+ * @brief Sets a callback for Ecore_Evas hide events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee is hidden.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_hide_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas delete request events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee gets a delete request.
+ * @brief Sets a callback for Ecore_Evas delete request events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee gets a delete request.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_delete_request_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas destroy events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee is destroyed.
+ * @brief Sets a callback for Ecore_Evas destroy events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee is destroyed.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_destroy_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas focus in events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee gets focus.
+ * @brief Sets a callback for Ecore_Evas focus in events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee gets focus.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_focus_in_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
-/**
- * Set a callback for Ecore_Evas focus out events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee loses focus.
+/**
+ * @brief Sets a callback for Ecore_Evas focus out events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee loses focus.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param ee The Ecore_Evas to set callbacks on
+ * @param func The function to call
*/
EAPI void ecore_evas_callback_focus_out_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas sticky events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee becomes sticky.
+ * @brief Sets a callback for Ecore_Evas sticky events.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee becomes sticky.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param ee The Ecore_Evas to set callbacks on
+ * @param func The function to call
*/
EAPI void ecore_evas_callback_sticky_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
-/**
- * Set a callback for Ecore_Evas un-sticky events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee becomes un-sticky.
+/**
+ * @brief Sets a callback for Ecore_Evas focus out events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee becomes un-sticky.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
+
*/
EAPI void ecore_evas_callback_unsticky_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas mouse in events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever the mouse enters @p ee.
+ * @brief Sets a callback for Ecore_Evas mouse in events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever the mouse enters @a ee.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_mouse_in_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas mouse out events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever the mouse leaves @p ee.
+ * @brief Sets a callback for Ecore_Evas mouse out events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever the mouse leaves @a ee.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_mouse_out_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas pre render events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called just before the evas in @p ee is rendered.
+ * @brief Sets a callback for Ecore_Evas pre render events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called just before the evas in @a ee is rendered.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_pre_render_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas mouse post render events.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called just after the evas in @p ee is rendered.
+ * @brief Sets a callback for Ecore_Evas mouse post render events.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called just after the evas in @a ee is rendered.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_post_render_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas pre-free event.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
+ * @brief Sets a callback for Ecore_Evas pre-free event.
*
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called just before the instance @p ee is freed.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called just before the instance @a ee is freed.
*
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_pre_free_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Set a callback for Ecore_Evas state changes.
- * @param ee The Ecore_Evas to set callbacks on
- * @param func The function to call
-
- * A call to this function will set a callback on an Ecore_Evas, causing
- * @p func to be called whenever @p ee changes state.
+ * @brief Sets a callback for Ecore_Evas state changes.
+ * @since 1.2
*
- * @since 1.2
- * @warning If and when this function is called depends on the underlying
- * windowing system.
+ * @remarks A call to this function sets a callback on an Ecore_Evas, causing
+ * @a func to be called whenever @a ee changes state.
+ *
+ * @remarks When this function is called depends on the underlying windowing system.
+ * @param[in] ee The Ecore_Evas to set callbacks on
+ * @param[in] func The function to call
*/
EAPI void ecore_evas_callback_state_change_set(Ecore_Evas *ee, Ecore_Evas_Event_Cb func);
/**
- * Get an Ecore_Evas's Evas
- * @param ee The Ecore_Evas whose Evas you wish to get
- * @return The Evas wrapped by @p ee
+ * @brief Gets an Ecore_Evas's Evas.
*
- * This function returns the Evas contained within @p ee.
+ * @details This function returns the Evas contained within @a ee.
+ *
+ * @param[in] ee The Ecore_Evas whose Evas you wish to get
+ * @return The Evas wrapped by @a ee
*/
EAPI Evas *ecore_evas_get(const Ecore_Evas *ee);
/**
- * Provide Managed move co-ordinates for an Ecore_Evas
- * @param ee The Ecore_Evas to move
- * @param x The x coordinate to set as the managed location
- * @param y The y coordinate to set as the managed location
+ * @brief Provides managed move co-ordinates for an Ecore_Evas.
+ *
+ * @details This sets the managed geometry position of the @a ee to (@a x, @a y).
*
- * This sets the managed geometry position of the @p ee to (@p x, @p y)
+ * @param[in] ee The Ecore_Evas to move
+ * @param[in] x The x coordinate to set as the managed location
+ * @param[in] y The y coordinate to set as the managed location
*/
EAPI void ecore_evas_managed_move(Ecore_Evas *ee, int x, int y);
/**
- * Set whether an Ecore_Evas is shaped or not.
+ * @brief Sets whether an Ecore_Evas is shaped or not.
*
- * @param ee The Ecore_Evas to shape.
- * @param shaped @c EINA_TRUE to shape, @c EINA_FALSE to not.
+ * @remarks This function allows one to make an Ecore_Evas shaped to the contents of the
+ * evas. If @a shaped is @c EINA_TRUE, @a ee is transparent in parts of
+ * the evas that contain no objects. If @a shaped is @c EINA_FALSE, then @a ee
+ * is rectangular, and parts with no data show random framebuffer
+ * artifacting. For non-shaped Ecore_Evases, it is recommended to cover the
+ * entire evas with a background object.
*
- * This function allows one to make an Ecore_Evas shaped to the contents of the
- * evas. If @p shaped is @c EINA_TRUE, @p ee will be transparent in parts of
- * the evas that contain no objects. If @p shaped is @c EINA_FALSE, then @p ee
- * will be rectangular, and parts with no data will show random framebuffer
- * artifacting. For non-shaped Ecore_Evases, it is recommended to cover the
- * entire evas with a background object.
+ * @param[in] ee The Ecore_Evas to shape
+ * @param[in] shaped Set @c EINA_TRUE to shape, \n
+ * otherwise set @c EINA_FALSE to not shape
*/
EAPI void ecore_evas_shaped_set(Ecore_Evas *ee, Eina_Bool shaped);
/**
- * Query whether an Ecore_Evas is shaped or not.
+ * @brief Checks whether an Ecore_Evas is shaped.
*
- * @param ee The Ecore_Evas to query.
- * @return @c EINA_TRUE if shaped, @c EINA_FALSE if not.
+ * @details This function returns @c EINA_TRUE if @a ee is shaped, and @c EINA_FALSE if not.
*
- * This function returns @c EINA_TRUE if @p ee is shaped, and @c EINA_FALSE if not.
+ * @param[in] ee The Ecore_Evas to query
+ * @return @c EINA_TRUE if shaped, \n
+ * otherwise @c EINA_FALSE if is not shaped
*/
EAPI Eina_Bool ecore_evas_shaped_get(const Ecore_Evas *ee);
/**
- * @brief Show an Ecore_Evas' window
+ * @brief Shows an Ecore_Evas window.
*
- * @param ee The Ecore_Evas to show.
+ * @details This function makes @a ee visible.
*
- * This function makes @p ee visible.
+ * @param[in] ee The Ecore_Evas to show
*/
EAPI void ecore_evas_show(Ecore_Evas *ee);
/**
- * @brief Hide an Ecore_Evas' window
+ * @brief Hides an Ecore_Evas' window.
*
- * @param ee The Ecore_Evas to hide.
+ * @details This function makes @a ee hidden (not visible).
*
- * This function makes @p ee hidden(not visible).
+ * @param[in] ee The Ecore_Evas to hide
*/
EAPI void ecore_evas_hide(Ecore_Evas *ee);
/**
- * Activate (set focus to, via the window manager) an Ecore_Evas' window.
- * @param ee The Ecore_Evas to activate.
+ * @brief Activates (sets focus to, via the window manager) an Ecore_Evas' window.
+ *
+ * @details This functions activates the Ecore_Evas.
*
- * This functions activates the Ecore_Evas.
+ * @param[in] ee The Ecore_Evas to activate
*/
EAPI void ecore_evas_activate(Ecore_Evas *ee);
/**
- * Set the minimum size of a given @c Ecore_Evas window
+ * @brief Sets the minimum size of a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w The minimum width
- * @param h The minimum height
+ * @details This function sets the minimum size of @a ee to be @a w x @a h.
+ * You cannot resize that window to dimensions smaller than
+ * the ones set.
*
- * This function sets the minimum size of @p ee to be @p w x @p h.
- * One won't be able to resize that window to dimensions smaller than
- * the ones set.
+ * @remarks When base sizes are set, using ecore_evas_size_base_set(),
+ * they are used to calculate a window's minimum size, instead of
+ * those set by this function.
*
- * @note When base sizes are set, via ecore_evas_size_base_set(),
- * they'll be used to calculate a window's minimum size, instead of
- * those set by this function.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[in] w The minimum width
+ * @param[in] h The minimum height
*
* @see ecore_evas_size_min_get()
*/
EAPI void ecore_evas_size_min_set(Ecore_Evas *ee, int w, int h);
/**
- * Get the minimum size set for a given @c Ecore_Evas window
+ * @brief Gets the minimum size set for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w A pointer to an int to place the minimum width in.
- * @param h A pointer to an int to place the minimum height in.
+ * @remarks Use @c NULL pointers on the size components that you are not
+ * interested in: they are ignored by the function.
*
- * @note Use @c NULL pointers on the size components you're not
- * interested in: they'll be ignored by the function.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[out] w A pointer to an int to place the minimum width in
+ * @param[out] h A pointer to an int to place the minimum height in
*
* @see ecore_evas_size_min_set() for more details
*/
EAPI void ecore_evas_size_min_get(const Ecore_Evas *ee, int *w, int *h);
/**
- * Set the maximum size of a given @c Ecore_Evas window
+ * @brief Sets the maximum size of a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w The maximum width
- * @param h The maximum height
+ * @details This function sets the maximum size of @a ee to be @a w x @a h.
+ * You cannot resize that window to dimensions bigger than
+ * the ones set.
*
- * This function sets the maximum size of @p ee to be @p w x @p h.
- * One won't be able to resize that window to dimensions bigger than
- * the ones set.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[in] w The maximum width
+ * @param[in] h The maximum height
*
* @see ecore_evas_size_max_get()
*/
EAPI void ecore_evas_size_max_set(Ecore_Evas *ee, int w, int h);
/**
- * Get the maximum size set for a given @c Ecore_Evas window
+ * @brief Gets the maximum size set for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w A pointer to an int to place the maximum width in.
- * @param h A pointer to an int to place the maximum height in.
+ * @remarks Use @c NULL pointers on the size components that you are not
+ * interested in: they are ignored by the function.
*
- * @note Use @c NULL pointers on the size components you're not
- * interested in: they'll be ignored by the function.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[out] w A pointer to an int to place the maximum width in
+ * @param[out] h A pointer to an int to place the maximum height in
*
* @see ecore_evas_size_max_set() for more details
*/
EAPI void ecore_evas_size_max_get(const Ecore_Evas *ee, int *w, int *h);
/**
- * Set the base size for a given @c Ecore_Evas window
+ * @brief Sets the base size for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w The base width
- * @param h The base height
+ * @details This function sets the @b base size of @a ee to be @a w x @a h.
+ * When base sizes are set, they are used to calculate a window's
+ * @b minimum size, instead of those set by ecore_evas_size_min_get().
*
- * This function sets the @b base size of @p ee to be @p w x @p h.
- * When base sizes are set, they'll be used to calculate a window's
- * @b minimum size, instead of those set by ecore_evas_size_min_get().
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[in] w The base width
+ * @param[in] h The base height
*
* @see ecore_evas_size_base_get()
*/
EAPI void ecore_evas_size_base_set(Ecore_Evas *ee, int w, int h);
/**
- * Get the base size set for a given @c Ecore_Evas window
+ * @brief Gets the base size set for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w A pointer to an int to place the base width in.
- * @param h A pointer to an int to place the base height in.
+ * @remarks Use @c NULL pointers on the size components that you are not
+ * interested in: they are ignored by the function.
*
- * @note Use @c NULL pointers on the size components you're not
- * interested in: they'll be ignored by the function.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[out] w A pointer to an int to place the base width in
+ * @param[out] h A pointer to an int to place the base height in
*
* @see ecore_evas_size_base_set() for more details
*/
EAPI void ecore_evas_size_base_get(const Ecore_Evas *ee, int *w, int *h);
/**
- * Set the "size step" for a given @c Ecore_Evas window
+ * @brief Sets the "size step" for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w The step width
- * @param h The step height
+ * @details This function sets the size steps of @a ee to be @a w x @a h. This
+ * limits the size of this @c Ecore_Evas window to be @b always an
+ * integer multiple of the step size, for each axis.
*
- * This function sets the size steps of @p ee to be @p w x @p h. This
- * limits the size of this @c Ecore_Evas window to be @b always an
- * integer multiple of the step size, for each axis.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[in] w The step width
+ * @param[in] h The step height
*/
EAPI void ecore_evas_size_step_set(Ecore_Evas *ee, int w, int h);
/**
- * Get the "size step" set for a given @c Ecore_Evas window
+ * @brief Gets the "size step" set for a given @c Ecore_Evas window.
*
- * @param ee An @c Ecore_Evas window's handle
- * @param w A pointer to an int to place the step width in.
- * @param h A pointer to an int to place the step height in.
+ * @remarks Use @c NULL pointers on the size components that you are not
+ * interested in: they are ignored by the function.
*
- * @note Use @c NULL pointers on the size components you're not
- * interested in: they'll be ignored by the function.
+ * @param[in] ee An @c Ecore_Evas window's handle
+ * @param[out] w A pointer to an int to place the step width in
+ * @param[out] h A pointer to an int to place the step height in
*
* @see ecore_evas_size_base_set() for more details
*/
EAPI void ecore_evas_size_step_get(const Ecore_Evas *ee, int *w, int *h);
/**
- * @brief Set the cursor of an Ecore_Evas.
+ * @brief Sets the cursor of an Ecore_Evas.
*
- * @param ee The Ecore_Evas
- * @param file The path to an image file for the cursor.
- * @param layer The layer in which the cursor will appear.
- * @param hot_x The x coordinate of the cursor's hot spot.
- * @param hot_y The y coordinate of the cursor's hot spot.
+ * @details This function makes the mouse cursor over @a ee be the image specified by
+ * @a file. The actual point within the image that the mouse is at is specified
+ * by @a hot_x and @a hot_y, which are coordinates with respect to the top left
+ * corner of the cursor image.
*
- * This function makes the mouse cursor over @p ee be the image specified by
- * @p file. The actual point within the image that the mouse is at is specified
- * by @p hot_x and @p hot_y, which are coordinates with respect to the top left
- * corner of the cursor image. Cursor object will be delete with Ecore_Evas.
+ * @remarks This function creates an object from the image and uses ecore_evas_object_cursor_set().
*
- * @note This function creates an object from the image and uses
- * ecore_evas_object_cursor_set().
- *
- * @warning Previos setted cursor will be delete.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] file The path to an image file for the cursor
+ * @param[in] layer The layer in which the cursor appears
+ * @param[in] hot_x The x coordinate of the cursor's hot spot
+ * @param[in] hot_y The y coordinate of the cursor's hot spot
*
* @see ecore_evas_object_cursor_set()
- * @see ecore_evas_cursor_unset()
*/
EAPI void ecore_evas_cursor_set(Ecore_Evas *ee, const char *file, int layer, int hot_x, int hot_y);
/**
- * @brief Get information about an Ecore_Evas' cursor
+ * @brief Gets information about an Ecore_Evas' cursor.
*
- * @param ee The Ecore_Evas to set
- * @param obj A pointer to an Evas_Object to place the cursor Evas_Object.
- * @param layer A pointer to an int to place the cursor's layer in.
- * @param hot_x A pointer to an int to place the cursor's hot_x coordinate in.
- * @param hot_y A pointer to an int to place the cursor's hot_y coordinate in.
+ * @details This function queries information about an Ecore_Evas' cursor.
*
- * This function queries information about an Ecore_Evas' cursor.
+ * @param[in] ee The Ecore_Evas to set
+ * @param[out] obj A pointer to an Evas_Object to place the cursor Evas_Object
+ * @param[out] layer A pointer to an int to place the cursor's layer in
+ * @param[out] hot_x A pointer to an int to place the cursor's hot_x coordinate in
+ * @param[out] hot_y A pointer to an int to place the cursor's hot_y coordinate in
*
* @see ecore_evas_cursor_set()
* @see ecore_evas_object_cursor_set()
- * @see ecore_evas_cursor_unset()
*/
EAPI void ecore_evas_cursor_get(const Ecore_Evas *ee, Evas_Object **obj, int *layer, int *hot_x, int *hot_y);
/**
- * @brief Set the cursor of an Ecore_Evas
- *
- * @param ee The Ecore_Evas
+ * @brief Sets the cursor of an Ecore_Evas.
*
- * @param obj The Evas_Object which will be the cursor.
- * @param layer The layer in which the cursor will appear.
- * @param hot_x The x coordinate of the cursor's hot spot.
- * @param hot_y The y coordinate of the cursor's hot spot.
+ * @details This function makes the mouse cursor over @a ee be the object specified by
+ * @a obj. The actual point within the object that the mouse is at is specified
+ * by @a hot_x and @a hot_y, which are coordinates with respect to the top left
+ * corner of the cursor object.
*
- * This function makes the mouse cursor over @p ee be the object specified by
- * @p obj. The actual point within the object that the mouse is at is specified
- * by @p hot_x and @p hot_y, which are coordinates with respect to the top left
- * corner of the cursor object. Cursor object will be delete with the Ecore_Evas.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] obj The Evas_Object which is the cursor
+ * @param[in] layer The layer in which the cursor appears
+ * @param[in] hot_x The x coordinate of the cursor's hot spot
+ * @param[in] hot_y The y coordinate of the cursor's hot spot
*
* @see ecore_evas_cursor_set()
*/
EAPI void ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int hot_x, int hot_y);
/**
- * @brief Unset the Ecore_Evas cursor
- *
- * @param ee The Ecore_Evas to unset the cursor.
- *
- * This function unsets the cursor from the Ecore_Evas, and returns the cursor
- * object. If the cursor was set from ecore_evas_cursor_set(), this function
- * returns the image. In this case, the image should be deleted when it is
- * no longer needed.
- *
- * @see ecore_evas_cursor_set()
- * @see ecore_evas_object_cursor_set()
- * @since 1.11
- */
-EAPI Evas_Object* ecore_evas_cursor_unset(Ecore_Evas *ee);
-
-/**
- * Tell the WM whether or not to ignore an Ecore_Evas' window
+ * @brief Tells the WM whether or not to ignore an Ecore_Evas' window.
*
- * @param ee The Ecore_Evas.
- * @param on @c EINA_TRUE to ignore, @c EINA_FALSE to not.
+ * @details This function causes the window manager to ignore @a ee if @a on is
+ * @c EINA_TRUE, or not ignore @a ee if @a on is @c EINA_FALSE.
*
- * This function causes the window manager to ignore @p ee if @p on is
- * @c EINA_TRUE, or not ignore @p ee if @p on is @c EINA_FALSE.
+ * @param[in] ee The Ecore_Evas
+ * @param[in] on Set @c EINA_TRUE to ignore, \n
+ * otherwise set @c EINA_FALSE to not ignore
*/
EAPI void ecore_evas_override_set(Ecore_Evas *ee, Eina_Bool on);
/**
- * Query whether an Ecore_Evas' window is overridden or not
+ * @brief Checks whether an Ecore_Evas window is overridden or not.
*
- * @param ee The Ecore_Evas to set.
- * @return @c EINA_TRUE if @p ee is overridden, @c EINA_FALSE if not.
- */
-EAPI Eina_Bool ecore_evas_override_get(const Ecore_Evas *ee);
-
-/**
- * Set whether or not an Ecore_Evas' window should avoid damage
- *
- * @param ee The Ecore_Evas
- * @param on The type of the damage management
- *
- * This option causes updates of the Ecore_Evas to be done on a pixmap, and
- * then copied to the window, or the pixmap used directly on the window,
- * depending on the setting. Possible options are:
- *
- * @li @ref ECORE_EVAS_AVOID_DAMAGE_NONE - every expose event triggers a new
- * damage and consequently render of the affected area. The rendering of things
- * happens directly on the window;
- *
- * @li @ref ECORE_EVAS_AVOID_DAMAGE_EXPOSE - there's a pixmap where everything
- * is rendered into, and then copied to the window. On expose events, there's
- * no need to render things again, just to copy the exposed region to the
- * window;
- *
- * @li @ref ECORE_EVAS_AVOID_DAMAGE_BUILT_IN - there's the same pixmap as the
- * previous one, but it is set as a "background pixmap" of the window. The
- * rendered things appear directly on the window, with no need to copy
- * anything, but would stay stored on the pixmap, so there's no need to render
- * things again on expose events. This option can be faster than the previous
- * one, but may lead to artifacts during resize of the window.
- */
-EAPI void ecore_evas_avoid_damage_set(Ecore_Evas *ee, Ecore_Evas_Avoid_Damage_Type on);
-
-/**
- * Query whether an Ecore_Evas' window avoids damage or not
- * @param ee The Ecore_Evas to set
- * @return The type of the damage management
+ * @param[in] ee The Ecore_Evas to set
+ * @return The type of the damage management
*
*/
EAPI Ecore_Evas_Avoid_Damage_Type ecore_evas_avoid_damage_get(const Ecore_Evas *ee);
/**
- * Set the withdrawn state of an Ecore_Evas' window.
- * @param ee The Ecore_Evas whose window's withdrawn state is set.
- * @param withdrawn The Ecore_Evas window's new withdrawn state.
+ * @brief Sets the withdrawn state of an Ecore_Evas' window.
+ *
+ * @param[in] ee The Ecore_Evas whose window's withdrawn state is set
+ * @param[in] withdrawn Set @c EINA_TRUE to set the withdrawn state, \n
+ * otherwise set @c EINA_FALSE to not set the state
*
*/
EAPI void ecore_evas_withdrawn_set(Ecore_Evas *ee, Eina_Bool withdrawn);
/**
- * Returns the withdrawn state of an Ecore_Evas' window.
- * @param ee The Ecore_Evas whose window's withdrawn state is returned.
- * @return The Ecore_Evas window's withdrawn state.
+ * @brief Gets the withdrawn state of an Ecore_Evas' window.
+ *
+ * @param[in] ee The Ecore_Evas whose window's withdrawn state is returned
+ * @return @c EINA_TRUE if the Ecore_Evas window's withdrawn state is state, \n
+ * otherwise @c EINA_FALSE if it is not state
*
*/
EAPI Eina_Bool ecore_evas_withdrawn_get(const Ecore_Evas *ee);
/**
- * Set the sticky state of an Ecore_Evas window.
+ * @brief Sets the sticky state of an Ecore_Evas window.
*
- * @param ee The Ecore_Evas whose window's sticky state is set.
- * @param sticky The Ecore_Evas window's new sticky state.
+ * @param[in] ee The Ecore_Evas whose window's sticky state is set
+ * @param[in] sticky Set @c EINA_TRUE to set the sticky state, \n
+ * otherwise set @c EINA_FALSE to not set it
*
*/
EAPI void ecore_evas_sticky_set(Ecore_Evas *ee, Eina_Bool sticky);
/**
- * Returns the sticky state of an Ecore_Evas' window.
+ * @brief Gets the sticky state of an Ecore_Evas' window.
*
- * @param ee The Ecore_Evas whose window's sticky state is returned.
- * @return The Ecore_Evas window's sticky state.
+ * @param[in] ee The Ecore_Evas whose window's sticky state is returned
+ * @return @c EINA_TRUE if the Ecore_Evas window's sticky state is set, \n
+ * otherwise @c EINA_FALSE if the state is not set
*
*/
EAPI Eina_Bool ecore_evas_sticky_get(const Ecore_Evas *ee);
/**
- * Enable/disable manual render
+ * @brief Enable/disable manual render
*
- * @param ee An @c Ecore_Evas handle
- * @param manual_render Enable/disable manual render. @c EINA_TRUE to enable
- * manual render, @c EINA_FALSE to disable manual render. @c EINA_FALSE by
- * default
+ * @details If @p manual_render is true, default ecore_evas render routine would be
+ * disabled and rendering will be done only manually. If @p manual_render is
+ * false, rendering will be done by default ecore_evas rendering routine, but
+ * still manual rendering is available. Call ecore_evas_manual_render() to
+ * force immediate render.
*
- * If @p manual_render is true, default ecore_evas render routine would be
- * disabled and rendering will be done only manually. If @p manual_render is
- * false, rendering will be done by default ecore_evas rendering routine, but
- * still manual rendering is available. Call ecore_evas_manual_render() to
- * force immediate render.
+ * @param[in] ee An @c Ecore_Evas handle
+ * @param[in] manual_render Enable/disable manual render. @c EINA_TRUE to enable
+ * manual render, @c EINA_FALSE to disable manual render. @c EINA_FALSE by
+ * default
*
* @see ecore_evas_manual_render_get()
* @see ecore_evas_manual_render()
@@ -2091,11 +2072,11 @@ EAPI Eina_Bool ecore_evas_sticky_get(const Ecore_Evas *ee);
EAPI void ecore_evas_manual_render_set(Ecore_Evas *ee, Eina_Bool manual_render);
/**
- * Get enable/disable status of manual render
+ * @brief Get enable/disable status of manual render
*
- * @param ee An @c Ecore_Evas handle
+ * @param[in] ee An @c Ecore_Evas handle
* @return @c EINA_TRUE if manual render is enabled, @c EINA_FALSE if manual
- * render is disabled
+ * render is disabled
*
* @see ecore_evas_manual_render_set()
* @see ecore_evas_manual_render()
@@ -2103,61 +2084,67 @@ EAPI void ecore_evas_manual_render_set(Ecore_Evas *ee, Eina_Bool manual_r
EAPI Eina_Bool ecore_evas_manual_render_get(const Ecore_Evas *ee);
/**
- * @brief Registers an @c Ecore_Evas to receive events through ecore_input_evas.
+ * @brief Registers an @c Ecore_Evas to receive events through ecore_input_evas.
*
- * @param ee The @c Ecore_Evas handle.
+ * @details This function calls ecore_event_window_register() with the @a ee as its @a
+ * id argument, @a window argument, and uses its @a Evas too. It is useful when
+ * no @a window information is available on a given @a Ecore_Evas backend.
+ * @since 1.1
*
- * This function calls ecore_event_window_register() with the @p ee as its @c
- * id argument, @c window argument, and uses its @c Evas too. It is useful when
- * no @c window information is available on a given @c Ecore_Evas backend.
+ * @param[in] ee The @c Ecore_Evas handle
*
* @see ecore_evas_input_event_unregister()
- * @since 1.1
*/
EAPI void ecore_evas_input_event_register(Ecore_Evas *ee);
+
/**
- * @brief Unregisters an @c Ecore_Evas receiving events through ecore_input_evas.
+ * @brief Unregisters an @c Ecore_Evas receiving events through ecore_input_evas.
+ * @since 1.1
*
- * @param ee The @c Ecore_Evas handle.
+ * @param[in] ee The @c Ecore_Evas handle
*
* @see ecore_evas_input_event_register()
- * @since 1.1
*/
EAPI void ecore_evas_input_event_unregister(Ecore_Evas *ee);
/**
- * @brief Force immediate rendering on a given @c Ecore_Evas window
- *
- * @param ee An @c Ecore_Evas handle
+ * @brief Forces immediate rendering on a given @c Ecore_Evas window.
*
- * Use this call to forcefully flush the @p ee's canvas rendering
- * pipeline, thus bring its window to an up to date state.
+ * @remarks Use this call to forcefully flush the @a ee's canvas rendering
+ * pipeline, thus bringing its window to an up-to-date state.
+ * @param[in] ee An @c Ecore_Evas handle
*/
EAPI void ecore_evas_manual_render(Ecore_Evas *ee);
EAPI void ecore_evas_comp_sync_set(Ecore_Evas *ee, Eina_Bool do_sync);
EAPI Eina_Bool ecore_evas_comp_sync_get(const Ecore_Evas *ee);
/**
- * @brief Get geometry of screen associated with this Ecore_Evas.
+ * @brief Gets geometry of screen associated with this Ecore_Evas.
*
- * @param ee The Ecore_Evas whose window's to query container screen geometry.
- * @param x where to return the horizontal offset value. May be @c NULL.
- * @param y where to return the vertical offset value. May be @c NULL.
- * @param w where to return the width value. May be @c NULL.
- * @param h where to return the height value. May be @c NULL.
+ * @since 1.1
*
- * @since 1.1
+ * @param[in] ee The Ecore_Evas whose window's to query container screen geometry
+ * @param[out] x The horizontal offset value that is returned \n
+ * This may be @c NULL.
+ * @param[out] y The vertical offset value that is returned \n
+ * This may be @c NULL.
+ * @param[out] w The width value that is returned \n
+ * This may be @c NULL.
+ * @param[out] h The height value \n
+ * This may be @c NULL.
*/
EAPI void ecore_evas_screen_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h);
/**
- * @brief Get the dpi of the screen the Ecore_Evas is primarily on.
+ * @brief Gets the DPI of the screen the Ecore_Evas is primarily on.
*
- * @param ee The Ecore_Evas whose window's to query.
- * @param xdpi Pointer to integer to store horizontal DPI. May be @c NULL.
- * @param ydpi Pointer to integer to store vertical DPI. May be @c NULL.
+ * @since 1.7
*
- * @since 1.7
+ * @param[in] ee The Ecore_Evas whose window's to query
+ * @param[out] xdpi The pointer to integer to store horizontal DPI \n
+ * This may be @c NULL.
+ * @param[out] ydpi The pointer to integer to store vertical DPI \n
+ * This may be @c NULL.
*/
EAPI void ecore_evas_screen_dpi_get(const Ecore_Evas *ee, int *xdpi, int *ydpi);
@@ -2165,85 +2152,82 @@ EAPI void ecore_evas_draw_frame_set(Ecore_Evas *ee, Eina_Bool draw_frame)
EAPI Eina_Bool ecore_evas_draw_frame_get(const Ecore_Evas *ee);
/**
- * @brief Associate the given object to this ecore evas.
- *
- * @param ee The Ecore_Evas to associate to @a obj
- * @param obj The object to associate to @a ee
- * @param flags The association flags.
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
- *
- * Association means that operations on one will affect the other, for
- * example moving the object will move the window, resize the object will
- * also affect the ecore evas window, hide and show applies as well.
- *
- * This is meant to simplify development, since you often need to associate
- * these events with your "base" objects, background or bottom-most object.
- *
- * Be aware that some methods might not be what you would like, deleting
- * either the window or the object will delete the other. If you want to
- * change that behavior, let's say to hide window when it's closed, you
- * must use ecore_evas_callback_delete_request_set() and set your own code,
- * like ecore_evas_hide(). Just remember that if you override delete_request
- * and still want to delete the window/object, you must do that yourself.
- *
- * Since we now define delete_request, deleting windows will not quit
- * main loop, if you wish to do so, you should listen for EVAS_CALLBACK_FREE
- * on the object, that way you get notified and you can call
- * ecore_main_loop_quit().
- *
- * Flags can be OR'ed of:
- * @li ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events
- * like delete, resize and move, but no stacking or layer are used.
- * @li ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations will act
- * on the Ecore_Evas, not the object. So evas_object_raise() will
- * call ecore_evas_raise(). Relative operations (stack_above, stack_below)
- * are still not implemented.
- * @li ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations will act
- * on the Ecore_Evas, not the object. So evas_object_layer_set() will
- * call ecore_evas_layer_set().
- * @li ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete will delete the
- * ecore_evas as well as delete_requests on the ecore_evas will delete
- * etc.
+ * @brief Associates the given object to this ecore evas.
+ *
+ * @remarks Association means that operations on one affects the other. For
+ * example, moving the object moves the window, resizing the object
+ * also affects the ecore evas window, hide and show applies as well.
+ *
+ * @remarks This is meant to simplify development, since you often need to associate
+ * these events with your "base" objects, background or bottom-most object.
+ *
+ * @remarks Be aware that some methods might not be what you would like, deleting
+ * either the window or the object deletes the other. If you want to
+ * change that behavior, say to hide window when it is closed, you
+ * must use ecore_evas_callback_delete_request_set() and set your own code,
+ * like ecore_evas_hide(). Just remember that if you override delete_request
+ * and still want to delete the window or object, you must do that yourself.
+ *
+ * @remarks Since we now define delete_request, deleting windows does not quit
+ * main loop. If you wish to do so, you should listen for EVAS_CALLBACK_FREE
+ * on the object, that way you get notified and you can call
+ * ecore_main_loop_quit().
+ *
+ * @remarks Flags can be OR'ed of:
+ * @li ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events
+ * like delete, resize and move, but no stacking or layer are used.
+ * @li ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations act
+ * on the Ecore_Evas, not the object. So evas_object_raise()
+ * calls ecore_evas_raise(). Relative operations (stack_above, stack_below)
+ * are still not implemented.
+ * @li ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations act
+ * on the Ecore_Evas, not the object. So evas_object_layer_set()
+ * calls ecore_evas_layer_set().
+ * @li ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete deletes the
+ * ecore_evas and the delete_requests on the ecore_evas are also deleted.
+ *
+ * @param[in] ee The Ecore_Evas to associate to @a obj
+ * @param[in] obj The object to associate to @a ee
+ * @param[in] flags The association flags
+ * @return @c EINA_TRUE if associated successfully, \n
+ * otherwise @c EINA_FALSE on failure
*/
EAPI Eina_Bool ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_Associate_Flags flags);
+
/**
- * @brief Cancel the association set with ecore_evas_object_associate().
+ * @brief Cancels the association set with ecore_evas_object_associate().
*
- * @param ee The Ecore_Evas to dissociate from @a obj
- * @param obj The object to dissociate from @a ee
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
+ * @param[in] ee The Ecore_Evas to dissociate from @a obj
+ * @param[in] obj The object to dissociate from @a ee
+ * @return @c EINA_TRUE if the association is cancelled successfully,
+ * otherwise @c EINA_FALSE on failure
*/
EAPI Eina_Bool ecore_evas_object_dissociate(Ecore_Evas *ee, Evas_Object *obj);
+
/**
- * @brief Get the object associated with @p ee
+ * @brief Gets the object associated with @a ee.
*
- * @param ee The Ecore_Evas to get the object from.
- * @return The associated object, or @c NULL if there is no associated object.
+ * @param[in] ee The Ecore_Evas to get the object from.
+ * @return The associated object, \n
+ * otherwise @c NULL if there is no associated object
*/
EAPI Evas_Object *ecore_evas_object_associate_get(const Ecore_Evas *ee);
-/* helper function to be used with ECORE_GETOPT_CALLBACK_*() */
+/* Helper function to be used with ECORE_GETOPT_CALLBACK_*() */
EAPI unsigned char ecore_getopt_callback_ecore_evas_list_engines(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, Ecore_Getopt_Value *storage);
/**
- * @brief Get a list of all the ecore_evases.
+ * @brief Gets a list of all the ecore_evases.
*
- * @return A list of ecore_evases.
+ * @remarks The returned list of ecore evases is only valid until the canvases are
+ * destroyed (and should not be cached for instance). The list can be freed by
+ * just deleting the list.
*
- * The returned list of ecore evases is only valid until the canvases are
- * destroyed (and should not be cached for instance). The list can be freed by
- * just deleting the list.
+ * @return A list of ecore_evases
*/
EAPI Eina_List *ecore_evas_ecore_evas_list_get(void);
-/**
- * @brief Get a list of all the sub ecore_evases.
- *
- * @param ee Ecore_Evas to get the list from.
- * @return A list of sub ecore_evases, or @c NULL if there is no sub ecore_evases.
- */
-EAPI Eina_List *ecore_evas_sub_ecore_evas_list_get(const Ecore_Evas *ee);
-/* specific calls to an x11 environment ecore_evas */
+/* Specific calls to an x11 environment ecore_evas */
EAPI void ecore_evas_x11_leader_set(Ecore_Evas *ee, Ecore_X_Window win);
EAPI Ecore_X_Window ecore_evas_x11_leader_get(Ecore_Evas *ee);
EAPI void ecore_evas_x11_leader_default_set(Ecore_Evas *ee);
@@ -2255,6 +2239,7 @@ EAPI void ecore_evas_x11_shape_input_reset(Ecore_Evas *ee);
EAPI void ecore_evas_x11_shape_input_apply(Ecore_Evas *ee);
/**
+ * @internal
* @defgroup Ecore_Evas_Ews Ecore_Evas Single Process Windowing System.
* @ingroup Ecore_Evas_Group
*
@@ -2266,157 +2251,163 @@ EAPI void ecore_evas_x11_shape_input_apply(Ecore_Evas *ee);
*/
/**
- * Sets the engine to be used by the backing store engine.
+ * @brief Sets the engine to be used by the backing store engine.
+ * @since 1.1
*
- * @param engine The engine to be set.
- * @param options The options of the engine to be set.
- * @return @c EINA_TRUE on success, @c EINA_FALSE if ews is already in use.
- * @since 1.1
+ * @param[in] engine The engine to be set
+ * @param[in] options The options of the engine to be set
+ * @return @c EINA_TRUE if the engine is set successfully, \n
+ * otherwise @c EINA_FALSE if ews is already in use
*/
EAPI Eina_Bool ecore_evas_ews_engine_set(const char *engine, const char *options);
/**
- * Reconfigure the backing store used.
+ * @brief Reconfigures the backing store used.
+ * @since 1.1
*
- * @param x The X coordinate to be used.
- * @param y The Y coordinate to be used.
- * @param w The width of the Ecore_Evas to setup.
- * @param h The height of the Ecore_Evas to setup.
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
- * @since 1.1
+ * @param[in] x The X coordinate to be used
+ * @param[in] y The Y coordinate to be used
+ * @param[in] w The width of the Ecore_Evas to setup
+ * @param[in] h The height of the Ecore_Evas to setup
+ * @return @c EINA_TRUE if the backing store is reconfigured successfully, \n
+ * otherwise @c EINA_FALSE on failure
*/
EAPI Eina_Bool ecore_evas_ews_setup(int x, int y, int w, int h);
/**
- * Return the internal backing store in use.
+ * @brief Gets the internal backing store in use.
+ * @since 1.1
*
- * @return The internal backing store in use.
- * @note this will forced it to be created, making future calls to
- * ecore_evas_ews_engine_set() void.
+ * @remarks This forces it to be created, making future calls to
+ * ecore_evas_ews_engine_set() void.
*
+ * @return The internal backing store in use
* @see ecore_evas_ews_evas_get()
- * @since 1.1
*/
EAPI Ecore_Evas *ecore_evas_ews_ecore_evas_get(void);
/**
- * Return the internal backing store in use.
+ * @brief Gets the internal backing store in use.
+ * @since 1.1
*
- * @return The internal backing store in use.
- * @note this will forced it to be created, making future calls to
- * ecore_evas_ews_engine_set() void.
+ * @remarks This forces it to be created, making future calls to
+ * ecore_evas_ews_engine_set() void.
*
+ * @return The internal backing store in use
* @see ecore_evas_ews_ecore_evas_get()
- * @since 1.1
*/
EAPI Evas *ecore_evas_ews_evas_get(void);
/**
- * Get the current background.
+ * @brief Gets the current background.
+ *
+ * @return The background object
+ * @see ecore_evas_ews_background_set()
*/
EAPI Evas_Object *ecore_evas_ews_background_get(void);
/**
- * Set the current background, must be created at evas ecore_evas_ews_evas_get()
+ * @brief Sets the current background.
+ * @details This must be created at evas ecore_evas_ews_evas_get().
*
- * It will be kept at lowest layer (EVAS_LAYER_MIN) and below
- * everything else. You can set any object, default is a black
- * rectangle.
+ * @remarks It is kept at lowest layer (EVAS_LAYER_MIN) and below
+ * everything else. You can set any object, default is a black
+ * rectangle.
*
- * @note previous object will be deleted!
- * @param o The Evas_Object for which to set the background.
+ * @remarks The previous object is deleted
+ * @param[in] o The Evas_Object for which to set the background
*/
EAPI void ecore_evas_ews_background_set(Evas_Object *o);
/**
- * Return all Ecore_Evas* created by EWS.
+ * @brief Gets all Ecore_Evas* created by EWS.
+ * @since 1.1
*
- * @return An eina list of Ecore_evases.
- e @note Do not change the returned list or its contents.
- * @since 1.1
+ * @remarks Do not change the returned list or its contents.
+ *
+ * @return An eina list of Ecore_evases
*/
EAPI const Eina_List *ecore_evas_ews_children_get(void);
/**
- * Set the identifier of the manager taking care of internal windows.
+ * @brief Sets the identifier of the manager taking care of internal windows.
+ * @since 1.1
*
- * The ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE event is issued. Consider
- * handling it to know if you should stop handling events yourself
- * (ie: another manager took over)
+ * @remarks The ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE event is issued. Consider
+ * handling it to know if you should stop handling events yourself
+ * (that is, another manager took over).
*
- * @param manager any unique identifier address.
+ * @param[in] manager A unique identifier address
*
* @see ecore_evas_ews_manager_get()
- * @since 1.1
*/
EAPI void ecore_evas_ews_manager_set(const void *manager);
/**
- * Get the identifier of the manager taking care of internal windows.
+ * @brief Gets the identifier of the manager taking care of internal windows.
+ * @since 1.1
*
- * @return the value set by ecore_evas_ews_manager_set()
- * @since 1.1
+ * @return The value set by ecore_evas_ews_manager_set()
*/
EAPI const void *ecore_evas_ews_manager_get(void);
-EAPI extern int ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE; /**< manager was changed @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_ADD; /**< window was created @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_DEL; /**< window was deleted, pointer is already invalid but may be used as reference for further cleanup work. @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_RESIZE; /**< window was resized @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_MOVE; /**< window was moved @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_SHOW; /**< window become visible @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_HIDE; /**< window become hidden @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_FOCUS; /**< window was focused @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_UNFOCUS; /**< window lost focus @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_RAISE; /**< window was raised @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_LOWER; /**< window was lowered @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_ACTIVATE; /**< window was activated @since 1.1 */
-
-EAPI extern int ECORE_EVAS_EWS_EVENT_ICONIFIED_CHANGE; /**< window minimized/iconified changed @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_MAXIMIZED_CHANGE; /**< window maximized changed @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_LAYER_CHANGE; /**< window layer changed @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_FULLSCREEN_CHANGE; /**< window fullscreen changed @since 1.1 */
-EAPI extern int ECORE_EVAS_EWS_EVENT_CONFIG_CHANGE; /**< some other window property changed (title, name, class, alpha, transparent, shaped...) @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_MANAGER_CHANGE; /**< Manager is changed @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_ADD; /**< Window is created @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_DEL; /**< Window is deleted, pointer is already invalid but may be used as reference for further cleanup work. @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_RESIZE; /**< Window is resized @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_MOVE; /**< Window is moved @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_SHOW; /**< Window becomes visible @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_HIDE; /**< Window becomes hidden @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_FOCUS; /**< Window is focused @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_UNFOCUS; /**< Window lost focus @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_RAISE; /**< Window is raised @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_LOWER; /**< Window is lowered @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_ACTIVATE; /**< Window is activated @since 1.1 */
+
+EAPI extern int ECORE_EVAS_EWS_EVENT_ICONIFIED_CHANGE; /**< Window minimized or iconified changed @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_MAXIMIZED_CHANGE; /**< Window maximized changed @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_LAYER_CHANGE; /**< Window layer changed @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_FULLSCREEN_CHANGE; /**< Window fullscreen changed @since 1.1 */
+EAPI extern int ECORE_EVAS_EWS_EVENT_CONFIG_CHANGE; /**< Some other window property changed (title, name, class, alpha, transparent, shaped etc) @since 1.1 */
/**
* @}
*/
/**
+ * @internal
* @defgroup Ecore_Evas_Extn External plug/socket infrastructure to remote canvases
* @ingroup Ecore_Evas_Group
*
- * These functions allow 1 process to create a "socket" was pluged into which another
+ * These functions allow one process to create a "socket" that is plugged into which another
* process can create a "plug" remotely to plug into.
- * Socket can provides content for several plugs.
+ * Socket can provide content for several plugs.
* This is best for small sized objects (about the size range
- * of a small icon up to a few large icons). Sine the plug is actually an
- * image object, you can fetch the pixel data
+ * of a small icon up to a few large icons). Since the plug is actually an
+ * image object, you can fetch the pixel data.
*
* @since 1.2
* @{
*/
-EAPI extern int ECORE_EVAS_EXTN_CLIENT_ADD; /**< this event is received when a plug has connected to an extn socket @since 1.2 */
-EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< this event is received when a plug has disconnected from an extn socket @since 1.2 */
+EAPI extern int ECORE_EVAS_EXTN_CLIENT_ADD; /**< This event is received when a plug has connected to an extn socket @since 1.2 */
+EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< This event is received when a plug has disconnected from an extn socket @since 1.2 */
/**
- * @brief Create a new Ecore_Evas canvas for the new external ecore evas socket
+ * @brief Creates a new Ecore_Evas canvas for the new external ecore evas socket.
*
- * @param w The width of the canvas, in pixels
- * @param h The height of the canvas, in pixels
- * @return A new @c Ecore_Evas instance or @c NULL, on failure
+ * @since 1.2
*
- * This creates a new extn_socket canvas wrapper, with image data array
- * @b bound to the ARGB format, 8 bits per pixel.
+ * @remarks This function creates a new extn_socket canvas wrapper, with image data array
+ * @b bound to the ARGB format, 8 bits per pixel.
*
- * If creation is successful, an Ecore_Evas handle is returned or @c NULL if
- * creation fails. Also focus, show, hide etc. callbacks will also be called
- * if the plug object is shown, or already visible on connect, or if it is
- * hidden later, focused or unfocused.
+ * @remarks If creation is successful, an Ecore_Evas handle is returned or @c NULL if
+ * creation fails. Also callbacks such as focus, show, and hide are also called
+ * if the plug object is shown, or already visible on connect, or if it is
+ * hidden later, focused or unfocused.
*
- * This function has to be flowed by ecore_evas_extn_socket_listen(),
- * for starting ecore ipc service.
+ * @remarks This function has to be flowed by ecore_evas_extn_socket_listen(),
+ * for starting ecore ipc service.
*
* @code
* Eina_Bool res = EINA_FALSE;
@@ -2437,133 +2428,203 @@ EAPI extern int ECORE_EVAS_EXTN_CLIENT_DEL; /**< this event is received when a p
* if (!res) return;
* @endcode
*
- * When a client(plug) connects, you will get the ECORE_EVAS_EXTN_CLIENT_ADD event
- * in the ecore event queue, with event_info being the image object pointer
- * passed as a void pointer. When a client disconnects you will get the
- * ECORE_EVAS_EXTN_CLIENT_DEL event.
+ * @remarks When a client(plug) connects, you get the ECORE_EVAS_EXTN_CLIENT_ADD event
+ * in the ecore event queue, with event_info being the image object pointer
+ * passed as a void pointer. When a client disconnects you get the
+ * ECORE_EVAS_EXTN_CLIENT_DEL event.
*
- * You can set up event handles for these events as follows:
+ * @remarks You can set up event handles for these events as follows:
*
* @code
- * static Eina_Bool client_add_cb(void *data, int event, void *event_info)
+ * static void client_add_cb(void *data, int event, void *event_info)
* {
- * Ecore_Evas *ee = event_info;
- * printf("client is connected to external socket %p\n", ee);
- * return ECORE_CALLBACK_PASS_ON;
+ * Evas_Object *obj = event_info;
+ * printf("client added to image object %p\n", obj);
+ * evas_object_show(obj);
* }
*
- * static Eina_Bool client_del_cb(void *data, int event, void *event_info)
+ * static void client_del_cb(void *data, int event, void *event_info)
* {
- * Ecore_Evas *ee = event_info;
- * printf("client is disconnected from external socket %p\n", ee);
- * return ECORE_CALLBACK_PASS_ON;
+ * Evas_Object *obj = event_info;
+ * printf("client deleted from image object %p\n", obj);
+ * evas_object_hide(obj);
* }
*
* void setup(void)
* {
- * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD,
+ * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD,
* client_add_cb, NULL);
- * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL,
+ * ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL,
* client_del_cb, NULL);
* }
* @endcode
*
- * Note that events come in later after the event happened. You may want to be
- * careful as data structures you had associated with the image object
- * may have been freed after deleting, but the object may still be around
- * awating cleanup and thus still be valid.You can change the size with something like:
+ * @remarks Note that events come in later after the event happened. You may want to be
+ * careful as data structures you had associated with the image object
+ * may have been freed after deleting, but the object may still be around
+ * awaiting cleanup and thus still be valid.
+ *
+ * @param[in] w The width of the canvas, in pixels
+ * @param[in] h The height of the canvas, in pixels
+ * @return A new @c Ecore_Evas instance, \n
+ * otherwise @c NULL on failure
*
* @see ecore_evas_extn_socket_listen()
* @see ecore_evas_extn_plug_new()
* @see ecore_evas_extn_plug_object_data_lock()
- * @see ecore_evas_extn_plug_object_data_unlock()
- *
- * @since 1.2
+ * @see ecore_evas_extn_plug_object_data_unlock()
*/
EAPI Ecore_Evas *ecore_evas_extn_socket_new(int w, int h);
/**
- * @brief Create a socket to provide the service for external ecore evas
- * socket.
+ * @brief Creates a socket to provide the service for external ecore evas socket.
*
- * @param ee The Ecore_Evas.
- * @param svcname The name of the service to be advertised. ensure that it is
- * unique (when combined with @p svcnum) otherwise creation may fail.
- * @param svcnum A number (any value, @c 0 being the common default) to
- * differentiate multiple instances of services with the same name.
- * @param svcsys A boolean that if true, specifies to create a system-wide
- * service all users can connect to, otherwise the service is private to the
- * user ide that created the service.
- * @return @c EINA_TRUE if creation is successful, @c EINA_FALSE if it does
- * not.
- *
- * This creates socket specified by @p svcname, @p svcnum and @p svcsys. If
- * creation is successful, @c EINA_TRUE is returned or @c EINA_FALSE if
- * creation fails.
+ * @details This creates socket specified by @a svcname, @a svcnum and @a svcsys. If
+ * creation is successful, @c EINA_TRUE is returned or @c EINA_FALSE if
+ * creation fails.
+ *
+ * @since 1.2
+ *
+ * @param[in] ee The Ecore_Evas
+ * @param[in] svcname The name of the service to be advertised \n
+ * Ensure that it is unique (when combined with @a svcnum).
+ * Otherwise creation may fail.
+ * @param[in] svcnum A number (any value, @c 0 being the common default) to
+ * differentiate multiple instances of services with the same name
+ * @param[in] svcsys Set @c EINA_TRUE to create a system-wide service all users can connect to, \n
+ * otherwise set @c EINA_FALSE if the service should be private to the
+ * user ID that created the service
+ * @return @c EINA_TRUE if created successfully, \n
+ * otherwise @c EINA_FALSE on failure
*
* @see ecore_evas_extn_socket_new()
* @see ecore_evas_extn_plug_new()
* @see ecore_evas_extn_plug_object_data_lock()
* @see ecore_evas_extn_plug_object_data_unlock()
- *
- * @since 1.2
*/
EAPI Eina_Bool ecore_evas_extn_socket_listen(Ecore_Evas *ee, const char *svcname, int svcnum, Eina_Bool svcsys);
/**
- * @brief Lock the pixel data so the socket cannot change it
+ * @brief Grabs a pointer to the actual pixels array of a given
+ * external ecore evas socket.
+ *
+ * @since 1.8
+ *
+ * @param[in] ee The Ecore_Evas
+ * @return The pixel data
+ */
+EAPI void *ecore_evas_extn_socket_pixels_get(Ecore_Evas *ee);
+
+/**
+ * @brief Marks a region of the extn_socket canvas that has been updated.
+ *
+ * @since 1.8
+ *
+ * @param[in] ee The Ecore_Evas
+ * @param[in] x The X-offset of the region to be updated
+ * @param[in] y The Y-offset of the region to be updated
+ * @param[in] w The width of the region to be updated
+ * @param[in] h The height of the region to be updated
+ */
+EAPI void ecore_evas_extn_socket_update_add(Ecore_Evas *ee, int x, int y, int w, int h);
+
+/**
+ * @brief Lock the pixel data so the plug cannot change it
+ *
+ * @param[in] ee The Ecore_Evas.
+ *
+ * @see ecore_evas_extn_socket_new()
+ * @see ecore_evas_extn_socket_unlock()
+ *
+ * @since 1.8
+ */
+EAPI void ecore_evas_extn_socket_lock(Ecore_Evas *ee);
+
+/**
+ * @brief Unlock the pixel data so the plug can change it again
+ *
+ * @param[in] ee The Ecore_Evas.
+ *
+ * @see ecore_evas_extn_socket_new()
+ * @see ecore_evas_extn_socket_lock()
+ *
+ * @since 1.8
+ */
+EAPI void ecore_evas_extn_socket_unlock(Ecore_Evas *ee);
+
+/**
+ * @brief Set the blocking about mouse events to Ecore Evas.
*
- * @param obj The image object returned by ecore_evas_extn_plug_new() to lock
+ * @param ee The Ecore_Evas.
+ * @param events_block The blocking about mouse events.
*
- * You may need to get the image pixel data with evas_object_image_data_get()
- * from the image object, but need to ensure that it does not change while
- * you are using the data. This function lets you set an advisory lock on the
- * image data so the external plug process will not render to it or alter it.
+ * @see ecore_evas_extn_socket_events_block_get()
*
- * You should only hold the lock for just as long as you need to read out the
- * image data or otherwise deal with it, and then unlock it with
- * ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than
- * 1 iteration of the main ecore loop will be problematic, so avoid it. Also
- * forgetting to unlock may cause the socket process to freeze and thus create
- * odd behavior.
+ * @since 1.11
+ */
+EINA_DEPRECATED EAPI void ecore_evas_extn_socket_events_block_set(Ecore_Evas *ee, Eina_Bool events_block);
+
+/**
+ * @brief Get the blocking about mouse events to Ecore Evas.
+ *
+ * @param ee The Ecore_Evas.
+
+ * @return The blocking about mouse events.
+ *
+ * @see ecore_evas_extn_socket_events_block_set()
+ *
+ * @since 1.11
+ */
+EINA_DEPRECATED EAPI Eina_Bool ecore_evas_extn_socket_events_block_get(Ecore_Evas *ee);
+
+/**
+ * @brief Locks the pixel data so the socket cannot change it.
+ * @since 1.2
+ *
+ * @remarks You may need to get the image pixel data with evas_object_image_data_get()
+ * from the image object, but need to ensure that it does not change while
+ * you are using the data. This function lets you set an advisory lock on the
+ * image data so the external plug process does not render to it or alter it.
+ *
+ * @remarks You should only hold the lock for just as long as you need to read out the
+ * image data or otherwise deal with it, and then unlock it with
+ * ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than
+ * one iteration of the main ecore loop is problematic, so avoid it. Also
+ * forgetting to unlock may cause the socket process to freeze and thus create
+ * odd behavior.
+ *
+ * @param[in] obj The image object returned by ecore_evas_extn_plug_new() to lock
*
* @see ecore_evas_extn_plug_new()
* @see ecore_evas_extn_plug_object_data_unlock()
- *
- * @since 1.2
*/
EAPI void ecore_evas_extn_plug_object_data_lock(Evas_Object *obj);
/**
- * @brief Unlock the pixel data so the socket can change it again.
+ * @brief Unlocks the pixel data so the socket can change it again.
*
- * @param obj The image object returned by ecore_evas_extn_plug_new() to unlock
+ * @details This function unlocks after an advisor lock has been taken by
+ * ecore_evas_extn_plug_object_data_lock().
+ * @since 1.2
*
- * This unlocks after an advisor lock has been taken by
- * ecore_evas_extn_plug_object_data_lock().
+ * @param[in] obj The image object returned by ecore_evas_extn_plug_new() to unlock
*
* @see ecore_evas_extn_plug_new()
* @see ecore_evas_extn_plug_object_data_lock()
- *
- * @since 1.2
*/
EAPI void ecore_evas_extn_plug_object_data_unlock(Evas_Object *obj);
/**
- * @brief Create a new external ecore evas plug
- *
- * @param ee_target The Ecore_Evas containing the canvas in which the new image object will live.
- * @return An evas image object that will contain the image output of a socket.
- *
- * This creates an image object that will contain the output of another
- * processes socket canvas when it connects. All input will be sent back to
- * this process as well, effectively swallowing or placing the socket process
- * in the canvas of the plug process in place of the image object. The image
- * object by default is created to be filled (equivalent of
- * evas_object_image_filled_add() on creation) so image content will scale
- * to fill the image unless otherwise reconfigured. The Ecore_Evas size
- * of the plug is the master size and determines size in pixels of the
- * plug canvas. You can change the size with something like:
+ * @brief Creates a new external ecore evas plug.
+ * @details This creates an image object that contains the output of another
+ * processes socket canvas when it connects. All input is sent back to
+ * this process as well, effectively swallowing or placing the socket process
+ * in the canvas of the plug process in place of the image object. The image
+ * object by default is created to be filled (equivalent of
+ * evas_object_image_filled_add() on creation) so image content scales
+ * to fill the image unless otherwise reconfigured. The Ecore_Evas size
+ * of the plug is the master size and determines size in pixels of the
+ * plug canvas. You can change the size with something like:
*
* @code
* Eina_Bool res = EINA_FALSE;
@@ -2574,97 +2635,77 @@ EAPI void ecore_evas_extn_plug_object_data_unlock(Evas_Object *obj);
* ecore_evas_resize(ee, 240, 400);
* @endcode
*
+ * @since 1.2
+ *
+ * @param[in] ee_target The Ecore_Evas containing the canvas in which the new image object lives
+ * @return An evas image object that contains the image output of a socket
+ *
* @see ecore_evas_extn_socket_new()
* @see ecore_evas_extn_plug_connect()
- * @since 1.2
*/
EAPI Evas_Object *ecore_evas_extn_plug_new(Ecore_Evas *ee_target);
/**
- * @brief Connect an external ecore evas plug to service provided by external
- * ecore evas socket.
+ * @brief Connects an external ecore evas plug to service provided by external
+ * ecore evas socket.
*
- * @param obj The Ecore_Evas containing the canvas in which the new image
- * object will live.
- * @param svcname The service name to connect to set up by the socket.
- * @param svcnum The service number to connect to (set up by socket).
- * @param svcsys Boolean to set if the service is a system one or not (set up
- * by socket).
- * @return @c EINA_TRUE if creation is successful, @c EINA_FALSE if it does
- * not.
+ * @since 1.2
*
- * @see ecore_evas_extn_plug_new()
+ * @param[in] obj The Ecore_Evas containing the canvas in which the new image
+ * object lives
+ * @param[in] svcname The service name to connect to set up by the socket
+ * @param[in] svcnum The service number to connect to (set up by socket)
+ * @param[in] svcsys Set @c EINA_TRUE to if the service is a system one, \n
+ * otherwise set @c EINA_FALSE if it is not a system one (set up by socket)
+ * @return @c EINA_TRUE if created successfully,
+ * otherwise @c EINA_FALSE on failure
*
- * @since 1.2
+ * @see ecore_evas_extn_plug_new()
*/
EAPI Eina_Bool ecore_evas_extn_plug_connect(Evas_Object *obj, const char *svcname, int svcnum, Eina_Bool svcsys);
/**
- * @brief Retrieve the coordinates of the mouse pointer
- *
- * @param ee The Ecore_Evas containing the pointer
- * @param x Pointer to integer to store horizontal coordinate. May be @c NULL.
- * @param y Pointer to integer to store vertical coordinate. May be @c NULL.
+ * @brief Retrieve the Visual used for pixmap creation
*
* @since 1.8
- */
-EAPI void ecore_evas_pointer_xy_get(const Ecore_Evas *ee, Evas_Coord *x, Evas_Coord *y);
-
-/**
- * @brief Retrieve the coordinates of the mouse pointer
- *
- * @param ee The Ecore_Evas containing the pointer
- * @param x The horizontal coordinate to move the pointer to
- * @param y The vertical coordinate to move the pointer to
*
- * @return @c EINA_TRUE on success, EINA_FALSE on failure.
- *
- * @since 1.8
- */
-EAPI Eina_Bool ecore_evas_pointer_warp(const Ecore_Evas *ee, Evas_Coord x, Evas_Coord y);
-
-/**
- * @brief Retrieve the Visual used for pixmap creation
- *
- * @param ee The Ecore_Evas containing the pixmap
+ * @param[in] ee The Ecore_Evas containing the pixmap
*
* @return The Visual which was used when creating the pixmap
*
* @warning If and when this function is called depends on the underlying
* windowing system. This function should only be called if the Ecore_Evas was
* created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new
- *
- * @since 1.8
*/
EAPI void *ecore_evas_pixmap_visual_get(const Ecore_Evas *ee);
/**
* @brief Retrieve the Colormap used for pixmap creation
*
- * @param ee The Ecore_Evas containing the pixmap
+ * @since 1.8
+ *
+ * @param[in] ee The Ecore_Evas containing the pixmap
*
* @return The Colormap which was used when creating the pixmap
*
* @warning If and when this function is called depends on the underlying
* windowing system. This function should only be called if the Ecore_Evas was
* created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new
- *
- * @since 1.8
*/
EAPI unsigned long ecore_evas_pixmap_colormap_get(const Ecore_Evas *ee);
/**
* @brief Retrieve the depth used for pixmap creation
*
- * @param ee The Ecore_Evas containing the pixmap
+ * @since 1.8
+ *
+ * @param[in] ee The Ecore_Evas containing the pixmap
*
* @return The depth which was used when creating the pixmap
*
* @warning If and when this function is called depends on the underlying
* windowing system. This function should only be called if the Ecore_Evas was
* created using @c ecore_evas_software_x11_pixmap_new or @c ecore_evas_gl_x11_pixmap_new
- *
- * @since 1.8
*/
EAPI int ecore_evas_pixmap_depth_get(const Ecore_Evas *ee);
diff --git a/src/lib/ecore_fb/Ecore_Fb.h b/src/lib/ecore_fb/Ecore_Fb.h
index 69d37a49dd..fc73df42f8 100644
--- a/src/lib/ecore_fb/Ecore_Fb.h
+++ b/src/lib/ecore_fb/Ecore_Fb.h
@@ -18,15 +18,14 @@
#endif
/* FIXME:
- * maybe a new module?
- * - code to get battery info
- * - code to get thermal info
+ * Maybe a new module?
+ * - Code to get the battery info
+ * - Code to get the thermal info
* ecore evas fb isn't good enough for weird things, like multiple fb's, same happens here.
* backlight support using new kernel interface
* absolute axis
* joystick
* ecore_fb_li_device_close_all ? or a shutdown of the subsystem?
- *
*/
#ifdef __cplusplus
@@ -34,23 +33,24 @@ extern "C" {
#endif
/**
+ * @internal
* @defgroup Ecore_FB_Group Ecore_FB - Frame buffer convenience functions.
- * @ingroup Ecore
+ * @ingroup Ecore_Group
*
- * Functions used to set up and shut down the Ecore_Framebuffer functions.
+ * @brief This group discusses the functions used to set up and shut down the Ecore_Framebuffer functions.
*
* @{
*/
/**
* @typedef Ecore_Fb_Input_Device
- * Input device handler.
+ * @brief The structure type containing the Input device handler.
*/
typedef struct _Ecore_Fb_Input_Device Ecore_Fb_Input_Device;
/**
* @enum _Ecore_Fb_Input_Device_Cap
- * Device capabilities.
+ * @brief Enumeration that defines the device capabilities.
*/
enum _Ecore_Fb_Input_Device_Cap
{
@@ -62,7 +62,7 @@ enum _Ecore_Fb_Input_Device_Cap
/**
* @typedef Ecore_Fb_Input_Device_Cap
- * Device capabilities.
+ * @brief Enumeration that defines the device capabilities.
*/
typedef enum _Ecore_Fb_Input_Device_Cap Ecore_Fb_Input_Device_Cap;
diff --git a/src/lib/ecore_file/Ecore_File.h b/src/lib/ecore_file/Ecore_File.h
index 806ad87f84..35276ded2d 100644
--- a/src/lib/ecore_file/Ecore_File.h
+++ b/src/lib/ecore_file/Ecore_File.h
@@ -35,6 +35,7 @@
#endif /* ! _WIN32 */
/**
+ * @internal
* @file Ecore_File.h
* @brief Files utility functions
*/
@@ -44,66 +45,67 @@ extern "C" {
#endif
/**
+ * @internal
* @defgroup Ecore_File_Group Ecore_File - Files and directories convenience functions
- * @ingroup Ecore
+ * @ingroup Ecore_Group
*
* @{
*/
/**
* @typedef Ecore_File_Monitor
- * Abstract type used when monitoring a directory.
+ * @brief The structure type containing the abstract type used to monitor a directory.
*/
typedef struct _Ecore_File_Monitor Ecore_File_Monitor;
/**
* @typedef Ecore_File_Download_Job
- * Abstract type used when aborting a download.
+ * @brief The structure type containing the abstract type used to abort a download.
*/
typedef struct _Ecore_File_Download_Job Ecore_File_Download_Job;
/**
* @typedef _Ecore_File_Event
- * The event type returned when a file or directory is monitored.
+ * @brief The structure type containing the event type returned when a file or directory is monitored.
*/
typedef enum _Ecore_File_Event
{
- ECORE_FILE_EVENT_NONE, /**< No event. */
- ECORE_FILE_EVENT_CREATED_FILE, /**< Created file event. */
- ECORE_FILE_EVENT_CREATED_DIRECTORY, /**< Created directory event. */
- ECORE_FILE_EVENT_DELETED_FILE, /**< Deleted file event. */
- ECORE_FILE_EVENT_DELETED_DIRECTORY, /**< Deleted directory event. */
- ECORE_FILE_EVENT_DELETED_SELF, /**< Deleted monitored directory event. */
- ECORE_FILE_EVENT_MODIFIED, /**< Modified file or directory event. */
+ ECORE_FILE_EVENT_NONE, /**< No event */
+ ECORE_FILE_EVENT_CREATED_FILE, /**< Created file event */
+ ECORE_FILE_EVENT_CREATED_DIRECTORY, /**< Created directory event */
+ ECORE_FILE_EVENT_DELETED_FILE, /**< Deleted file event */
+ ECORE_FILE_EVENT_DELETED_DIRECTORY, /**< Deleted directory event */
+ ECORE_FILE_EVENT_DELETED_SELF, /**< Deleted monitored directory event */
+ ECORE_FILE_EVENT_MODIFIED, /**< Modified file or directory event */
ECORE_FILE_EVENT_CLOSED /**< Closed file event */
} Ecore_File_Event;
/**
* @typedef Ecore_File_Monitor_Cb
- * Callback type used when a monitored directory has changes.
+ * @brief Called to be used when a monitored directory has changed.
*/
typedef void (*Ecore_File_Monitor_Cb)(void *data, Ecore_File_Monitor *em, Ecore_File_Event event, const char *path);
/**
* @typedef Ecore_File_Download_Completion_Cb
- * Callback type used when a download is finished.
+ * @brief Called to be used when a download has finished.
*/
typedef void (*Ecore_File_Download_Completion_Cb)(void *data, const char *file, int status);
/**
* @typedef _Ecore_File_Progress_Return
- * What to do with the download as a return from the
- * Ecore_File_Download_Progress_Cb function, if provided.
+ * @brief Enumeration on what to do with the download as a return from the
+ * Ecore_File_Download_Progress_Cb function, if provided.
*/
typedef enum _Ecore_File_Progress_Return
{
- ECORE_FILE_PROGRESS_CONTINUE = 0, /**< Continue the download. */
- ECORE_FILE_PROGRESS_ABORT = 1 /**< Abort the download. */
+ ECORE_FILE_PROGRESS_CONTINUE = 0, /**< Continue the download */
+ ECORE_FILE_PROGRESS_ABORT = 1 /**< Abort the download */
} Ecore_File_Progress_Return;
/**
* @typedef Ecore_File_Download_Progress_Cb
- * Callback type used while a download is in progress.
+ * @brief Called to be used while a download is in progress.
*/
typedef int (*Ecore_File_Download_Progress_Cb)(void *data,
const char *file,
@@ -140,6 +142,7 @@ 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 5618f3130d..1615374872 100644
--- a/src/lib/ecore_imf/Ecore_IMF.h
+++ b/src/lib/ecore_imf/Ecore_IMF.h
@@ -34,68 +34,57 @@ extern "C" {
#endif
/**
- * @defgroup Ecore_IMF_Lib_Group Ecore_IMF - Ecore Input Method Library Functions
- * @ingroup Ecore
+ * @internal
+ * @defgroup Ecore_IMF_Group Ecore_IMF - Ecore Input Method Library Functions
+ * @ingroup Ecore_Group
*
* Utility functions that set up and shut down the Ecore Input Method
* library.
+ *
+ * @{
*/
/**
+ * @internal
* @defgroup Ecore_IMF_Context_Group Ecore Input Method Context Functions
- * @ingroup Ecore_IMF_Lib_Group
+ * @ingroup Ecore_IMF_Group
*
- * Functions that operate on Ecore Input Method Context objects.
+ * @brief This group discusses the functions that operate on Ecore Input Method Context objects.
- * Ecore Input Method Context Function defines the interface for EFL input methods.
- * An input method is used by EFL text input widgets like elm_entry
- * (based on edje_entry) to map from key events to Unicode character strings.
- *
- * The default input method can be set through setting the ECORE_IMF_MODULE environment variable.
- * eg) export ECORE_IMF_MODULE=xim (or scim or ibus)
+ * @remarks Ecore Input Method Context Function defines the interface for EFL input methods.
+ * An input method is used by EFL text input widgets like elm_entry
+ * (based on edje_entry) to map from key events to Unicode character strings.
*
- * An input method may consume multiple key events in sequence and finally output the composed result.
- * This is called preediting, and an input method may provide feedback about
- * this process by displaying the intermediate composition states as preedit text.
+ * @remarks The default input method can be set through setting the ECORE_IMF_MODULE environment variable.
+ * eg: export ECORE_IMF_MODULE=xim (or scim or ibus)
*
- * Immodule is plugin to connect your application and input method framework such as SCIM, ibus, and so on.@n
- * ecore_imf_init() should be called to initialize and load immodule.@n
- * ecore_imf_shutdown() is used for shutdowning and unloading immodule.
+ * @remarks An input method may consume multiple key events in sequence and finally give the composed result as output.
+ * This is called preediting, and an input method may provide feedback about
+ * this process by displaying the intermediate composition states as preedit text.
*
- * An example of usage of these functions can be found at:
- * @li @ref ecore_imf_example_c
- */
-
-/**
- * @addtogroup Ecore_IMF_Context_Group
+ * @remarks Immodule is a plugin to connect your application and input method framework such as SCIM, ibus, and so on. \n
+ * ecore_imf_init() should be called to initialize and load immodule. \n
+ * ecore_imf_shutdown() is used to shutdown and unload immodule.
*
* @{
*/
/**
- * @example ecore_imf_example.c
- * Show how to write simple editor using the Ecore_IMF library
- */
-
-/* ecore_imf_context_input_panel_event_callback_add() flag */
-
-/**
- * @typedef Ecore_IMF_Input_Panel_Event
- * Enum containing input panel events.
+ * @brief Enumeration of Ecore IMF Input Panel State type
+ * @see ecore_imf_context_input_panel_event_callback_add
*/
typedef enum
{
- ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< called when the state of the input panel is changed. @since 1.7 */
- ECORE_IMF_INPUT_PANEL_LANGUAGE_EVENT, /**< called when the language of the input panel is changed. @since 1.7 */
- ECORE_IMF_INPUT_PANEL_SHIFT_MODE_EVENT, /**< called when the shift key state of the input panel is changed @since 1.7 */
- ECORE_IMF_INPUT_PANEL_GEOMETRY_EVENT, /**< called when the size of the input panel is changed. @since 1.7 */
- ECORE_IMF_CANDIDATE_PANEL_STATE_EVENT, /**< called when the state of the candidate word panel is changed. @since 1.7 */
- ECORE_IMF_CANDIDATE_PANEL_GEOMETRY_EVENT /**< called when the size of the candidate word panel is changed. @since 1.7 */
+ ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< Called when the state of the input panel is changed @since 1.7 */
+ ECORE_IMF_INPUT_PANEL_LANGUAGE_EVENT, /**< Called when the language of the input panel is changed @since 1.7 */
+ ECORE_IMF_INPUT_PANEL_SHIFT_MODE_EVENT, /**< Called when the shift key state of the input panel is changed @since 1.7 */
+ ECORE_IMF_INPUT_PANEL_GEOMETRY_EVENT, /**< Called when the size of the input panel is changed @since 1.7 */
+ ECORE_IMF_CANDIDATE_PANEL_STATE_EVENT, /**< Called when the state of the candidate word panel is changed @since 1.7 */
+ 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.
+ * @brief Enumeration of Ecore IMF Input Panel State type
*/
typedef enum
{
@@ -105,8 +94,7 @@ typedef enum
} Ecore_IMF_Input_Panel_State;
/**
- * @typedef Ecore_IMF_Input_Panel_Shift_Mode
- * Enum containing input shift mode states.
+ * @brief Enumeration of Ecore IMF Input Panel Shift Mode type
*/
typedef enum
{
@@ -115,8 +103,7 @@ typedef enum
} Ecore_IMF_Input_Panel_Shift_Mode;
/**
- * @typedef Ecore_IMF_Candidate_Panel_State
- * Enum containing candidate word panel state notifications.
+ * @brief Enumeration of Ecore IMF Candidate Panel type
*/
typedef enum
{
@@ -132,7 +119,7 @@ typedef struct _Ecore_IMF_Event_Commit Ecore_IMF_Event_Commit;
typedef struct _Ecore_IMF_Event_Delete_Surrounding Ecore_IMF_Event_Delete_Surrounding;
typedef struct _Ecore_IMF_Event_Selection Ecore_IMF_Event_Selection;
-/* Events to filter */
+/* Events to the filter */
typedef struct _Ecore_IMF_Event_Mouse_Down Ecore_IMF_Event_Mouse_Down;
typedef struct _Ecore_IMF_Event_Mouse_Up Ecore_IMF_Event_Mouse_Up;
typedef struct _Ecore_IMF_Event_Mouse_In Ecore_IMF_Event_Mouse_In;
@@ -145,7 +132,7 @@ typedef union _Ecore_IMF_Event Ecore_IMF_Event;
typedef struct _Ecore_IMF_Context Ecore_IMF_Context; /**< An Input Method Context */
typedef struct _Ecore_IMF_Context_Class Ecore_IMF_Context_Class; /**< An Input Method Context class */
-typedef struct _Ecore_IMF_Context_Info Ecore_IMF_Context_Info; /**< An Input Method Context info */
+typedef struct _Ecore_IMF_Context_Info Ecore_IMF_Context_Info; /**< Input Method Context info */
/* Preedit attribute info */
typedef struct _Ecore_IMF_Preedit_Attr Ecore_IMF_Preedit_Attr;
@@ -156,27 +143,20 @@ 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);
/**
* @typedef Ecore_IMF_Callback_Type
*
- * Ecore IMF Event callback types.
+ * @brief Enumeration that defines the Ecore IMF Event callback types.
*
* @see ecore_imf_context_event_callback_add()
*/
typedef enum
{
- ECORE_IMF_CALLBACK_PREEDIT_START, /**< "PREEDIT_START" is called when a new preediting sequence starts. @since 1.2 */
- ECORE_IMF_CALLBACK_PREEDIT_END, /**< "PREEDIT_END" is called when a preediting sequence has been completed or canceled. @since 1.2 */
- ECORE_IMF_CALLBACK_PREEDIT_CHANGED, /**< "PREEDIT_CHANGED" is called whenever the preedit sequence currently being entered has changed. @since 1.2 */
+ ECORE_IMF_CALLBACK_PREEDIT_START, /**< "PREEDIT_START" is called when a new preediting sequence starts @since 1.2 */
+ ECORE_IMF_CALLBACK_PREEDIT_END, /**< "PREEDIT_END" is called when a preediting sequence has been completed or cancelled @since 1.2 */
+ ECORE_IMF_CALLBACK_PREEDIT_CHANGED, /**< "PREEDIT_CHANGED" is called whenever the preedit sequence currently being entered has changed @since 1.2 */
ECORE_IMF_CALLBACK_COMMIT, /**< "COMMIT" is called when a complete input sequence has been entered by the user @since 1.2 */
ECORE_IMF_CALLBACK_DELETE_SURROUNDING, /**< "DELETE_SURROUNDING" is called when the input method needs to delete all or part of the context surrounding the cursor @since 1.2 */
ECORE_IMF_CALLBACK_SELECTION_SET, /**< "SELECTION_SET" is called when the input method needs to set the selection @since 1.9 */
@@ -186,7 +166,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Event_Type
*
- * Ecore IMF event types.
+ * @brief Enumeration that defines the Ecore IMF event types.
*
* @see ecore_imf_context_filter_event()
*/
@@ -203,7 +183,7 @@ typedef enum
} Ecore_IMF_Event_Type;
/**
* @typedef Ecore_IMF_Keyboard_Modifiers
- * Type for Ecore_IMF keyboard modifiers
+ * @brief Enumeration that defines the types of Ecore_IMF keyboard modifiers.
*/
typedef enum
{
@@ -217,7 +197,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Keyboard_Locks
- * Type for Ecore_IMF keyboard locks
+ * @brief Enumeration that defines the types of Ecore_IMF keyboard locks.
*/
typedef enum
{
@@ -229,7 +209,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Mouse_Flags
- * Type for Ecore_IMF mouse flags
+ * @brief Enumeration that defines the types of Ecore_IMF mouse flags.
*/
typedef enum
{
@@ -238,10 +218,6 @@ 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,
@@ -257,7 +233,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Preedit_Type
*
- * Ecore IMF Preedit style types
+ * @brief Enumeration that defines the Ecore IMF Preedit style types.
*
* @see ecore_imf_context_preedit_string_with_attributes_get()
*/
@@ -276,22 +252,22 @@ typedef enum
/**
* @typedef Ecore_IMF_Autocapital_Type
*
- * Autocapitalization Types.
+ * @brief Enumeration that defines the auto-capitalization types.
*
* @see ecore_imf_context_autocapital_type_set()
*/
typedef enum
{
ECORE_IMF_AUTOCAPITAL_TYPE_NONE, /**< No auto-capitalization when typing @since 1.1 */
- ECORE_IMF_AUTOCAPITAL_TYPE_WORD, /**< Autocapitalize each word typed @since 1.1 */
- ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE, /**< Autocapitalize the start of each sentence @since 1.1 */
- ECORE_IMF_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Autocapitalize all letters @since 1.1 */
+ ECORE_IMF_AUTOCAPITAL_TYPE_WORD, /**< Auto-capitalize each type word @since 1.1 */
+ ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE, /**< Auto-capitalize the start of each sentence @since 1.1 */
+ ECORE_IMF_AUTOCAPITAL_TYPE_ALLCHARACTER, /**< Auto-capitalize all letters @since 1.1 */
} Ecore_IMF_Autocapital_Type;
/**
* @typedef Ecore_IMF_Input_Panel_Layout
*
- * Input panel (virtual keyboard) layout types.
+ * @brief Enumeration that defines the input panel (virtual keyboard) layout types.
*
* @see ecore_imf_context_input_panel_layout_set()
*/
@@ -307,8 +283,8 @@ typedef enum
ECORE_IMF_INPUT_PANEL_LAYOUT_NUMBERONLY, /**< Number Only layout */
ECORE_IMF_INPUT_PANEL_LAYOUT_INVALID, /**< Never use this */
ECORE_IMF_INPUT_PANEL_LAYOUT_HEX, /**< Hexadecimal layout @since 1.2 */
- ECORE_IMF_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout including ESC, Alt, Ctrl key, so on (no auto-correct, no auto-capitalization) @since 1.2 */
- ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD, /**< Like normal, but no auto-correct, no auto-capitalization etc. @since 1.2 */
+ ECORE_IMF_INPUT_PANEL_LAYOUT_TERMINAL, /**< Command-line terminal layout including the ESC, Alt, Ctrl key, and so on (no auto-correct, no auto-capitalization) @since 1.2 */
+ ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD, /**< Like normal, but no auto-correct, no auto-capitalization, and so on @since 1.2 */
ECORE_IMF_INPUT_PANEL_LAYOUT_DATETIME, /**< Date and time layout @since 1.8 */
ECORE_IMF_INPUT_PANEL_LAYOUT_EMOTICON /**< Emoticon layout @since 1.10 */
} Ecore_IMF_Input_Panel_Layout;
@@ -316,7 +292,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Input_Panel_Lang
*
- * Input panel (virtual keyboard) language modes.
+ * @brief Enumeration that defines the input panel (virtual keyboard) language modes.
*
* @see ecore_imf_context_input_panel_language_set()
*/
@@ -329,7 +305,7 @@ typedef enum
/**
* @typedef Ecore_IMF_Input_Panel_Return_Key_Type
*
- * "Return" Key types on the input panel (virtual keyboard).
+ * @brief Enumeration that defines the "Return" key types on the input panel (virtual keyboard).
*
* @see ecore_imf_context_input_panel_return_key_type_set()
*/
@@ -378,6 +354,7 @@ enum
ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NORMAL, /**< The normal password layout @since 1.12 */
ECORE_IMF_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY /**< The password layout to allow only number @since 1.12 */
};
+
/**
* @typedef Ecore_IMF_BiDi_Direction
* @brief Enumeration that defines the types of Ecore_IMF bidirectionality
@@ -385,52 +362,32 @@ enum
*/
typedef enum
{
- ECORE_IMF_BIDI_DIRECTION_NEUTRAL, /**< The Neutral mode @since 1.12 */
+ ECORE_IMF_BIDI_DIRECTION_NEUTRAL, /**< The neutral mode @since 1.12 */
ECORE_IMF_BIDI_DIRECTION_LTR, /**< The Left to Right mode @since 1.12 */
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;
@@ -438,10 +395,6 @@ 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;
@@ -449,48 +402,36 @@ 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 */
+ int button; /**< The button that has been pressed */
struct {
int x, y;
} output;
struct {
int x, y;
} canvas;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
- Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding the mouse click (single, double or triple click) */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
+ Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding to a mouse click (single, double, or triple click) */
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 */
+ int button; /**< The button that has been pressed */
struct {
int x, y;
} output;
struct {
int x, y;
} canvas;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
- Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding the mouse click (single, double or triple click) */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
+ Ecore_IMF_Mouse_Flags flags; /**< The flags corresponding to a mouse click (single, double, or triple click) */
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;
@@ -500,15 +441,11 @@ struct _Ecore_IMF_Event_Mouse_In
struct {
int x, y;
} canvas;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
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;
@@ -518,15 +455,11 @@ struct _Ecore_IMF_Event_Mouse_Out
struct {
int x, y;
} canvas;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
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;
@@ -538,15 +471,11 @@ struct _Ecore_IMF_Event_Mouse_Move
int x, y;
} canvas;
} cur, prev;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
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 */
@@ -557,44 +486,33 @@ struct _Ecore_IMF_Event_Mouse_Wheel
struct {
int x, y;
} canvas;
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
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 */
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ const char *keyname; /**< The string name of the key that has been pressed */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
const char *key; /**< The logical key : (eg shift+1 == exclamation) */
const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
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 */
- Ecore_IMF_Keyboard_Modifiers modifiers; /**< The keyboard modifiers active when the event has been emitted */
- Ecore_IMF_Keyboard_Locks locks; /**< The keyboard locks active when the event has been emitted */
+ const char *keyname; /**< The string name of the key that has been pressed */
+ Ecore_IMF_Keyboard_Modifiers modifiers; /**< The active keyboard modifiers when the event has been emitted */
+ Ecore_IMF_Keyboard_Locks locks; /**< The active keyboard locks when the event has been emitted */
const char *key; /**< The logical key : (eg shift+1 == exclamation) */
const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
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;
@@ -607,171 +525,124 @@ 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 */
- unsigned int start_index; /**< start index of the range (in bytes) */
- unsigned int end_index; /**< end index of the range (in bytes) */
+ Ecore_IMF_Preedit_Type preedit_type; /**< The preedit style type */
+ unsigned int start_index; /**< The start index of the range (in bytes) */
+ unsigned int end_index; /**< The 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); /**< 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 */
+ 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);
};
-/**
- * @struct _Ecore_IMF_Context_Info
- * @brief A IMF structure containing context information.
- */
struct _Ecore_IMF_Context_Info
{
- const char *id; /* ID */
- const char *description; /* Human readable description */
- const char *default_locales; /* Languages for which this context is the default, separated by : */
- const char *canvas_type; /* The canvas type used by the input method. Eg.: evas */
- int canvas_required; /* Whether the canvas usage is required for this input method */
+ const char *id; /**< ID */
+ const char *description; /**< Human readable description */
+ const char *default_locales; /**< Languages for which this context is the default, separated by : */
+ const char *canvas_type; /**< The canvas type used by the input method. Eg.: evas */
+ int canvas_required; /**< Whether canvas usage is required for this input method */
};
/**
- * @}
- */
-
-/**
- * Initialises the Ecore_IMF library.
- * @return Number of times the library has been initialised without being
- * shut down.
- * @ingroup Ecore_IMF_Lib_Group
+ * @brief Initialises the Ecore_IMF library.
+ *
+ * @return The number of times the library has been initialised without being
+ * shut down
+ * @ingroup Ecore_IMF_Group
*/
EAPI int ecore_imf_init(void);
/**
- * Shuts down the Ecore_IMF library.
- * @return Number of times the library has been initialised without being
- * shut down.
- * @ingroup Ecore_IMF_Lib_Group
+ * @brief Shuts down the Ecore_IMF library.
+ *
+ * @return The number of times the library has been initialised without being
+ * shut down
+ * @ingroup Ecore_IMF_Group
*/
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));
/**
- * Hide the input panel.
- * @return EINA_TRUE if the input panel will be hidden
- EINA_FALSE if the input panel is already in hidden state
- * @ingroup Ecore_IMF_Lib_Group
+ * @brief Hides the input panel.
+ *
* @since 1.8.0
+ *
+ * @return @c EINA_TRUE if the input panel is hidden,
+ * otherwise @c EINA_FALSE if the input panel is already in the hidden state
+ * @ingroup Ecore_IMF_Group
*/
EAPI Eina_Bool ecore_imf_input_panel_hide(void);
/**
- * Get the list of the available Input Method Context ids.
+ * @brief Gets the list of available Input Method Context IDs.
*
- * Note that the caller is responsible for freeing the Eina_List
- * when finished with it. There is no need to finish the list strings.
+ * @remarks Note that the caller is responsible for freeing the Eina_List
+ * when he is finished with it. There is no need to finish the list strings.
*
- * @return Return an Eina_List of strings;
- * on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Group
+ * @return An Eina_List of strings,
+ * otherwise @c NULL on failure
*/
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);
/**
- * Get the id of the default Input Method Context.
- * The id may to used to create a new instance of an Input Method
- * Context object.
+ * @brief Gets the ID of the default Input Method Context.
*
- * @return Return a string containing the id of the default Input
- * Method Context; on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Group
+ * @remarks The ID may be used to create a new instance of an Input Method
+ * Context object.
+ *
+ * @return A string containing the ID of the default Input Method Context,
+ * otherwise @c NULL on failure
*/
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);
/**
* Retrieve the info for the Input Method Context with @p id.
*
- * @param id The Input Method Context id to query for.
+ * @param[in] id The Input Method Context id to query for.
* @return Return a #Ecore_IMF_Context_Info for the Input Method Context with @p id;
* on failure it returns NULL.
* @ingroup Ecore_IMF_Context_Group
@@ -805,127 +676,125 @@ EAPI const char *ecore_imf_context_default_id_by_canvas_type_g
EAPI const Ecore_IMF_Context_Info *ecore_imf_context_info_by_id_get(const char *id);
/**
- * Create a new Input Method Context defined by the given id.
+ * @brief Gets the info for the Input Method Context with ID @a id.
*
- * @param id The Input Method Context id.
- * @return A newly allocated Input Method Context;
- * on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] id The Input Method Context ID to query for
+ * @return An #Ecore_IMF_Context_Info for the Input Method Context with ID @a id,
+ * otherwise @c NULL on failure
*/
EAPI Ecore_IMF_Context *ecore_imf_context_add(const char *id);
/**
- * Retrieve the info for the given Input Method Context.
+ * @brief Gets the info for the given Input Method Context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return Return a #Ecore_IMF_Context_Info for the given Input Method Context;
- * on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return An #Ecore_IMF_Context_Info for the given Input Method Context,
+ * otherwise @c NULL on failure
*/
EAPI const Ecore_IMF_Context_Info *ecore_imf_context_info_get(Ecore_IMF_Context *ctx);
/**
- * Delete the given Input Method Context and free its memory.
+ * @brief Deletes the given Input Method Context and frees its memory.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_del(Ecore_IMF_Context *ctx);
/**
- * Set the client window for the Input Method Context; this is the
- * Ecore_X_Window when using X11, Ecore_Win32_Window when using Win32, etc.
- * This window is used in order to correctly position status windows, and may
- * also be used for purposes internal to the Input Method Context.
+ * @brief Sets the client window for the Input Method Context. This is the
+ * Ecore_X_Window when using X11, Ecore_Win32_Window when using Win32, and so on.
+ *
+ * @remarks This window is used in order to correctly position status windows and may
+ * also be used for purposes that are internal to the Input Method Context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param window The client window. This may be @c NULL to indicate
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] window The client windowc\n
+ * This may be @c NULL to indicate
* that the previous client window no longer exists.
- * @ingroup Ecore_IMF_Context_Group
*/
EAPI void ecore_imf_context_client_window_set(Ecore_IMF_Context *ctx, void *window);
/**
- * Get the client window of the Input Method Context
+ * @brief Gets the client window of the Input Method Context.
*
- * See @ref ecore_imf_context_client_window_set for more details.
- *
- * @param ctx An #Ecore_IMF_Context.
- * @return Return the client window.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The client window
+ *
+ * @see ecore_imf_context_client_window_set()
*/
EAPI void *ecore_imf_context_client_window_get(Ecore_IMF_Context *ctx);
/**
- * Set the client canvas for the Input Method Context; this is the
- * canvas in which the input appears.
- * The canvas type can be determined by using the context canvas type.
- * Actually only canvas with type "evas" (Evas *) is supported.
- * This canvas may be used in order to correctly position status windows, and may
- * also be used for purposes internal to the Input Method Context.
+ * @brief Sets the client canvas for the Input Method Context. This is the
+ * canvas in which the input appears.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param canvas The client canvas. This may be @c NULL to indicate
+ * @remarks The canvas type can be determined by using the context canvas type.
+ * Actually only a canvas with type "evas" (Evas *) is supported.
+ *
+ * @remarks This canvas may be used in order to correctly position status windows, and may
+ * also be used for purposes that are internal to the Input Method Context.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] canvas The client canvas \n
+ * This may be @c NULL to indicate
* that the previous client canvas no longer exists.
- * @ingroup Ecore_IMF_Context_Group
*/
EAPI void ecore_imf_context_client_canvas_set(Ecore_IMF_Context *ctx, void *canvas);
/**
- * Get the client canvas of the Input Method Context.
+ * @brief Gets the client canvas of the Input Method Context.
*
- * See @ref ecore_imf_context_client_canvas_set for more details.
- *
- * @param ctx An #Ecore_IMF_Context.
- * @return Return the client canvas.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The client canvas
+ *
+ * @see ecore_imf_context_client_canvas_set()
*/
EAPI void *ecore_imf_context_client_canvas_get(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to show itself.
+ * @brief Asks the Input Method Context to show itself.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_show(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to hide itself.
+ * @brief Asks the Input Method Context to hide itself.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_hide(Ecore_IMF_Context *ctx);
/**
- * Retrieve the current preedit string and cursor position
- * for the Input Method Context.
+ * @brief Gets the current preedit string and cursor position
+ * for the Input Method Context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param str Location to store the retrieved string. The
- * string retrieved must be freed with free().
- * @param cursor_pos Location to store position of cursor (in characters)
- * within the preedit string.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] str The location to store the retrieved string \n
+ * The string retrieved must be freed with free().
+ * @param[out] cursor_pos The location to store the position of the cursor (in characters)
+ * within the preedit string
*/
EAPI void ecore_imf_context_preedit_string_get(Ecore_IMF_Context *ctx, char **str, int *cursor_pos);
/**
- * Retrieve the current preedit string, attributes and
- * cursor position for the Input Method Context.
+ * @brief Gets the current preedit string, attributes, and
+ * cursor position for the Input Method Context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param str Location to store the retrieved string. The
- * string retrieved must be freed with free().
- * @param attrs an Eina_List of attributes
- * @param cursor_pos Location to store position of cursor (in characters)
- * within the preedit string.
- * @ingroup Ecore_IMF_Context_Group
+ * @since 1.1.0
*
- * Example
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] str The location to store the retrieved string \n
+ * The string retrieved must be freed with free().
+ * @param[in] attrs An Eina_List of attributes
+ * @param[out] cursor_pos The location to store the position of the cursor (in characters)
+ * within the preedit string
+ *
+ * Example:
* @code
* char *preedit_string;
* int cursor_pos;
@@ -964,18 +833,16 @@ EAPI void ecore_imf_context_preedit_string_get(Ecore_IM
*
* free(preedit_string);
* @endcode
- * @since 1.1.0
*/
EAPI void ecore_imf_context_preedit_string_with_attributes_get(Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos);
/**
- * Notify the Input Method Context that the widget to which its
- * correspond has gained focus.
+ * @brief Notifies the Input Method Context that the widget to which it
+ * corresponds has gained focus.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*
- * Example
+ * Example:
* @code
* static void
* _focus_in_cb(void *data, Evas_Object *o, const char *emission, const char *source)
@@ -990,13 +857,12 @@ EAPI void ecore_imf_context_preedit_string_with_attribu
EAPI void ecore_imf_context_focus_in(Ecore_IMF_Context *ctx);
/**
- * Notify the Input Method Context that the widget to which its
- * correspond has lost focus.
+ * @brief Notifies the Input Method Context that the widget to which it
+ * corresponds has lost focus.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*
- * Example
+ * Example:
* @code
* static void
* _focus_out_cb(void *data, Evas_Object *o, const char *emission, const char *source)
@@ -1012,21 +878,20 @@ EAPI void ecore_imf_context_focus_in(Ecore_IMF_Context
EAPI void ecore_imf_context_focus_out(Ecore_IMF_Context *ctx);
/**
- * Notify the Input Method Context that a change such as a
- * change in cursor position has been made. This will typically
- * cause the Input Method Context to clear the preedit state or commit the preedit string.
+ * @brief Notifies the Input Method Context that a change, such as a
+ * change in the cursor position, has been made. This typically
+ * causes the Input Method Context to clear the preedit state or commit the preedit string.
*
- * The operation of ecore_imf_context_reset() depends on the specific characteristics of
- * each language. For example, the preedit string is cleared in the Chinese and Japanese Input Method Engine.
- * However, The preedit string is committed and then cleared in the Korean Input Method Engine.
+ * @remarks The operation of ecore_imf_context_reset() depends on the specific characteristics of
+ * each language. For example, the preedit string is cleared in the Chinese and Japanese Input Method Engine.
+ * However, The preedit string is committed and then cleared in the Korean Input Method Engine.
*
- * This function should be called in case of the focus-out and mouse down event callback function.
- * In addition, it should be called before inserting some text.
+ * @remarks This function should be called for the focus-out and mouse down event callback function.
+ * In addition, it should be called before inserting some text.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*
- * Example
+ * Example:
* @code
* static void
* _focus_out_cb(void *data, Evas_Object *o, const char *emission, const char *source)
@@ -1042,117 +907,114 @@ EAPI void ecore_imf_context_focus_out(Ecore_IMF_Context
EAPI void ecore_imf_context_reset(Ecore_IMF_Context *ctx);
/**
- * Notify the Input Method Context that a change in the cursor
- * position has been made.
+ * @brief Notifies the Input Method Context that a change in the cursor
+ * position has been made.
*
- * This function should be called when cursor position is changed or mouse up event is generated.
- * Some input methods that do a heavy job using this event can give a critical performance latency problem.
- * For better typing performance, we suggest that the cursor position change events need to be occurred
- * only if the cursor position is on a confirmed status not on moving status.
+ * @remarks This function should be called when the cursor position is changed or a mouse up event is generated.
+ * Some input methods that do a heavy job using this event can give a critical performance latency problem.
+ * For better typing performance, we suggest that the cursor position change events need to occur
+ * only if the cursor position is on a confirmed status, not on a moving status.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param cursor_pos New cursor position in characters.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] cursor_pos The new cursor position in characters
*/
EAPI void ecore_imf_context_cursor_position_set(Ecore_IMF_Context *ctx, int cursor_pos);
/**
- * Notify the Input Method Context that a change in the cursor
- * location has been made. The location is relative to the canvas.
- * The cursor location can be used to determine the position of
- * candidate word window in the immodule.
+ * @brief Notifies the Input Method Context that a change in the cursor
+ * location has been made. The location is relative to the canvas.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param x cursor x position.
- * @param y cursor y position.
- * @param w cursor width.
- * @param h cursor height.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @remarks The cursor location can be used to determine the position of
+ * the candidate word window in the immodule.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] x The cursor's x position
+ * @param[in] y The cursor's y position
+ * @param[in] w The cursor width
+ * @param[in] h The cursor height
*/
EAPI void ecore_imf_context_cursor_location_set(Ecore_IMF_Context *ctx, int x, int y, int w, int h);
/**
- * Set whether the IM context should use the preedit string
- * to display feedback. If @c use_preedit is @c EINA_FALSE (default
- * is @c EINA_TRUE), then the IM context may use some other method to display
- * feedback, such as displaying it in a child of the root window.
+ * @brief Sets whether the IM context should use the preedit string
+ * to display feedback.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param use_preedit Whether the IM context should use the preedit string.
- * @ingroup Ecore_IMF_Context_Group
+ * @remarks If @a use_preedit is @c EINA_FALSE (default
+ * is @c EINA_TRUE), then the IM context may use some other method to display
+ * feedback, such as displaying it in a child of the root window.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] use_preedit The boolean value that indicates whether the IM context should use the preedit string
*/
EAPI void ecore_imf_context_use_preedit_set(Ecore_IMF_Context *ctx, Eina_Bool use_preedit);
/**
- * Set the callback to be used on surrounding_get request.
+ * @brief Sets the callback to be used on the surrounding_get request.
*
- * This callback will be called when the Input Method Context
- * module requests the surrounding context.
- * Input methods typically want context in order to constrain input text based on existing text;
- * this is important for languages such as Thai where only some sequences of characters are allowed.
+ * @remarks This callback is called when the Input Method Context
+ * module requests the surrounding context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param func The callback to be called.
- * @param data The data pointer to be passed to @p func
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] func The callback to be called
+ * @param[in] data The data pointer to be passed to @a func
*/
EAPI void ecore_imf_context_retrieve_surrounding_callback_set(Ecore_IMF_Context *ctx, Eina_Bool (*func)(void *data, Ecore_IMF_Context *ctx, char **text, int *cursor_pos), const void *data);
/**
- * Set the callback to be used on selection_get request.
+ * @brief Sets the callback to be used on the selection_get request.
*
- * This callback will be called when the Input Method Context
- * module requests the selection context.
- *
- * @param ctx An #Ecore_IMF_Context.
- * @param func The callback to be called.
- * @param data The data pointer to be passed to @p func
- * @ingroup Ecore_IMF_Context_Group
* @since 1.9.0
+ *
+ * @remarks This callback is called when the Input Method Context
+ * module requests the selection context.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] func The callback to be called
+ * @param[in] data The data pointer to be passed to @a func
*/
EAPI void ecore_imf_context_retrieve_selection_callback_set(Ecore_IMF_Context *ctx, Eina_Bool (*func)(void *data, Ecore_IMF_Context *ctx, char **text), const void *data);
/**
- * Set the input mode used by the Ecore Input Context.
+ * @brief Sets the callback to be used on the surrounding_get request.
*
- * The input mode can be one of the input modes defined in
- * Ecore_IMF_Input_Mode. The default input mode is
- * ECORE_IMF_INPUT_MODE_FULL.
+ * @remarks The input mode can be one of the input modes defined in
+ * Ecore_IMF_Input_Mode. The default input mode is
+ * @c ECORE_IMF_INPUT_MODE_FULL.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param input_mode The input mode to be used by @p ctx.
- * @ingroup Ecore_IMF_Context_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] input_mode The input mode to be used by @a ctx
*/
EAPI void ecore_imf_context_input_mode_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode);
/**
- * Get the input mode being used by the Ecore Input Context.
+ * @brief Gets the input mode being used by the Ecore Input Context.
*
- * See @ref ecore_imf_context_input_mode_set for more details.
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The input mode being used by @a ctx
*
- * @param ctx An #Ecore_IMF_Context.
- * @return The input mode being used by @p ctx.
- * @ingroup Ecore_IMF_Context_Group
+ * @see ecore_imf_context_input_mode_set
*/
EAPI Ecore_IMF_Input_Mode ecore_imf_context_input_mode_get(Ecore_IMF_Context *ctx);
/**
- * Allow an Ecore Input Context to internally handle an event.
- * If this function returns @c EINA_TRUE, then no further processing
- * should be done for this event.
+ * @brief Allows an Ecore Input Context to internally handle an event.
*
- * Input methods must be able to accept all types of events (simply
- * returning @c EINA_FALSE if the event was not handled), but there is no
- * obligation of any events to be submitted to this function.
+ * @remarks If this function returns @c EINA_TRUE, then no further processing
+ * should be done for this event.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param type The type of event defined by #Ecore_IMF_Event_Type.
- * @param event The event itself.
- * @return @c EINA_TRUE if the event was handled; otherwise @c EINA_FALSE.
- * @ingroup Ecore_IMF_Context_Group
+ * @remarks Input methods must be able to accept all types of events (simply
+ * returning @c EINA_FALSE if the event is not handled), but there is no
+ * obligation of any events to be submitted to this function.
*
- * Example
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] type The type of event defined by #Ecore_IMF_Event_Type
+ * @param[in] event The event itself
+ * @return @c EINA_TRUE if the event is handled,
+ * otherwise @c EINA_FALSE
+ *
+ * Example:
* @code
* static void
* _key_down_cb(void *data, Evas *e, Evas_Object *obj, void *event_info)
@@ -1176,186 +1038,177 @@ EAPI Ecore_IMF_Input_Mode ecore_imf_context_input_mode_get(Ecore_IMF_Co
*/
EAPI Eina_Bool ecore_imf_context_filter_event(Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event);
-/* plugin specific functions */
-
-/**
- * @defgroup Ecore_IMF_Context_Module_Group Ecore Input Method Context Module Functions
- * @ingroup Ecore_IMF_Lib_Group
- *
- * Functions that should be used by Ecore Input Method Context modules.
- */
+/* Plugin specific functions */
/**
- * Creates a new Input Method Context with klass specified by @p ctxc.
+ * @brief Creates a new Input Method Context with the class specified by @a ctxc.
*
- * This method should be used by modules implementing the Input
- * Method Context interface.
+ * @remarks This method should be used by modules implementing the Input
+ * Method Context interface.
*
- * @param ctxc An #Ecore_IMF_Context_Class.
- * @return A new #Ecore_IMF_Context; on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctxc An #Ecore_IMF_Context_Class
+ * @return A new #Ecore_IMF_Context,
+ * otherwise @c NULL on failure
*/
EAPI Ecore_IMF_Context *ecore_imf_context_new(const Ecore_IMF_Context_Class *ctxc);
/**
- * Set the Input Method Context specific data.
+ * @brief Sets the Input Method Context specific data.
*
- * Note that this method should be used by modules to set
- * the Input Method Context specific data and it's not meant to
- * be used by applications to store application specific data.
+ * @remarks Note that this method should be used by modules to set
+ * the Input Method Context specific data and it's not meant to
+ * be used by applications to store application specific data.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param data The Input Method Context specific data.
- * @return A new #Ecore_IMF_Context; on failure it returns NULL.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] data The Input Method Context specific data
+ * @return A new #Ecore_IMF_Context,
+ * otherwise @c NULL on failure
*/
EAPI void ecore_imf_context_data_set(Ecore_IMF_Context *ctx, void *data);
/**
- * Get the Input Method Context specific data.
+ * @brief Gets the Input Method Context specific data.
*
- * See @ref ecore_imf_context_data_set for more details.
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The Input Method Context specific data
*
- * @param ctx An #Ecore_IMF_Context.
- * @return The Input Method Context specific data.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @see ecore_imf_context_data_set()
*/
EAPI void *ecore_imf_context_data_get(Ecore_IMF_Context *ctx);
/**
- * Retrieve context around insertion point.
- * Input methods typically want context in order to constrain input text based on existing text;
- * this is important for languages such as Thai where only some sequences of characters are allowed.
- * In addition, the text around the insertion point can be used for supporting autocapital feature.
+ * @brief Gets the context around the insertion point.
+ *
+ * @remarks Input methods typically want context in order to constrain the input text based on existing text.
+ * This is important for languages such as Thai where only some sequences of characters are allowed.
+ * In addition, the text around the insertion point can be used for supporting the auto-capital feature.
*
- * This function is implemented by calling the
- * Ecore_IMF_Context::retrieve_surrounding_func (
- * set using #ecore_imf_context_retrieve_surrounding_callback_set).
+ * @remarks This function is implemented by calling the
+ * Ecore_IMF_Context::retrieve_surrounding_func
+ * (set using #ecore_imf_context_retrieve_surrounding_callback_set).
*
- * There is no obligation for a widget to respond to the
- * retrieve_surrounding_func, so input methods must be prepared
- * to function without context.
+ * @remarks There is no obligation for a widget to respond to
+ * retrieve_surrounding_func, so input methods must be prepared
+ * to function without context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param text Location to store a UTF-8 encoded string of text
- * holding context around the insertion point.
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] text The location to store a UTF-8 encoded string of text
+ * holding context around the insertion point \n
* If the function returns @c EINA_TRUE, then you must free
- * the result stored in this location with free().
- * @param cursor_pos Location to store the position in characters of
- * the insertion cursor within @p text.
- * @return @c EINA_TRUE if surrounding text was provided; otherwise
- * @c EINA_FALSE.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * the result stored in this location using free().
+ * @param[out] cursor_pos The location to store the position in characters of
+ * the insertion cursor within @a text
+ * @return @c EINA_TRUE if the surrounding text is provided,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_surrounding_get(Ecore_IMF_Context *ctx, char **text, int *cursor_pos);
/**
- * Retrieve the selected text.
+ * @brief Gets the selected text.
+ *
+ * @since 1.9.0
*
- * This function is implemented by calling the
- * Ecore_IMF_Context::retrieve_selection_func (
- * set using #ecore_imf_context_retrieve_selection_callback_set).
+ * @remarks This function is implemented by calling
+ * Ecore_IMF_Context::retrieve_selection_func
+ * (set using #ecore_imf_context_retrieve_selection_callback_set).
*
- * There is no obligation for a widget to respond to the
- * retrieve_surrounding_func, so input methods must be prepared
- * to function without context.
+ * @remarks There is no obligation for a widget to respond to
+ * retrieve_surrounding_func, so input methods must be prepared
+ * to function without context.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param text Location to store a UTF-8 encoded string of the selected text.
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] text The location to store a UTF-8 encoded string of the selected text \n
* If the function returns @c EINA_TRUE, then you must free
- * the result stored in this location with free().
- * @return @c EINA_TRUE if selected text was provided; otherwise
- * @c EINA_FALSE.
- * @ingroup Ecore_IMF_Context_Module_Group
- * @since 1.9.0
+ * the result stored in this location using free().
+ * @return @c EINA_TRUE if the selected text is provided,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_selection_get(Ecore_IMF_Context *ctx, char **text);
/**
- * Adds ECORE_IMF_EVENT_PREEDIT_START to the event queue.
+ * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_START to the event queue.
*
- * ECORE_IMF_EVENT_PREEDIT_START should be added when a new preedit sequence starts.
- * It's asynchronous method to put event to the event queue.
- * ecore_imf_context_event_callback_call() can be used as synchronous method.
+ * @remarks @c ECORE_IMF_EVENT_PREEDIT_START should be added when a new preedit sequence starts.
+ * It's an asynchronous method to put an event to the event queue.
+ * ecore_imf_context_event_callback_call() can be used as a synchronous method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_preedit_start_event_add(Ecore_IMF_Context *ctx);
/**
- * Adds ECORE_IMF_EVENT_PREEDIT_END to the event queue.
+ * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_END to the event queue.
*
- * ECORE_IMF_EVENT_PREEDIT_END should be added when a new preedit sequence has been completed or canceled.
- * It's asynchronous method to put event to the event queue.
- * ecore_imf_context_event_callback_call() can be used as synchronous method.
+ * @remarks @c ECORE_IMF_EVENT_PREEDIT_END should be added when a new preedit sequence has been completed or cancelled.
+ * It's an asynchronous method to put an event to the event queue.
+ * ecore_imf_context_event_callback_call() can be used as a synchronous method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_preedit_end_event_add(Ecore_IMF_Context *ctx);
/**
- * Adds ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue.
+ * @brief Adds @c ECORE_IMF_EVENT_PREEDIT_CHANGED to the event queue.
*
- * It's asynchronous method to put event to the event queue.
- * ecore_imf_context_event_callback_call() can be used as synchronous method.
+ * @remarks It's an asynchronous method to put an event to the event queue.
+ * ecore_imf_context_event_callback_call() can be used as a synchronous method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_preedit_changed_event_add(Ecore_IMF_Context *ctx);
/**
- * Adds ECORE_IMF_EVENT_COMMIT to the event queue.
+ * @brief Adds @c ECORE_IMF_EVENT_COMMIT to the event queue.
*
- * It's asynchronous method to put event to the event queue.
- * ecore_imf_context_event_callback_call() can be used as synchronous method.
+ * @remarks It's an asynchronous method to put an event to the event queue.
+ * ecore_imf_context_event_callback_call() can be used as a synchronous method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param str The committed string.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] str The committed string
*/
EAPI void ecore_imf_context_commit_event_add(Ecore_IMF_Context *ctx, const char *str);
/**
- * Adds ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.
+ * @brief Adds @c ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.
*
- * Asks the widget that the input context is attached to to delete characters around the cursor position
- * by adding the ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.
- * Note that offset and n_chars are in characters not in bytes.
+ * @remarks This asks the widget that the input context is attached to delete characters around the cursor position
+ * by adding @c ECORE_IMF_EVENT_DELETE_SURROUNDING to the event queue.
+ * Note that @a offset and @a n_chars are in characters and not in bytes.
*
- * It's asynchronous method to put ECORE_IMF_EVENT_DELETE_SURROUNDING event to the event queue.
- * ecore_imf_context_event_callback_call() can be used as synchronous method.
+ * @remarks It's an asynchronous method to put the @c ECORE_IMF_EVENT_DELETE_SURROUNDING event to the event queue.
+ * ecore_imf_context_event_callback_call() can be used as a synchronous method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param offset The start offset of surrounding to be deleted.
- * @param n_chars The number of characters to be deleted.
- * @ingroup Ecore_IMF_Context_Module_Group
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] offset The start offset of the surrounding to be deleted
+ * @param[in] n_chars The number of characters to be deleted
*/
EAPI void ecore_imf_context_delete_surrounding_event_add(Ecore_IMF_Context *ctx, int offset, int n_chars);
/**
- * Add (register) a callback function to a given context event.
- *
- * This function adds a function callback to the context @p ctx when the
- * event of type @p type occurs on it. The function pointer is @p
- * func.
+ * @}
+ */
+
+/**
+ * @brief Adds (registers) a callback function to a given context event.
*
- * The event type @p type to trigger the function may be one of
- * #ECORE_IMF_CALLBACK_PREEDIT_START, #ECORE_IMF_CALLBACK_PREEDIT_END,
- * #ECORE_IMF_CALLBACK_PREEDIT_CHANGED, #ECORE_IMF_CALLBACK_COMMIT and
- * #ECORE_IMF_CALLBACK_DELETE_SURROUNDING.
+ * @details This function adds a function callback to the context @a ctx when the
+ * event of type @a type occurs on it. The function pointer is
+ * @a func.
*
- * @param ctx Ecore_IMF_Context to attach a callback to.
- * @param type The type of event that will trigger the callback
- * @param func The (callback) function to be called when the event is
- * triggered
- * @param data The data pointer to be passed to @p func
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
*
- * Example
+ * @remarks The event type @a type to trigger the function may be one of
+ * #ECORE_IMF_CALLBACK_PREEDIT_START, #ECORE_IMF_CALLBACK_PREEDIT_END,
+ * #ECORE_IMF_CALLBACK_PREEDIT_CHANGED, #ECORE_IMF_CALLBACK_COMMIT, or
+ * #ECORE_IMF_CALLBACK_DELETE_SURROUNDING.
+ *
+ * @param[in] ctx The Ecore_IMF_Context to attach a callback to
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] func The (callback) function to be called when the event is
+ * triggered
+ * @param[in] data The data pointer to be passed to @a func
+ *
+ * Example:
* @code
* static void
* _imf_event_commit_cb(void *data, Ecore_IMF_Context *ctx, void *event_info)
@@ -1370,442 +1223,453 @@ EAPI void ecore_imf_context_delete_surrounding_event_ad
EAPI void ecore_imf_context_event_callback_add(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, Ecore_IMF_Event_Cb func, const void *data);
/**
- * Delete (unregister) a callback function registered to a given
- * context event.
- *
- * This function removes a function callback from the context @p ctx when the
- * event of type @p type occurs on it. The function pointer is @p
- * func.
+ * @brief Deletes (unregisters) a callback function registered to a given
+ * context event.
*
- * @see ecore_imf_context_event_callback_add() for more details
+ * @details This function removes a function callback from the context @a ctx when the
+ * event of type @a type occurs on it. The function pointer is
+ * @a func.
*
- * @param ctx Ecore_IMF_Context to remove a callback from.
- * @param type The type of event that was triggering the callback
- * @param func The (callback) function that was to be called when the event was triggered
- * @return the data pointer
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx The Ecore_IMF_Context to remove a callback from
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] func The (callback) function to be called when the event is triggered
+ * @return The data pointer
+ *
+ * @see ecore_imf_context_event_callback_add()
*/
EAPI void *ecore_imf_context_event_callback_del(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, Ecore_IMF_Event_Cb func);
/**
- * Call a given callback on the context @p ctx.
+ * @brief Calls a given callback on the context @a ctx.
+ *
+ * @since 1.2.0
*
- * ecore_imf_context_preedit_start_event_add(), ecore_imf_context_preedit_end_event_add(),
- * ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_commit_event_add() and
- * ecore_imf_context_delete_surrounding_event_add() APIs are asynchronous
- * because those API adds each event to the event queue.
+ * @remarks The ecore_imf_context_preedit_start_event_add(), ecore_imf_context_preedit_end_event_add(),
+ * ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_commit_event_add(), and
+ * ecore_imf_context_delete_surrounding_event_add() APIs are asynchronous
+ * because those APIs add each event to the event queue.
*
- * This API provides the way to call each callback function immediately.
+ * @remarks This API provides a way to call each callback function immediately.
*
- * @param ctx Ecore_IMF_Context.
- * @param type The type of event that will trigger the callback
- * @param event_info The pointer to event specific struct or information to
- * pass to the callback functions registered on this event
- * @ingroup Ecore_IMF_Context_Module_Group
- * @since 1.2.0
+ * @param[in] ctx An Ecore_IMF_Context
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] event_info A pointer to an event specific struct or information to
+ * pass to the callback functions registered on this event
*/
EAPI void ecore_imf_context_event_callback_call(Ecore_IMF_Context *ctx, Ecore_IMF_Callback_Type type, void *event_info);
/**
- * Set whether the IM context should allow to use the text prediction.
- * If @p prediction is @c EINA_FALSE (default is @c EINA_TRUE), then the IM
- * context will not display the text prediction window.
+ * @brief Sets whether the IM context should allow text prediction.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param prediction Whether the IM context should allow to use the text prediction.
- * @note Default value is EINA_TRUE.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @remarks If @a prediction is @c EINA_FALSE (default is @c EINA_TRUE), then the IM
+ * context does not display the text prediction window.
+ * Default value is @c EINA_TRUE.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] prediction The boolean value that indicates whether the IM context should allow text prediction
*/
EAPI void ecore_imf_context_prediction_allow_set(Ecore_IMF_Context *ctx, Eina_Bool prediction);
/**
- * Get whether the IM context should allow to use the text prediction.
+ * @brief Gets whether the IM context should allow text prediction.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return @c EINA_TRUE if it allows to use the text prediction, otherwise
- * @c EINA_FALSE.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return @c EINA_TRUE if it allows text prediction,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_prediction_allow_get(Ecore_IMF_Context *ctx);
/**
- * Set the autocapitalization type on the immodule.
+ * @brief Sets the auto-capitalization type on the immodule.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param autocapital_type the autocapitalization type.
- * @note Default type is ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @remarks Default type is @c ECORE_IMF_AUTOCAPITAL_TYPE_SENTENCE.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] autocapital_type The auto-capitalization type
*/
EAPI void ecore_imf_context_autocapital_type_set(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type);
/**
- * Get the autocapitalization type.
+ * @brief Gets the auto-capitalization type.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return The autocapital type being used by @p ctx.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The autocapital type being used by @a ctx
*/
EAPI Ecore_IMF_Autocapital_Type ecore_imf_context_autocapital_type_get(Ecore_IMF_Context *ctx);
/**
* @brief Sets the input hint which allows input methods to fine-tune their behavior.
*
- * @param ctx An #Ecore_IMF_Context
- * @param hints input hint
- * @note The default input hint is @c ECORE_IMF_INPUT_HINT_AUTO_COMPLETE.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.12
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] hints input hint
+ * @note The default input hint is ECORE_IMF_INPUT_HINT_AUTO_COMPLETE.
*/
EAPI void ecore_imf_context_input_hint_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints hints);
/**
* @brief Gets the value of input hint.
*
- * @param ctx An #Ecore_IMF_Context
- * @return The value of input hint
- * @ingroup Ecore_IMF_Context_Group
* @since 1.12
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The value of input hint
*/
EAPI Ecore_IMF_Input_Hints ecore_imf_context_input_hint_get(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to show the control panel of using Input Method.
+ * @brief Asks the Input Method Context to show the control panel for using the Input Method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_control_panel_show(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to hide the control panel of using Input Method.
+ * @brief Asks the Input Method Context to hide the control panel for using the Input Method.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_control_panel_hide(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to show the input panel (virtual keyboard).
+ * @brief Asks the Input Method Context to show the input panel (virtual keyboard).
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_input_panel_show(Ecore_IMF_Context *ctx);
/**
- * Ask the Input Method Context to hide the input panel.
+ * @brief Asks the Input Method Context to hide the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
*/
EAPI void ecore_imf_context_input_panel_hide(Ecore_IMF_Context *ctx);
/**
- * Set the layout of the input panel.
+ * @brief Sets the layout of the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param layout see #Ecore_IMF_Input_Panel_Layout
- * @note Default layout type is ECORE_IMF_INPUT_PANEL_LAYOUT_NORMAL.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @remarks Default layout type is @c ECORE_IMF_INPUT_PANEL_LAYOUT_NORMAL.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] layout The #Ecore_IMF_Input_Panel_Layout
*/
EAPI void ecore_imf_context_input_panel_layout_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout);
/**
- * Get the layout of the current active input panel.
+ * @brief Gets the layout of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return layout see #Ecore_IMF_Input_Panel_Layout
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return layout The #Ecore_IMF_Input_Panel_Layout
*/
EAPI Ecore_IMF_Input_Panel_Layout ecore_imf_context_input_panel_layout_get(Ecore_IMF_Context *ctx);
/**
- * Set the layout variation of the current active input panel.
+ * @brief Sets the layout variation of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param variation the layout variation
- * @note Default layout variation type is NORMAL.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @remarks Default layout variation type is @c NORMAL.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] variation The layout variation
*/
EAPI void ecore_imf_context_input_panel_layout_variation_set(Ecore_IMF_Context *ctx, int variation);
/**
- * Get the layout variation of the current active input panel.
+ * @brief Gets the layout variation of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return the layout variation
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The layout variation
*/
EAPI int ecore_imf_context_input_panel_layout_variation_get(Ecore_IMF_Context *ctx);
/**
- * Set the language of the input panel.
- * This API can be used when you want to show the English keyboard.
+ * @brief Sets the language of the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param lang the language to be set to the input panel.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @remarks This API can be used when you want to show the English keyboard.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] lang The language to be set for the input panel
*/
EAPI void ecore_imf_context_input_panel_language_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang);
/**
- * Get the language of the input panel.
- *
- * See @ref ecore_imf_context_input_panel_language_set for more details.
+ * @brief Gets the language of the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return Ecore_IMF_Input_Panel_Lang
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The Ecore_IMF_Input_Panel_Lang
+ *
+ * @see ecore_imf_context_input_panel_language_set()
*/
EAPI Ecore_IMF_Input_Panel_Lang ecore_imf_context_input_panel_language_get(Ecore_IMF_Context *ctx);
/**
- * Set whether the Input Method Context should request to show the input panel automatically
- * when the widget has focus.
+ * @brief Sets whether the Input Method Context should request to show the input panel automatically
+ * when the widget has focus.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param enabled If true, the input panel will be shown when the widget is clicked or has focus.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] enabled If @c true the input panel is shown when the widget is clicked or has focus,
+ * otherwise @c false
*/
EAPI void ecore_imf_context_input_panel_enabled_set(Ecore_IMF_Context *ctx, Eina_Bool enabled);
/**
- * Get whether the Input Method Context requests to show the input panel automatically.
+ * @brief Gets whether the Input Method Context requests to show the input panel automatically.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return Return the attribute to show the input panel automatically
- * @ingroup Ecore_IMF_Context_Group
* @since 1.1.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The attribute to show the input panel automatically
*/
EAPI Eina_Bool ecore_imf_context_input_panel_enabled_get(Ecore_IMF_Context *ctx);
/**
- * Set the input panel-specific data to deliver to the input panel.
- * This API is used by applications to deliver specific data to the input panel.
- * The data format MUST be negotiated by both application and the input panel.
- * The size and format of data are defined by the input panel.
- *
- * @param ctx An #Ecore_IMF_Context.
- * @param data The specific data to be set to the input panel.
- * @param len the length of data, in bytes, to send to the input panel
- * @ingroup Ecore_IMF_Context_Group
+ * @brief Sets the input panel-specific data to deliver to the input panel.
+ *
* @since 1.2.0
+ *
+ * @remarks This API is used by applications to deliver specific data to the input panel.
+ * The data format MUST be negotiated by both the application and the input panel.
+ * The size and format of data is defined by the input panel.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] data The specific data to be set to the input panel
+ * @param[in] len The length of data, in bytes, to send to the input panel
*/
EAPI void ecore_imf_context_input_panel_imdata_set(Ecore_IMF_Context *ctx, const void *data, int len);
/**
- * Get the specific data of the current active input panel.
+ * @brief Gets the specific data of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param data The specific data to be got from the input panel
- * @param len The length of data
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] data The specific data to be obtained from the input panel
+ * @param[out] len The length of the data
*/
EAPI void ecore_imf_context_input_panel_imdata_get(Ecore_IMF_Context *ctx, void *data, int *len);
/**
- * Set the "return" key type. This type is used to set string or icon on the "return" key of the input panel.
- *
- * An input panel displays the string or icon associated with this type
+ * @brief Sets the "return" key type. This type is used to set a string or icon on the "return" key of the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param return_key_type The type of "return" key on the input panel
- * @note Default type is ECORE_IMF_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @remarks An input panel displays the string or icon associated to this type.
+ *
+ * @remarks Default type is @c ECORE_IMF_INPUT_PANEL_RETURN_KEY_TYPE_DEFAULT.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] return_key_type The type of "return" key on the input panel
*/
EAPI void ecore_imf_context_input_panel_return_key_type_set(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type);
/**
- * Get the "return" key type.
+ * @brief Gets the "return" key type.
*
- * @see ecore_imf_context_input_panel_return_key_type_set() for more details
+ * @since 1.2.0
*
- * @param ctx An #Ecore_IMF_Context.
+ * @param[in] ctx An #Ecore_IMF_Context
* @return The type of "return" key on the input panel
- * @ingroup Ecore_IMF_Context_Group
- * @since 1.2.0
+ *
+ * @see ecore_imf_context_input_panel_return_key_type_set()
*/
EAPI Ecore_IMF_Input_Panel_Return_Key_Type ecore_imf_context_input_panel_return_key_type_get(Ecore_IMF_Context *ctx);
/**
- * Set the return key on the input panel to be disabled.
+ * @brief Sets the return key on the input panel to be disabled.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param disabled The state
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] disabled The return key state
*/
EAPI void ecore_imf_context_input_panel_return_key_disabled_set(Ecore_IMF_Context *ctx, Eina_Bool disabled);
/**
- * Get whether the return key on the input panel should be disabled or not.
+ * @brief Gets whether the return key on the input panel should be disabled.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return @c EINA_TRUE if it should be disabled.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return @c EINA_TRUE if it should be disabled,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_input_panel_return_key_disabled_get(Ecore_IMF_Context *ctx);
/**
- * Set the caps lock mode on the input panel.
+ * @brief Sets the caps lock mode on the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param mode Turn on caps lock on the input panel if @c EINA_TRUE.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] mode If @c EINA_TRUE caps lock on the input panel is turned on,
+ * otherwise @c EINA_FALSE
*/
EAPI void ecore_imf_context_input_panel_caps_lock_mode_set(Ecore_IMF_Context *ctx, Eina_Bool mode);
/**
- * Get the caps lock mode on the input panel.
+ * @brief Gets the caps lock mode on the input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return @c EINA_TRUE if the caps lock is turned on.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.2.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return @c EINA_TRUE if caps lock is turned on,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_input_panel_caps_lock_mode_get(Ecore_IMF_Context *ctx);
/**
- * Get the position of the current active input panel.
+ * @brief Gets the position of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param x top-left x co-ordinate of the input panel
- * @param y top-left y co-ordinate of the input panel
- * @param w width of the input panel
- * @param h height of the input panel
- * @ingroup Ecore_IMF_Context_Group
- * @since 1.3
+ * @since 1.30
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] x The top-left x co-ordinate of the input panel
+ * @param[out] y The top-left y co-ordinate of the input panel
+ * @param[out] w The width of the input panel
+ * @param[out] h The height of the input panel
*/
EAPI void ecore_imf_context_input_panel_geometry_get(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h);
/**
- * Get state of current active input panel.
+ * @brief Gets the state of the current active input panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return The state of input panel.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.3
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return The state of the input panel
*/
EAPI Ecore_IMF_Input_Panel_State ecore_imf_context_input_panel_state_get(Ecore_IMF_Context *ctx);
/**
- * Register a callback function which will be called if there is change in input panel state,language,mode etc.
- * In order to deregister the callback function
- * Use @ref ecore_imf_context_input_panel_event_callback_del.
- *
- * @param ctx An #Ecore_IMF_Context
- * @param type event type
- * @param func the callback function
- * @param data application-input panel specific data.
- * @ingroup Ecore_IMF_Context_Group
+ * @brief Registers a callback function which is called if there is a change in the input panel state, language, mode, and so on.
+ *
* @since 1.3
+ *
+ * @remarks In order to unregister the callback function
+ * use @ref ecore_imf_context_input_panel_event_callback_del.
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] type The event type
+ * @param[in] func The callback function
+ * @param[in] data The application-input panel specific data
*/
EAPI void ecore_imf_context_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), const void *data);
/**
- * Unregister a callback function which will be called if there is change in input panel state, language, mode etc.
+ * @brief Unregisters a callback function which is called if there is a change in the input panel state, language, mode, and so on.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param type An #Ecore_IMF_Input_Panel_Event.
- * @param func the callback function
- * @ingroup Ecore_IMF_Context_Group
* @since 1.3
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] type An #Ecore_IMF_Input_Panel_Event
+ * @param[in] func The callback function
*/
EAPI void ecore_imf_context_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));
/**
- * Call a given input panel callback on the context @p ctx.
+ * @brief Calls a given input panel callback on the context @a ctx.
*
- * @param ctx Ecore_IMF_Context.
- * @param type The type of event that will trigger the callback
- * @param value the event value
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @param[in] ctx An Ecore_IMF_Context
+ * @param[in] type The type of event that triggers the callback
+ * @param[in] value The event value
*/
EAPI void ecore_imf_context_input_panel_event_callback_call(Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, int value);
/**
- * Delete all input panel callback on the context @p ctx.
+ * @brief Deletes all input panel callbacks on the context @a ctx.
*
- * Delete all input panel callback to be registered by ecore_imf_context_input_panel_event_callback_add()
+ * @details This deletes all input panel callbacks to be registered by ecore_imf_context_input_panel_event_callback_add().
*
- * @param ctx Ecore_IMF_Context.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @param[in] ctx An Ecore_IMF_Context
*/
EAPI void ecore_imf_context_input_panel_event_callback_clear(Ecore_IMF_Context *ctx);
/**
- * Get the current language locale of the input panel.
- *
- * ex) fr_FR
+ * @brief Gets the current language locale of the input panel, eg: fr_FR.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param lang Location to store the retrieved language string. The
- * string retrieved must be freed with free().
- * @ingroup Ecore_IMF_Context_Group
* @since 1.3
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] lang The location to store the retrieved language string \n
+ * The string retrieved must be freed with free().
*/
EAPI void ecore_imf_context_input_panel_language_locale_get(Ecore_IMF_Context *ctx, char **lang);
/**
- * Get the geometry information of the candidate panel.
+ * @brief Gets the geometry information of the candidate panel.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param x top-left x co-ordinate of the candidate panel
- * @param y top-left y co-ordinate of the candidate panel
- * @param w width of the candidate panel
- * @param h height of the candidate panel
- * @ingroup Ecore_IMF_Context_Group
* @since 1.3
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[out] x The top-left x co-ordinate of the candidate panel
+ * @param[out] y The top-left y co-ordinate of the candidate panel
+ * @param[out] w The width of the candidate panel
+ * @param[out] h The height of the candidate panel
*/
EAPI void ecore_imf_context_candidate_panel_geometry_get(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h);
/**
- * Set whether the Input Method Context should request to show the input panel in case of only an user's explicit Mouse Up event.
- * It doesn't request to show the input panel even though the Input Method Context has focus.
+ * @brief Sets whether the Input Method Context should request to show the input panel if only one user's explicit Mouse Up event has occurred.
+ * It doesn't request to show the input panel even though the Input Method Context has focus.
*
- * @param ctx An #Ecore_IMF_Context.
- * @param ondemand If true, the input panel will be shown in case of only Mouse up event. (Focus event will be ignored.)
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @param[in] ondemand If @c true the input panel is shown when only one user's Mouse up event occurs, (Focus event is ignored)
+ * otherwise @c false
*/
EAPI void ecore_imf_context_input_panel_show_on_demand_set(Ecore_IMF_Context *ctx, Eina_Bool ondemand);
/**
- * Get whether the Input Method Context should request to show the input panel in case of only an user's explicit Mouse Up event.
+ * @brief Gets whether the Input Method Context should request to show the input panel if only one user's explicit Mouse Up event has occurred.
*
- * @param ctx An #Ecore_IMF_Context.
- * @return @c EINA_TRUE if the input panel will be shown in case of only Mouse up event.
- * @ingroup Ecore_IMF_Context_Group
* @since 1.8.0
+ *
+ * @param[in] ctx An #Ecore_IMF_Context
+ * @return @c EINA_TRUE if the input panel is shown when only one user's Mouse up event occurs,
+ * otherwise @c EINA_FALSE
*/
EAPI Eina_Bool ecore_imf_context_input_panel_show_on_demand_get(Ecore_IMF_Context *ctx);
/**
* @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
@@ -1816,7 +1680,6 @@ 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
@@ -1824,7 +1687,7 @@ EAPI void ecore_imf_context_bidi_direction_set(Ecore_IM
*/
EAPI Ecore_IMF_BiDi_Direction ecore_imf_context_bidi_direction_get(Ecore_IMF_Context *ctx);
-/* The following entry points must be exported by each input method module
+/* The following entry points must be exported by each input method module.
*/
/*
@@ -1833,6 +1696,14 @@ EAPI Ecore_IMF_BiDi_Direction ecore_imf_context_bidi_direction_get(Ecore_IM
* Ecore_IMF_Context *imf_module_create (void);
*/
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
#ifdef __cplusplus
}
#endif
diff --git a/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h b/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h
index 84794c2db2..55de59b644 100644
--- a/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h
+++ b/src/lib/ecore_imf_evas/Ecore_IMF_Evas.h
@@ -31,80 +31,29 @@
#endif /* ! _WIN32 */
/**
+ * @internal
* @defgroup Ecore_IMF_Evas_Group Ecore Input Method Context Evas Helper Functions
- * @ingroup Ecore_IMF_Lib_Group
+ * @ingroup Ecore_IMF_Group
*
* Helper functions to make it easy to use Evas with Ecore_IMF.
* Converts each event from Evas to the corresponding event of Ecore_IMF.
*
- * An example of usage of these functions can be found at:
- * @li @ref ecore_imf_example_c
+ * @{
*/
#ifdef __cplusplus
extern "C" {
#endif
-/**
- * Converts a "mouse_in" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_in_wrap(Evas_Event_Mouse_In *evas_event, Ecore_IMF_Event_Mouse_In *imf_event);
-
-/**
- * Converts a "mouse_out" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_out_wrap(Evas_Event_Mouse_Out *evas_event, Ecore_IMF_Event_Mouse_Out *imf_event);
-
-/**
- * Converts a "mouse_move" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_move_wrap(Evas_Event_Mouse_Move *evas_event, Ecore_IMF_Event_Mouse_Move *imf_event);
-
-/**
- * Converts a "mouse_down" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_down_wrap(Evas_Event_Mouse_Down *evas_event, Ecore_IMF_Event_Mouse_Down *imf_event);
-
-/**
- * Converts a "mouse_up" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_up_wrap(Evas_Event_Mouse_Up *evas_event, Ecore_IMF_Event_Mouse_Up *imf_event);
-
-/**
- * Converts a "mouse_wheel" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
- */
EAPI void ecore_imf_evas_event_mouse_wheel_wrap(Evas_Event_Mouse_Wheel *evas_event, Ecore_IMF_Event_Mouse_Wheel *imf_event);
/**
- * Converts a "key_down" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
+ * @brief Converts a "key_down" event from Evas to the corresponding event of Ecore_IMF.
*
* Example
* @code
@@ -127,15 +76,14 @@ EAPI void ecore_imf_evas_event_mouse_wheel_wrap(Evas_Event_Mouse_Wheel *evas_eve
*
* evas_object_event_callback_add(obj, EVAS_CALLBACK_KEY_DOWN, _key_down_cb, data);
* @endcode
+ *
+ * @param[in] evas_event The received Evas event.
+ * @param[out] imf_event The location to store the converted Ecore_IMF event.
*/
EAPI void ecore_imf_evas_event_key_down_wrap(Evas_Event_Key_Down *evas_event, Ecore_IMF_Event_Key_Down *imf_event);
/**
- * Converts a "key_up" event from Evas to the corresponding event of Ecore_IMF.
- *
- * @param evas_event The received Evas event.
- * @param imf_event The location to store the converted Ecore_IMF event.
- * @ingroup Ecore_IMF_Evas_Group
+ * @brief Converts a "key_up" event from Evas to the corresponding event of Ecore_IMF.
*
* Example
* @code
@@ -158,6 +106,9 @@ EAPI void ecore_imf_evas_event_key_down_wrap(Evas_Event_Key_Down *evas_event, Ec
*
* evas_object_event_callback_add(obj, EVAS_CALLBACK_KEY_UP, _key_up_cb, data);
* @endcode
+ *
+ * @param[in] evas_event The received Evas event.
+ * @param[out] imf_event The location to store the converted Ecore_IMF event.
*/
EAPI void ecore_imf_evas_event_key_up_wrap(Evas_Event_Key_Up *evas_event, Ecore_IMF_Event_Key_Up *imf_event);
@@ -165,4 +116,8 @@ EAPI void ecore_imf_evas_event_key_up_wrap(Evas_Event_Key_Up *evas_event, Ecore_
}
#endif
+/**
+ * @}
+ */
+
#endif
diff --git a/src/lib/ecore_input/Ecore_Input.h b/src/lib/ecore_input/Ecore_Input.h
index e6e1259c08..d9b3181369 100644
--- a/src/lib/ecore_input/Ecore_Input.h
+++ b/src/lib/ecore_input/Ecore_Input.h
@@ -39,20 +39,14 @@
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;
- EAPI extern int ECORE_EVENT_MOUSE_BUTTON_UP;
- EAPI extern int ECORE_EVENT_MOUSE_MOVE;
- EAPI extern int ECORE_EVENT_MOUSE_WHEEL;
- EAPI extern int ECORE_EVENT_MOUSE_IN;
- EAPI extern int ECORE_EVENT_MOUSE_OUT;
+EAPI extern int ECORE_EVENT_KEY_DOWN;
+EAPI extern int ECORE_EVENT_KEY_UP;
+EAPI extern int ECORE_EVENT_MOUSE_BUTTON_DOWN;
+EAPI extern int ECORE_EVENT_MOUSE_BUTTON_UP;
+EAPI extern int ECORE_EVENT_MOUSE_MOVE;
+EAPI extern int ECORE_EVENT_MOUSE_WHEEL;
+EAPI extern int ECORE_EVENT_MOUSE_IN;
+EAPI extern int ECORE_EVENT_MOUSE_OUT;
#define ECORE_EVENT_MODIFIER_SHIFT 0x0001
#define ECORE_EVENT_MODIFIER_CTRL 0x0002
@@ -67,257 +61,176 @@ extern "C" {
#define ECORE_EVENT_LOCK_SHIFT 0x0300
#define ECORE_EVENT_MODIFIER_ALTGR 0x0400 /**< @since 1.7 */
-#ifndef _ECORE_WINDOW_PREDEF
- typedef uintptr_t Ecore_Window;
-#define _ECORE_WINDOW_PREDEF 1
-#endif
-
- typedef struct _Ecore_Event_Key Ecore_Event_Key;
- typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button;
- typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel;
- 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,
- ECORE_SHIFT,
- ECORE_CTRL,
- ECORE_ALT,
- ECORE_WIN,
- ECORE_SCROLL,
- ECORE_CAPS,
- ECORE_MODE, /**< @since 1.7 */
- 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,
- ECORE_COMPOSE_MIDDLE,
- ECORE_COMPOSE_DONE
- } Ecore_Compose_State;
-
- /**
- * @struct _Ecore_Event_Key
- * Contains information about an Ecore keyboard event.
- */
- struct _Ecore_Event_Key
- {
- const char *keyname; /**< The key name */
- const char *key; /**< The key symbol */
- const char *string;
- 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; /**< Time when the event occurred */
- unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/
-
- 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; /**< 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; /**< x coordinate relative to window where event happened */
- int y; /**< y coordinate relative to window where event happened */
- struct {
- int x;
- int y;
- } root; /**< Coordinates relative to root window */
-
+typedef uintptr_t Ecore_Window;
+typedef struct _Ecore_Event_Key Ecore_Event_Key;
+typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button;
+typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel;
+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 enum _Ecore_Event_Modifier
+ {
+ ECORE_NONE,
+ ECORE_SHIFT,
+ ECORE_CTRL,
+ ECORE_ALT,
+ ECORE_WIN,
+ ECORE_SCROLL,
+ ECORE_CAPS,
+ ECORE_MODE, /**< @since 1.7 */
+ ECORE_LAST
+ } Ecore_Event_Modifier;
+
+typedef enum _Ecore_Event_Press
+ {
+ ECORE_DOWN,
+ ECORE_UP
+ } Ecore_Event_Press;
+
+typedef enum _Ecore_Event_IO
+ {
+ ECORE_IN,
+ ECORE_OUT
+ } Ecore_Event_IO;
+
+typedef enum _Ecore_Compose_State
+ {
+ ECORE_COMPOSE_NONE,
+ ECORE_COMPOSE_MIDDLE,
+ ECORE_COMPOSE_DONE
+ } Ecore_Compose_State;
+
+struct _Ecore_Event_Key
+ {
+ const char *keyname;
+ const char *key;
+ const char *string;
+ const char *compose;
+ Ecore_Window window;
+ Ecore_Window root_window;
+ Ecore_Window event_window;
+
+ unsigned int timestamp;
+ unsigned int modifiers;
+
+ int same_screen;
+ };
+
+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;
+
+ int x;
+ int y;
+ struct {
+ int x;
+ int y;
+ } root;
+
+ struct {
+ int device; /* @c 0 if normal mouse, @c 1+ for other mouse-devices (eg multi-touch - other fingers) */
+ double radius, radius_x, radius_y; /* radius of press point - radius_x and radius_y if it is 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 the 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 {
- 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; /**< 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; /**< 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,..)*/
-
- 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; /**< x coordinate relative to window where event happened */
- int y; /**< y coordinate relative to window where event happened */
+ double x, y;
+ } root;
+ } multi;
+ };
+
+struct _Ecore_Event_Mouse_Wheel
+ {
+ Ecore_Window window;
+ Ecore_Window root_window;
+ Ecore_Window event_window;
+
+ unsigned int timestamp;
+ unsigned int modifiers;
+
+ int same_screen;
+ int direction;
+ int z;
+
+ int x;
+ int y;
+ struct {
+ int x;
+ int y;
+ } root;
+ };
+
+struct _Ecore_Event_Mouse_Move
+ {
+ Ecore_Window window;
+ Ecore_Window root_window;
+ Ecore_Window event_window;
+
+ unsigned int timestamp;
+ unsigned int modifiers;
+
+ int same_screen;
+
+ int x;
+ int y;
+ struct {
+ int x;
+ int y;
+ } root;
+
+ struct {
+ int device; /* @c 0 if normal mouse, @c 1+ for other mouse-devices (eg multi-touch - other fingers) */
+ double radius, radius_x, radius_y; /* radius of press point - radius_x and radius_y if it is 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 the 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 {
- int x;
- int y;
- } 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; /**< 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,..)*/
-
- int same_screen; /**< Same screen flag */
-
- 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; /**< 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 */
- 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; /**< The main 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,..)*/
-
- 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);
-
- /**
- * 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);
+ double x, y;
+ } root;
+ } multi;
+ };
+
+struct _Ecore_Event_Mouse_IO
+ {
+ Ecore_Window window;
+ Ecore_Window event_window;
+
+ unsigned int timestamp;
+ unsigned int modifiers;
+
+ int x;
+ int y;
+ };
+
+struct _Ecore_Event_Modifiers
+ {
+ unsigned int size;
+ unsigned int array[ECORE_LAST];
+ };
+
+EAPI int ecore_event_init(void);
+EAPI int ecore_event_shutdown(void);
+EAPI unsigned int ecore_event_modifier_mask(Ecore_Event_Modifier modifier);
+EAPI Ecore_Event_Modifier ecore_event_update_modifier(const char *key, Ecore_Event_Modifiers *modifiers, int inc);
+
+/**
+ * @internal
+ * @since 1.7
+ */
+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 a3e38710b4..da5380e67e 100644
--- a/src/lib/ecore_ipc/Ecore_Ipc.h
+++ b/src/lib/ecore_ipc/Ecore_Ipc.h
@@ -30,11 +30,9 @@
#endif
/**
- * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions.
- * @ingroup Ecore
- *
- *
- * @{
+ * @internal
+ * @file Ecore_Ipc.h
+ * @brief Ecore inter-process communication functions.
*/
#ifdef __cplusplus
@@ -44,17 +42,17 @@ extern "C" {
typedef struct _Ecore_Ipc_Server Ecore_Ipc_Server; /**< An IPC connection handle */
typedef struct _Ecore_Ipc_Client Ecore_Ipc_Client; /**< An IPC connection handle */
-EAPI unsigned short _ecore_ipc_swap_16(unsigned short v) EINA_DEPRECATED;
-EAPI unsigned int _ecore_ipc_swap_32(unsigned int v) EINA_DEPRECATED;
-EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED;
+EAPI unsigned short _ecore_ipc_swap_16(unsigned short v);
+EAPI unsigned int _ecore_ipc_swap_32(unsigned int v);
+EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v);
#ifdef WORDS_BIGENDIAN
-#define ECORE_IPC_SWAP2NET64(x) eina_swap64(x)
-#define ECORE_IPC_SWAP2CPU64(x) eina_swap64(x)
-#define ECORE_IPC_SWAP2NET32(x) eina_swap32(x)
-#define ECORE_IPC_SWAP2CPU32(x) eina_swap32(x)
-#define ECORE_IPC_SWAP2NET16(x) eina_swap16(x)
-#define ECORE_IPC_SWAP2CPU16(x) eina_swap16(x)
+#define ECORE_IPC_SWAP2NET64(x) _ecore_ipc_swap_64(x)
+#define ECORE_IPC_SWAP2CPU64(x) _ecore_ipc_swap_64(x)
+#define ECORE_IPC_SWAP2NET32(x) _ecore_ipc_swap_32(x)
+#define ECORE_IPC_SWAP2CPU32(x) _ecore_ipc_swap_32(x)
+#define ECORE_IPC_SWAP2NET16(x) _ecore_ipc_swap_16(x)
+#define ECORE_IPC_SWAP2CPU16(x) _ecore_ipc_swap_16(x)
#define ECORE_IPC_SWAP2NET8(x) (x)
#define ECORE_IPC_SWAP2CPU8(x) (x)
#else
@@ -166,7 +164,7 @@ EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED
ptr = d;
/* footer for the hell of it */
#define ECORE_IPC_DEC_STRUCT_FOOT() return 1
-/* header for encoder - gives native struct type and size of flattened packet */
+/* header for encoder - gives native strct type and size of flattened packet */
#define ECORE_IPC_ENC_STRUCT_HEAD(typ, sz) \
typ *p; \
unsigned char *d, *ptr; \
@@ -220,11 +218,6 @@ 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,
@@ -241,81 +234,50 @@ 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; /**< An IPC connection handle */
+ Ecore_Ipc_Client *client;
};
-/**
- * @struct _Ecore_Ipc_Event_Client_Del
- *
- * An IPC structure for client_del event.
- */
struct _Ecore_Ipc_Event_Client_Del
{
- Ecore_Ipc_Client *client; /**< An IPC connection handle */
+ Ecore_Ipc_Client *client;
};
-/**
- * @struct _Ecore_Ipc_Event_Server_Add
- *
- * An IPC structure for server_add event.
- */
struct _Ecore_Ipc_Event_Server_Add
{
- Ecore_Ipc_Server *server; /**< An IPC connection handle */
+ Ecore_Ipc_Server *server;
};
-/**
- * @struct _Ecore_Ipc_Event_Server_Del
- *
- * An IPC structure for server_del event.
- */
struct _Ecore_Ipc_Event_Server_Del
{
- Ecore_Ipc_Server *server; /**< An IPC connection handle */
-
+ Ecore_Ipc_Server *server;
};
-
-/**
- * @struct _Ecore_Ipc_Event_Client_Data
- *
- * An IPC structure for client_data event.
- */
+
struct _Ecore_Ipc_Event_Client_Data
{
- Ecore_Ipc_Client *client; /**< An IPC connection handle */
- /* FIXME: this needs to become an ipc message */
- 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) */
+ Ecore_Ipc_Client *client;
+ /* FIXME: This needs to become an IPC message */
+ int major;
+ int minor;
+ int ref;
+ int ref_to;
+ int response;
+ void *data;
+ int size;
};
-
-/**
- * @struct _Ecore_Ipc_Event_Server_Data
- *
- * An IPC structure for server_data event.
- */
+
struct _Ecore_Ipc_Event_Server_Data
{
- Ecore_Ipc_Server *server; /**< An IPC connection handle */
- /* FIXME: this needs to become an ipc message */
- 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) */
+ Ecore_Ipc_Server *server;
+ /* FIXME: This needs to become an IPC message */
+ int major;
+ int minor;
+ int ref;
+ int ref_to;
+ int response;
+ void *data;
+ int size;
};
EAPI extern int ECORE_IPC_EVENT_CLIENT_ADD;
@@ -328,16 +290,16 @@ EAPI extern int ECORE_IPC_EVENT_SERVER_DATA;
EAPI int ecore_ipc_init(void);
EAPI int ecore_ipc_shutdown(void);
-/* FIXME: need to add protocol type parameter */
+/* FIXME: Need to add protocol type parameter */
EAPI Ecore_Ipc_Server *ecore_ipc_server_add(Ecore_Ipc_Type type, const char *name, int port, const void *data);
-/* FIXME: need to add protocol type parameter */
+/* FIXME: Need to add protocol type parameter */
EAPI Ecore_Ipc_Server *ecore_ipc_server_connect(Ecore_Ipc_Type type, char *name, int port, const void *data);
EAPI void *ecore_ipc_server_del(Ecore_Ipc_Server *svr);
EAPI void *ecore_ipc_server_data_get(Ecore_Ipc_Server *svr);
EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr);
EAPI Eina_List *ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr);
-/* FIXME: this needs to become an ipc message */
+/* FIXME: This needs to become an IPC message */
EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size);
EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients);
EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *srv, int size);
@@ -345,7 +307,7 @@ EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *srv)
EAPI const char *ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr);
EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr);
-/* FIXME: this needs to become an ipc message */
+/* FIXME: This needs to become an IPC message */
EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size);
EAPI Ecore_Ipc_Server *ecore_ipc_client_server_get(Ecore_Ipc_Client *cl);
EAPI void *ecore_ipc_client_del(Ecore_Ipc_Client *cl);
@@ -357,14 +319,11 @@ EAPI const char *ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl);
EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl);
EAPI int ecore_ipc_ssl_available_get(void);
-/* FIXME: need to add a callback to "ok" large ipc messages greater than */
+/* FIXME: Need to add a callback to "ok" large IPC messages greater than */
/* a certain size (security/DOS attack safety) */
#ifdef __cplusplus
}
#endif
-/**
- * @}
- */
#endif
diff --git a/src/lib/ecore_x/Ecore_X.h b/src/lib/ecore_x/Ecore_X.h
index 7272b6a948..90e4270203 100644..100755
--- a/src/lib/ecore_x/Ecore_X.h
+++ b/src/lib/ecore_x/Ecore_X.h
@@ -2,7 +2,6 @@
#define _ECORE_X_H
#include <Eina.h>
-#include <Efl_Config.h>
#ifdef EAPI
# undef EAPI
@@ -26,74 +25,41 @@
# endif // ifdef __GNUC__
#endif // ifdef _MSC_VER
-#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; /** < 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;
-
-#include "ecore_x_version.h"
-
#include <sys/types.h>
/**
+ * @internal
* @file
- * @brief Ecore functions for dealing with the X Windows System
+ * @brief Ecore functions for dealing with the X Windows System.
*
- * @defgroup Ecore_X_Group Ecore_X - X11 Integration
- * @ingroup Ecore
- *
- * Ecore_X provides a wrapper and convenience functions for using the
- * X Windows System. Function groups for this part of the library
- * include the following:
+ * @remarks Ecore_X provides wrapper and convenience functions for using the
+ * X Windows System. Function groups for this part of the library
+ * include the following:
* @li @ref Ecore_X_Init_Group
* @li @ref Ecore_X_Display_Attr_Group
* @li @ref Ecore_X_Flush_Group
- * @li @ref Ecore_X_DPMS_Group
- * @li @ref Ecore_X_Drawable_Group
- * @li @ref Ecore_X_Pixmap_Group
- * @li @ref Ecore_X_Window_Create_Group
- * @li @ref Ecore_X_Window_Properties_Group
- * @li @ref Ecore_X_Window_Destroy_Group
- * @li @ref Ecore_X_Window_Visibility_Group
- * @li @ref Ecore_X_Window_Geometry_Group
- * @li @ref Ecore_X_Window_Focus_Functions
- * @li @ref Ecore_X_Window_Z_Order_Group
- * @li @ref Ecore_X_Window_Parent_Group
- * @li @ref Ecore_X_Window_Shape
- *
- * When using the XLib backend, setting the ECORE_X_SYNC environment variable
- * will cause X calls to be run synchronously for easier debugging.
+ */
+
+/**
+ * @internal
+ * @defgroup Ecore_X_Group Ecore X
+ * @ingroup Ecore_Group
+ * @{
*/
typedef unsigned int Ecore_X_ID;
#ifndef _ECORE_X_WINDOW_PREDEF
typedef Ecore_X_ID Ecore_X_Window;
-typedef Ecore_X_ID Ecore_X_Pixmap;
-typedef Ecore_X_ID Ecore_X_Atom;
-typedef struct _Ecore_X_Icon
-{
- unsigned int width, height;
- unsigned int *data;
-} Ecore_X_Icon;
#endif // ifndef _ECORE_X_WINDOW_PREDEF
typedef void *Ecore_X_Visual;
+typedef Ecore_X_ID Ecore_X_Pixmap;
typedef Ecore_X_ID Ecore_X_Drawable;
#ifdef HAVE_ECORE_X_XCB
typedef Ecore_X_ID Ecore_X_GC;
#else // ifdef HAVE_ECORE_X_XCB
typedef void *Ecore_X_GC;
#endif /* HAVE_ECORE_X_XCB */
+typedef Ecore_X_ID Ecore_X_Atom;
typedef Ecore_X_ID Ecore_X_Colormap;
typedef Ecore_X_ID Ecore_X_Time;
typedef Ecore_X_ID Ecore_X_Cursor;
@@ -102,7 +68,6 @@ typedef void Ecore_X_Connection;
typedef void Ecore_X_Screen;
typedef Ecore_X_ID Ecore_X_Sync_Counter;
typedef Ecore_X_ID Ecore_X_Sync_Alarm;
-typedef Ecore_X_ID Ecore_X_Sync_Fence; /**< @since 1.9 */
typedef void Ecore_X_XRegion;
typedef Ecore_X_ID Ecore_X_Randr_Output;
@@ -123,6 +88,12 @@ typedef struct _Ecore_X_Rectangle
unsigned int width, height;
} Ecore_X_Rectangle;
+typedef struct _Ecore_X_Icon
+{
+ unsigned int width, height;
+ unsigned int *data;
+} Ecore_X_Icon;
+
typedef enum _Ecore_X_GC_Value_Mask
{
ECORE_X_GC_VALUE_MASK_FUNCTION = (1L << 0),
@@ -158,22 +129,22 @@ typedef enum _Ecore_X_Composite_Update_Type
/**
* @typedef _Ecore_X_Window_State
- * Defines the different states of the window of Ecore_X.
+ * @brief Enumeration of the different states of the window of Ecore_X.
*/
typedef enum _Ecore_X_Window_State
{
ECORE_X_WINDOW_STATE_UNKNOWN = 0,
- ECORE_X_WINDOW_STATE_ICONIFIED, /** The window is iconified. */
- ECORE_X_WINDOW_STATE_MODAL, /** The window is a modal dialog box. */
- ECORE_X_WINDOW_STATE_STICKY, /** The window manager should keep the window's position fixed
- * even if the virtual desktop scrolls. */
- ECORE_X_WINDOW_STATE_MAXIMIZED_VERT, /** The window has the maximum vertical size. */
- ECORE_X_WINDOW_STATE_MAXIMIZED_HORZ, /** The window has the maximum horizontal size. */
- ECORE_X_WINDOW_STATE_SHADED, /** The window is shaded. */
- ECORE_X_WINDOW_STATE_SKIP_TASKBAR, /** The window should not be included in the taskbar. */
- ECORE_X_WINDOW_STATE_SKIP_PAGER, /** The window should not be included in the pager. */
- ECORE_X_WINDOW_STATE_HIDDEN, /** The window is invisible (i.e. minimized/iconified) */
- ECORE_X_WINDOW_STATE_FULLSCREEN, /** The window should fill the entire screen and have no
+ ECORE_X_WINDOW_STATE_ICONIFIED, /**< The window is iconified */
+ ECORE_X_WINDOW_STATE_MODAL, /**< The window is a modal dialog box */
+ ECORE_X_WINDOW_STATE_STICKY, /**< The window manager should keep the window's position fixed
+ * even if the virtual desktop scrolls */
+ ECORE_X_WINDOW_STATE_MAXIMIZED_VERT, /**< The window has the maximum vertical size */
+ ECORE_X_WINDOW_STATE_MAXIMIZED_HORZ, /**< The window has the maximum horizontal size */
+ ECORE_X_WINDOW_STATE_SHADED, /**< The window is shaded */
+ ECORE_X_WINDOW_STATE_SKIP_TASKBAR, /**< The window should not be included in the taskbar */
+ ECORE_X_WINDOW_STATE_SKIP_PAGER, /**< The window should not be included in the pager */
+ ECORE_X_WINDOW_STATE_HIDDEN, /**< The window is invisible (i.e. minimized/iconified) */
+ ECORE_X_WINDOW_STATE_FULLSCREEN, /**< The window should fill the entire screen and have no
* window border/decorations */
ECORE_X_WINDOW_STATE_ABOVE,
ECORE_X_WINDOW_STATE_BELOW,
@@ -196,6 +167,26 @@ typedef enum _Ecore_X_Window_Stack_Mode
ECORE_X_WINDOW_STACK_OPPOSITE = 4
} Ecore_X_Window_Stack_Mode;
+/**
+ * @typedef _Ecore_X_Window_Rotation_Transform_Hint
+ * @brief Enumeration of the different transform hints of the window of Ecore_X.
+ *
+ * @remarks A value of @c 3 means, HINT_0 goes to HINT_180(0x3).
+ * It is same as HINT_0 goes to HINT_FLIP_H(0x1) and it goes to HINT_FLIP_V(0x2).( 0x1 + 0x2 = 0x3 )
+ *
+ * @remarks A value of @c 7 means, HINT_0 goes to HINT_270(0x7).
+ * It is same as HINT_0 goes to HINT_90(0x4) and it goes to HINT_FLIP_H(0x1) and HINT_FLIP_V(0x2).( 0x4 + 0x1 + 0x2 = 0x7 )
+ */
+typedef enum _Ecore_X_Window_Rotation_Transform_Hint
+{
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_0 = 0,
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_FLIP_H = 0x1, /**< Rotate source image along the horizontal axis */
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_FLIP_V = 0x2, /**< Rotate source image along the vertical axis */
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_180 = 0x3, /**< Rotate source image 180 degrees clockwise */
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_90 = 0x4, /**< Rotate source image 90 degrees clockwise */
+ ECORE_X_WINDOW_ROTATION_TRANSFORM_HINT_270 = 0x7 /**< Rotate source image 270 degrees clockwise */
+} Ecore_X_Window_Rotation_Transform_Hint;
+
typedef enum _Ecore_X_Randr_Orientation
{
ECORE_X_RANDR_ORIENTATION_ROT_0 = (1 << 0),
@@ -279,7 +270,6 @@ typedef enum _Ecore_X_Randr_Edid_Aspect_Ratio
#define ECORE_X_SELECTION_TARGET_STRING "STRING"
#define ECORE_X_SELECTION_TARGET_UTF8_STRING "UTF8_STRING"
#define ECORE_X_SELECTION_TARGET_FILENAME "FILENAME"
-#define ECORE_X_SELECTION_TARGET_X_MOZ_URL "X_MOZ_URL"
#define ECORE_X_DND_VERSION 5
@@ -390,42 +380,34 @@ typedef enum _Ecore_X_Netwm_Direction
/**
* @typedef _Ecore_X_Error_Code
- * Defines the error codes of Ecore_X which wraps the X Window Systems
- * protocol's errors.
+ * @brief Enumeration of the error codes of Ecore_X that wraps the X Window Systems
+ * protocol errors.
*
* @since 1.7.0
*/
typedef enum _Ecore_X_Error_Code
{
- /** Everything is okay. */
- ECORE_X_ERROR_CODE_SUCCESS = 0, /** Bad request code */
- ECORE_X_ERROR_CODE_BAD_REQUEST = 1, /** Int parameter out of range */
- ECORE_X_ERROR_CODE_BAD_VALUE = 2, /** Parameter not a Window */
- ECORE_X_ERROR_CODE_BAD_WINDOW = 3, /** Parameter not a Pixmap */
- ECORE_X_ERROR_CODE_BAD_PIXMAP = 4, /** Parameter not an Atom */
- ECORE_X_ERROR_CODE_BAD_ATOM = 5, /** Parameter not a Cursor */
- ECORE_X_ERROR_CODE_BAD_CURSOR = 6, /** Parameter not a Font */
- ECORE_X_ERROR_CODE_BAD_FONT = 7, /** Parameter mismatch */
- ECORE_X_ERROR_CODE_BAD_MATCH = 8, /** Parameter not a Pixmap or Window */
- ECORE_X_ERROR_CODE_BAD_DRAWABLE = 9, /** Bad access */
- ECORE_X_ERROR_CODE_BAD_ACCESS = 10, /** Insufficient resources */
- ECORE_X_ERROR_CODE_BAD_ALLOC = 11, /** No such colormap */
- ECORE_X_ERROR_CODE_BAD_COLOR = 12, /** Parameter not a GC */
- ECORE_X_ERROR_CODE_BAD_GC = 13, /** Choice not in range or already used */
- ECORE_X_ERROR_CODE_BAD_ID_CHOICE = 14, /** Font or color name doesn't exist */
- ECORE_X_ERROR_CODE_BAD_NAME = 15, /** Request length incorrect */
- ECORE_X_ERROR_CODE_BAD_LENGTH = 16, /** Server is defective */
+ /** Everything is okay */
+ ECORE_X_ERROR_CODE_SUCCESS = 0, /**< Bad request code */
+ ECORE_X_ERROR_CODE_BAD_REQUEST = 1, /**< Integer parameter is out of range */
+ ECORE_X_ERROR_CODE_BAD_VALUE = 2, /**< Parameter is not a Window */
+ ECORE_X_ERROR_CODE_BAD_WINDOW = 3, /**< Parameter is not a Pixmap */
+ ECORE_X_ERROR_CODE_BAD_PIXMAP = 4, /**< Parameter is not an Atom */
+ ECORE_X_ERROR_CODE_BAD_ATOM = 5, /**< Parameter is not a Cursor */
+ ECORE_X_ERROR_CODE_BAD_CURSOR = 6, /**< Parameter is not a Font */
+ ECORE_X_ERROR_CODE_BAD_FONT = 7, /**< Parameter mismatch */
+ ECORE_X_ERROR_CODE_BAD_MATCH = 8, /**< Parameter is not a Pixmap or Window */
+ ECORE_X_ERROR_CODE_BAD_DRAWABLE = 9, /**< Bad access */
+ ECORE_X_ERROR_CODE_BAD_ACCESS = 10, /**< Insufficient resources */
+ ECORE_X_ERROR_CODE_BAD_ALLOC = 11, /**< No such colormap */
+ ECORE_X_ERROR_CODE_BAD_COLOR = 12, /**< Parameter is not a GC */
+ ECORE_X_ERROR_CODE_BAD_GC = 13, /**< Choice is not in the range or already used */
+ ECORE_X_ERROR_CODE_BAD_ID_CHOICE = 14, /**< Font or color name doesn't exist */
+ ECORE_X_ERROR_CODE_BAD_NAME = 15, /**< Request length is incorrect */
+ ECORE_X_ERROR_CODE_BAD_LENGTH = 16, /**< Server is defective */
ECORE_X_ERROR_CODE_BAD_IMPLEMENTATION = 17,
} Ecore_X_Error_Code;
-typedef enum _Ecore_X_Dpms_Mode
-{
- ECORE_X_DPMS_MODE_ON = 0,
- ECORE_X_DPMS_MODE_STANDBY = 1,
- ECORE_X_DPMS_MODE_SUSPEND = 2,
- ECORE_X_DPMS_MODE_OFF = 3
-} Ecore_X_Dpms_Mode;
-
typedef struct _Ecore_X_Event_Mouse_In Ecore_X_Event_Mouse_In;
typedef struct _Ecore_X_Event_Mouse_Out Ecore_X_Event_Mouse_Out;
typedef struct _Ecore_X_Event_Window_Focus_In Ecore_X_Event_Window_Focus_In;
@@ -456,7 +438,6 @@ typedef struct _Ecore_X_Event_Fixes_Selection_Notify Ecore_X_Event_Fixes_S
typedef struct _Ecore_X_Selection_Data Ecore_X_Selection_Data;
typedef struct _Ecore_X_Selection_Data_Files Ecore_X_Selection_Data_Files;
typedef struct _Ecore_X_Selection_Data_Text Ecore_X_Selection_Data_Text;
-typedef struct _Ecore_X_Selection_Data_X_Moz_Url Ecore_X_Selection_Data_X_Moz_Url;
typedef struct _Ecore_X_Selection_Data_Targets Ecore_X_Selection_Data_Targets;
typedef struct _Ecore_X_Event_Xdnd_Enter Ecore_X_Event_Xdnd_Enter;
typedef struct _Ecore_X_Event_Xdnd_Position Ecore_X_Event_Xdnd_Position;
@@ -492,18 +473,11 @@ typedef struct _Ecore_X_Event_Startup_Sequence Ecore_X_Event_Startup
typedef struct _Ecore_X_Event_Generic Ecore_X_Event_Generic;
-
-typedef struct Ecore_X_Event_Present_Configure Ecore_X_Event_Present_Configure; /**< @since 1.9 */
-typedef struct Ecore_X_Event_Present_Complete Ecore_X_Event_Present_Complete; /**< @since 1.9 */
-typedef struct Ecore_X_Event_Present_Idle Ecore_X_Event_Present_Idle; /**< @since 1.9 */
-
typedef struct _Ecore_X_Randr_Screen_Size Ecore_X_Randr_Screen_Size;
typedef struct _Ecore_X_Randr_Screen_Size_MM Ecore_X_Randr_Screen_Size_MM;
-typedef struct _Ecore_X_Randr_Crtc_Info Ecore_X_Randr_Crtc_Info; /**< @since 1.8 */
typedef struct _Ecore_X_Xdnd_Position Ecore_X_Xdnd_Position;
-
struct _Ecore_X_Event_Mouse_In
{
int modifiers;
@@ -596,7 +570,7 @@ struct _Ecore_X_Event_Window_Hide
Ecore_X_Window win;
Ecore_X_Window event_win;
Ecore_X_Time time;
- Eina_Bool send_event : 1; /**< @since 1.8 */
+ Eina_Bool send_event : 1;
};
struct _Ecore_X_Event_Window_Show
@@ -750,7 +724,6 @@ struct _Ecore_X_Selection_Data
ECORE_X_SELECTION_CONTENT_NONE,
ECORE_X_SELECTION_CONTENT_TEXT,
ECORE_X_SELECTION_CONTENT_FILES,
- ECORE_X_SELECTION_CONTENT_X_MOZ_URL,
ECORE_X_SELECTION_CONTENT_TARGETS,
ECORE_X_SELECTION_CONTENT_CUSTOM
} content;
@@ -773,13 +746,6 @@ struct _Ecore_X_Selection_Data_Text
char *text;
};
-struct _Ecore_X_Selection_Data_X_Moz_Url
-{
- Ecore_X_Selection_Data data;
- Eina_Inarray *links;
- Eina_Inarray *link_names;
-};
-
struct _Ecore_X_Selection_Data_Targets
{
Ecore_X_Selection_Data data;
@@ -895,25 +861,11 @@ struct _Ecore_X_Randr_Screen_Size_MM
int width, height, width_mm, height_mm;
};
-struct _Ecore_X_Randr_Crtc_Info
-{
- Ecore_X_Time timestamp;
- int x, y;
- unsigned int width, height;
- Ecore_X_Randr_Mode mode;
- Ecore_X_Randr_Orientation rotation;
- int noutput;
- Ecore_X_Randr_Output *outputs;
- Ecore_X_Randr_Orientation rotations;
- int npossible;
- Ecore_X_Randr_Output *possible;
-}; /**< @since 1.8 */
-
struct _Ecore_X_Event_Screen_Change
{
Ecore_X_Window win;
Ecore_X_Window root;
- Ecore_X_Randr_Screen_Size_MM size; /* in pixel and millimeters */
+ Ecore_X_Randr_Screen_Size_MM size; /* In pixel and millimeters */
Ecore_X_Time time;
Ecore_X_Time config_time;
Ecore_X_Randr_Orientation orientation;
@@ -1062,62 +1014,9 @@ struct _Ecore_X_Event_Generic
void *data;
};
-typedef enum Ecore_X_Present_Event_Mask
-{
- ECORE_X_PRESENT_EVENT_MASK_NO_EVENT = 0,
- ECORE_X_PRESENT_EVENT_MASK_CONFIGURE_NOTIFY = 1,
- ECORE_X_PRESENT_EVENT_MASK_COMPLETE_NOTIFY = 2,
- ECORE_X_PRESENT_EVENT_MASK_IDLE_NOTIFY = 4,
-} Ecore_X_Present_Event_Mask; /**< @since 1.9 */
-
-typedef struct Ecore_X_Present
-{
- Ecore_X_Window win;
- unsigned int serial;
-} Ecore_X_Present; /**< @since 1.9 */
-
-struct Ecore_X_Event_Present_Configure
-{
- Ecore_X_Window win;
-
- int x, y;
- unsigned int width, height;
- int off_x, off_y;
- int pixmap_width, pixmap_height;
- long pixmap_flags;
-}; /**< @since 1.9 */
-
-typedef enum
-{
- ECORE_X_PRESENT_COMPLETE_MODE_COPY,
- ECORE_X_PRESENT_COMPLETE_MODE_FLIP,
- ECORE_X_PRESENT_COMPLETE_MODE_SKIP,
-} Ecore_X_Present_Complete_Mode;
-
-struct Ecore_X_Event_Present_Complete
-{
- Ecore_X_Window win;
-
- unsigned int serial; // value provided when generating request
- unsigned long long ust; // system time of presentation
- unsigned long long msc; // frame count at time of presentation
- Eina_Bool kind : 1; /* 0 for PresentCompleteKindPixmap (PresentPixmap completion),
- 1 for PresentCompleteKindNotifyMsc (PresentNotifyMSC completion) */
- Ecore_X_Present_Complete_Mode mode;
-}; /**< @since 1.9 */
-
-struct Ecore_X_Event_Present_Idle
-{
- Ecore_X_Window win;
-
- unsigned int serial;
- Ecore_X_Pixmap pixmap;
- Ecore_X_Sync_Fence idle_fence;
-}; /**< @since 1.9 */
-
-EAPI extern int ECORE_X_EVENT_ANY; /**< low level event dependent on
- backend in use, if Xlib will be XEvent, if XCB will be xcb_generic_event_t.
- @warning avoid using it.
+EAPI extern int ECORE_X_EVENT_ANY; /**< Low level event is dependent on the
+ backend being used, if Xlib is XEvent, if XCB is xcb_generic_event_t.
+ @remarks Avoid using it
*/
EAPI extern int ECORE_X_EVENT_MOUSE_IN;
EAPI extern int ECORE_X_EVENT_MOUSE_OUT;
@@ -1180,10 +1079,6 @@ EAPI extern int ECORE_X_EVENT_XKB_NEWKBD_NOTIFY; /** @since 1.7 */
EAPI extern int ECORE_X_EVENT_GENERIC;
-EAPI extern int ECORE_X_EVENT_PRESENT_CONFIGURE; /**< @since 1.9 */
-EAPI extern int ECORE_X_EVENT_PRESENT_COMPLETE; /**< @since 1.9 */
-EAPI extern int ECORE_X_EVENT_PRESENT_IDLE; /**< @since 1.9 */
-
EAPI extern int ECORE_X_EVENT_XDND_ENTER;
EAPI extern int ECORE_X_EVENT_XDND_POSITION;
EAPI extern int ECORE_X_EVENT_XDND_STATUS;
@@ -1206,61 +1101,67 @@ EAPI extern int ECORE_X_RAW_BUTTON_PRESS; /**< @since 1.8 */
EAPI extern int ECORE_X_RAW_BUTTON_RELEASE; /**< @since 1.8 */
EAPI extern int ECORE_X_RAW_MOTION; /**< @since 1.8 */
+/**
+ * @brief Ecore X WM Protocol
+ */
typedef enum _Ecore_X_WM_Protocol
{
- /** If enabled the window manager will be asked to send a
- * delete message instead of just closing (destroying) the window. */
+ /**< If enabled, the window manager is asked to send a
+ * delete message instead of just closing (destroying) the window */
ECORE_X_WM_PROTOCOL_DELETE_REQUEST,
- /** If enabled the window manager will be told that the window
- * explicitly sets input focus. */
+ /**< If enabled, the window manager is told that the window
+ * explicitly sets the input focus */
ECORE_X_WM_PROTOCOL_TAKE_FOCUS,
- /** If enabled the window manager can ping the window to check
- * if it is alive. */
+ /**< If enabled, the window manager can ping the window to check
+ * if it is alive */
ECORE_X_NET_WM_PROTOCOL_PING,
- /** If enabled the window manager can sync updating with the
+ /**< If enabled, the window manager can sync updating with the
* window (?) */
ECORE_X_NET_WM_PROTOCOL_SYNC_REQUEST,
- /** Number of defined items */
+ /**< Number of defined items */
ECORE_X_WM_PROTOCOL_NUM
} Ecore_X_WM_Protocol;
+/**
+ * @brief Enumeration Ecore X Window Input Mode type
+ */
typedef enum _Ecore_X_Window_Input_Mode
{
- /** The window can never be focused */
+ /**< The window can never be focused */
ECORE_X_WINDOW_INPUT_MODE_NONE,
- /** The window can be focused by the WM but doesn't focus itself */
+ /**< The window can be focused by the WM but doesn't focus itself */
ECORE_X_WINDOW_INPUT_MODE_PASSIVE,
- /** The window sets the focus itself if one of its sub-windows
- * already is focused */
+ /**< The window sets the focus on its own if one of its sub-windows
+ * is already focused */
ECORE_X_WINDOW_INPUT_MODE_ACTIVE_LOCAL,
- /** The window sets the focus itself even if another window
+ /**< The window sets the focus itself even if another window
* is currently focused */
ECORE_X_WINDOW_INPUT_MODE_ACTIVE_GLOBAL
} Ecore_X_Window_Input_Mode;
/**
* @typedef _Ecore_X_Window_State_Hint
- * Defines the different state hint of the window of Ecore_X.
+ * @brief Enumeration of the different state hints of the window of Ecore_X.
*/
typedef enum _Ecore_X_Window_State_Hint
{
- /** Do not provide any state hint to the window manager */
+ /**< Do not provide any state hint to the window manager */
ECORE_X_WINDOW_STATE_HINT_NONE = -1,
- /** The window wants to remain hidden and NOT iconified */
+ /**< The window wants to remain hidden and NOT iconified */
ECORE_X_WINDOW_STATE_HINT_WITHDRAWN,
- /** The window wants to be mapped normally */
+ /**< The window wants to be mapped normally */
ECORE_X_WINDOW_STATE_HINT_NORMAL,
- /** The window wants to start in an iconified state */
+ /**< The window wants to start in an iconified state */
ECORE_X_WINDOW_STATE_HINT_ICONIC
} Ecore_X_Window_State_Hint;
@@ -1364,7 +1265,8 @@ typedef enum _Ecore_X_Illume_Indicator_Opacity_Mode
ECORE_X_ILLUME_INDICATOR_OPACITY_UNKNOWN = 0,
ECORE_X_ILLUME_INDICATOR_OPAQUE,
ECORE_X_ILLUME_INDICATOR_TRANSLUCENT,
- ECORE_X_ILLUME_INDICATOR_TRANSPARENT
+ ECORE_X_ILLUME_INDICATOR_TRANSPARENT,
+ ECORE_X_ILLUME_INDICATOR_BG_TRANSPARENT
} Ecore_X_Illume_Indicator_Opacity_Mode;
typedef enum _Ecore_X_Illume_Indicator_Type_Mode
@@ -1373,12 +1275,13 @@ typedef enum _Ecore_X_Illume_Indicator_Type_Mode
ECORE_X_ILLUME_INDICATOR_TYPE_1,
ECORE_X_ILLUME_INDICATOR_TYPE_2,
ECORE_X_ILLUME_INDICATOR_TYPE_3
-} Ecore_X_Illume_Indicator_Type_Mode; /**< @since 1.8 */
+} Ecore_X_Illume_Indicator_Type_Mode;
typedef enum _Ecore_X_Illume_Window_State
{
ECORE_X_ILLUME_WINDOW_STATE_NORMAL = 0,
- ECORE_X_ILLUME_WINDOW_STATE_FLOATING
+ ECORE_X_ILLUME_WINDOW_STATE_FLOATING,
+ ECORE_X_ILLUME_WINDOW_STATE_ASSISTANT_MENU
} Ecore_X_Illume_Window_State;
/* Window layer constants */
@@ -1394,21 +1297,55 @@ typedef enum _Ecore_X_Illume_Window_State
EAPI int ecore_x_init(const char *name);
EAPI int ecore_x_shutdown(void);
EAPI int ecore_x_disconnect(void);
+
+/**
+ * Retrieves the Ecore_X_Display handle used for the current X connection.
+ * @return The current X display.
+ * @ingroup Ecore_X_Display_Attr_Group
+ */
EAPI Ecore_X_Display *ecore_x_display_get(void);
EAPI Ecore_X_Connection *ecore_x_connection_get(void);
EAPI int ecore_x_fd_get(void);
EAPI Ecore_X_Screen *ecore_x_default_screen_get(void);
EAPI void ecore_x_screen_size_get(const Ecore_X_Screen *screen, int *w, int *h);
+
+/**
+ * Retrieves the number of screens.
+ *
+ * @return The count of the number of screens.
+ * @ingroup Ecore_X_Display_Attr_Group
+ *
+ * @since 1.1
+ */
EAPI int ecore_x_screen_count_get(void);
EAPI int ecore_x