Enlightenment CVS committal
Author : rephorm
Project : e17
Module : libs/evas
Dir : e17/libs/evas/src/lib/canvas
Modified Files:
evas_events.c evas_object_smart.c evas_smart.c evas_stack.c
Log Message:
add some documentation
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_events.c,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -3 -r1.49 -r1.50
--- evas_events.c 16 Nov 2006 03:20:24 -0000 1.49
+++ evas_events.c 8 Dec 2006 07:51:48 -0000 1.50
@@ -114,7 +114,7 @@
*/
/**
- * Freeze alll event processing
+ * Freeze all event processing
* @param e The canvas to freeze event processing on
*
* This function will indicate to evas that the canvas @p e is to have all
@@ -934,10 +934,23 @@
}
/**
- * To be documented.
+ * @defgroup Evas_Object_Event_Flags_Group Evas Object Event Flag Functions
*
- * FIXME: To be fixed.
+ * Functions that deal with how events on an Evas Object are processed.
+ */
+
+/**
+ * Set an object's pass events state.
+ * @param obj the evas object
+ * @param pass whether to pass events or not
+ *
+ * If @p pass is true, this will cause events on @p obj to be ignored.
+ * They will be triggered on the next lower object (that is not set to
+ * pass events) instead.
*
+ * If @p pass is false, events will be processed as normal.
+ *
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI void
evas_object_pass_events_set(Evas_Object *obj, Evas_Bool pass)
@@ -958,10 +971,11 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Determine whether an object is set to pass events.
+ * @param obj
+ * @return pass events state
*
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI Evas_Bool
evas_object_pass_events_get(Evas_Object *obj)
@@ -973,10 +987,18 @@
}
/**
- * To be documented.
+ * Set an object's repeat events state.
+ * @param obj the object
+ * @param repeat wheter to repeat events or not
+ *
+ * If @p repeat is true, this will cause events on @p obj to trigger
+ * callbacks, but also to be repeated on the next lower object in the
+ * stack.
*
- * FIXME: To be fixed.
+ * If @p repeat is false, events occuring on @p obj will be processed
+ * normally.
*
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI void
evas_object_repeat_events_set(Evas_Object *obj, Evas_Bool repeat)
@@ -996,10 +1018,11 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Determine whether an object is set to repeat events.
+ * @param obj
+ * @return repeat events state
*
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI Evas_Bool
evas_object_repeat_events_get(Evas_Object *obj)
@@ -1011,10 +1034,22 @@
}
/**
- * To be documented.
+ * Set whether events on a smart member object should propagate to its parent.
*
- * FIXME: To be fixed.
+ * @param obj the smart member object
+ * @param prop wheter to propagate events or not
+ *
+ * This function has no effect if @p obj is not a member of a smart
+ * object.
*
+ * If @p prop is true, events occuring on this object will propagate on
+ * to the smart object of which @p obj is a member.
+ *
+ * If @p prop is false, events for which callbacks are set on the member
+ * object, @p obj, will not be passed on to the parent smart object.
+ *
+ * The default value is true.
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI void
evas_object_propagate_events_set(Evas_Object *obj, Evas_Bool prop)
@@ -1026,10 +1061,11 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Determine whether an object is set to propagate events.
+ * @param obj
+ * @return propogate events state
*
+ * @ingroup Evas_Object_Event_Flags_Group
*/
EAPI Evas_Bool
evas_object_propagate_events_get(Evas_Object *obj)
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_object_smart.c,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -3 -r1.25 -r1.26
--- evas_object_smart.c 15 Oct 2006 12:15:36 -0000 1.25
+++ evas_object_smart.c 8 Dec 2006 07:51:48 -0000 1.26
@@ -48,10 +48,23 @@
/* public funcs */
/**
- * To be documented.
+ * @defgroup Evas_Smart_Object_Group Evas Smart Object Functions
*
- * FIXME: To be fixed.
+ * Functions dealing with evas smart objects.
*
+ * Smart objects are groupings of primitive evas objects that behave as a
+ * cohesive group. For instance, a file manager icon may be a smart object
+ * composed of an image object, a text label and two rectangles that appear
+ * behind the image and text when the icon is selected. As a smart object,
+ * the normal evas api could be used on the icon object.
+ *
+ */
+/**
+ * Store a pointer to user data for a smart object.
+ *
+ * @param obj The smart object
+ * @param data A pointer to user data
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void
evas_object_smart_data_set(Evas_Object *obj, void *data)
@@ -69,10 +82,12 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Retrieve user data stored on a smart object.
*
+ * @param obj The smart object
+ * @return A pointer to data stored using evas_object_smart_data_set(), or
+ * NULL if none has been set.
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void *
evas_object_smart_data_get(Evas_Object *obj)
@@ -90,10 +105,11 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Get the Evas_Smart from which @p obj was created.
*
+ * @param obj a smart object
+ * @return the Evas_Smart
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI Evas_Smart *
evas_object_smart_smart_get(Evas_Object *obj)
@@ -111,10 +127,18 @@
}
/**
- * To be documented.
+ * Set an evas object as a member of a smart object.
*
- * FIXME: To be fixed.
+ * @param obj The member object
+ * @param smart_obj The smart object
*
+ * Members will automatically be stacked and layered with the smart object.
+ * The various stacking function will operate on members relative to the
+ * other members instead of the entire canvas.
+ *
+ * Non-member objects can not interleave a smart object's members.
+ *
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void
evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj)
@@ -160,9 +184,14 @@
}
/**
- * To be documented.
+ * Removes a member object from a smart object.
+ *
+ * @param obj the member object
+ * @ingroup Evas_Smart_Object_Group
*
- * FIXME: To be fixed.
+ * This removes a member object from a smart object. The object will still
+ * be on the canvas, but no longer associated with whichever smart object
+ * it was associated with.
*
*/
EAPI void
@@ -187,6 +216,7 @@
* Gets the smart parent of an Evas_Object
* @param obj the Evas_Object you want to get the parent
* @return Returns the smart parent of @a obj, or NULL if @a obj is not a
smart member of another Evas_Object
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI Evas_Object *
evas_object_smart_parent_get(Evas_Object *obj)
@@ -222,10 +252,12 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Instantiates a new smart object described by @p s.
*
+ * @param e the evas on which to add the object
+ * @param s the Evas_Smart describing the smart object
+ * @return a new Evas_Object
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI Evas_Object *
evas_object_smart_add(Evas *e, Evas_Smart *s)
@@ -254,10 +286,13 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Add a callback for the smart event specified by @p event.
*
+ * @param obj a smart object
+ * @param event the event name
+ * @param func the callback function
+ * @param data user data to be passed to the callback function
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void
evas_object_smart_callback_add(Evas_Object *obj, const char *event, void
(*func) (void *data, Evas_Object *obj, void *event_info), const void *data)
@@ -282,10 +317,15 @@
}
/**
- * To be documented.
+ * Remove a smart callback
*
- * FIXME: To be fixed.
+ * Removes a callback that was added by evas_object_smart_callback_add()
*
+ * @param obj a smart object
+ * @param event the event name
+ * @param func the callback function
+ * @return the data pointer
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void *
evas_object_smart_callback_del(Evas_Object *obj, const char *event, void
(*func) (void *data, Evas_Object *obj, void *event_info))
@@ -321,10 +361,17 @@
}
/**
- * To be documented.
+ * Call any smart callbacks on @p obj for @p event.
+ *
+ * @param obj the smart object
+ * @param event the event name
+ * @param event_info an event specific struct of info to pass to the callback
*
- * FIXME: To be fixed.
+ * This should be called internally in the smart object when some specific
+ * event has occured. The documentation for the smart object should include
+ * a list of possible events and what type of @p event_info to expect.
*
+ * @ingroup Evas_Smart_Object_Group
*/
EAPI void
evas_object_smart_callback_call(Evas_Object *obj, const char *event, void
*event_info)
@@ -437,7 +484,7 @@
static void
evas_object_smart_init(Evas_Object *obj)
{
- /* alloc image ob, setup methods and default values */
+ /* alloc smart obj, setup methods and default values */
obj->object_data = evas_object_smart_new();
/* set up default settings for this kind of object */
obj->cur.color.r = 255;
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_smart.c,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -3 -r1.13 -r1.14
--- evas_smart.c 2 Dec 2006 03:20:56 -0000 1.13
+++ evas_smart.c 8 Dec 2006 07:51:48 -0000 1.14
@@ -4,9 +4,39 @@
/* all public */
/**
- * To be documented.
+ * @defgroup Evas_Smart_Group Evas Smart Functions
*
- * FIXME: To be fixed.
+ * Functions that deal with Evas_Smart's.
+ *
+ */
+
+/**
+ * Create an Evas_Smart, which can be used to instantiate new smart objects.
+ *
+ * This function internally creates an Evas_Smart_Class and sets the
+ * provided callbacks. Callbacks that are unneeded (or marked DEPRECATED
+ * below) should be set to NULL.
+ *
+ * Alternatively you can create an Evas_Smart_Class yourself and use
+ * evas_smart_class_new().
+ *
+ * @param name a unique name for the smart
+ * @param func_add callback called when smart object is added
+ * @param func_del callback called when smart object is deleted
+ * @param func_layer_set DEPRECATED
+ * @param func_raise DEPRECATED
+ * @param func_lower DEPRECATED
+ * @param func_stack_above DEPRECATED
+ * @param func_stack_below DEPRECATED
+ * @param func_move callback called when smart object is moved
+ * @param func_resize callback called when smart object is resized
+ * @param func_show callback called when smart object is shown
+ * @param func_hide callback called when smart object is hidden
+ * @param func_color_set callback called when smart object has its color set
+ * @param func_clip_set callback called when smart object has its clip set
+ * @param func_clip_unset callback called when smart object has its clip unset
+ * @param data a pointer to user data for the smart
+ * @return an Evas_Smart
*
*/
EAPI Evas_Smart *
@@ -60,9 +90,12 @@
}
/**
- * To be documented.
+ * Free an Evas_Smart
*
- * FIXME: To be fixed.
+ * If this smart was created using evas_smart_class_new(), the associated
+ * Evas_Smart_Class will not be freed.
+ *
+ * @param s the Evas_Smart to free
*
*/
EAPI void
@@ -78,10 +111,10 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Creates an Evas_Smart from an Evas_Smart_Class.
*
+ * @param Evas_Smart_Class the smart class definition
+ * @return an Evas_Smart
*/
EAPI Evas_Smart *
evas_smart_class_new(Evas_Smart_Class *sc)
@@ -104,10 +137,10 @@
}
/**
- * To be documented.
- *
- * FIXME: To be fixed.
+ * Get the Evas_Smart_Class of an Evas_Smart
*
+ * @param s the Evas_Smart
+ * @return the Evas_Smart_Class
*/
EAPI Evas_Smart_Class *
evas_smart_class_get(Evas_Smart *s)
@@ -119,9 +152,13 @@
}
/**
- * To be documented.
+ * Get the data pointer set on an Evas_Smart.
+ *
+ * This data pointer is set either as the final parameter to
+ * evas_smart_new or as the data field in the Evas_Smart_Class passed
+ * in to evas_smart_class_new
*
- * FIXME: To be fixed.
+ * @param Evas_Smart
*
*/
EAPI void *
===================================================================
RCS file: /cvs/e/e17/libs/evas/src/lib/canvas/evas_stack.c,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -3 -r1.23 -r1.24
--- evas_stack.c 7 Jun 2006 23:30:14 -0000 1.23
+++ evas_stack.c 8 Dec 2006 07:51:48 -0000 1.24
@@ -41,9 +41,9 @@
}
/**
- * To be documented.
+ * Raise @p obj to the top of its layer.
*
- * FIXME: To be fixed.
+ * @param obj the object to raise
*
*/
EAPI void
@@ -100,9 +100,9 @@
}
/**
- * To be documented.
+ * Lower @p obj to the bottom of its layer.
*
- * FIXME: To be fixed.
+ * @param obj the object to lower
*
*/
EAPI void
@@ -159,9 +159,16 @@
}
/**
- * To be documented.
+ * Stack @p obj immediately above @p above
*
- * FIXME: To be fixed.
+ * If @p obj is a member of a smart object, then @p above must also be
+ * a member of the same smart object.
+ *
+ * Similarly, if @p obj is not a member of smart object, @p above may
+ * not either.
+ *
+ * @param obj the object to stack
+ * @param above the object above which to stack
*
*/
EAPI void
@@ -236,9 +243,16 @@
}
/**
- * To be documented.
+ * Stack @p obj immediately below @p below
+ *
+ * If @p obj is a member of a smart object, then @p below must also be
+ * a member of the same smart object.
+ *
+ * Similarly, if @p obj is not a member of smart object, @p below may
+ * not either.
*
- * FIXME: To be fixed.
+ * @param obj the object to stack
+ * @param below the object below which to stack
*
*/
EAPI void
@@ -313,9 +327,10 @@
}
/**
- * To be documented.
+ * Get the evas object above @p obj
*
- * FIXME: To be fixed.
+ * @param obj an Evas_Object
+ * @return the Evas_Object directly above
*
*/
EAPI Evas_Object *
@@ -344,9 +359,10 @@
}
/**
- * To be documented.
+ * Get the evas object below @p obj
*
- * FIXME: To be fixed.
+ * @param obj an Evas_Object
+ * @return the Evas_Object directly below
*
*/
EAPI Evas_Object *
@@ -375,9 +391,10 @@
}
/**
- * To be documented.
+ * Get the lowest evas object on the Evas @p e
*
- * FIXME: To be fixed.
+ * @param e an Evas
+ * @return the lowest object
*
*/
EAPI Evas_Object *
@@ -401,9 +418,10 @@
}
/**
- * To be documented.
+ * Get the highest evas object on the Evas @p e
*
- * FIXME: To be fixed.
+ * @param e an Evas
+ * @return the highest object
*
*/
EAPI Evas_Object *
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
enlightenment-cvs mailing list
enlightenment-cvs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
