From 5a4cffcf908e8b3fb48bb60a9f342b84506a42c2 Mon Sep 17 00:00:00 2001 From: rephorm Date: Fri, 8 Dec 2006 07:51:48 +0000 Subject: [PATCH] add some documentation SVN revision: 27380 --- legacy/evas/src/lib/canvas/evas_events.c | 68 ++++++++++---- .../evas/src/lib/canvas/evas_object_smart.c | 93 ++++++++++++++----- legacy/evas/src/lib/canvas/evas_smart.c | 61 +++++++++--- legacy/evas/src/lib/canvas/evas_stack.c | 50 ++++++---- 4 files changed, 205 insertions(+), 67 deletions(-) diff --git a/legacy/evas/src/lib/canvas/evas_events.c b/legacy/evas/src/lib/canvas/evas_events.c index 8b9f1ddce6..edbea9fa70 100644 --- a/legacy/evas/src/lib/canvas/evas_events.c +++ b/legacy/evas/src/lib/canvas/evas_events.c @@ -114,7 +114,7 @@ evas_event_list_copy(Evas_List *list) */ /** - * 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 @@ evas_event_feed_key_up(Evas *e, const char *keyname, const char *key, const char } /** - * 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 @@ evas_object_pass_events_set(Evas_Object *obj, Evas_Bool pass) } /** - * 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 @@ evas_object_pass_events_get(Evas_Object *obj) } /** - * To be documented. + * Set an object's repeat events state. + * @param obj the object + * @param repeat wheter to repeat events or not * - * FIXME: To be fixed. + * 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. * + * 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 @@ evas_object_repeat_events_set(Evas_Object *obj, Evas_Bool repeat) } /** - * 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 @@ evas_object_repeat_events_get(Evas_Object *obj) } /** - * 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 @@ evas_object_propagate_events_set(Evas_Object *obj, Evas_Bool prop) } /** - * 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) diff --git a/legacy/evas/src/lib/canvas/evas_object_smart.c b/legacy/evas/src/lib/canvas/evas_object_smart.c index cc57b202a0..7a9224ac90 100644 --- a/legacy/evas/src/lib/canvas/evas_object_smart.c +++ b/legacy/evas/src/lib/canvas/evas_object_smart.c @@ -48,10 +48,23 @@ static Evas_Object_Func object_func = /* 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 @@ evas_object_smart_data_set(Evas_Object *obj, void *data) } /** - * 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 @@ evas_object_smart_data_get(Evas_Object *obj) } /** - * 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 @@ evas_object_smart_smart_get(Evas_Object *obj) } /** - * 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 @@ evas_object_smart_member_add(Evas_Object *obj, Evas_Object *smart_obj) } /** - * To be documented. + * Removes a member object from a smart object. * - * FIXME: To be fixed. + * @param obj the member object + * @ingroup Evas_Smart_Object_Group + * + * 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 @@ evas_object_smart_member_del(Evas_Object *obj) * 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 @@ evas_object_smart_members_get(Evas_Object *obj) } /** - * 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 @@ evas_object_smart_add(Evas *e, Evas_Smart *s) } /** - * 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 @@ evas_object_smart_callback_add(Evas_Object *obj, const char *event, void (*func) } /** - * 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 @@ evas_object_smart_callback_del(Evas_Object *obj, const char *event, void (*func) } /** - * To be documented. + * Call any smart callbacks on @p obj for @p event. * - * FIXME: To be fixed. + * @param obj the smart object + * @param event the event name + * @param event_info an event specific struct of info to pass to the callback * + * 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 @@ evas_object_smart_member_cache_invalidate(Evas_Object *obj) 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; diff --git a/legacy/evas/src/lib/canvas/evas_smart.c b/legacy/evas/src/lib/canvas/evas_smart.c index b3a0c5f7b2..2ecc0134cf 100644 --- a/legacy/evas/src/lib/canvas/evas_smart.c +++ b/legacy/evas/src/lib/canvas/evas_smart.c @@ -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 @@ evas_smart_new(const char *name, } /** - * 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 @@ evas_smart_free(Evas_Smart *s) } /** - * 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 @@ evas_smart_class_new(Evas_Smart_Class *sc) } /** - * 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 @@ evas_smart_class_get(Evas_Smart *s) } /** - * To be documented. + * Get the data pointer set on an Evas_Smart. * - * FIXME: To be fixed. + * 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 + * + * @param Evas_Smart * */ EAPI void * diff --git a/legacy/evas/src/lib/canvas/evas_stack.c b/legacy/evas/src/lib/canvas/evas_stack.c index 024a805b55..994d8d9838 100644 --- a/legacy/evas/src/lib/canvas/evas_stack.c +++ b/legacy/evas/src/lib/canvas/evas_stack.c @@ -41,9 +41,9 @@ evas_object_below_get_internal(Evas_Object *obj) } /** - * 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 @@ evas_object_raise(Evas_Object *obj) } /** - * 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 @@ evas_object_lower(Evas_Object *obj) } /** - * 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 @@ evas_object_stack_above(Evas_Object *obj, Evas_Object *above) } /** - * To be documented. + * Stack @p obj immediately below @p below * - * FIXME: To be fixed. + * 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. + * + * @param obj the object to stack + * @param below the object below which to stack * */ EAPI void @@ -313,9 +327,10 @@ evas_object_stack_below(Evas_Object *obj, Evas_Object *below) } /** - * 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 @@ evas_object_above_get(Evas_Object *obj) } /** - * 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 @@ evas_object_below_get(Evas_Object *obj) } /** - * 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 @@ evas_object_bottom_get(Evas *e) } /** - * 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 *