-// 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
* 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
* 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.
* @{
*/
-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
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 <b>Double clicks</b> 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
*/
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
*/
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,
* 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
*
* @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
*
* @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
*/
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.
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.
*
*/
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.
*
* @ingroup Gengrid
*
*/
-//XXX: Does this API working well?
EAPI void elm_gengrid_filled_set(Evas_Object *obj, Eina_Bool fill);
/**
*
* @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);
+
+/**
* @}
*/
projects / framework / uifw / elementary.git / blobdiff