From dfe6bb6f4ea745009df9f5de19cd9b6a7c9fc700 Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Fri, 20 Feb 2004 07:06:39 +0000 Subject: [PATCH] some more docs... SVN revision: 9038 --- legacy/evas/evas.c.in | 5 +- legacy/evas/src/lib/canvas/evas_data.c | 77 ++++++++++++++++++++++---- 2 files changed, 70 insertions(+), 12 deletions(-) diff --git a/legacy/evas/evas.c.in b/legacy/evas/evas.c.in index 3619f56778..b8e7487ad8 100644 --- a/legacy/evas/evas.c.in +++ b/legacy/evas/evas.c.in @@ -244,12 +244,13 @@ make install @todo (1.0) Document API +@todo (1.0) Evas engine that renders to Evas_Objects @todo (1.0) OpenGL engine needs to use texture meshes @todo (1.0) OpenGL engine needs texture cache and size setting @todo (1.0) OpenGL Engine needs YUV import API to YUV texture @todo (1.0) All engines need pixel import API @todo (1.0) Add parital render through composite layer api to engines -@todo (1.0) Move callback processing to a queue and do it asynchronously +@todo (1.0) Move callback processing to a queue and do it asynchronously??? @todo (1.0) Add button grabbing @todo (1.0) Add generic object method call system @todo (1.0) Add callbacks set for smart object parents to be set on all child smart objects too. @@ -259,7 +260,7 @@ make install @todo (1.0) Add font listing calls @todo (1.0) Add ability to check image comments & disk format @todo (1.0) Add group objects -@todo (1.0) Export engine rnedering etc. API cleanly to Evas API +@todo (1.0) Export engine rendering API cleanly to Evas API @todo (1.0) Add smart object ability to provide rendering callback @todo (1.1) Make freetype optional and put in optional graymap font engine @todo (1.1) Free images if object invisible (and put back in chache) diff --git a/legacy/evas/src/lib/canvas/evas_data.c b/legacy/evas/src/lib/canvas/evas_data.c index 9d5da175f3..0f6a21813e 100644 --- a/legacy/evas/src/lib/canvas/evas_data.c +++ b/legacy/evas/src/lib/canvas/evas_data.c @@ -3,10 +3,35 @@ #include "Evas.h" /** - * To be documented. - * - * FIXME: To be fixed. + * Set an attached data pointer to an object with a given string key. + * @param obj The object to attach the data pointer to + * @param key The string key for the data to access it + * @param data The ponter to the data to be attached * + * This attaches the pointer @p data to the object @p obj given the string + * @p key. This pointer will stay "hooked" to the object until a new pointer + * with the same string key is attached with evas_object_data_set() or it is + * deleted with evas_object_data_del(). On deletion of the object @p obj, the + * pointers will not be accessible from the object anymore. + * + * You can find the pointer attached under a string key using + * evas_object_data_get(). It is the job of the calling application to free + * any data pointed to by @p data when it is no longer required. + * + * If @p data is NULL, the old value stored at @p key will be removed but no + * new value will be stored. This is synonymous with calling + * evas_object_data_del() with @p obj and @p key. + * + * Example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = malloc(500); + * evas_object_data_set(obj, "name_of_data", my_data); + * printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data")); + * @endcode */ void evas_object_data_set(Evas_Object *obj, const char *key, const void *data) @@ -19,7 +44,7 @@ evas_object_data_set(Evas_Object *obj, const char *key, const void *data) if (!key) return; evas_object_data_del(obj, key); - + if (data == NULL) return; node = malloc(sizeof(Evas_Data_Node)); node->key = strdup(key); node->data = (void *)data; @@ -27,10 +52,29 @@ evas_object_data_set(Evas_Object *obj, const char *key, const void *data) } /** - * To be documented. - * - * FIXME: To be fixed. + * Return an attached data pointer by its given string key. + * @param obj The object to which the data was attached + * @param key The string key the data was stored under + * @return The data pointer stored, or NULL if none was stored * + * This function will return the data pointer attached to the object @p obj + * stored using the string key @p key. If the object is valid and data was + * stored under the given key, the pointer that was stored will be reuturned. + * If this is not the case, NULL will be returned, signifying an invalid object + * or non-existent key. It is possible a NULL pointer was stored given that + * key, but this situation is non-sensical and thus can be considered an error + * as well. NULL pointers are never stored as this is the return value if an + * error occurs. + * + * Example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = evas_object_data_get(obj, "name_of_my_data"); + * if (my_data) printf("Data stored was %p\n", my_data); + * else printf("No data was stored on the object\n"); */ void * evas_object_data_get(Evas_Object *obj, const char *key) @@ -58,10 +102,23 @@ evas_object_data_get(Evas_Object *obj, const char *key) } /** - * To be documented. - * - * FIXME: To be fixed. + * Delete at attached data pointer from an object. + * @param obj The object to delete the data pointer from + * @param key The string key the data was stored under + * @return The original data pointer stored at @p key on @p obj * + * This will remove thee stored data pointer from @p obj stored under @p key, + * and return the original pointer stored under @p key, if any, nor NULL if + * nothing was stored under that key. + * + * Example: + * + * @code + * int *my_data; + * extern Evas_Object *obj; + * + * my_data = evas_object_data_del(obj, "name_of_my_data"); + * @endcode */ void * evas_object_data_del(Evas_Object *obj, const char *key)