X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Flib%2Felm_gengrid.h;h=c88232a16b9861a2bab78358fd0dd460f82b6df3;hb=8b32f3712183fc44ce1f965e8a95069fe2bbc6cd;hp=bb454f905772a35bb1522ba234ff9e899433ec2e;hpb=ab7b3fc0b2d16e7d15ce0dccbcafdec1a583dd6b;p=framework%2Fuifw%2Felementary.git diff --git a/src/lib/elm_gengrid.h b/src/lib/elm_gengrid.h index bb454f9..c88232a 100644 --- a/src/lib/elm_gengrid.h +++ b/src/lib/elm_gengrid.h @@ -1,7 +1,6 @@ -// XXX: elm_gengrid - make sure api's match 1:1 with genlist api's -// for eventual move to back-end of gengrid == genlist (in grid mode) /** * @defgroup Gengrid Gengrid (Generic grid) + * @ingroup Elementary * * This widget aims to position objects in a grid layout while * actually creating and rendering only the visible ones, using the @@ -93,9 +92,9 @@ * of the state parts in the Edje group implementing the item's * theme. Return @c EINA_FALSE for false/off or @c EINA_TRUE for * true/on. Gengrids will emit a signal to its theming Edje object - * with @c "elm,state,XXX,active" and @c "elm" as "emission" and + * with @c "elm,state,xxx,active" and @c "elm" as "emission" and * "source" arguments, respectively, when the state is true (the - * default is false), where @c XXX is the name of the (state) part. + * default is false), where @c xxx is the name of the (state) part. * See #Elm_Gengrid_Item_State_Get_Cb. * - @c func.del - This is called when elm_object_item_del() is * called on an item or elm_gengrid_clear() is called on the @@ -131,8 +130,9 @@ * Grid cells will only have their selection smart callbacks called * when firstly getting selected. Any further clicks will do * nothing, unless you enable the "always select mode", with - * elm_gengrid_always_select_mode_set(), thus making every click to - * issue selection callbacks. elm_gengrid_no_select_mode_set() will + * elm_gengrid_select_mode_set() as ELM_OBJECT_SELECT_MODE_ALWAYS, + * thus making every click to issue selection callbacks. + * elm_gengrid_select_mode_set() as ELM_OBJECT_SELECT_MODE_NONE will * turn off the ability to select items entirely in the widget and * they will neither appear selected nor call the selection smart * callbacks. @@ -222,63 +222,47 @@ * @{ */ -typedef struct _Elm_Gengrid_Item_Class Elm_Gengrid_Item_Class; /**< Gengrid item class definition structs */ +#define ELM_GENGRID_ITEM_CLASS_VERSION ELM_GEN_ITEM_CLASS_VERSION +#define ELM_GENGRID_ITEM_CLASS_HEADER ELM_GEN_ITEM_CLASS_HEADER + +/** + * Defines where to position the item in the genlist. + * + * @ingroup Genlist + */ +typedef enum +{ + ELM_GENGRID_ITEM_SCROLLTO_NONE = 0, /**< no scrollto */ + ELM_GENGRID_ITEM_SCROLLTO_IN = (1 << 0), /**< to the nearest viewport */ + ELM_GENGRID_ITEM_SCROLLTO_TOP = (1 << 1), /**< to the top of viewport */ + ELM_GENGRID_ITEM_SCROLLTO_MIDDLE = (1 << 2) /**< to the middle of viewport */ +} Elm_Gengrid_Item_Scrollto_Type; -#define Elm_Gengrid_Item_Class Elm_Gen_Item_Class -typedef struct _Elm_Gengrid_Item_Class_Func Elm_Gengrid_Item_Class_Func; /**< Class functions for gengrid item classes. */ /** - * Text fetching class function for Elm_Gen_Item_Class. - * @param data The data passed in the item creation function - * @param obj The base widget object - * @param part The part name of the swallow - * @return The allocated (NOT stringshared) string to set as the text + * @see Elm_Gen_Item_Class */ -typedef char *(*Elm_Gengrid_Item_Text_Get_Cb)(void *data, Evas_Object *obj, const char *part); +typedef Elm_Gen_Item_Class Elm_Gengrid_Item_Class; /** - * Content (swallowed object) fetching class function for Elm_Gen_Item_Class. - * @param data The data passed in the item creation function - * @param obj The base widget object - * @param part The part name of the swallow - * @return The content object to swallow + * @see Elm_Gen_Item_Text_Get_Cb */ -typedef Evas_Object *(*Elm_Gengrid_Item_Content_Get_Cb)(void *data, Evas_Object *obj, const char *part); +typedef Elm_Gen_Item_Text_Get_Cb Elm_Gengrid_Item_Text_Get_Cb; /** - * State fetching class function for Elm_Gen_Item_Class. - * @param data The data passed in the item creation function - * @param obj The base widget object - * @param part The part name of the swallow - * @return The hell if I know + * @see Elm_Gen_Item_Content_Get_Cb */ -typedef Eina_Bool (*Elm_Gengrid_Item_State_Get_Cb)(void *data, Evas_Object *obj, const char *part); +typedef Elm_Gen_Item_Content_Get_Cb Elm_Gengrid_Item_Content_Get_Cb; /** - * Deletion class function for Elm_Gen_Item_Class. - * @param data The data passed in the item creation function - * @param obj The base widget object + * @see Elm_Gen_Item_State_Get_Cb */ -typedef void (*Elm_Gengrid_Item_Del_Cb)(void *data, Evas_Object *obj); +typedef Elm_Gen_Item_State_Get_Cb Elm_Gengrid_Item_State_Get_Cb; /** - * @struct _Elm_Gengrid_Item_Class - * - * Gengrid item class definition. See @ref Gengrid_Item_Class for - * field details. + * @see Elm_Gen_Item_Del_Cb */ -struct _Elm_Gengrid_Item_Class -{ - const char *item_style; - struct _Elm_Gengrid_Item_Class_Func - { - Elm_Gengrid_Item_Text_Get_Cb text_get; /**< Text fetching class function for gengrid item classes.*/ - Elm_Gengrid_Item_Content_Get_Cb content_get; /**< Content fetching class function for gengrid item classes. */ - Elm_Gengrid_Item_State_Get_Cb state_get; /**< State fetching class function for gengrid item classes. */ - Elm_Gengrid_Item_Del_Cb del; /**< Deletion class function for gengrid item classes. */ - } func; -}; /**< #Elm_Gengrid_Item_Class member definitions */ -#define Elm_Gengrid_Item_Class_Func Elm_Gen_Item_Class_Func +typedef Elm_Gen_Item_Del_Cb Elm_Gengrid_Item_Del_Cb; /** * Add a new gengrid widget to the given parent Elementary @@ -387,79 +371,6 @@ EAPI void elm_gengrid_horizontal_set(Evas_Object *obj, EAPI Eina_Bool elm_gengrid_horizontal_get(const Evas_Object *obj); /** - * Set whether items on a given gengrid widget are to get their - * selection callbacks issued for @b every subsequent selection - * click on them or just for the first click. - * - * @param obj The gengrid object - * @param always_select @c EINA_TRUE to make items "always - * selected", @c EINA_FALSE, otherwise - * - * By default, grid items will only call their selection callback - * function when firstly getting selected, any subsequent further - * clicks will do nothing. With this call, you make those - * subsequent clicks also to issue the selection callbacks. - * - * @note Double clicks will @b always be reported on items. - * - * @see elm_gengrid_always_select_mode_get() - * - * @ingroup Gengrid - */ -//XXX: How about elm_gengrid_select_mode_set() ? -EAPI void elm_gengrid_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select); - -/** - * Get whether items on a given gengrid widget have their selection - * callbacks issued for @b every subsequent selection click on them - * or just for the first click. - * - * @param obj The gengrid object. - * @return @c EINA_TRUE if the gengrid items are "always selected", - * @c EINA_FALSE, otherwise - * - * @see elm_gengrid_always_select_mode_set() for more details - * - * @ingroup Gengrid - */ -//XXX: How about elm_gengrid_select_mode_get() ? -EAPI Eina_Bool elm_gengrid_always_select_mode_get(const Evas_Object *obj); - -/** - * Set whether items on a given gengrid widget can be selected or not. - * - * @param obj The gengrid object - * @param no_select @c EINA_TRUE to make items selectable, - * @c EINA_FALSE otherwise - * - * This will make items in @p obj selectable or not. In the latter - * case, any user interaction on the gengrid items will neither make - * them appear selected nor them call their selection callback - * functions. - * - * @see elm_gengrid_no_select_mode_get() - * - * @ingroup Gengrid - */ -//XXX: elm_gengrid_always_select_mode_set and elm_gengrid_no_select_mode_set API could be merged to elm_genlist_select_mode_set() -EAPI void elm_gengrid_no_select_mode_set(Evas_Object *obj, Eina_Bool no_select); - -/** - * Get whether items on a given gengrid widget can be selected or - * not. - * - * @param obj The gengrid object - * @return @c EINA_TRUE, if items are selectable, @c EINA_FALSE - * otherwise - * - * @see elm_gengrid_no_select_mode_set() for more details - * - * @ingroup Gengrid - */ -//XXX: elm_gengrid_always_select_mode_get and elm_gengrid_no_select_mode_get API could be merged to elm_genlist_select_mode_get() -EAPI Eina_Bool elm_gengrid_no_select_mode_get(const Evas_Object *obj); - -/** * Enable or disable bouncing effect for a given gengrid widget * * @param obj The gengrid object @@ -647,8 +558,41 @@ EAPI Elm_Object_Item *elm_gengrid_selected_item_get(const Evas_Objec */ EAPI const Eina_List *elm_gengrid_selected_items_get(const Evas_Object *obj); -//XXX: let's add -//EAPI Eina_List *elm_gengrid_realized_items_get(const Evas_Object *obj); +/** + * Get a list of realized items in gengrid + * + * @param obj The gengrid object + * @return The list of realized items, nor NULL if none are realized. + * + * This returns a list of the realized items in the gengrid. The list + * contains gengrid item pointers. The list must be freed by the + * caller when done with eina_list_free(). The item pointers in the + * list are only valid so long as those items are not deleted or the + * gengrid is not deleted. + * + * @see elm_gengrid_realized_items_update() + * + * @ingroup Gengrid + */ +EAPI Eina_List *elm_gengrid_realized_items_get(const Evas_Object *obj); + +/** + * Update the contents of all realized items. + * + * @param obj The gengrid object. + * + * This updates all realized items by calling all the item class functions again + * to get the contents, texts and states. Use this when the original + * item data has changed and the changes are desired to be reflected. + * + * To update just one item, use elm_gengrid_item_update(). + * + * @see elm_gengrid_realized_items_get() + * @see elm_gengrid_item_update() + * + * @ingroup Gengrid + */ +EAPI void elm_gengrid_realized_items_update(Evas_Object *obj); /** * Get the first item in a given gengrid widget @@ -682,11 +626,39 @@ EAPI Elm_Object_Item *elm_gengrid_first_item_get(const Evas_Object * */ EAPI Elm_Object_Item *elm_gengrid_last_item_get(const Evas_Object *obj); -//XXX: let's add -//EAPI void elm_gengrid_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v); +/** + * Set the scrollbar policy + * + * @param obj The gengrid object + * @param policy_h Horizontal scrollbar policy. + * @param policy_v Vertical scrollbar policy. + * + * This sets the scrollbar visibility policy for the given gengrid + * scroller. #ELM_SCROLLER_POLICY_AUTO means the scrollbar is + * made visible if it is needed, and otherwise kept hidden. + * #ELM_SCROLLER_POLICY_ON turns it on all the time, and + * #ELM_SCROLLER_POLICY_OFF always keeps it off. This applies + * respectively for the horizontal and vertical scrollbars. Default is + * #ELM_SCROLLER_POLICY_AUTO + * + * @see elm_gengrid_scroller_policy_get() + * + * @ingroup Gengrid + */ +EAPI void elm_gengrid_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v); -//XXX: lets' add -//EAPI void elm_gengrid_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v); +/** + * Get the scrollbar policy + * + * @param obj The gengrid object + * @param policy_h Pointer to store the horizontal scrollbar policy. + * @param policy_v Pointer to store the vertical scrollbar policy. + * + * @see elm_gengrid_scroller_policy_set() + * + * @ingroup Gengrid + */ +EAPI void elm_gengrid_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v); /** * Get the @b next item in a gengrid widget's internal list of items, @@ -759,6 +731,7 @@ EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Objec * item, @b immediately. * * @param it The item to display + * @param type Where to position the item in the viewport. * * This causes gengrid to @b redraw its viewport's contents to the * region containing the given @p item item, if it is not fully @@ -768,13 +741,14 @@ EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Objec * * @ingroup Gengrid */ -EAPI void elm_gengrid_item_show(Elm_Object_Item *it); +EAPI void elm_gengrid_item_show(Elm_Object_Item *it, Elm_Gengrid_Item_Scrollto_Type type); /** * Animatedly bring in, to the visible area of a gengrid, a given * item on it. * * @param it The gengrid item to display + * @param type Where to position the item in the viewport. * * This causes gengrid to jump to the given @p item and show * it (by scrolling), if it is not fully visible. This will use @@ -784,13 +758,7 @@ EAPI void elm_gengrid_item_show(Elm_Object_Item *it); * * @ingroup Gengrid */ -EAPI void elm_gengrid_item_bring_in(Elm_Object_Item *it); - -//XXX: Let's add as possible -//EAPI void elm_gengrid_item_top_show(Elm_Object_Item *it); -//EAPI void elm_gengrid_item_top_bring_in(Elm_Object_Item *it); -//EAPI void elm_gengrid_item_middle_show(Elm_Object_Item *it); -//EAPI void elm_gengrid_item_middle_bring_in(Elm_Object_Item *it); +EAPI void elm_gengrid_item_bring_in(Elm_Object_Item *it, Elm_Gengrid_Item_Scrollto_Type type); /** * Update the contents of a given gengrid item @@ -832,19 +800,34 @@ EAPI void elm_gengrid_item_item_class_update(Elm_Object */ EAPI const Elm_Gengrid_Item_Class *elm_gengrid_item_item_class_get(const Elm_Object_Item *it); -//XXX: Let's add -//EAPI int elm_gengrid_item_index_get(const Elm_Object_Item *it); -//EAPI void elm_gengrid_realized_items_update(Evas_Object *obj); -//EAPI unsigned int elm_gengrid_items_count(const Evas_Object *obj); +/** + * Get the index of the item. It is only valid once displayed. + * + * @param it a gengrid item + * @return the position inside the list of item. + * + * @ingroup Gengrid + */ +EAPI int elm_gengrid_item_index_get(const Elm_Object_Item *it); -#define ELM_GENGRID_ITEM_CLASS_VERSION 2 /* current version number */ +/** + * Return how many items are currently in a list + * + * @param obj The list + * @return The total number of list items in the list + * + * This behavior is O(1) and includes items which may or may not be realized. + * + * @ingroup Gengrid + */ +EAPI unsigned int elm_gengrid_items_count(const Evas_Object *obj); /** * Add a new gengrid item class in a given gengrid widget. * * @return New allocated a gengrid item class. * - * This adds gengrid item class for the gengrid widget. When adding a item, + * This adds gengrid item class for the gengrid widget. When adding an item, * gengrid_item_{append, prepend, insert} function needs item class of the item. * Given callback parameters are used at retrieving {text, content} of * added item. Set as NULL if it's not used. @@ -858,7 +841,7 @@ EAPI const Elm_Gengrid_Item_Class *elm_gengrid_item_item_class_get(const Elm_Obj EAPI Elm_Gengrid_Item_Class *elm_gengrid_item_class_new(void); /** - * Remove a item class in a given gengrid widget. + * Remove an item class in a given gengrid widget. * * @param itc The itc to be removed. * @@ -902,8 +885,6 @@ EAPI void elm_gengrid_item_class_ref(Elm_Gengrid_Item_Class *itc); */ EAPI void elm_gengrid_item_class_unref(Elm_Gengrid_Item_Class *itc); -//XXX: Need to review tooltip & cursor APIs - /** * Set the text to be shown in a given gengrid item's tooltips. * @@ -1501,7 +1482,6 @@ EAPI void elm_gengrid_item_pos_get(const Elm_Object_Ite * @ingroup Gengrid * */ -//XXX: Does this API working well? EAPI void elm_gengrid_filled_set(Evas_Object *obj, Eina_Bool fill); /** @@ -1518,9 +1498,118 @@ EAPI void elm_gengrid_filled_set(Evas_Object *obj, Eina * * @ingroup Gengrid */ -//XXX: Does this API working well? EAPI Eina_Bool elm_gengrid_filled_get(const Evas_Object *obj); /** + * Set the gengrid select mode. + * + * @param obj The gengrid object + * @param mode The select mode + * + * elm_gengrid_select_mode_set() changes item select mode in the gengrid widget. + * - ELM_OBJECT_SELECT_MODE_DEFAULT : Items will only call their selection func and + * callback when first becoming selected. Any further clicks will + * do nothing, unless you set always select mode. + * - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, + * every click will make the selected callbacks be called. + * - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select items + * entirely and they will neither appear selected nor call selected + * callback functions. + * + * @see elm_gengrid_select_mode_get() + * + * @ingroup Gengrid + */ +EAPI void elm_gengrid_select_mode_set(Evas_Object *obj, Elm_Object_Select_Mode mode); + +/** + * Get the gengrid select mode. + * + * @param obj The gengrid object + * @return The select mode + * (If getting mode is failed, it returns ELM_OBJECT_SELECT_MODE_MAX) + * + * @see elm_gengrid_select_mode_set() + * + * @ingroup Gengrid + */ +EAPI Elm_Object_Select_Mode elm_gengrid_select_mode_get(const Evas_Object *obj); + +/** + * Set whether the gengrid items' should be highlighted when item selected. + * + * @param obj The gengrid object. + * @param highlight @c EINA_TRUE to enable highlight or @c EINA_FALSE to + * disable it. + * + * This will turn on/off the highlight effect when items are selected and + * they will or will not be highlighted. The selected and clicked + * callback functions will still be called. + * + * highlight is enabled by default. + * + * @see elm_gengrid_highlight_mode_get(). + * + * @ingroup Gengrid + */ + +EAPI void elm_gengrid_highlight_mode_set(Evas_Object *obj, Eina_Bool highlight); + +/** + * Get whether the gengrid items' should be highlighted when item selected. + * + * @param obj The gengrid object. + * @return @c EINA_TRUE means items can be highlighted. @c EINA_FALSE indicates + * they can't. If @p obj is @c NULL, @c EINA_FALSE is returned. + * + * @see elm_gengrid_highlight_mode_set() for details. + * + * @ingroup Gengrid + */ + +EAPI Eina_Bool elm_gengrid_highlight_mode_get(const Evas_Object *obj); + +/** + * Set the gengrid item's select mode. + * + * @param it The gengrid item object + * @param mode The select mode + * + * elm_gengrid_select_mode_set() changes item's select mode. + * - ELM_OBJECT_SELECT_MODE_DEFAULT : The item will only call their selection func and + * callback when first becoming selected. Any further clicks will + * do nothing, unless you set always select mode. + * - ELM_OBJECT_SELECT_MODE_ALWAYS : This means that, even if selected, + * every click will make the selected callbacks be called. + * - ELM_OBJECT_SELECT_MODE_NONE : This will turn off the ability to select the item + * entirely and they will neither appear selected nor call selected + * callback functions. + * - ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY : This will apply no-finger-size rule + * with ELM_OBJECT_SELECT_MODE_NONE. No-finger-size rule makes an item can be + * smaller than lower limit. Clickable objects should be bigger than + * human touch point device (your finger) for some touch or + * small screen devices. So it is enabled, the item can be shrink than + * predefined finger-size value. And the item will be updated. + * + * @see elm_gengrid_item_select_mode_get() + * + * @ingroup Gengrid + */ +EAPI void elm_gengrid_item_select_mode_set(Elm_Object_Item *it, Elm_Object_Select_Mode mode); + +/** + * Get the gengrid item's select mode. + * + * @param it The gengrid item object + * @return The select mode + * (If getting mode is failed, it returns ELM_OBJECT_SELECT_MODE_MAX) + * + * @see elm_gengrid_item_select_mode_set() + * + * @ingroup Gengrid + */ +EAPI Elm_Object_Select_Mode elm_gengrid_item_select_mode_get(const Elm_Object_Item *it); + +/** * @} */