Ecore: ecore_evas basics documentation.

SVN revision: 62055
This commit is contained in:
Jonas M. Gastal 2011-08-03 14:38:32 +00:00
parent c33aaf812f
commit 92f409501d
5 changed files with 275 additions and 111 deletions

View File

@ -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
*/

View File

@ -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

View File

@ -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 <Ecore.h>
#include <Ecore_Evas.h>
#include <unistd.h>
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;
}

View File

@ -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 */

View File

@ -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)
{