Enlightenment CVS committal
Author : raster
Project : e17
Module : libs/evas
Dir : e17/libs/evas/src/lib/canvas
Modified Files:
evas_data.c
Log Message:
some more docs...
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/evas/src/lib/canvas/evas_data.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -3 -r1.3 -r1.4
--- evas_data.c 5 Mar 2003 02:30:14 -0000 1.3
+++ evas_data.c 20 Feb 2004 07:06:39 -0000 1.4
@@ -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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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)
-------------------------------------------------------
SF.Net is sponsored by: Speed Start Your Linux Apps Now.
Build and deploy apps & Web services for Linux with
a free DVD software kit from IBM. Click Now!
http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
