From aa1072d75a1173d5368cb3da6bb0796194664e3b Mon Sep 17 00:00:00 2001 From: gastal Date: Wed, 3 Aug 2011 14:38:32 +0000 Subject: [PATCH] Ecore: ecore_evas basics documentation. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@62055 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/examples.dox | 56 +++++++++++++- src/examples/Makefile.am | 6 +- src/examples/ecore_evas_basics_example.c | 91 ++++++++++++++++++++++ src/lib/ecore_evas/Ecore_Evas.h | 125 +++++++++++++++++++++++++++++++ src/lib/ecore_evas/ecore_evas.c | 108 -------------------------- 5 files changed, 275 insertions(+), 111 deletions(-) create mode 100644 src/examples/ecore_evas_basics_example.c diff --git a/doc/examples.dox b/doc/examples.dox index cb63847..9f9a207 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -16,6 +16,7 @@ * @li @ref ecore_con_client_simple_example_c * @li @ref ecore_evas_callbacks_example_c * @li @ref ecore_evas_object_example_c + * @li @ref ecore_evas_basics_example_c * */ @@ -959,7 +960,7 @@ * pipe, fork our process, and then the child is going to comunicate to the * parent the result of its processing through the pipe. * - * As always we start with our includes, nothing especial: + * As always we start with our includes, nothing special: * @skip #include * @until Ecore.h * @@ -1325,3 +1326,56 @@ * @include ecore_evas_object_example.c * @example ecore_evas_object_example.c */ + +/** + * @page ecore_evas_basics_example_c Ecore Evas basics example + * @dontinclude ecore_evas_basics_example.c + * + * This example will ilustrate the usage of some basic Ecore_Evas functions. + * This example will list the available evas engines, check which one we used to + * create our window and set some data on our Ecore_Evas. It also allows you to + * hide/show all windows in this process(we only have one, but if there were + * more they would be hidden), to hide the windows type 'h' and hit return, to + * show them, type 's' and hit return. + * + * The very first thing we'll do is init ecore_evas: + * @skipline evas_init + * @until return 1 + * + * Once inited we query which engines are available: + * @until ecore_evas_engines_free + * + * We then create an Ecore_Evas(window) with the first available engine, on + * position 0,0 with size 200,200 and no especial flags: + * @until evas_show + * + * We now add some important data to our Ecore_Evas: + * @until data_set + * + * And since our data is dinamically allocated we'll need to free it when the + * Ecore_Evas dies: + * @until delete_request + * @dontinclude ecore_evas_basics_example.c + * @skip static void + * @until } + * @skip printf("Using + * + * We now print which Evas engine is being used for our example: + * @until printf + * + * Next we are going to add a background to our window, for which we'll need to + * get the canvas(Evas) on which to draw it: + * @until canvas + * + * We then do a sanity check, veryfing if the Ecore_Evas of the Evas is the + * Ecore_Evas from which we got the Evas: + * @until printf + * + * Once all else is done we run our main loop, and when that is done(application + * is exiting) we free our Ecore_Evas and shutdown the ecore_evas subsystem: + * @until shutdown + * + * Here you have the full-source of the code: + * @include ecore_evas_basics_example.c + * @example ecore_evas_basics_example.c + */ \ No newline at end of file diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index 7ebbfc6..58d2052 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -46,7 +46,8 @@ SRCS = \ ecore_thread_example.c \ ecore_evas_callbacks.c \ ecore_evas_window_sizes_example.c \ - ecore_evas_object_example.c + ecore_evas_object_example.c \ + ecore_evas_basics_example.c EXTRA_DIST = $(SRCS) @@ -78,7 +79,8 @@ pkglib_PROGRAMS += \ ecore_thread_example \ ecore_evas_callbacks \ ecore_evas_window_sizes_example \ - ecore_evas_object_example + ecore_evas_object_example \ + ecore_evas_basics_example ecore_con_lookup_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_con_url_headers_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la diff --git a/src/examples/ecore_evas_basics_example.c b/src/examples/ecore_evas_basics_example.c new file mode 100644 index 0000000..5f0231f --- /dev/null +++ b/src/examples/ecore_evas_basics_example.c @@ -0,0 +1,91 @@ +/** + * Ecore example illustrating the basics of ecore evas usage. + * + * You'll need at least one Evas engine built for it (excluding the + * buffer one). See stdout/stderr for output. + * + * @verbatim + * gcc -o ecore_evas_basics_example ecore_evas_basics_example.c `pkg-config --libs --cflags ecore-evas` + * @endverbatim + */ + +#include +#include +#include + +static Eina_Bool +_stdin_cb(void *data, Ecore_Fd_Handler *handler) +{ + Eina_List *l; + Ecore_Evas *ee; + char c; + + scanf("%c", &c); + if (c == 'h') + EINA_LIST_FOREACH(ecore_evas_ecore_evas_list_get(), l, ee) + ecore_evas_hide(ee); + else if (c == 's') + EINA_LIST_FOREACH(ecore_evas_ecore_evas_list_get(), l, ee) + ecore_evas_show(ee); + + return ECORE_CALLBACK_RENEW; +} + +static void +_on_delete(Ecore_Evas *ee) +{ + free(ecore_evas_data_get(ee, "key")); + ecore_main_loop_quit(); +} + +int +main(void) +{ + Ecore_Evas *ee; + Evas *canvas; + Evas_Object *bg; + Eina_List *engines, *l; + char *data; + + if(ecore_evas_init() <= 0) + return 1; + + engines = ecore_evas_engines_get(); + printf("Available engines:\n"); + EINA_LIST_FOREACH(engines, l, data) + printf("%s\n", data); + ecore_evas_engines_free(engines); + + ee = ecore_evas_new(NULL, 0, 0, 200, 200, NULL); + ecore_evas_title_set(ee, "Ecore Evas basics Example"); + ecore_evas_show(ee); + + data = malloc(sizeof(char) * 6); + sprintf(data, "%s", "hello"); + ecore_evas_data_set(ee, "key", data); + ecore_evas_callback_delete_request_set(ee, _on_delete); + + printf("Using %s engine!\n", ecore_evas_engine_name_get(ee)); + + canvas = ecore_evas_get(ee); + if(ecore_evas_ecore_evas_get(canvas) == ee) + printf("Everything is sane!\n"); + + bg = evas_object_rectangle_add(canvas); + evas_object_color_set(bg, 0, 0, 255, 255); + evas_object_resize(bg, 200, 200); + evas_object_show(bg); + ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE); + + ecore_main_fd_handler_add(STDIN_FILENO, + ECORE_FD_READ | ECORE_FD_ERROR, + _stdin_cb, + NULL, NULL, NULL); + + ecore_main_loop_begin(); + + ecore_evas_free(ee); + ecore_evas_shutdown(); + + return 0; +} diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h index d602e4a..dc512af 100644 --- a/src/lib/ecore_evas/Ecore_Evas.h +++ b/src/lib/ecore_evas/Ecore_Evas.h @@ -38,6 +38,7 @@ * 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 */ /* FIXME: @@ -142,14 +143,61 @@ typedef struct _Ecore_Evas Ecore_Evas; EAPI int ecore_evas_engine_type_supported_get(Ecore_Evas_Engine_Type engine); +/** + * @brief Init the Ecore_Evas system. + * + * @return How many times the lib has been initialized, 0 indicates failure. + * + * Set up the Evas wrapper system. Init Evas and Ecore libraries. + * + * @see ecore_evas_shutdown() + */ EAPI int ecore_evas_init(void); +/** + * @brief Shut down the Ecore_Evas system. + * + * @return 0 if ecore evas is fully shut down, or > 0 if it still being used. + * + * This closes the Evas wrapper system down. Shut down Evas and Ecore libraries. + * + * @see ecore_evas_init() + */ EAPI int ecore_evas_shutdown(void); 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. + * + * @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(). + */ EAPI Eina_List *ecore_evas_engines_get(void); +/** + * @brief Free list returned by ecore_evas_engines_get() + */ 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 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 NULL if creation failed. + */ EAPI Ecore_Evas *ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options); @@ -276,10 +324,64 @@ EAPI Ecore_WinCE_Window *ecore_evas_software_wince_window_get(const Ecore_Evas * EAPI Ecore_Evas *ecore_evas_cocoa_new(const char* name, int w, int h); /* generic manipulation calls */ +/** + * @brief Get 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() + * + * @see ecore_evas_free() + */ EAPI const char *ecore_evas_engine_name_get(const Ecore_Evas *ee); +/** + * @brief Return 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 NULL if not held by one. + * + * @warning Only use on Evas' created with ecore evas! + */ EAPI Ecore_Evas *ecore_evas_ecore_evas_get(const Evas *e); +/** + * @brief Free an Ecore_Evas + * + * @param ee The Ecore_Evas to free + * + * This frees up any memory used by the Ecore_Evas. + */ EAPI void ecore_evas_free(Ecore_Evas *ee); +/** + * @brief Retrieve 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. + * + * This function retrieves user specific data that has been stored within an + * Ecore_Evas structure with ecore_evas_data_set(). + * + * @returns NULL on error or no data found, A pointer to the user data on + * success. + * + * @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. + * + * @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. + * + * 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. + * + * @see ecore_evas_callback_pre_free_set() + * @see ecore_evas_free() + * @see ecore_evas_data_get() + */ EAPI void ecore_evas_data_set(Ecore_Evas *ee, const char *key, const void *data); /** * Set a callback for Ecore_Evas resize events. @@ -476,7 +578,21 @@ EAPI void ecore_evas_alpha_set(Ecore_Evas *ee, Eina_Bool alpha); EAPI Eina_Bool ecore_evas_alpha_get(const Ecore_Evas *ee); EAPI void ecore_evas_transparent_set(Ecore_Evas *ee, Eina_Bool transparent); EAPI Eina_Bool ecore_evas_transparent_get(const Ecore_Evas *ee); +/** + * @brief Show an Ecore_Evas' window + * + * @param ee The Ecore_Evas to show. + * + * This function makes @p ee visible. + */ EAPI void ecore_evas_show(Ecore_Evas *ee); +/** + * @brief Hide an Ecore_Evas' window + * + * @param ee The Ecore_Evas to hide. + * + * This function makes @p ee hidden(not visible). + */ EAPI void ecore_evas_hide(Ecore_Evas *ee); EAPI int ecore_evas_visibility_get(const Ecore_Evas *ee); EAPI void ecore_evas_raise(Ecore_Evas *ee); @@ -751,6 +867,15 @@ EAPI Evas_Object *ecore_evas_object_associate_get(const Ecore_Evas *ee); /* 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. + * + * @return A list of ecore_evases. + * + * 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. + */ EAPI Eina_List *ecore_evas_ecore_evas_list_get(void); /* specific calls to an x11 environment ecore_evas */ diff --git a/src/lib/ecore_evas/ecore_evas.c b/src/lib/ecore_evas/ecore_evas.c index 7404a3c..fd05ec3 100644 --- a/src/lib/ecore_evas/ecore_evas.c +++ b/src/lib/ecore_evas/ecore_evas.c @@ -187,12 +187,6 @@ ecore_evas_engine_type_supported_get(Ecore_Evas_Engine_Type engine) }; } -/** - * Init the Evas system. - * @return greater than 0 on success, 0 on failure - * - * Set up the Evas wrapper system. Init Evas and Ecore libraries. - */ EAPI int ecore_evas_init(void) { @@ -237,12 +231,6 @@ ecore_evas_init(void) return --_ecore_evas_init_count; } -/** - * Shut down the Evas system. - * @return 0 if ecore evas is fully shut down, or > 0 if it still needs to be shut down - * - * This closes the Evas wrapper system down. Shut down Evas and Ecore libraries. - */ EAPI int ecore_evas_shutdown(void) { @@ -693,13 +681,6 @@ static const struct ecore_evas_engine _engines[] = { {NULL, NULL} }; -/** - * Returns 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 them, to avoid problems use ecore_evas_engines_free() - */ EAPI Eina_List * ecore_evas_engines_get(void) { @@ -712,9 +693,6 @@ ecore_evas_engines_get(void) return lst; } -/** - * Free list returned by ecore_evas_engines_get() - */ EAPI void ecore_evas_engines_free(Eina_List *engines) { @@ -742,25 +720,6 @@ _ecore_evas_new_auto_discover(int x, int y, int w, int h, const char *extra_opti return NULL; } -/** - * 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 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 NULL if creation failed. - */ EAPI Ecore_Evas * ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char *extra_options) { @@ -788,12 +747,6 @@ ecore_evas_new(const char *engine_name, int x, int y, int w, int h, const char * return NULL; } -/** - * Get the engine name used by this engine. - * - * should return one of the values in ecore_evas_engines_get(), usually - * acceptable by ecore_evas_new(). - */ EAPI const char * ecore_evas_engine_name_get(const Ecore_Evas *ee) { @@ -802,12 +755,6 @@ ecore_evas_engine_name_get(const Ecore_Evas *ee) return ee->driver; } -/** - * Return 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 NULL if not hold by one. - */ EAPI Ecore_Evas * ecore_evas_ecore_evas_get(const Evas *e) { @@ -821,12 +768,6 @@ ecore_evas_ecore_evas_get(const Evas *e) return ee; } -/** - * Free an Ecore_Evas - * @param ee The Ecore_Evas to free - * - * This frees up any memory used by the Ecore_Evas. - */ EAPI void ecore_evas_free(Ecore_Evas *ee) { @@ -840,19 +781,6 @@ ecore_evas_free(Ecore_Evas *ee) return; } -/** - * Retrieve 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. - * - * This function retrieves user specific data that has been stored within an - * Ecore_Evas structure with ecore_evas_data_set(). - * - * @returns NULL on error or no data found, A pointer to the user data on - * success. - * - * @see ecore_evas_data_set - */ EAPI void * ecore_evas_data_get(const Ecore_Evas *ee, const char *key) { @@ -869,21 +797,6 @@ ecore_evas_data_get(const Ecore_Evas *ee, const char *key) return eina_hash_find(ee->data, key); } -/** - * Store 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. - * - * 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. - * - * @see ecore_evas_free - */ EAPI void ecore_evas_data_set(Ecore_Evas *ee, const char *key, const void *data) { @@ -1498,12 +1411,6 @@ ecore_evas_transparent_get(const Ecore_Evas *ee) return ee->transparent ? EINA_TRUE : 0; } -/** - * Show an Ecore_Evas' window - * @param ee The Ecore_Evas to show. - * - * This function makes @p ee visible. - */ EAPI void ecore_evas_show(Ecore_Evas *ee) { @@ -1517,12 +1424,6 @@ ecore_evas_show(Ecore_Evas *ee) IFE; } -/** - * Hide an Ecore_Evas' window - * @param ee The Ecore_Evas to show. - * - * This function makes @p ee hidden. - */ EAPI void ecore_evas_hide(Ecore_Evas *ee) { @@ -2823,15 +2724,6 @@ _ecore_evas_mouse_multi_up_process(Ecore_Evas *ee, int device, flags, timestamp, NULL); } -/** - * Get a list of all the ecore_evases. - * - * 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 free by just deleting the list. - * - * @return A list of ecore_evases. - */ EAPI Eina_List * ecore_evas_ecore_evas_list_get(void) { -- 2.7.4