From 5a8b288fe3357d64f95580b4ee141ebfd8a9565a Mon Sep 17 00:00:00 2001 From: Daniel Juyung Seo Date: Mon, 10 Jan 2011 05:39:13 +0000 Subject: [PATCH] From: Daniel Juyung Seo Subject: [E-devel] [Patch] elm_genlist doxygen fix and addition. I fixed some typos of Genlist doxygen and added more explanations. Please review this and apply this to upstream. SVN revision: 56017 --- legacy/elementary/src/lib/elm_genlist.c | 107 +++++++++++++----------- 1 file changed, 60 insertions(+), 47 deletions(-) diff --git a/legacy/elementary/src/lib/elm_genlist.c b/legacy/elementary/src/lib/elm_genlist.c index a5e886aac4..24351254ac 100644 --- a/legacy/elementary/src/lib/elm_genlist.c +++ b/legacy/elementary/src/lib/elm_genlist.c @@ -9,11 +9,11 @@ /** * @defgroup Genlist Genlist * - * The Aim was to have more expansive list that the simple list in + * The aim was to have more expansive list than the simple list in * Elementary that could have more flexible items and allow many more entries * while still being fast and low on memory usage. At the same time it was * also made to be able to do tree structures. But the price to pay is more - * complexity when it comes to usage. If all you want is a simple list with + * complex when it comes to usage. If all you want is a simple list with * icons and a single label, use the normal List object. * * Signals that you can add callbacks for are: @@ -27,7 +27,7 @@ * unselected - This is called when a user has made an item unselected. The * event_info parameter is the genlist item that was unselected. * - * expanded - This is called when elm_genlist_item_expanded_set() is called + * expanded - This is called when elm_genlist_item_expanded_set() is called * and the item is now meant to be expanded. The event_info parameter is the * genlist item that was indicated to expand. It is the job of this callback * to then fill in the child items. @@ -35,7 +35,7 @@ * contracted - This is called when elm_genlist_item_expanded_set() is called * and the item is now meant to be contracted. The event_info parameter is * the genlist item that was indicated to contract. It is the job of this - * callback to then delete the child items + * callback to then delete the child items. * * expand,request - This is called when a user has indicated they want to * expand a tree branch item. The callback should decide if the item can @@ -56,7 +56,7 @@ * where it may point to freed objects. * * unrealized - This is called just before an item is unrealized. After - * this call icon objects provideed will be deleted and the item object + * this call icon objects provided will be deleted and the item object * itself delete or be put into a floating cache. * * drag,start,up - This is called when the item in the list has been dragged @@ -111,7 +111,7 @@ * * Genlist has a fairly large API, mostly because it's relatively complex, * trying to be both expansive, powerful and efficient. First we will begin - * an overview o the theory behind genlist. + * an overview on the theory behind genlist. * * Evas tracks every object you create. Every time it processes an event * (mouse move, down, up etc.) it needs to walk through objects and find out @@ -146,8 +146,9 @@ * more icons (which are simply objects swallowed into the genlist item) and * 0 or more boolean states that can be used for check, radio or other * indicators by the edje theme style. An item may be one of several styles - * (Elementary provides 2 by default - “default” and “double_label”, but this - * can be extended by system or application custom themes/overlays/extensions). + * (Elementary provides 4 by default - “default”, “double_label”, "group_index" + * and "icon_top_text_bottom", but this can be extended by system or + * application custom themes/overlays/extensions). * * In order to implement the ability to add and delete items on the fly, * Genlist implements a class/callback system where the application provides @@ -176,7 +177,7 @@ * of the icon part in the edje design that is listed as one of the possible * icons that can be set. This must return NULL for no object or a valid * object. The object will be deleted by genlist on shutdown or when the item - * its unrealized. + * is unrealized. * * func.state_get - This function is called when an actual item object is * created. The data parameter is the data parameter passed to @@ -198,14 +199,16 @@ * handle that is an internal member inside the genlist. They all take a data * parameter that is meant to be used for a handle to the applications * internal data (eg the struct with the original item data). The parent - * parameter is the parent genlist item this belongs to if it is a tree, and - * NULL if there is no parent. The flags can be a bitmask of - * ELM_GENLIST_ITEM_NONE and ELM_GENLIST_ITEM_SUBITEMS. If - * ELM_GENLIST_ITEM_SUBITEMS is set then this item is displayed as a item - * that is able to expand and have child items. The func parameter is a + * parameter is the parent genlist item this belongs to if it is a tree or + * an indexed group, and NULL if there is no parent. The flags can be a bitmask + * of ELM_GENLIST_ITEM_NONE, ELM_GENLIST_ITEM_SUBITEMS and + * ELM_GENLIST_ITEM_GROUP. If ELM_GENLIST_ITEM_SUBITEMS is set then this item + * is displayed as an item that is able to expand and have child items. + * If ELM_GENLIST_ITEM_GROUP is set then this item is group idex item that is + * displayed at the top until the next group comes. The func parameter is a * convenience callback that is called when the item is selected and the data * parameter will be the func_data parameter, obj be the genlist object and - * vent_info will be the genlist item. + * event_info will be the genlist item. * * elm_genlist_item_append() appends an item to the end of the list, or if * there is a parent, to the end of all the child items of the parent. @@ -225,7 +228,7 @@ * will return the selected item, if any, or NULL I none is selected. If the * list is multi-select then elm_genlist_selected_items_get() will return a * list (that is only valid as long as no items are modified (added, deleted, - * selected or unselected). + * selected or unselected)). * * To help inspect list items you can jump to the item at the top of the list * with elm_genlist_first_item_get() which will return the item pointer, and @@ -238,7 +241,7 @@ * wanted). * * There are also convenience functions. elm_genlist_item_genlist_get() will - * return the genlist object the item belongs to. elm_genlist_item_show() + * return the genlist object the item belongs to. elm_genlist_item_show() * will make the scroller scroll to show that specific item so its visible. * elm_genlist_item_data_get() returns the data pointer set by the item * creation functions. @@ -250,7 +253,7 @@ * * To programmatically (un)select an item use elm_genlist_item_selected_set(). * To get its selected state use elm_genlist_item_selected_get(). Similarly - * to expand/contract and item and get its expanded state, use + * to expand/contract an item and get its expanded state, use * elm_genlist_item_expanded_set() and elm_genlist_item_expanded_get(). And * again to make an item disabled (unable to be selected and appear * differently) use elm_genlist_item_disabled_set() to set this and @@ -261,7 +264,7 @@ * ELM_LIST_LIMIT and ELM_LIST_SCROLL . The default is ELM_LIST_SCROLL. This * mode means that if items are too wide to fit, the scroller will scroll * horizontally. Otherwise items are expanded to fill the width of the - * viewport of the scroller. If it is ELM_LIST_LIMIT, Items will be expanded + * viewport of the scroller. If it is ELM_LIST_LIMIT, items will be expanded * to the viewport width and limited to that size. This can be combined with * a different style that uses edjes' ellipsis feature (cutting text off like * this: “tex...”). @@ -274,7 +277,7 @@ * items entirely and they will neither appear selected nor call selected * callback functions. * - * Remember that you can create new styles and add you own theme augmentation + * Remember that you can create new styles and add your own theme augmentation * per application with elm_theme_extension_add(). If you absolutely must * have a specific style that overrides any theme the user or system sets up * you can use elm_theme_overlay_add() to add such a file. @@ -2995,7 +2998,7 @@ elm_genlist_item_prepend(Evas_Object *obj, * Insert item before another in the genlist * * This inserts an item before another in the list. It will be in the - * same tree level as the item it is inseted before. + * same tree level or group as the item it is inseted before. * * @param obj The genlist object * @param itc The item class for the item @@ -3040,10 +3043,10 @@ elm_genlist_item_insert_before(Evas_Object *obj, } /** - * Insert and item after another in the genlst + * Insert an item after another in the genlst * * This inserts an item after another in the list. It will be in the - * same tree level as the item it is inseted after. + * same tree level or group as the item it is inseted after. * * @param obj The genlist object * @param itc The item class for the item @@ -3227,7 +3230,7 @@ elm_genlist_multi_select_get(const Evas_Object *obj) * * This gets the selected item in the list (if multi-select is enabled * only the first item in the list is selected - which is not very - * useful, so see elm_genlist_selected_items_get()for when + * useful, so see elm_genlist_selected_items_get() for when * multi-select is used). * * If no item is selected, NULL is returned. @@ -3250,7 +3253,7 @@ elm_genlist_selected_item_get(const Evas_Object *obj) /** * Get a list of selected items in the genlist * - * This retgurns a list of the selected items. This list pointer is + * This returns a list of the selected items. This list pointer is * only valid so long as no items are selected or unselected (or * unselected implicitly by deletion). The list contains * Elm_Genlist_Item pointers. @@ -3275,7 +3278,7 @@ elm_genlist_selected_items_get(const Evas_Object *obj) * This returns a list of the realized items in the genlist. The list * contains Elm_Genlist_Item pointers. The list must be freed by the * caller when done with eina_list_free(). The item pointers in the - * list are only vallid so long as those items are not deleted or the + * list are only valid so long as those items are not deleted or the * genlist is not deleted. * * @param obj The genlist object @@ -3494,7 +3497,7 @@ elm_genlist_item_genlist_get(const Elm_Genlist_Item *it) /** * Get the parent item of the given item * - * This returns the prent item of the item @p it given. + * This returns the parent item of the item @p it given. * * @param it The item * @return The parent of the item or NULL if none @@ -3538,7 +3541,7 @@ elm_genlist_item_subitems_clear(Elm_Genlist_Item *it) * item @p it. * * @param it The item - * @param selected The slected state + * @param selected The selected state * * @ingroup Genlist */ @@ -3587,7 +3590,7 @@ elm_genlist_item_selected_get(const Elm_Genlist_Item *it) /** * Sets the expanded state of an item (if it's a parent) * - * This expands or contracts a parent iterm (thus showing or hiding the + * This expands or contracts a parent item (thus showing or hiding the * children). * * @param it The item @@ -3680,7 +3683,7 @@ elm_genlist_item_disabled_set(Elm_Genlist_Item *it, /** * Get the disabled state of an item * - * This gets the disabld state of the given item. + * This gets the disabled state of the given item. * * @param it The item * @return The disabled state @@ -3969,7 +3972,8 @@ elm_genlist_item_middle_bring_in(Elm_Genlist_Item *it) * Delete a given item * * This deletes the item from genlist and calls the genlist item del - * class callback defined in the item class, if it is set. + * class callback defined in the item class, if it is set. This clears all + * subitems if it is a tree. * * @param it The item * @@ -4028,7 +4032,7 @@ elm_genlist_item_data_set(Elm_Genlist_Item *it, * Get the data item from the genlist item * * This returns the data value passed on the elm_genlist_item_append() - * and related item addition calls. + * and related item addition calls and elm_genlist_item_data_set(). * * @param it The item * @return The data pointer provided when created @@ -4071,14 +4075,14 @@ elm_genlist_item_icons_orphan(Elm_Genlist_Item *it) * Get the real evas object of the genlist item * * This returns the actual evas object used for the specified genlist - * item. This may be NULL as it may not be created, and ma be deleted + * item. This may be NULL as it may not be created, and may be deleted * at any time by genlist. Do not modify this object (move, resize, * show, hide etc.) as genlist is controlling it. This function is for * querying, emitting custom signals or hooking lower level callbacks * for events. Do not delete this object under any circumstances. * * @param it The item - * @return The objct pointer + * @return The object pointer * * @ingroup Genlist */ @@ -4181,11 +4185,11 @@ elm_genlist_item_tooltip_text_set(Elm_Genlist_Item *item, * * Setup the tooltip to item. The item can have only one tooltip, so * any previous tooltip data is removed. @p func(with @p data) will be - * called every time that need show the tooltip and it should return a + * called every time that need to show the tooltip and it should return a * valid Evas_Object. This object is then managed fully by tooltip * system and is deleted when the tooltip is gone. * - * @param item the genlist item being attached a tooltip. + * @param item the genlist item being attached by a tooltip. * @param func the function used to create the tooltip contents. * @param data what to provide to @a func as callback data/context. * @param del_cb called when data is not needed anymore, either when @@ -4459,7 +4463,7 @@ elm_genlist_horizontal_mode_set(Evas_Object *obj, * * @param obj The genlist object * @return The mode to use - * (ELM_LIST_LIMIT, ELM_LIST_SCROLL, ELM_LIST_LIMIT) + * (ELM_LIST_LIMIT, ELM_LIST_SCROLL) * * @ingroup Genlist */ @@ -4477,9 +4481,9 @@ elm_genlist_horizontal_mode_get(const Evas_Object *obj) * * Items will only call their selection func and callback when first * becoming selected. Any further clicks will do nothing, unless you - * enable always select with - * elm_genlist_always_select_mode_set(). This means even if selected, - * every click will make the selected callbacks be called. + * enable always select with elm_genlist_always_select_mode_set(). + * This means even if selected, every click will make the selected + * callbacks be called. * * @param obj The genlist object * @param always_select The always select mode @@ -4603,7 +4607,7 @@ elm_genlist_compress_mode_get(const Evas_Object *obj) * * With height-for-width mode the item width will be fixed (restricted * to a minimum of) to the list width when calculating its size in - * order to allow the height to be calculated based on it. This allow, + * order to allow the height to be calculated based on it. This allows, * for instance, text block to wrap lines if the Edje part is * configured with "text.min: 0 1". * @@ -4702,7 +4706,7 @@ elm_genlist_bounce_get(const Evas_Object *obj, * * This will enable the homogeneous mode where items are of the same * height and width so that genlist may do the lazy-loading at its - * maximum. This implies 'compressed' mode + * maximum. This implies 'compressed' mode. * * @param obj The genlist object * @param homogeneous Assume the items within the genlist are of the @@ -4818,17 +4822,17 @@ elm_genlist_longpress_timeout_get(const Evas_Object *obj) * Set the scrollbar policy * * This sets the scrollbar visibility policy for the given genlist - * scroller. ELM_SMART_SCROLLER_POLICY_AUTO means the scrollber is - * made visible if it is needed, and otherwise kept - * hidden. ELM_SMART_SCROLLER_POLICY_ON turns it on all the time, and - * ELM_SMART_SCROLLER_POLICY_OFF always keeps it off. This applies + * scroller. ELM_SMART_SCROLLER_POLICY_AUTO means the scrollbar is + * made visible if it is needed, and otherwise kept hidden. + * ELM_SMART_SCROLLER_POLICY_ON turns it on all the time, and + * ELM_SMART_SCROLLER_POLICY_OFF always keeps it off. This applies * respectively for the horizontal and vertical scrollbars. * * @param obj The genlist object * @param policy_h Horizontal scrollbar policy * @param policy_v Vertical scrollbar policy * - * @ingroup List + * @ingroup Genlist */ EAPI void elm_genlist_scroller_policy_set(Evas_Object *obj, @@ -4845,6 +4849,15 @@ elm_genlist_scroller_policy_set(Evas_Object *obj, elm_smart_scroller_policy_set(wd->scr, policy_h, policy_v); } +/** + * Get the scrollbar policy + * + * @param obj The genlist object + * @param policy_h Horizontal scrollbar policy + * @param policy_v Vertical scrollbar policy + * + * @ingroup Genlist + */ EAPI void elm_genlist_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h,