From 9c8855693dc200961cb7aa99d5aad065d06c71bd Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Sun, 31 May 2009 21:59:31 +0000 Subject: [PATCH] more... DOCS! SVN revision: 40868 --- src/lib/elc_anchorblock.c | 66 ++++++++++++ src/lib/elc_anchorview.c | 63 +++++++++++ src/lib/elc_hoversel.c | 113 ++++++++++++++++++++ src/lib/elm_genlist.c | 266 ++++++++++++++++++++++++++++++++-------------- 4 files changed, 426 insertions(+), 82 deletions(-) diff --git a/src/lib/elc_anchorblock.c b/src/lib/elc_anchorblock.c index e4a4e34..3e85e66 100644 --- a/src/lib/elc_anchorblock.c +++ b/src/lib/elc_anchorblock.c @@ -1,6 +1,20 @@ #include #include "elm_priv.h" +/** + * @defgroup Anchorblock Anchorblock + * + * Anchorblock is for displaying tet that contains markup with anchors like: + * \something\ in it. These will be drawn differently and will + * be able to be clicked on by the user to display a popup. This popup then + * is intended to contain extra options such as "call", "add to contacts", + * "open web page" etc. + * + * Signals that you can add callbacks for are: + * + * anchor,clicked - achor called was clicked. event_info is anchor info - + * Elm_Entry_Anchorview_Info + */ typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -119,6 +133,14 @@ _parent_del(void *data, Evas *e, Evas_Object *obj, void *event_info) wd->hover_parent = NULL; } +/** + * Add a new Anchorblock object + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * @ingroup Anchorblock + */ EAPI Evas_Object * elm_anchorblock_add(Evas_Object *parent) { @@ -152,6 +174,19 @@ elm_anchorblock_add(Evas_Object *parent) return obj; } +/** + * Set the text markup of the anchorblock + * + * This sets the text of the anchorblock to be the text given as @p text. This + * text is in markup format with \ beginning an achor with the + * string link of 'XXX', and \ or \ ending the link. Other markup can + * be used dependign on the style support. + * + * @param obj The anchorblock object + * @param text The text to set, or NULL to clear + * + * @ingroup Anchorblock + */ EAPI void elm_anchorblock_text_set(Evas_Object *obj, const char *text) { @@ -164,6 +199,17 @@ elm_anchorblock_text_set(Evas_Object *obj, const char *text) _sizing_eval(obj); } +/** + * Set the parent of the hover popup + * + * This sets the parent of the hover that anchorblock will create. See hover + * objects for more information on this. + * + * @param obj The anchorblock object + * @param parent The parent the hover should use + * + * @ingroup Anchorblock + */ EAPI void elm_anchorblock_hover_parent_set(Evas_Object *obj, Evas_Object *parent) { @@ -175,6 +221,17 @@ elm_anchorblock_hover_parent_set(Evas_Object *obj, Evas_Object *parent) evas_object_event_callback_add(wd->hover_parent, EVAS_CALLBACK_DEL, _parent_del, obj); } +/** + * Set the style that the hover should use + * + * This sets the style for the hover that anchorblock will create. See hover + * objects for more information + * + * @param obj The anchorblock object + * @param style The style to use + * + * @ingroup Anchorblock + */ EAPI void elm_anchorblock_hover_style_set(Evas_Object *obj, const char *style) { @@ -184,6 +241,15 @@ elm_anchorblock_hover_style_set(Evas_Object *obj, const char *style) if (style) wd->hover_style = eina_stringshare_add(style); } +/** + * Stop the hover popup in the anchorblock + * + * This will stop the hover popup in the anchorblock if it is currently active. + * + * @param obj The anchorblock object + * + * @ingroup Anchorblock + */ EAPI void elm_anchorblock_hover_end(Evas_Object *obj) { diff --git a/src/lib/elc_anchorview.c b/src/lib/elc_anchorview.c index d78e4c5..b6e3600 100644 --- a/src/lib/elc_anchorview.c +++ b/src/lib/elc_anchorview.c @@ -1,6 +1,17 @@ #include #include "elm_priv.h" +/** + * @defgroup Anchorview Anchorview + * + * This is just like the Anchorblock object, but provides a scroller to hold + * the text automatically. + * + * Signals that you can add callbacks for are: + * + * anchor,clicked - achor called was clicked. event_info is anchor info - + * Elm_Entry_Anchorview_Info + */ typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -108,6 +119,14 @@ _parent_del(void *data, Evas *e, Evas_Object *obj, void *event_info) wd->hover_parent = NULL; } +/** + * Add a new Anchorview object + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * @ingroup Anchorview + */ EAPI Evas_Object * elm_anchorview_add(Evas_Object *parent) { @@ -144,6 +163,19 @@ elm_anchorview_add(Evas_Object *parent) return obj; } +/** + * Set the text markup of the anchorview + * + * This sets the text of the anchorview to be the text given as @p text. This + * text is in markup format with \ beginning an achor with the + * string link of 'XXX', and \ or \ ending the link. Other markup can + * be used dependign on the style support. + * + * @param obj The anchorview object + * @param text The text to set, or NULL to clear + * + * @ingroup Anchorview + */ EAPI void elm_anchorview_text_set(Evas_Object *obj, const char *text) { @@ -156,6 +188,17 @@ elm_anchorview_text_set(Evas_Object *obj, const char *text) _sizing_eval(obj); } +/** + * Set the parent of the hover popup + * + * This sets the parent of the hover that anchorview will create. See hover + * objects for more information on this. + * + * @param obj The anchorview object + * @param parent The parent the hover should use + * + * @ingroup Anchorview + */ EAPI void elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent) { @@ -167,6 +210,17 @@ elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent) evas_object_event_callback_add(wd->hover_parent, EVAS_CALLBACK_DEL, _parent_del, obj); } +/** + * Set the style that the hover should use + * + * This sets the style for the hover that anchorview will create. See hover + * objects for more information + * + * @param obj The anchorview object + * @param style The style to use + * + * @ingroup Anchorview + */ EAPI void elm_anchorview_hover_style_set(Evas_Object *obj, const char *style) { @@ -176,6 +230,15 @@ elm_anchorview_hover_style_set(Evas_Object *obj, const char *style) if (style) wd->hover_style = eina_stringshare_add(style); } +/** + * Stop the hover popup in the anchorview + * + * This will stop the hover popup in the anchorview if it is currently active. + * + * @param obj The anchorview object + * + * @ingroup Anchorview + */ EAPI void elm_anchorview_hover_end(Evas_Object *obj) { diff --git a/src/lib/elc_hoversel.c b/src/lib/elc_hoversel.c index 02c7262..6a6e4e1 100644 --- a/src/lib/elc_hoversel.c +++ b/src/lib/elc_hoversel.c @@ -1,6 +1,24 @@ #include #include "elm_priv.h" +/** + * @defgroup Hoversel + * + * A hoversel is a button that pops up a list of items (automatically + * choosing the direction to display) that have a lable and/or an icon to + * select from. It is a convenience widget to avoid the need to do all the + * piecing together yourself. It is intended for a small numbr of items in + * the hoversel menu (no more than 8), though is capable of many more. + * + * Signals that you can add callbacks for are: + * + * clicked - the user clicked the hoversel button and popped up the sel + * + * selected - an item in the hoversel list is selected. event_info is the item + * selected - Elm_Hoversel_Item + * + * dismissed - the hover is dismissed + */ typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -149,6 +167,14 @@ _parent_del(void *data, Evas *e, Evas_Object *obj, void *event_info) wd->hover_parent = NULL; } +/** + * Add a new Hoversel object + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * @ingroup Hoversel + */ EAPI Evas_Object * elm_hoversel_add(Evas_Object *parent) { @@ -175,6 +201,16 @@ elm_hoversel_add(Evas_Object *parent) return obj; } +/** + * Set the Hover parent + * + * Sets the hover parent object. See Hover objects for more information. + * + * @param obj The hoversel object + * @param parent The parent to use + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent) { @@ -187,6 +223,17 @@ elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent) evas_object_event_callback_add(wd->hover_parent, EVAS_CALLBACK_DEL, _parent_del, obj); } +/** + * Set the hoversel button label + * + * This sets the label of the button that is always visible (before it is + * clicked and expanded). Also see elm_button_label_set(). + * + * @param obj The hoversel object + * @param label The label text. + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_label_set(Evas_Object *obj, const char *label) { @@ -195,6 +242,17 @@ elm_hoversel_label_set(Evas_Object *obj, const char *label) elm_button_label_set(wd->btn, label); } +/** + * Set the icon of the hoversel button + * + * Sets the icon of the button that is always visible (before it is clicked + * and expanded). Also see elm_button_icon_set(). + * + * @param obj The hoversel object + * @param icon The icon object + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_icon_set(Evas_Object *obj, Evas_Object *icon) { @@ -203,6 +261,15 @@ elm_hoversel_icon_set(Evas_Object *obj, Evas_Object *icon) elm_button_icon_set(wd->btn, icon); } +/** + * Trigger the hoversel popup from code + * + * This makes the hoversel popup activate with the items added being listed. + * + * @param obj The hoversel object + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_hover_begin(Evas_Object *obj) { @@ -212,6 +279,15 @@ elm_hoversel_hover_begin(Evas_Object *obj) _activate(obj); } +/** + * This ends the hoversel popup. + * + * This will close the hoversel popup, making it disappear, if it was active. + * + * @param obj The hoversel object + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_hover_end(Evas_Object *obj) { @@ -225,6 +301,22 @@ elm_hoversel_hover_end(Evas_Object *obj) } } +/** + * Add an item to the hoversel button + * + * This adds an item to the hoversel to show when it is clicked + * + * @param obj The hoversel object + * @param label The text abel to use for the item (NULL if not desired) + * @param icon_file A image file path on disk to use for the icon or standard + * icon name(NULL if not desired) + * @param icon_type The icon type if relevant + * @param func Convenience function to call when this item is selected + * @param data Data to pass to the conveience function + * @return A handle to the item added. + * + * @ingroup Hoversel + */ EAPI Elm_Hoversel_Item * elm_hoversel_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, void (*func) (void *data, Evas_Object *obj, void *event_info), const void *data) { @@ -242,6 +334,16 @@ elm_hoversel_item_add(Evas_Object *obj, const char *label, const char *icon_file return it; } +/** + * Delete an item from the hoversel + * + * This deletes the item from the hoversel (should not be called while the + * hoversel is active). + * + * @param it The item to delete + * + * @ingroup Hoversel + */ EAPI void elm_hoversel_item_del(Elm_Hoversel_Item *it) { @@ -254,6 +356,17 @@ elm_hoversel_item_del(Elm_Hoversel_Item *it) free(it); } +/** + * Get the data pointer passed to the item add function + * + * This returns the data pointer supplied with elm_hoversel_item_add() that + * will be passed to the select function callback. + * + * @param it The item to get the data from + * @return The data pointer set with elm_hoversel_item_add() + * + * @ingroup Hoversel + */ EAPI void * elm_hoversel_item_data_get(Elm_Hoversel_Item *it) { diff --git a/src/lib/elm_genlist.c b/src/lib/elm_genlist.c index d510298..c5fa10b 100644 --- a/src/lib/elm_genlist.c +++ b/src/lib/elm_genlist.c @@ -1307,10 +1307,19 @@ _item_queue(Widget_Data *wd, Elm_Genlist_Item *it) } /** - * XXX + * Append item to the end of the genlist * - * @param xxx XXX - * @return XXX + * This appends the given item to the end of the list or the end of the + * children if the parent is given. + * + * @param obj The genlist object + * @param itc The item class for the item + * @param data The item data + * @param parent The parent item, or NULL if none + * @param flags Item flags + * @param func Convenience function called when item selected + * @param func_data Data passed to @p func above. + * @return A handle to the item added or NULL if not possible * * @ingroup Genlist */ @@ -1346,10 +1355,19 @@ elm_genlist_item_append(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, } /** - * XXX + * Prepend item at start of the genlist * - * @param xxx XXX - * @return XXX + * This adds an item to the beginning of the list or beginning of the children + * of the parent if given. + * + * @param obj The genlist object + * @param itc The item class for the item + * @param data The item data + * @param parent The parent item, or NULL if none + * @param flags Item flags + * @param func Convenience function called when item selected + * @param func_data Data passed to @p func above. + * @return A handle to the item added or NULL if not possible * * @ingroup Genlist */ @@ -1375,10 +1393,19 @@ elm_genlist_item_prepend(Evas_Object *obj, const Elm_Genlist_Item_Class *itc, } /** - * XXX + * 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. * - * @param xxx XXX - * @return XXX + * @param obj The genlist object + * @param itc The item class for the item + * @param data The item data + * @param before The item to insert before + * @param flags Item flags + * @param func Convenience function called when item selected + * @param func_data Data passed to @p func above. + * @return A handle to the item added or NULL if not possible * * @ingroup Genlist */ @@ -1405,10 +1432,19 @@ elm_genlist_item_insert_before(Evas_Object *obj, const Elm_Genlist_Item_Class *i } /** - * XXX + * Insert and item after another in the genlst * - * @param xxx XXX - * @return XXX + * This inserts an item after another in the list. It will be in the same tree + * level as the item it is inseted after. + * + * @param obj The genlist object + * @param itc The item class for the item + * @param data The item data + * @param after The item to insert after + * @param flags Item flags + * @param func Convenience function called when item selected + * @param func_data Data passed to @p func above. + * @return A handle to the item added or NULL if not possible * * @ingroup Genlist */ @@ -1435,10 +1471,11 @@ elm_genlist_item_insert_after(Evas_Object *obj, const Elm_Genlist_Item_Class *it } /** - * XXX + * Clear the genlist * - * @param xxx XXX - * @return XXX + * This clears all items in the list, leaving it empty. + * + * @param obj The genlist object * * @ingroup Genlist */ @@ -1492,10 +1529,13 @@ elm_genlist_clear(Evas_Object *obj) } /** - * XXX + * Enable or disable multi-select in the genlist * - * @param xxx XXX - * @return XXX + * This enables (1) or disableds (0) multi-select in the list. This allows + * more than 1 item to be selected. + * + * @param obj The genlist object + * @param multi Multi-select enable/disable * * @ingroup Genlist */ @@ -1507,10 +1547,16 @@ elm_genlist_multi_select_set(Evas_Object *obj, Evas_Bool multi) } /** - * XXX + * Get the selectd item in the genlist * - * @param xxx XXX - * @return XXX + * 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 multi-select is used). + * + * If no item is selected, NULL is returned. + * + * @param obj The genlist object + * @return The selected item, or NULL if none. * * @ingroup Genlist */ @@ -1523,10 +1569,14 @@ elm_genlist_selected_item_get(const Evas_Object *obj) } /** - * XXX + * Get a list of selected items in the genlist * - * @param xxx XXX - * @return XXX + * This retgurns 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. + * + * @param obj The genlist object + * @return The list of selected items, nor NUL if none are selected. * * @ingroup Genlist */ @@ -1538,10 +1588,12 @@ elm_genlist_selected_items_get(const Evas_Object *obj) } /** - * XXX + * Get the first item in the genlist * - * @param xxx XXX - * @return XXX + * This returns the first item in the list. + * + * @param obj The genlist object + * @return The first item, or NULL if none * * @ingroup Genlist */ @@ -1556,10 +1608,11 @@ elm_genlist_first_item_get(const Evas_Object *obj) } /** - * XXX + * Get the last item in the genlist * - * @param xxx XXX - * @return XXX + * This returns the last item in the list. + * + * @return The last item, or NULL if none * * @ingroup Genlist */ @@ -1575,10 +1628,12 @@ elm_genlist_last_item_get(const Evas_Object *obj) } /** - * XXX + * Get the next item in the genlist * - * @param xxx XXX - * @return XXX + * This returns the item after the item @p it. + * + * @param it The item + * @return The item after @p it, or NULL if none * * @ingroup Genlist */ @@ -1594,10 +1649,12 @@ elm_genlist_item_next_get(const Elm_Genlist_Item *it) } /** - * XXX + * Get the previous item in the genlist * - * @param xxx XXX - * @return XXX + * This returns the item before the item @p it. + * + * @param it The item + * @return The item before @p it, or NULL if none * * @ingroup Genlist */ @@ -1613,10 +1670,12 @@ elm_genlist_item_prev_get(const Elm_Genlist_Item *it) } /** - * XXX + * Get the genlist object from an item * - * @param xxx XXX - * @return XXX + * This returns the genlist object itself that an item belongs to. + * + * @param it The item + * @return The genlist object * * @ingroup Genlist */ @@ -1628,10 +1687,12 @@ elm_genlist_item_genlist_get(const Elm_Genlist_Item *it) } /** - * XXX + * Get the parent item of the given item * - * @param xxx XXX - * @return XXX + * This returns the prent item of the item @p it given. + * + * @param it The item + * @return The parent of the item or NULL if none * * @ingroup Genlist */ @@ -1643,10 +1704,12 @@ elm_genlist_item_parent_get(const Elm_Genlist_Item *it) } /** - * XXX + * Clear all sub-items (children) of the given item + * + * This clears all items that are children (or their descendants) of the + * given item @p it. * - * @param xxx XXX - * @return XXX + * @param it The item * * @ingroup Genlist */ @@ -1664,10 +1727,13 @@ elm_genlist_item_subitems_clear(Elm_Genlist_Item *it) } /** - * XXX + * Set the selected state of an item + * + * This sets the selected state (1 selected, 0 not selected) of the given + * item @p it. * - * @param xxx XXX - * @return XXX + * @param it The item + * @param selcted The slected state * * @ingroup Genlist */ @@ -1696,10 +1762,12 @@ elm_genlist_item_selected_set(Elm_Genlist_Item *it, Evas_Bool selected) } /** - * XXX - * - * @param xxx XXX - * @return XXX + * Get the selected state of an item + * + * This gets the selected state of an item (1 selected, 0 not selected). + * + * @param it The item + * @return The selected state * * @ingroup Genlist */ @@ -1711,10 +1779,13 @@ elm_genlist_item_selected_get(const Elm_Genlist_Item *it) } /** - * XXX + * Sets the expanded state of an item (if it's a parent) + * + * This expands or contracts a parent iterm (thus showing or hiding the + * children). * - * @param xxx XXX - * @return XXX + * @param it The item + * @param expanded The expanded state (1 expanded, 0 not expanded). * * @ingroup Genlist */ @@ -1739,10 +1810,12 @@ elm_genlist_item_expanded_set(Elm_Genlist_Item *it, Evas_Bool expanded) } /** - * XXX + * Get the expanded state of an item * - * @param xxx XXX - * @return XXX + * This gets the expanded state of an item + * + * @param it The item + * @return Thre expanded state * * @ingroup Genlist */ @@ -1754,10 +1827,14 @@ elm_genlist_item_expanded_get(const Elm_Genlist_Item *it) } /** - * XXX + * Sets the disabled state of an item. + * + * A disabled item cannot be selected or unselected. It will also change + * appearance to appear disabled. This sets the disabled state (1 disabled, 0 + * not disabled). * - * @param xxx XXX - * @return XXX + * @param it The item + * @param disabled The disabled state * * @ingroup Genlist */ @@ -1778,10 +1855,12 @@ elm_genlist_item_disabled_set(Elm_Genlist_Item *it, Evas_Bool disabled) } /** - * XXX + * Get the disabled state of an item * - * @param xxx XXX - * @return XXX + * This gets the disabld state of the given item. + * + * @param it The item + * @return The disabled state * * @ingroup Genlist */ @@ -1794,10 +1873,12 @@ elm_genlist_item_disabled_get(const Elm_Genlist_Item *it) } /** - * XXX + * Show the given item * - * @param xxx XXX - * @return XXX + * This causes genlist to jump to the given item @p it and show it (by scrolling), + * if it is not fully visible. + * + * @param it The item * * @ingroup Genlist */ @@ -1855,10 +1936,13 @@ elm_genlist_item_del(Elm_Genlist_Item *it) } /** - * XXX + * Get the data item from the genlist item * - * @param xxx XXX - * @return XXX + * This returns the data value passed on the elm_genlist_item_append() and + * related item addition calls. + * + * @param it The item + * @return The data pointer provided when created * * @ingroup Genlist */ @@ -1869,10 +1953,13 @@ elm_genlist_item_data_get(const Elm_Genlist_Item *it) } /** - * XXX + * Update the contents of an item * - * @param xxx XXX - * @return XXX + * This updates an item by calling all the item class functions again to get + * the icons, labels and states. Use this when he original item data has + * changed and the changes are desired to be reflected. + * + * @param it The item * * @ingroup Genlist */ @@ -1921,10 +2008,17 @@ elm_genlist_item_update(Elm_Genlist_Item *it) } /** - * XXX + * This sets the horizontal stretching mode * - * @param xxx XXX - * @return XXX + * This sets the mode used for sizing items horizontally. Valid modes are + * 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 + * to the viewport width and limited to that size. + * + * @param obj The genlist object + * @param mode The mode to use * * @ingroup Genlist */ @@ -1941,10 +2035,15 @@ elm_genlist_horizontal_mode_set(Evas_Object *obj, Elm_List_Mode mode) } /** - * XXX + * Set the always select mode. + * + * 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. * - * @param xxx XXX - * @return XXX + * @param obj The genlist object + * @param always_select The always select mode (1 on, 2 off) * * @ingroup Genlist */ @@ -1956,10 +2055,13 @@ elm_genlist_always_select_mode_set(Evas_Object *obj, Evas_Bool always_select) } /** - * XXX + * Set no select mode * - * @param xxx XXX - * @return XXX + * This will turn off the ability to select items entirely and they will + * neither appear selected nor call selected callback functions. + * + * @param obj The genlist object + * @param no_select The no select mode (1 on, 2 off) * * @ingroup Genlist */ -- 2.7.4