EAPI Evas_Object *elm_gengrid_add(Evas_Object *parent);
/**
- * Set the size for the items of a given gengrid widget
+ * Remove all items from a given gengrid widget
*
* @param obj The gengrid object.
- * @param w The items' width.
- * @param h The items' height;
*
- * A gengrid, after creation, has still no information on the size
- * to give to each of its cells. So, you most probably will end up
- * with squares one @ref Fingers "finger" wide, the default
- * size. Use this function to force a custom size for you items,
- * making them as big as you wish.
+ * This removes (and deletes) all items in @p obj, leaving it
+ * empty.
*
- * @see elm_gengrid_item_size_get()
+ * @see elm_object_item_del(), to remove just one item.
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
+EAPI void elm_gengrid_clear(Evas_Object *obj);
/**
- * Get the size set for the items of a given gengrid widget
+ * Enable or disable multi-selection in a given gengrid widget
*
* @param obj The gengrid object.
- * @param w Pointer to a variable where to store the items' width.
- * @param h Pointer to a variable where to store the items' height.
+ * @param multi @c EINA_TRUE, to enable multi-selection,
+ * @c EINA_FALSE to disable it.
*
- * @note Use @c NULL pointers on the size values you're not
- * interested in: they'll be ignored by the function.
+ * Multi-selection is the ability to have @b more than one
+ * item selected, on a given gengrid, simultaneously. When it is
+ * enabled, a sequence of clicks on different items will make them
+ * all selected, progressively. A click on an already selected item
+ * will unselect it. If interacting via the keyboard,
+ * multi-selection is enabled while holding the "Shift" key.
*
- * @see elm_gengrid_item_size_get() for more details
+ * @note By default, multi-selection is @b disabled on gengrids
+ *
+ * @see elm_gengrid_multi_select_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
+EAPI void elm_gengrid_multi_select_set(Evas_Object *obj, Eina_Bool multi);
/**
- * Set the size for the group items of a given gengrid widget
+ * Get whether multi-selection is enabled or disabled for a given
+ * gengrid widget
*
* @param obj The gengrid object.
- * @param w The group items' width.
- * @param h The group items' height;
- *
- * A gengrid, after creation, has still no information on the size
- * to give to each of its cells. So, you most probably will end up
- * with squares one @ref Fingers "finger" wide, the default
- * size. Use this function to force a custom size for you group items,
- * making them as big as you wish.
+ * @return @c EINA_TRUE, if multi-selection is enabled, @c
+ * EINA_FALSE otherwise
*
- * @see elm_gengrid_group_item_size_get()
+ * @see elm_gengrid_multi_select_set() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_group_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
+EAPI Eina_Bool elm_gengrid_multi_select_get(const Evas_Object *obj);
/**
- * Get the size set for the group items of a given gengrid widget
+ * Set the direction in which a given gengrid widget will expand while
+ * placing its items.
*
* @param obj The gengrid object.
- * @param w Pointer to a variable where to store the group items' width.
- * @param h Pointer to a variable where to store the group items' height.
+ * @param horizontal @c EINA_TRUE to make the gengrid expand
+ * horizontally, @c EINA_FALSE to expand vertically.
*
- * @note Use @c NULL pointers on the size values you're not
- * interested in: they'll be ignored by the function.
+ * When in "horizontal mode" (@c EINA_TRUE), items will be placed
+ * in @b columns, from top to bottom and, when the space for a
+ * column is filled, another one is started on the right, thus
+ * expanding the grid horizontally. When in "vertical mode"
+ * (@c EINA_FALSE), though, items will be placed in @b rows, from left
+ * to right and, when the space for a row is filled, another one is
+ * started below, thus expanding the grid vertically.
*
- * @see elm_gengrid_group_item_size_get() for more details
+ * @see elm_gengrid_horizontal_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_group_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
+EAPI void elm_gengrid_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
/**
- * Set the items grid's alignment within a given gengrid widget
+ * Get for what direction a given gengrid widget will expand while
+ * placing its items.
*
* @param obj The gengrid object.
- * @param align_x Alignment in the horizontal axis (0 <= align_x <= 1).
- * @param align_y Alignment in the vertical axis (0 <= align_y <= 1).
+ * @return @c EINA_TRUE, if @p obj is set to expand horizontally,
+ * @c EINA_FALSE if it's set to expand vertically.
*
- * This sets the alignment of the whole grid of items of a gengrid
- * within its given viewport. By default, those values are both
- * 0.5, meaning that the gengrid will have its items grid placed
- * exactly in the middle of its viewport.
+ * @see elm_gengrid_horizontal_set() for more details
*
- * @note If given alignment values are out of the cited ranges,
- * they'll be changed to the nearest boundary values on the valid
- * ranges.
+ * @ingroup Gengrid
+ */
+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.
*
- * @see elm_gengrid_align_get()
+ * @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
*/
-EAPI void elm_gengrid_align_set(Evas_Object *obj, double align_x, double align_y);
+//XXX: How about elm_gengrid_select_mode_set() ?
+EAPI void elm_gengrid_always_select_mode_set(Evas_Object *obj, Eina_Bool always_select);
/**
- * Get the items grid's alignment values within a given gengrid
- * widget
+ * 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.
- * @param align_x Pointer to a variable where to store the
- * horizontal alignment.
- * @param align_y Pointer to a variable where to store the vertical
- * alignment.
+ * @return @c EINA_TRUE if the gengrid items are "always selected",
+ * @c EINA_FALSE, otherwise
*
- * @note Use @c NULL pointers on the alignment values you're not
- * interested in: they'll be ignored by the function.
+ * @see elm_gengrid_always_select_mode_set() for more details
*
- * @see elm_gengrid_align_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
*/
-EAPI void elm_gengrid_align_get(const Evas_Object *obj, double *align_x, double *align_y);
+//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);
/**
- * Set whether a given gengrid widget is or not able have items
- * @b reordered
+ * Get whether items on a given gengrid widget can be selected or
+ * not.
*
* @param obj The gengrid object
- * @param reorder_mode Use @c EINA_TRUE to turn reordering on,
- * @c EINA_FALSE to turn it off
+ * @return @c EINA_TRUE, if items are selectable, @c EINA_FALSE
+ * otherwise
*
- * If a gengrid is set to allow reordering, a click held for more
- * than 0.5 over a given item will highlight it specially,
- * signaling the gengrid has entered the reordering state. From
- * that time on, the user will be able to, while still holding the
- * mouse button down, move the item freely in the gengrid's
- * viewport, replacing to said item to the locations it goes to.
- * The replacements will be animated and, whenever the user
- * releases the mouse button, the item being replaced gets a new
- * definitive place in the grid.
+ * @see elm_gengrid_no_select_mode_set() for more details
*
- * @see elm_gengrid_reorder_mode_get()
+ * @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
+ * @param h_bounce @c EINA_TRUE, to enable @b horizontal bouncing,
+ * @c EINA_FALSE to disable it
+ * @param v_bounce @c EINA_TRUE, to enable @b vertical bouncing,
+ * @c EINA_FALSE to disable it
+ *
+ * The bouncing effect occurs whenever one reaches the gengrid's
+ * edge's while panning it -- it will scroll past its limits a
+ * little bit and return to the edge again, in a animated for,
+ * automatically.
+ *
+ * @note By default, gengrids have bouncing enabled on both axis
+ *
+ * @see elm_gengrid_bounce_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode);
+EAPI void elm_gengrid_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
/**
- * Get whether a given gengrid widget is or not able have items
- * @b reordered
+ * Get whether bouncing effects are enabled or disabled, for a
+ * given gengrid widget, on each axis
*
* @param obj The gengrid object
- * @return @c EINA_TRUE, if reordering is on, @c EINA_FALSE if it's
- * off
+ * @param h_bounce Pointer to a variable where to store the
+ * horizontal bouncing flag.
+ * @param v_bounce Pointer to a variable where to store the
+ * vertical bouncing flag.
*
- * @see elm_gengrid_reorder_mode_set() for more details
+ * @see elm_gengrid_bounce_set() for more details
*
* @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_reorder_mode_get(const Evas_Object *obj);
+EAPI void elm_gengrid_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
/**
* Append a new item in a given gengrid widget.
EAPI Elm_Object_Item *elm_gengrid_item_sorted_insert(Evas_Object *obj, const Elm_Gengrid_Item_Class *gic, const void *data, Eina_Compare_Cb comp, Evas_Smart_Cb func, const void *func_data);
/**
- * 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.
+ * Get the selected item in a given gengrid widget
*
- * @note <b>Double clicks</b> will @b always be reported on items.
+ * @param obj The gengrid object.
+ * @return The selected item's handle or @c NULL, if none is
+ * selected at the moment (and on errors)
*
- * @see elm_gengrid_always_select_mode_get()
+ * This returns the selected item in @p obj. If multi selection is
+ * enabled on @p obj (@see elm_gengrid_multi_select_set()), only
+ * the first item in the list is selected, which might not be very
+ * useful. For that case, see elm_gengrid_selected_items_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);
+EAPI Elm_Object_Item *elm_gengrid_selected_item_get(const Evas_Object *obj);
/**
- * 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.
+ * Get <b>a list</b> of selected items in a given gengrid
*
* @param obj The gengrid object.
- * @return @c EINA_TRUE if the gengrid items are "always selected",
- * @c EINA_FALSE, otherwise
+ * @return The list of selected items or @c NULL, if none is
+ * selected at the moment (and on errors)
*
- * @see elm_gengrid_always_select_mode_set() for more details
+ * This returns a list of the selected items, in the order that
+ * they appear in the grid. This list is only valid as long as no
+ * more items are selected or unselected (or unselected implicitly
+ * by deletion). The list contains #Gengrid item pointers as
+ * data, naturally.
+ *
+ * @see elm_gengrid_selected_item_get()
*
* @ingroup Gengrid
*/
-//XXX: How about elm_gengrid_select_mode_get() ?
-EAPI Eina_Bool elm_gengrid_always_select_mode_get(const Evas_Object *obj);
+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);
/**
- * Set whether items on a given gengrid widget can be selected or not.
+ * Get the first item in a given gengrid widget
*
* @param obj The gengrid object
- * @param no_select @c EINA_TRUE to make items selectable,
- * @c EINA_FALSE otherwise
+ * @return The first item's handle or @c NULL, if there are no
+ * items in @p obj (and on errors)
*
- * 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.
+ * This returns the first item in the @p obj's internal list of
+ * items.
*
- * @see elm_gengrid_no_select_mode_get()
+ * @see elm_gengrid_last_item_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);
+EAPI Elm_Object_Item *elm_gengrid_first_item_get(const Evas_Object *obj);
/**
- * Get whether items on a given gengrid widget can be selected or
- * not.
+ * Get the last item in a given gengrid widget
*
* @param obj The gengrid object
- * @return @c EINA_TRUE, if items are selectable, @c EINA_FALSE
- * otherwise
+ * @return The last item's handle or @c NULL, if there are no
+ * items in @p obj (and on errors)
*
- * @see elm_gengrid_no_select_mode_set() for more details
+ * This returns the last item in the @p obj's internal list of
+ * items.
+ *
+ * @see elm_gengrid_first_item_get()
*
* @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);
+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);
+
+//XXX: lets' add
+//EAPI void elm_gengrid_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
/**
- * Enable or disable multi-selection in a given gengrid widget
- *
- * @param obj The gengrid object.
- * @param multi @c EINA_TRUE, to enable multi-selection,
- * @c EINA_FALSE to disable it.
+ * Get the @b next item in a gengrid widget's internal list of items,
+ * given a handle to one of those items.
*
- * Multi-selection is the ability to have @b more than one
- * item selected, on a given gengrid, simultaneously. When it is
- * enabled, a sequence of clicks on different items will make them
- * all selected, progressively. A click on an already selected item
- * will unselect it. If interacting via the keyboard,
- * multi-selection is enabled while holding the "Shift" key.
+ * @param it The gengrid item to fetch next from
+ * @return The item after @p item, or @c NULL if there's none (and
+ * on errors)
*
- * @note By default, multi-selection is @b disabled on gengrids
+ * This returns the item placed after the @p item, on the container
+ * gengrid.
*
- * @see elm_gengrid_multi_select_get()
+ * @see elm_gengrid_item_prev_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_multi_select_set(Evas_Object *obj, Eina_Bool multi);
+EAPI Elm_Object_Item *elm_gengrid_item_next_get(const Elm_Object_Item *it);
/**
- * Get whether multi-selection is enabled or disabled for a given
- * gengrid widget
+ * Get the @b previous item in a gengrid widget's internal list of items,
+ * given a handle to one of those items.
*
- * @param obj The gengrid object.
- * @return @c EINA_TRUE, if multi-selection is enabled, @c
- * EINA_FALSE otherwise
+ * @param it The gengrid item to fetch previous from
+ * @return The item before @p item, or @c NULL if there's none (and
+ * on errors)
*
- * @see elm_gengrid_multi_select_set() for more details
+ * This returns the item placed before the @p item, on the container
+ * gengrid.
+ *
+ * @see elm_gengrid_item_next_get()
*
* @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_multi_select_get(const Evas_Object *obj);
+EAPI Elm_Object_Item *elm_gengrid_item_prev_get(const Elm_Object_Item *it);
/**
- * Enable or disable bouncing effect for a given gengrid widget
- *
- * @param obj The gengrid object
- * @param h_bounce @c EINA_TRUE, to enable @b horizontal bouncing,
- * @c EINA_FALSE to disable it
- * @param v_bounce @c EINA_TRUE, to enable @b vertical bouncing,
- * @c EINA_FALSE to disable it
+ * Set whether a given gengrid item is selected or not
*
- * The bouncing effect occurs whenever one reaches the gengrid's
- * edge's while panning it -- it will scroll past its limits a
- * little bit and return to the edge again, in a animated for,
- * automatically.
+ * @param it The gengrid item
+ * @param selected Use @c EINA_TRUE, to make it selected, @c
+ * EINA_FALSE to make it unselected
*
- * @note By default, gengrids have bouncing enabled on both axis
+ * This sets the selected state of an item. If multi-selection is
+ * not enabled on the containing gengrid and @p selected is @c
+ * EINA_TRUE, any other previously selected items will get
+ * unselected in favor of this new one.
*
- * @see elm_gengrid_bounce_get()
+ * @see elm_gengrid_item_selected_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
+EAPI void elm_gengrid_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
/**
- * Get whether bouncing effects are enabled or disabled, for a
- * given gengrid widget, on each axis
+ * Get whether a given gengrid item is selected or not
*
- * @param obj The gengrid object
- * @param h_bounce Pointer to a variable where to store the
- * horizontal bouncing flag.
- * @param v_bounce Pointer to a variable where to store the
- * vertical bouncing flag.
+ * @param it The gengrid item
+ * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
*
- * @see elm_gengrid_bounce_set() for more details
+ * This API returns EINA_TRUE for all the items selected in multi-select mode as well.
+ *
+ * @see elm_gengrid_item_selected_set() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
+EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Object_Item *it);
/**
- * Set a given gengrid widget's scrolling page size, relative to
- * its viewport size.
- *
- * @param obj The gengrid object
- * @param h_pagerel The horizontal page (relative) size
- * @param v_pagerel The vertical page (relative) size
- *
- * The gengrid's scroller is capable of binding scrolling by the
- * user to "pages". It means that, while scrolling and, specially
- * after releasing the mouse button, the grid will @b snap to the
- * nearest displaying page's area. When page sizes are set, the
- * grid's continuous content area is split into (equal) page sized
- * pieces.
+ * Show the portion of a gengrid's internal grid containing a given
+ * item, @b immediately.
*
- * This function sets the size of a page <b>relatively to the
- * viewport dimensions</b> of the gengrid, for each axis. A value
- * @c 1.0 means "the exact viewport's size", in that axis, while @c
- * 0.0 turns paging off in that axis. Likewise, @c 0.5 means "half
- * a viewport". Sane usable values are, than, between @c 0.0 and @c
- * 1.0. Values beyond those will make it behave behave
- * inconsistently. If you only want one axis to snap to pages, use
- * the value @c 0.0 for the other one.
+ * @param it The item to display
*
- * There is a function setting page size values in @b absolute
- * values, too -- elm_gengrid_page_size_set(). Naturally, its use
- * is mutually exclusive to this one.
+ * This causes gengrid to @b redraw its viewport's contents to the
+ * region containing the given @p item item, if it is not fully
+ * visible.
*
- * @see elm_gengrid_page_relative_get()
+ * @see elm_gengrid_item_bring_in()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel);
+EAPI void elm_gengrid_item_show(Elm_Object_Item *it);
/**
- * Get a given gengrid widget's scrolling page size, relative to
- * its viewport size.
+ * Animatedly bring in, to the visible area of a gengrid, a given
+ * item on it.
*
- * @param obj The gengrid object
- * @param h_pagerel Pointer to a variable where to store the
- * horizontal page (relative) size
- * @param v_pagerel Pointer to a variable where to store the
- * vertical page (relative) size
+ * @param it The gengrid item to display
*
- * @see elm_gengrid_page_relative_set() for more details
+ * This causes gengrid to jump to the given @p item and show
+ * it (by scrolling), if it is not fully visible. This will use
+ * animation to do so and take a period of time to complete.
+ *
+ * @see elm_gengrid_item_show()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_page_relative_get(const Evas_Object *obj, double *h_pagerel, double *v_pagerel);
+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);
/**
- * Set a given gengrid widget's scrolling page size
- *
- * @param obj The gengrid object
- * @param h_pagesize The horizontal page size, in pixels
- * @param v_pagesize The vertical page size, in pixels
- *
- * The gengrid's scroller is capable of binding scrolling by the
- * user to "pages". It means that, while scrolling and, specially
- * after releasing the mouse button, the grid will @b snap to the
- * nearest displaying page's area. When page sizes are set, the
- * grid's continuous content area is split into (equal) page sized
- * pieces.
+ * Update the contents of a given gengrid item
*
- * This function sets the size of a page of the gengrid, in pixels,
- * for each axis. Sane usable values are, between @c 0 and the
- * dimensions of @p obj, for each axis. Values beyond those will
- * make it behave behave inconsistently. If you only want one axis
- * to snap to pages, use the value @c 0 for the other one.
+ * @param it The gengrid item
*
- * There is a function setting page size values in @b relative
- * values, too -- elm_gengrid_page_relative_set(). Naturally, its
- * use is mutually exclusive to this one.
+ * This updates an item 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 you want the changes to be
+ * reflected.
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize);
+EAPI void elm_gengrid_item_update(Elm_Object_Item *it);
/**
- * @brief Get gengrid current page number.
+ * Update the item class of a gengrid item.
*
- * @param obj The gengrid object
- * @param h_pagenumber The horizontal page number
- * @param v_pagenumber The vertical page number
+ * This sets another class of the item, changing the way that it is
+ * displayed. After changing the item class, elm_gengrid_item_update() is
+ * called on the item @p it.
*
- * The page number starts from 0. 0 is the first page.
- * Current page means the page which meet the top-left of the viewport.
- * If there are two or more pages in the viewport, it returns the number of page
- * which meet the top-left of the viewport.
+ * @param it The gengrid item
+ * @param gic The gengrid item class describing the function pointers and the item style.
*
- * @see elm_gengrid_last_page_get()
- * @see elm_gengrid_page_show()
- * @see elm_gengrid_page_bring_in()
+ * @ingroup Gengrid
*/
-EAPI void elm_gengrid_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
+EAPI void elm_gengrid_item_item_class_update(Elm_Object_Item *it, const Elm_Gengrid_Item_Class *gic);
/**
- * @brief Get gengrid last page number.
+ * Get the Gengrid Item class for the given Gengrid Item.
*
- * @param obj The gengrid object
- * @param h_pagenumber The horizontal page number
- * @param v_pagenumber The vertical page number
+ * @param it The gengrid item
*
- * The page number starts from 0. 0 is the first page.
- * This returns the last page number among the pages.
+ * This returns the Gengrid_Item_Class for the given item. It can be used to examine
+ * the function pointers and item_style.
*
- * @see elm_gengrid_current_page_get()
- * @see elm_gengrid_page_show()
- * @see elm_gengrid_page_bring_in()
+ * @ingroup Gengrid
*/
-EAPI void elm_gengrid_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
+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 iint elm_gengrid_items_count(const Evas_Object *obj);
+
+#define ELM_GENGRID_ITEM_CLASS_VERSION 2 /* current version number */
/**
- * Show a specific virtual region within the gengrid content object by page number.
- *
- * @param obj The gengrid object
- * @param h_pagenumber The horizontal page number
- * @param v_pagenumber The vertical page number
+ * Add a new gengrid item class in a given gengrid widget.
*
- * 0, 0 of the indicated page is located at the top-left of the viewport.
- * This will jump to the page directly without animation.
+ * @return New allocated a gengrid item class.
*
- * Example of usage:
+ * This adds gengrid item class for the gengrid widget. When adding a item,
+ * gengrid_item_{append, prepend, insert} function needs item class of the item.
+ * Given callback paramters are used at retrieving {text, content} of
+ * added item. Set as NULL if it's not used.
+ * If there's no available memory, return can be NULL.
*
- * @code
- * sc = elm_gengrid_add(win);
- * elm_gengrid_content_set(sc, content);
- * elm_gengrid_page_relative_set(sc, 1, 0);
- * elm_gengrid_current_page_get(sc, &h_page, &v_page);
- * elm_gengrid_page_show(sc, h_page + 1, v_page);
- * @endcode
+ * @see elm_gengrid_item_class_free()
+ * @see elm_gengrid_item_append()
*
- * @see elm_gengrid_page_bring_in()
+ * @ingroup Gengrid
*/
-EAPI void elm_gengrid_page_show(const Evas_Object *obj, int h_pagenumber, int v_pagenumber);
+EAPI Elm_Gengrid_Item_Class *elm_gengrid_item_class_new(void);
/**
- * Show a specific virtual region within the gengrid content object by page number.
- *
- * @param obj The gengrid object
- * @param h_pagenumber The horizontal page number
- * @param v_pagenumber The vertical page number
- *
- * 0, 0 of the indicated page is located at the top-left of the viewport.
- * This will slide to the page with animation.
+ * Remove a item class in a given gengrid widget.
*
- * Example of usage:
+ * @param itc The itc to be removed.
*
- * @code
- * sc = elm_gengrid_add(win);
- * elm_gengrid_content_set(sc, content);
- * elm_gengrid_page_relative_set(sc, 1, 0);
- * elm_gengrid_last_page_get(sc, &h_page, &v_page);
- * elm_gengrid_page_bring_in(sc, h_page, v_page);
- * @endcode
+ * This removes item class from the gengrid widget.
+ * Whenever it has no more references to it, item class is going to be freed.
+ * Otherwise it just decreases its reference count.
*
- * @see elm_gengrid_page_show()
+ * @see elm_gengrid_item_class_new()
+ * @see elm_gengrid_item_class_ref()
+ * @see elm_gengrid_item_class_unref()
+ *
+ * @ingroup Gengrid
*/
-EAPI void elm_gengrid_page_bring_in(const Evas_Object *obj, int h_pagenumber, int v_pagenumber);
+EAPI void elm_gengrid_item_class_free(Elm_Gengrid_Item_Class *itc);
/**
- * Set the direction in which a given gengrid widget will expand while
- * placing its items.
+ * Increments object reference count for the item class.
*
- * @param obj The gengrid object.
- * @param horizontal @c EINA_TRUE to make the gengrid expand
- * horizontally, @c EINA_FALSE to expand vertically.
+ * @param itc The given item class object to reference
*
- * When in "horizontal mode" (@c EINA_TRUE), items will be placed
- * in @b columns, from top to bottom and, when the space for a
- * column is filled, another one is started on the right, thus
- * expanding the grid horizontally. When in "vertical mode"
- * (@c EINA_FALSE), though, items will be placed in @b rows, from left
- * to right and, when the space for a row is filled, another one is
- * started below, thus expanding the grid vertically.
+ * This API just increases its reference count for item class management.
*
- * @see elm_gengrid_horizontal_get()
+ * @see elm_gengrid_item_class_unref()
*
* @ingroup Gengrid
*/
-//XXX: elm_gengrid_mode_set()
-EAPI void elm_gengrid_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
+EAPI void elm_gengrid_item_class_ref(Elm_Gengrid_Item_Class *itc);
/**
- * Get for what direction a given gengrid widget will expand while
- * placing its items.
+ * Decrements object reference count for the item class.
*
- * @param obj The gengrid object.
- * @return @c EINA_TRUE, if @p obj is set to expand horizontally,
- * @c EINA_FALSE if it's set to expand vertically.
+ * @param itc The given item class object to reference
*
- * @see elm_gengrid_horizontal_set() for more details
+ * This API just decreases its reference count for item class management.
+ * Reference count can't be less than 0.
+ *
+ * @see elm_gengrid_item_class_ref()
+ * @see elm_gengrid_item_class_free()
*
* @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_horizontal_get(const Evas_Object *obj);
+EAPI void elm_gengrid_item_class_unref(Elm_Gengrid_Item_Class *itc);
+
+//XXX: Need to review tooltip & cursor APIs
/**
- * Get the first item in a given gengrid widget
+ * Set the text to be shown in a given gengrid item's tooltips.
*
- * @param obj The gengrid object
- * @return The first item's handle or @c NULL, if there are no
- * items in @p obj (and on errors)
+ * @param it The gengrid item
+ * @param text The text to set in the content
*
- * This returns the first item in the @p obj's internal list of
- * items.
+ * This call will setup the text to be used as tooltip to that item
+ * (analogous to elm_object_tooltip_text_set(), but being item
+ * tooltips with higher precedence than object tooltips). It can
+ * have only one tooltip at a time, so any previous tooltip data
+ * will get removed.
*
- * @see elm_gengrid_last_item_get()
+ * In order to set a content or something else as a tooltip, look at
+ * elm_gengrid_item_tooltip_content_cb_set().
*
* @ingroup Gengrid
*/
-EAPI Elm_Object_Item *elm_gengrid_first_item_get(const Evas_Object *obj);
+EAPI void elm_gengrid_item_tooltip_text_set(Elm_Object_Item *it, const char *text);
/**
- * Get the last item in a given gengrid widget
+ * Set the content to be shown in a given gengrid item's tooltip
*
- * @param obj The gengrid object
- * @return The last item's handle or @c NULL, if there are no
- * items in @p obj (and on errors)
+ * @param it The gengrid item.
+ * @param func The function returning 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
+ * another callback replaces @p func, the tooltip is unset with
+ * elm_gengrid_item_tooltip_unset() or the owner @p item
+ * dies. This callback receives as its first parameter the
+ * given @p data, being @c event_info the item handle.
*
- * This returns the last item in the @p obj's internal list of
- * items.
+ * This call will setup the tooltip's contents to @p item
+ * (analogous to elm_object_tooltip_content_cb_set(), but being
+ * item tooltips with higher precedence than object tooltips). It
+ * can have only one tooltip at a time, so any previous tooltip
+ * content will get removed. @p func (with @p data) will be called
+ * every time Elementary needs to show the tooltip and it should
+ * return a valid Evas object, which will be fully managed by the
+ * tooltip system, getting deleted when the tooltip is gone.
*
- * @see elm_gengrid_first_item_get()
+ * In order to set just a text as a tooltip, look at
+ * elm_gengrid_item_tooltip_text_set().
*
* @ingroup Gengrid
*/
-EAPI Elm_Object_Item *elm_gengrid_last_item_get(const Evas_Object *obj);
+EAPI void elm_gengrid_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
/**
- * Get the @b next item in a gengrid widget's internal list of items,
- * given a handle to one of those items.
+ * Unset a tooltip from a given gengrid item
*
- * @param it The gengrid item to fetch next from
- * @return The item after @p item, or @c NULL if there's none (and
- * on errors)
+ * @param it gengrid item to remove a previously set tooltip from.
*
- * This returns the item placed after the @p item, on the container
- * gengrid.
+ * This call removes any tooltip set on @p item. The callback
+ * provided as @c del_cb to
+ * elm_gengrid_item_tooltip_content_cb_set() will be called to
+ * notify it is not used anymore (and have resources cleaned, if
+ * need be).
*
- * @see elm_gengrid_item_prev_get()
+ * @see elm_gengrid_item_tooltip_content_cb_set()
*
* @ingroup Gengrid
*/
-EAPI Elm_Object_Item *elm_gengrid_item_next_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_item_tooltip_unset(Elm_Object_Item *it);
/**
- * Get the @b previous item in a gengrid widget's internal list of items,
- * given a handle to one of those items.
+ * Set a different @b style for a given gengrid item's tooltip.
*
- * @param it The gengrid item to fetch previous from
- * @return The item before @p item, or @c NULL if there's none (and
- * on errors)
+ * @param it gengrid item with tooltip set
+ * @param style the <b>theme style</b> to use on tooltips (e.g. @c
+ * "default", @c "transparent", etc)
*
- * This returns the item placed before the @p item, on the container
- * gengrid.
+ * Tooltips can have <b>alternate styles</b> to be displayed on,
+ * which are defined by the theme set on Elementary. This function
+ * works analogously as elm_object_tooltip_style_set(), but here
+ * applied only to gengrid item objects. The default style for
+ * tooltips is @c "default".
*
- * @see elm_gengrid_item_next_get()
+ * @note before you set a style you should define a tooltip with
+ * elm_gengrid_item_tooltip_content_cb_set() or
+ * elm_gengrid_item_tooltip_text_set()
+ *
+ * @see elm_gengrid_item_tooltip_style_get()
*
* @ingroup Gengrid
*/
-EAPI Elm_Object_Item *elm_gengrid_item_prev_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_item_tooltip_style_set(Elm_Object_Item *it, const char *style);
/**
- * Update the contents of a given gengrid item
+ * Get the style set a given gengrid item's tooltip.
*
- * @param it The gengrid item
+ * @param it gengrid item with tooltip already set on.
+ * @return style the theme style in use, which defaults to
+ * "default". If the object does not have a tooltip set,
+ * then @c NULL is returned.
*
- * This updates an item 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 you want the changes to be
- * reflected.
+ * @see elm_gengrid_item_tooltip_style_set() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_update(Elm_Object_Item *it);
+EAPI const char *elm_gengrid_item_tooltip_style_get(const Elm_Object_Item *it);
/**
- * Get the Gengrid Item class for the given Gengrid Item.
- *
- * @param it The gengrid item
+ * @brief Disable size restrictions on an object's tooltip
+ * @param it The tooltip's anchor object
+ * @param disable If EINA_TRUE, size restrictions are disabled
+ * @return EINA_FALSE on failure, EINA_TRUE on success
*
- * This returns the Gengrid_Item_Class for the given item. It can be used to examine
- * the function pointers and item_style.
+ * This function allows a tooltip to expand beyond its parent window's canvas.
+ * It will instead be limited only by the size of the display.
+ */
+EAPI Eina_Bool elm_gengrid_item_tooltip_window_mode_set(Elm_Object_Item *it, Eina_Bool disable);
+
+/**
+ * @brief Retrieve size restriction state of an object's tooltip
+ * @param it The tooltip's anchor object
+ * @return If EINA_TRUE, size restrictions are disabled
*
- * @ingroup Gengrid
+ * This function returns whether a tooltip is allowed to expand beyond
+ * its parent window's canvas.
+ * It will instead be limited only by the size of the display.
*/
-EAPI const Elm_Gengrid_Item_Class *elm_gengrid_item_item_class_get(const Elm_Object_Item *it);
+EAPI Eina_Bool elm_gengrid_item_tooltip_window_mode_get(const Elm_Object_Item *it);
/**
- * Update the item class of a gengrid item.
+ * Set the type of mouse pointer/cursor decoration to be shown,
+ * when the mouse pointer is over the given gengrid widget item
*
- * This sets another class of the item, changing the way that it is
- * displayed. After changing the item class, elm_gengrid_item_update() is
- * called on the item @p it.
+ * @param it gengrid item to customize cursor on
+ * @param cursor the cursor type's name
*
- * @param it The gengrid item
- * @param gic The gengrid item class describing the function pointers and the item style.
+ * This function works analogously as elm_object_cursor_set(), but
+ * here the cursor's changing area is restricted to the item's
+ * area, and not the whole widget's. Note that that item cursors
+ * have precedence over widget cursors, so that a mouse over @p
+ * item will always show cursor @p type.
+ *
+ * If this function is called twice for an object, a previously set
+ * cursor will be unset on the second call.
+ *
+ * @see elm_object_cursor_set()
+ * @see elm_gengrid_item_cursor_get()
+ * @see elm_gengrid_item_cursor_unset()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_item_class_update(Elm_Object_Item *it, const Elm_Gengrid_Item_Class *gic);
+EAPI void elm_gengrid_item_cursor_set(Elm_Object_Item *it, const char *cursor);
/**
- * Get a given gengrid item's position, relative to the whole
- * gengrid's grid area.
+ * Get the type of mouse pointer/cursor decoration set to be shown,
+ * when the mouse pointer is over the given gengrid widget item
*
- * @param it The Gengrid item.
- * @param x Pointer to variable to store the item's <b>row number</b>.
- * @param y Pointer to variable to store the item's <b>column number</b>.
+ * @param it gengrid item with custom cursor set
+ * @return the cursor type's name or @c NULL, if no custom cursors
+ * were set to @p item (and on errors)
*
- * This returns the "logical" position of the item within the
- * gengrid. For example, @c (0, 1) would stand for first row,
- * second column.
+ * @see elm_object_cursor_get()
+ * @see elm_gengrid_item_cursor_set() for more details
+ * @see elm_gengrid_item_cursor_unset()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_pos_get(const Elm_Object_Item *it, unsigned int *x, unsigned int *y);
+EAPI const char *elm_gengrid_item_cursor_get(const Elm_Object_Item *it);
/**
- * Set whether a given gengrid item is selected or not
+ * Unset any custom mouse pointer/cursor decoration set to be
+ * shown, when the mouse pointer is over the given gengrid widget
+ * item, thus making it show the @b default cursor again.
*
- * @param it The gengrid item
- * @param selected Use @c EINA_TRUE, to make it selected, @c
- * EINA_FALSE to make it unselected
+ * @param it a gengrid item
*
- * This sets the selected state of an item. If multi-selection is
- * not enabled on the containing gengrid and @p selected is @c
- * EINA_TRUE, any other previously selected items will get
- * unselected in favor of this new one.
+ * Use this call to undo any custom settings on this item's cursor
+ * decoration, bringing it back to defaults (no custom style set).
*
- * @see elm_gengrid_item_selected_get()
+ * @see elm_object_cursor_unset()
+ * @see elm_gengrid_item_cursor_set() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
+EAPI void elm_gengrid_item_cursor_unset(Elm_Object_Item *it);
/**
- * Get the selected item in a given gengrid widget
+ * Set a different @b style for a given custom cursor set for a
+ * gengrid item.
*
- * @param obj The gengrid object.
- * @return The selected item's handle or @c NULL, if none is
- * selected at the moment (and on errors)
+ * @param it gengrid item with custom cursor set
+ * @param style the <b>theme style</b> to use (e.g. @c "default",
+ * @c "transparent", etc)
*
- * This returns the selected item in @p obj. If multi selection is
- * enabled on @p obj (@see elm_gengrid_multi_select_set()), only
- * the first item in the list is selected, which might not be very
- * useful. For that case, see elm_gengrid_selected_items_get().
+ * This function only makes sense when one is using custom mouse
+ * cursor decorations <b>defined in a theme file</b> , which can
+ * have, given a cursor name/type, <b>alternate styles</b> on
+ * it. It works analogously as elm_object_cursor_style_set(), but
+ * here applied only to gengrid item objects.
+ *
+ * @warning Before you set a cursor style you should have defined a
+ * custom cursor previously on the item, with
+ * elm_gengrid_item_cursor_set()
+ *
+ * @see elm_gengrid_item_cursor_engine_only_set()
+ * @see elm_gengrid_item_cursor_style_get()
*
* @ingroup Gengrid
*/
-EAPI Elm_Object_Item *elm_gengrid_selected_item_get(const Evas_Object *obj);
+EAPI void elm_gengrid_item_cursor_style_set(Elm_Object_Item *it, const char *style);
/**
- * Get <b>a list</b> of selected items in a given gengrid
- *
- * @param obj The gengrid object.
- * @return The list of selected items or @c NULL, if none is
- * selected at the moment (and on errors)
+ * Get the current @b style set for a given gengrid item's custom
+ * cursor
*
- * This returns a list of the selected items, in the order that
- * they appear in the grid. This list is only valid as long as no
- * more items are selected or unselected (or unselected implicitly
- * by deletion). The list contains #Gengrid item pointers as
- * data, naturally.
+ * @param it gengrid item with custom cursor set.
+ * @return style the cursor style in use. If the object does not
+ * have a cursor set, then @c NULL is returned.
*
- * @see elm_gengrid_selected_item_get()
+ * @see elm_gengrid_item_cursor_style_set() for more details
*
* @ingroup Gengrid
*/
-EAPI const Eina_List *elm_gengrid_selected_items_get(const Evas_Object *obj);
+EAPI const char *elm_gengrid_item_cursor_style_get(const Elm_Object_Item *it);
/**
- * Get whether a given gengrid item is selected or not
+ * Set if the (custom) cursor for a given gengrid item should be
+ * searched in its theme, also, or should only rely on the
+ * rendering engine.
*
- * @param it The gengrid item
- * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
+ * @param it item with custom (custom) cursor already set on
+ * @param engine_only Use @c EINA_TRUE to have cursors looked for
+ * only on those provided by the rendering engine, @c EINA_FALSE to
+ * have them searched on the widget's theme, as well.
*
- * This API returns EINA_TRUE for all the items selected in multi-select mode as well.
+ * @note This call is of use only if you've set a custom cursor
+ * for gengrid items, with elm_gengrid_item_cursor_set().
*
- * @see elm_gengrid_item_selected_set() for more details
+ * @note By default, cursors will only be looked for between those
+ * provided by the rendering engine.
*
* @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_item_selected_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only);
/**
- * Show the portion of a gengrid's internal grid containing a given
- * item, @b immediately.
- *
- * @param it The item to display
+ * Get if the (custom) cursor for a given gengrid item is being
+ * searched in its theme, also, or is only relying on the rendering
+ * engine.
*
- * This causes gengrid to @b redraw its viewport's contents to the
- * region containing the given @p item item, if it is not fully
- * visible.
+ * @param it a gengrid item
+ * @return @c EINA_TRUE, if cursors are being looked for only on
+ * those provided by the rendering engine, @c EINA_FALSE if they
+ * are being searched on the widget's theme, as well.
*
- * @see elm_gengrid_item_bring_in()
+ * @see elm_gengrid_item_cursor_engine_only_set(), for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_show(Elm_Object_Item *it);
+EAPI Eina_Bool elm_gengrid_item_cursor_engine_only_get(const Elm_Object_Item *it);
/**
- * Animatedly bring in, to the visible area of a gengrid, a given
- * item on it.
+ * Set the size for the items of a given gengrid widget
*
- * @param it The gengrid item to display
+ * @param obj The gengrid object.
+ * @param w The items' width.
+ * @param h The items' height;
*
- * This causes gengrid to jump to the given @p item and show
- * it (by scrolling), if it is not fully visible. This will use
- * animation to do so and take a period of time to complete.
+ * A gengrid, after creation, has still no information on the size
+ * to give to each of its cells. So, you most probably will end up
+ * with squares one @ref Fingers "finger" wide, the default
+ * size. Use this function to force a custom size for you items,
+ * making them as big as you wish.
*
- * @see elm_gengrid_item_show()
+ * @see elm_gengrid_item_size_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_bring_in(Elm_Object_Item *it);
-
-//XXX: Need to review tooltip & cursor APIs
+EAPI void elm_gengrid_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
- * Set the text to be shown in a given gengrid item's tooltips.
+ * Get the size set for the items of a given gengrid widget
*
- * @param it The gengrid item
- * @param text The text to set in the content
+ * @param obj The gengrid object.
+ * @param w Pointer to a variable where to store the items' width.
+ * @param h Pointer to a variable where to store the items' height.
*
- * This call will setup the text to be used as tooltip to that item
- * (analogous to elm_object_tooltip_text_set(), but being item
- * tooltips with higher precedence than object tooltips). It can
- * have only one tooltip at a time, so any previous tooltip data
- * will get removed.
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
*
- * In order to set a content or something else as a tooltip, look at
- * elm_gengrid_item_tooltip_content_cb_set().
+ * @see elm_gengrid_item_size_get() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_tooltip_text_set(Elm_Object_Item *it, const char *text);
+EAPI void elm_gengrid_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
/**
- * Set the content to be shown in a given gengrid item's tooltip
+ * Set the size for the group items of a given gengrid widget
*
- * @param it The gengrid item.
- * @param func The function returning 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
- * another callback replaces @p func, the tooltip is unset with
- * elm_gengrid_item_tooltip_unset() or the owner @p item
- * dies. This callback receives as its first parameter the
- * given @p data, being @c event_info the item handle.
+ * @param obj The gengrid object.
+ * @param w The group items' width.
+ * @param h The group items' height;
*
- * This call will setup the tooltip's contents to @p item
- * (analogous to elm_object_tooltip_content_cb_set(), but being
- * item tooltips with higher precedence than object tooltips). It
- * can have only one tooltip at a time, so any previous tooltip
- * content will get removed. @p func (with @p data) will be called
- * every time Elementary needs to show the tooltip and it should
- * return a valid Evas object, which will be fully managed by the
- * tooltip system, getting deleted when the tooltip is gone.
+ * A gengrid, after creation, has still no information on the size
+ * to give to each of its cells. So, you most probably will end up
+ * with squares one @ref Fingers "finger" wide, the default
+ * size. Use this function to force a custom size for you group items,
+ * making them as big as you wish.
*
- * In order to set just a text as a tooltip, look at
- * elm_gengrid_item_tooltip_text_set().
+ * @see elm_gengrid_group_item_size_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
+EAPI void elm_gengrid_group_item_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
- * Unset a tooltip from a given gengrid item
+ * Get the size set for the group items of a given gengrid widget
*
- * @param it gengrid item to remove a previously set tooltip from.
+ * @param obj The gengrid object.
+ * @param w Pointer to a variable where to store the group items' width.
+ * @param h Pointer to a variable where to store the group items' height.
*
- * This call removes any tooltip set on @p item. The callback
- * provided as @c del_cb to
- * elm_gengrid_item_tooltip_content_cb_set() will be called to
- * notify it is not used anymore (and have resources cleaned, if
- * need be).
+ * @note Use @c NULL pointers on the size values you're not
+ * interested in: they'll be ignored by the function.
*
- * @see elm_gengrid_item_tooltip_content_cb_set()
+ * @see elm_gengrid_group_item_size_get() for more details
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_tooltip_unset(Elm_Object_Item *it);
+EAPI void elm_gengrid_group_item_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
/**
- * Set a different @b style for a given gengrid item's tooltip.
+ * Set the items grid's alignment within a given gengrid widget
*
- * @param it gengrid item with tooltip set
- * @param style the <b>theme style</b> to use on tooltips (e.g. @c
- * "default", @c "transparent", etc)
+ * @param obj The gengrid object.
+ * @param align_x Alignment in the horizontal axis (0 <= align_x <= 1).
+ * @param align_y Alignment in the vertical axis (0 <= align_y <= 1).
*
- * Tooltips can have <b>alternate styles</b> to be displayed on,
- * which are defined by the theme set on Elementary. This function
- * works analogously as elm_object_tooltip_style_set(), but here
- * applied only to gengrid item objects. The default style for
- * tooltips is @c "default".
+ * This sets the alignment of the whole grid of items of a gengrid
+ * within its given viewport. By default, those values are both
+ * 0.5, meaning that the gengrid will have its items grid placed
+ * exactly in the middle of its viewport.
*
- * @note before you set a style you should define a tooltip with
- * elm_gengrid_item_tooltip_content_cb_set() or
- * elm_gengrid_item_tooltip_text_set()
+ * @note If given alignment values are out of the cited ranges,
+ * they'll be changed to the nearest boundary values on the valid
+ * ranges.
*
- * @see elm_gengrid_item_tooltip_style_get()
+ * @see elm_gengrid_align_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_tooltip_style_set(Elm_Object_Item *it, const char *style);
+EAPI void elm_gengrid_align_set(Evas_Object *obj, double align_x, double align_y);
/**
- * Get the style set a given gengrid item's tooltip.
+ * Get the items grid's alignment values within a given gengrid
+ * widget
*
- * @param it gengrid item with tooltip already set on.
- * @return style the theme style in use, which defaults to
- * "default". If the object does not have a tooltip set,
- * then @c NULL is returned.
+ * @param obj The gengrid object.
+ * @param align_x Pointer to a variable where to store the
+ * horizontal alignment.
+ * @param align_y Pointer to a variable where to store the vertical
+ * alignment.
*
- * @see elm_gengrid_item_tooltip_style_set() for more details
+ * @note Use @c NULL pointers on the alignment values you're not
+ * interested in: they'll be ignored by the function.
+ *
+ * @see elm_gengrid_align_set() for more details
*
* @ingroup Gengrid
*/
-EAPI const char *elm_gengrid_item_tooltip_style_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_align_get(const Evas_Object *obj, double *align_x, double *align_y);
/**
- * @brief Disable size restrictions on an object's tooltip
- * @param it The tooltip's anchor object
- * @param disable If EINA_TRUE, size restrictions are disabled
- * @return EINA_FALSE on failure, EINA_TRUE on success
+ * Set whether a given gengrid widget is or not able have items
+ * @b reordered
*
- * This function allows a tooltip to expand beyond its parent window's canvas.
- * It will instead be limited only by the size of the display.
+ * @param obj The gengrid object
+ * @param reorder_mode Use @c EINA_TRUE to turn reordering on,
+ * @c EINA_FALSE to turn it off
+ *
+ * If a gengrid is set to allow reordering, a click held for more
+ * than 0.5 over a given item will highlight it specially,
+ * signaling the gengrid has entered the reordering state. From
+ * that time on, the user will be able to, while still holding the
+ * mouse button down, move the item freely in the gengrid's
+ * viewport, replacing to said item to the locations it goes to.
+ * The replacements will be animated and, whenever the user
+ * releases the mouse button, the item being replaced gets a new
+ * definitive place in the grid.
+ *
+ * @see elm_gengrid_reorder_mode_get()
+ *
+ * @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_item_tooltip_window_mode_set(Elm_Object_Item *it, Eina_Bool disable);
+EAPI void elm_gengrid_reorder_mode_set(Evas_Object *obj, Eina_Bool reorder_mode);
/**
- * @brief Retrieve size restriction state of an object's tooltip
- * @param it The tooltip's anchor object
- * @return If EINA_TRUE, size restrictions are disabled
+ * Get whether a given gengrid widget is or not able have items
+ * @b reordered
*
- * This function returns whether a tooltip is allowed to expand beyond
- * its parent window's canvas.
- * It will instead be limited only by the size of the display.
+ * @param obj The gengrid object
+ * @return @c EINA_TRUE, if reordering is on, @c EINA_FALSE if it's
+ * off
+ *
+ * @see elm_gengrid_reorder_mode_set() for more details
+ *
+ * @ingroup Gengrid
*/
-EAPI Eina_Bool elm_gengrid_item_tooltip_window_mode_get(const Elm_Object_Item *it);
+EAPI Eina_Bool elm_gengrid_reorder_mode_get(const Evas_Object *obj);
+
/**
- * Set the type of mouse pointer/cursor decoration to be shown,
- * when the mouse pointer is over the given gengrid widget item
+ * Set a given gengrid widget's scrolling page size, relative to
+ * its viewport size.
*
- * @param it gengrid item to customize cursor on
- * @param cursor the cursor type's name
+ * @param obj The gengrid object
+ * @param h_pagerel The horizontal page (relative) size
+ * @param v_pagerel The vertical page (relative) size
*
- * This function works analogously as elm_object_cursor_set(), but
- * here the cursor's changing area is restricted to the item's
- * area, and not the whole widget's. Note that that item cursors
- * have precedence over widget cursors, so that a mouse over @p
- * item will always show cursor @p type.
+ * The gengrid's scroller is capable of binding scrolling by the
+ * user to "pages". It means that, while scrolling and, specially
+ * after releasing the mouse button, the grid will @b snap to the
+ * nearest displaying page's area. When page sizes are set, the
+ * grid's continuous content area is split into (equal) page sized
+ * pieces.
*
- * If this function is called twice for an object, a previously set
- * cursor will be unset on the second call.
+ * This function sets the size of a page <b>relatively to the
+ * viewport dimensions</b> of the gengrid, for each axis. A value
+ * @c 1.0 means "the exact viewport's size", in that axis, while @c
+ * 0.0 turns paging off in that axis. Likewise, @c 0.5 means "half
+ * a viewport". Sane usable values are, than, between @c 0.0 and @c
+ * 1.0. Values beyond those will make it behave behave
+ * inconsistently. If you only want one axis to snap to pages, use
+ * the value @c 0.0 for the other one.
*
- * @see elm_object_cursor_set()
- * @see elm_gengrid_item_cursor_get()
- * @see elm_gengrid_item_cursor_unset()
+ * There is a function setting page size values in @b absolute
+ * values, too -- elm_gengrid_page_size_set(). Naturally, its use
+ * is mutually exclusive to this one.
+ *
+ * @see elm_gengrid_page_relative_get()
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_cursor_set(Elm_Object_Item *it, const char *cursor);
+EAPI void elm_gengrid_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel);
/**
- * Get the type of mouse pointer/cursor decoration set to be shown,
- * when the mouse pointer is over the given gengrid widget item
+ * Get a given gengrid widget's scrolling page size, relative to
+ * its viewport size.
*
- * @param it gengrid item with custom cursor set
- * @return the cursor type's name or @c NULL, if no custom cursors
- * were set to @p item (and on errors)
+ * @param obj The gengrid object
+ * @param h_pagerel Pointer to a variable where to store the
+ * horizontal page (relative) size
+ * @param v_pagerel Pointer to a variable where to store the
+ * vertical page (relative) size
*
- * @see elm_object_cursor_get()
- * @see elm_gengrid_item_cursor_set() for more details
- * @see elm_gengrid_item_cursor_unset()
+ * @see elm_gengrid_page_relative_set() for more details
*
* @ingroup Gengrid
*/
-EAPI const char *elm_gengrid_item_cursor_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_page_relative_get(const Evas_Object *obj, double *h_pagerel, double *v_pagerel);
/**
- * Unset any custom mouse pointer/cursor decoration set to be
- * shown, when the mouse pointer is over the given gengrid widget
- * item, thus making it show the @b default cursor again.
+ * Set a given gengrid widget's scrolling page size
*
- * @param it a gengrid item
+ * @param obj The gengrid object
+ * @param h_pagesize The horizontal page size, in pixels
+ * @param v_pagesize The vertical page size, in pixels
*
- * Use this call to undo any custom settings on this item's cursor
- * decoration, bringing it back to defaults (no custom style set).
+ * The gengrid's scroller is capable of binding scrolling by the
+ * user to "pages". It means that, while scrolling and, specially
+ * after releasing the mouse button, the grid will @b snap to the
+ * nearest displaying page's area. When page sizes are set, the
+ * grid's continuous content area is split into (equal) page sized
+ * pieces.
*
- * @see elm_object_cursor_unset()
- * @see elm_gengrid_item_cursor_set() for more details
+ * This function sets the size of a page of the gengrid, in pixels,
+ * for each axis. Sane usable values are, between @c 0 and the
+ * dimensions of @p obj, for each axis. Values beyond those will
+ * make it behave behave inconsistently. If you only want one axis
+ * to snap to pages, use the value @c 0 for the other one.
+ *
+ * There is a function setting page size values in @b relative
+ * values, too -- elm_gengrid_page_relative_set(). Naturally, its
+ * use is mutually exclusive to this one.
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_item_cursor_unset(Elm_Object_Item *it);
+EAPI void elm_gengrid_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize);
/**
- * Set a different @b style for a given custom cursor set for a
- * gengrid item.
- *
- * @param it gengrid item with custom cursor set
- * @param style the <b>theme style</b> to use (e.g. @c "default",
- * @c "transparent", etc)
- *
- * This function only makes sense when one is using custom mouse
- * cursor decorations <b>defined in a theme file</b> , which can
- * have, given a cursor name/type, <b>alternate styles</b> on
- * it. It works analogously as elm_object_cursor_style_set(), but
- * here applied only to gengrid item objects.
+ * @brief Get gengrid current page number.
*
- * @warning Before you set a cursor style you should have defined a
- * custom cursor previously on the item, with
- * elm_gengrid_item_cursor_set()
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
*
- * @see elm_gengrid_item_cursor_engine_only_set()
- * @see elm_gengrid_item_cursor_style_get()
+ * The page number starts from 0. 0 is the first page.
+ * Current page means the page which meet the top-left of the viewport.
+ * If there are two or more pages in the viewport, it returns the number of page
+ * which meet the top-left of the viewport.
*
- * @ingroup Gengrid
+ * @see elm_gengrid_last_page_get()
+ * @see elm_gengrid_page_show()
+ * @see elm_gengrid_page_bring_in()
*/
-EAPI void elm_gengrid_item_cursor_style_set(Elm_Object_Item *it, const char *style);
+EAPI void elm_gengrid_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
/**
- * Get the current @b style set for a given gengrid item's custom
- * cursor
+ * @brief Get gengrid last page number.
*
- * @param it gengrid item with custom cursor set.
- * @return style the cursor style in use. If the object does not
- * have a cursor set, then @c NULL is returned.
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
*
- * @see elm_gengrid_item_cursor_style_set() for more details
+ * The page number starts from 0. 0 is the first page.
+ * This returns the last page number among the pages.
*
- * @ingroup Gengrid
+ * @see elm_gengrid_current_page_get()
+ * @see elm_gengrid_page_show()
+ * @see elm_gengrid_page_bring_in()
*/
-EAPI const char *elm_gengrid_item_cursor_style_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
/**
- * Set if the (custom) cursor for a given gengrid item should be
- * searched in its theme, also, or should only rely on the
- * rendering engine.
+ * Show a specific virtual region within the gengrid content object by page number.
*
- * @param it item with custom (custom) cursor already set on
- * @param engine_only Use @c EINA_TRUE to have cursors looked for
- * only on those provided by the rendering engine, @c EINA_FALSE to
- * have them searched on the widget's theme, as well.
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
*
- * @note This call is of use only if you've set a custom cursor
- * for gengrid items, with elm_gengrid_item_cursor_set().
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will jump to the page directly without animation.
*
- * @note By default, cursors will only be looked for between those
- * provided by the rendering engine.
+ * Example of usage:
*
- * @ingroup Gengrid
+ * @code
+ * sc = elm_gengrid_add(win);
+ * elm_gengrid_content_set(sc, content);
+ * elm_gengrid_page_relative_set(sc, 1, 0);
+ * elm_gengrid_current_page_get(sc, &h_page, &v_page);
+ * elm_gengrid_page_show(sc, h_page + 1, v_page);
+ * @endcode
+ *
+ * @see elm_gengrid_page_bring_in()
*/
-EAPI void elm_gengrid_item_cursor_engine_only_set(Elm_Object_Item *it, Eina_Bool engine_only);
+EAPI void elm_gengrid_page_show(const Evas_Object *obj, int h_pagenumber, int v_pagenumber);
/**
- * Get if the (custom) cursor for a given gengrid item is being
- * searched in its theme, also, or is only relying on the rendering
- * engine.
+ * Show a specific virtual region within the gengrid content object by page number.
*
- * @param it a gengrid item
- * @return @c EINA_TRUE, if cursors are being looked for only on
- * those provided by the rendering engine, @c EINA_FALSE if they
- * are being searched on the widget's theme, as well.
+ * @param obj The gengrid object
+ * @param h_pagenumber The horizontal page number
+ * @param v_pagenumber The vertical page number
*
- * @see elm_gengrid_item_cursor_engine_only_set(), for more details
+ * 0, 0 of the indicated page is located at the top-left of the viewport.
+ * This will slide to the page with animation.
*
- * @ingroup Gengrid
+ * Example of usage:
+ *
+ * @code
+ * sc = elm_gengrid_add(win);
+ * elm_gengrid_content_set(sc, content);
+ * elm_gengrid_page_relative_set(sc, 1, 0);
+ * elm_gengrid_last_page_get(sc, &h_page, &v_page);
+ * elm_gengrid_page_bring_in(sc, h_page, v_page);
+ * @endcode
+ *
+ * @see elm_gengrid_page_show()
*/
-EAPI Eina_Bool elm_gengrid_item_cursor_engine_only_get(const Elm_Object_Item *it);
+EAPI void elm_gengrid_page_bring_in(const Evas_Object *obj, int h_pagenumber, int v_pagenumber);
/**
- * Remove all items from a given gengrid widget
- *
- * @param obj The gengrid object.
+ * Get a given gengrid item's position, relative to the whole
+ * gengrid's grid area.
*
- * This removes (and deletes) all items in @p obj, leaving it
- * empty.
+ * @param it The Gengrid item.
+ * @param x Pointer to variable to store the item's <b>row number</b>.
+ * @param y Pointer to variable to store the item's <b>column number</b>.
*
- * @see elm_object_item_del(), to remove just one item.
+ * This returns the "logical" position of the item within the
+ * gengrid. For example, @c (0, 1) would stand for first row,
+ * second column.
*
* @ingroup Gengrid
*/
-EAPI void elm_gengrid_clear(Evas_Object *obj);
+EAPI void elm_gengrid_item_pos_get(const Elm_Object_Item *it, unsigned int *x, unsigned int *y);
/**
* Set how the items grid's filled within a given gengrid widget
//XXX: Does this API working well?
EAPI Eina_Bool elm_gengrid_filled_get(const Evas_Object *obj);
-#define ELM_GENGRID_ITEM_CLASS_VERSION 2 /* current version number */
-
-/**
- * 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,
- * gengrid_item_{append, prepend, insert} function needs item class of the item.
- * Given callback paramters are used at retrieving {text, content} of
- * added item. Set as NULL if it's not used.
- * If there's no available memory, return can be NULL.
- *
- * @see elm_gengrid_item_class_free()
- * @see elm_gengrid_item_append()
- *
- * @ingroup Gengrid
- */
-EAPI Elm_Gengrid_Item_Class *elm_gengrid_item_class_new(void);
-
-/**
- * Remove a item class in a given gengrid widget.
- *
- * @param itc The itc to be removed.
- *
- * This removes item class from the gengrid widget.
- * Whenever it has no more references to it, item class is going to be freed.
- * Otherwise it just decreases its reference count.
- *
- * @see elm_gengrid_item_class_new()
- * @see elm_gengrid_item_class_ref()
- * @see elm_gengrid_item_class_unref()
- *
- * @ingroup Gengrid
- */
-EAPI void elm_gengrid_item_class_free(Elm_Gengrid_Item_Class *itc);
-
-/**
- * Increments object reference count for the item class.
- *
- * @param itc The given item class object to reference
- *
- * This API just increases its reference count for item class management.
- *
- * @see elm_gengrid_item_class_unref()
- *
- * @ingroup Gengrid
- */
-EAPI void elm_gengrid_item_class_ref(Elm_Gengrid_Item_Class *itc);
-
-/**
- * Decrements object reference count for the item class.
- *
- * @param itc The given item class object to reference
- *
- * This API just decreases its reference count for item class management.
- * Reference count can't be less than 0.
- *
- * @see elm_gengrid_item_class_ref()
- * @see elm_gengrid_item_class_free()
- *
- * @ingroup Gengrid
- */
-EAPI void elm_gengrid_item_class_unref(Elm_Gengrid_Item_Class *itc);
-
/**
* @}
*/
EAPI Eina_Bool elm_genlist_no_select_mode_get(const Evas_Object *obj);
/**
- * Enable/disable compress mode.
- *
- * @param obj The genlist object
- * @param compress The compress mode
- * (@c EINA_TRUE = on, @c EINA_FALSE = off). Default is @c EINA_FALSE.
- *
- * This will enable the compress mode where items are "compressed"
- * horizontally to fit the genlist scrollable viewport width. This is
- * special for genlist. Do not rely on
- * elm_genlist_horizontal_set() being set to @c ELM_LIST_COMPRESS to
- * work as genlist needs to handle it specially.
- *
- * @see elm_genlist_compress_mode_get()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_compress_mode_set(Evas_Object *obj, Eina_Bool compress);
-
-/**
- * Get whether the compress mode is enabled.
- *
- * @param obj The genlist object
- * @return The compress mode
- * (@c EINA_TRUE = on, @c EINA_FALSE = off)
- *
- * @see elm_genlist_compress_mode_set()
- *
- * @ingroup Genlist
- */
-EAPI Eina_Bool elm_genlist_compress_mode_get(const Evas_Object *obj);
-
-/**
- * Enable/disable height-for-width mode.
- *
- * @param obj The genlist object
- * @param height_for_width The height-for-width mode (@c EINA_TRUE = on,
- * @c EINA_FALSE = off). Default is @c EINA_FALSE.
- *
- * 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 allows,
- * for instance, text block to wrap lines if the Edje part is
- * configured with "text.min: 0 1".
- *
- * @note This mode will make list resize slower as it will have to
- * recalculate every item height again whenever the list width
- * changes!
- *
- * @note When height-for-width mode is enabled, it also enables
- * compress mode (see elm_genlist_compress_mode_set()) and
- * disables homogeneous (see elm_genlist_homogeneous_set()).
- *
- * @ingroup Genlist
- */
-//XXX: API name is ambiguous.. How about elm_genlist_mode_fixed_width_set?
-EAPI void elm_genlist_height_for_width_mode_set(Evas_Object *obj, Eina_Bool height_for_width);
-
-/**
- * Get whether the height-for-width mode is enabled.
- *
- * @param obj The genlist object
- * @return The height-for-width mode (@c EINA_TRUE = on, @c EINA_FALSE =
- * off)
- *
- * @ingroup Genlist
- */
-//XXX: API name is ambigious elm_genlist_mode_fixed_width_get() ?????
-EAPI Eina_Bool elm_genlist_height_for_width_mode_get(const Evas_Object *obj);
-
-/**
* Enable/disable horizontal and vertical bouncing effect.
*
* @param obj The genlist object
EAPI void elm_genlist_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
/**
- * Enable/disable homogeneous mode.
- *
- * @param obj The genlist object
- * @param homogeneous Assume the items within the genlist are of the
- * same height and width (EINA_TRUE = on, EINA_FALSE = off). Default is @c
- * EINA_FALSE.
- *
- * 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 (which increases the performance for scrolling the list). This
- * implies 'compressed' mode.
- *
- * @see elm_genlist_compress_mode_set()
- * @see elm_genlist_homogeneous_get()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous);
-
-/**
- * Get whether the homogeneous mode is enabled.
- *
- * @param obj The genlist object
- * @return Assume the items within the genlist are of the same height
- * and width (EINA_TRUE = on, EINA_FALSE = off)
- *
- * @see elm_genlist_homogeneous_set()
- *
- * @ingroup Genlist
- */
-EAPI Eina_Bool elm_genlist_homogeneous_get(const Evas_Object *obj);
-
-/**
- * Set the maximum number of items within an item block
- *
- * @param obj The genlist object
- * @param count Maximum number of items within an item block. Default is 32.
- *
- * This will configure the block count to tune to the target with particular
- * performance matrix.
- *
- * A block of objects will be used to reduce the number of operations due to
- * many objects in the screen. It can determine the visibility, or if the
- * object has changed, it theme needs to be updated, etc. doing this kind of
- * calculation to the entire block, instead of per object.
- *
- * The default value for the block count is enough for most lists, so unless
- * you know you will have a lot of objects visible in the screen at the same
- * time, don't try to change this.
- *
- * @see elm_genlist_block_count_get()
- * @see @ref Genlist_Implementation
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_block_count_set(Evas_Object *obj, int count);
-
-/**
- * Get the maximum number of items within an item block
- *
- * @param obj The genlist object
- * @return Maximum number of items within an item block
- *
- * @see elm_genlist_block_count_set()
- *
- * @ingroup Genlist
- */
-EAPI int elm_genlist_block_count_get(const Evas_Object *obj);
-
-/**
- * Set the timeout in seconds for the longpress event.
- *
- * @param obj The genlist object
- * @param timeout timeout in seconds. Default is elm config value(1.0)
- *
- * This option will change how long it takes to send an event "longpressed"
- * after the mouse down signal is sent to the list. If this event occurs, no
- * "clicked" event will be sent.
- *
- * @warning If you set the longpress timeout value with this API, your genlist
- * will not be affected by the longpress value of elementary config value
- * later.
- *
- * @see elm_genlist_longpress_timeout_set()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_longpress_timeout_set(Evas_Object *obj, double timeout);
-
-/**
- * Get the timeout in seconds for the longpress event.
- *
- * @param obj The genlist object
- * @return timeout in seconds
- *
- * @see elm_genlist_longpress_timeout_get()
- *
- * @ingroup Genlist
- */
-EAPI double elm_genlist_longpress_timeout_get(const Evas_Object *obj);
-
-/**
* Append a new item in a given genlist widget.
*
* @param obj The genlist object
EAPI Eina_List *elm_genlist_realized_items_get(const Evas_Object *obj);
/**
- * Get the item that is at the x, y canvas coords.
- *
- * @param obj The genlist object.
- * @param x The input x coordinate
- * @param y The input y coordinate
- * @param posret The position relative to the item returned here
- * @return The item at the coordinates or NULL if none
- *
- * This returns the item at the given coordinates (which are canvas
- * relative, not object-relative). If an item is at that coordinate,
- * that item handle is returned, and if @p posret is not NULL, the
- * integer pointed to is set to a value of -1, 0 or 1, depending if
- * the coordinate is on the upper portion of that item (-1), on the
- * middle section (0) or on the lower part (1). If NULL is returned as
- * an item (no item found there), then posret may indicate -1 or 1
- * based if the coordinate is above or below all items respectively in
- * the genlist.
- *
- * @ingroup Genlist
- */
-EAPI Elm_Object_Item *elm_genlist_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret);
-
-/**
* Get the first item in the genlist
*
* This returns the first item in the list.
EAPI Elm_Object_Item *elm_genlist_item_prev_get(const Elm_Object_Item *it);
/**
- * Get the parent item of the given item
- *
- * @param it The item
- * @return The parent of the item or @c NULL if it has no parent.
- *
- * This returns the item that was specified as parent of the item @p it on
- * elm_genlist_item_append() and insertion related functions.
- *
- * @ingroup Genlist
- */
-EAPI Elm_Object_Item *elm_genlist_item_parent_get(const Elm_Object_Item *it);
-
-/**
- * Remove all sub-items (children) of the given item
- *
- * @param it The item
- *
- * This removes all items that are children (and their descendants) of the
- * given item @p it.
- *
- * @see elm_genlist_clear()
- * @see elm_object_item_del()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_item_subitems_clear(Elm_Object_Item *it);
-
-/**
* Set whether a given genlist item is selected or not
*
* @param it The item
EAPI Eina_Bool elm_genlist_item_selected_get(const Elm_Object_Item *it);
/**
- * Sets the expanded state of an item.
- *
- * @param it The item
- * @param expanded The expanded state (@c EINA_TRUE expanded, @c EINA_FALSE not expanded).
- *
- * This function flags the item of type #ELM_GENLIST_ITEM_SUBITEMS as
- * expanded or not.
+ * Show the portion of a genlist's internal list containing a given
+ * item, immediately.
*
- * The theme will respond to this change visually, and a signal "expanded" or
- * "contracted" will be sent from the genlist with a pointer to the item that
- * has been expanded/contracted.
+ * @param it The item to display
*
- * Calling this function won't show or hide any child of this item (if it is
- * a parent). You must manually delete and create them on the callbacks of
- * the "expanded" or "contracted" signals.
+ * This causes genlist to jump to the given item @p it and show it (by
+ * jumping to that position), if it is not fully visible.
*
- * @see elm_genlist_item_expanded_get()
+ * @see elm_genlist_item_bring_in()
+ * @see elm_genlist_item_top_show()
+ * @see elm_genlist_item_middle_show()
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_item_expanded_set(Elm_Object_Item *it, Eina_Bool expanded);
+//XXX: elm_genlist_item_show(it, TOP/MIDDLE/BOTTOM/...); this kind of API would cover all similar APIs - item_show, item_top_show...
+EAPI void elm_genlist_item_show(Elm_Object_Item *it);
/**
- * Get the expanded state of an item
- *
- * @param it The item
- * @return The expanded state
+ * Animatedly bring in, to the visible are of a genlist, a given
+ * item on it.
*
- * This gets the expanded state of an item.
- *
- * @see elm_genlist_item_expanded_set()
- *
- * @ingroup Genlist
- */
-EAPI Eina_Bool elm_genlist_item_expanded_get(const Elm_Object_Item *it);
-
-/**
- * Get the depth of expanded item
- *
- * @param it The genlist item object
- * @return The depth of expanded item
- *
- * @ingroup Genlist
- */
-EAPI int elm_genlist_item_expanded_depth_get(const Elm_Object_Item *it);
-
-
-/**
- * Sets the display only state of an item.
- *
- * @param it The item
- * @param display_only @c EINA_TRUE if the item is display only, @c
- * EINA_FALSE otherwise.
- *
- * A display only item cannot be selected or unselected. It is for
- * display only and not selecting or otherwise clicking, dragging
- * etc. by the user, thus finger size rules will not be applied to
- * this item.
- *
- * It's good to set group index items to display only state.
- *
- * @see elm_genlist_item_display_only_get()
- *
- * @ingroup Genlist
- */
-//XXX: elm_genlist_item_event_freeze_set()?
-EAPI void elm_genlist_item_display_only_set(Elm_Object_Item *it, Eina_Bool display_only);
-
-/**
- * Get the display only state of an item
- *
- * @param it The item
- * @return @c EINA_TRUE if the item is display only, @c
- * EINA_FALSE otherwise.
- *
- * @see elm_genlist_item_display_only_set()
- *
- * @ingroup Genlist
- */
-//XXX: elm_genlist_item_event_freeze_get()?
-EAPI Eina_Bool elm_genlist_item_display_only_get(const Elm_Object_Item *it);
-
-/**
- * Show the portion of a genlist's internal list containing a given
- * item, immediately.
- *
- * @param it The item to display
- *
- * This causes genlist to jump to the given item @p it and show it (by
- * jumping to that position), if it is not fully visible.
- *
- * @see elm_genlist_item_bring_in()
- * @see elm_genlist_item_top_show()
- * @see elm_genlist_item_middle_show()
- *
- * @ingroup Genlist
- */
-//XXX: elm_genlist_item_show(it, TOP/MIDDLE/BOTTOM/...); this kind of API would cover all similar APIs - item_show, item_top_show...
-EAPI void elm_genlist_item_show(Elm_Object_Item *it);
-
-/**
- * Animatedly bring in, to the visible are of a genlist, a given
- * item on it.
- *
- * @param it The item to display
+ * @param it The item to display
*
* This causes genlist to jump to the given item @p it and show it (by
* animatedly scrolling), if it is not fully visible. This may use animation
EAPI void elm_genlist_item_middle_bring_in(Elm_Object_Item *it);
/**
- * Tells genlist to "orphan" contents fetched by the item class
- *
- * @param it The item
- *
- * This instructs genlist to release references to contents in the item,
- * meaning that they will no longer be managed by genlist and are
- * floating "orphans" that can be re-used elsewhere if the user wants
- * to.
- *
- * @ingroup Genlist
- */
-//XXX: elm_genlist_item_all_contents_unset() ??
-EAPI void elm_genlist_item_contents_orphan(Elm_Object_Item *it);
-
-/**
* Update the contents of an item
*
* @param it The item
EAPI void elm_genlist_item_update(Elm_Object_Item *it);
/**
- * Promote an item to the top of the list
+ * Update the item class of an item
*
* @param it The item
+ * @param itc The item class for the item
+ *
+ * This sets another class of the item, changing the way that it is
+ * displayed. After changing the item class, elm_genlist_item_update() is
+ * called on the item @p it.
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_item_promote(Elm_Object_Item *it);
+EAPI void elm_genlist_item_item_class_update(Elm_Object_Item *it, const Elm_Genlist_Item_Class *itc);
/**
- * Demote an item to the end of the list
+ * Get the Genlist Item class for the given Genlist Item.
*
- * @param it The item
+ * @param it The genlist item
+ *
+ * This returns the Genlist_Item_Class for the given item. It can be used to
+ * examine the function pointers and item_style.
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_item_demote(Elm_Object_Item *it);
+EAPI const Elm_Genlist_Item_Class *elm_genlist_item_item_class_get(const Elm_Object_Item *it);
/**
- * Update the part of an item
+ * Get the index of the item. It is only valid once displayed.
*
- * @param it The item
- * @param parts The name of item's part
- * @param itf The flags of item's part type
+ * @param it a genlist item
+ * @return the position inside the list of item.
*
- * This updates an item's part by calling item's fetching functions again
+ * @ingroup Genlist
+ */
+EAPI int elm_genlist_item_index_get(const Elm_Object_Item *it);
+
+/**
+ * Update the contents of all realized items.
+ *
+ * @param obj The genlist 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.
- * Second parts argument is used for globbing to match '*', '?', and '.'
- * It can be used at updating multi fields.
*
- * Use elm_genlist_realized_items_update() to update an item's all
- * property.
+ * To update just one item, use elm_genlist_item_update().
*
+ * @see elm_genlist_realized_items_get()
* @see elm_genlist_item_update()
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_item_fields_update(Elm_Object_Item *it, const char *parts, Elm_Genlist_Item_Field_Flags itf);
+EAPI void elm_genlist_realized_items_update(Evas_Object *obj);
/**
- * Update the item class of an item
+ * Return how many items are currently in a list
*
- * @param it The item
- * @param itc The item class for the item
+ * @param obj The list
+ * @return The total number of list items in the list
*
- * This sets another class of the item, changing the way that it is
- * displayed. After changing the item class, elm_genlist_item_update() is
- * called on the item @p it.
+ * This behavior is O(1) and includes items which may or may not be realized.
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_item_item_class_update(Elm_Object_Item *it, const Elm_Genlist_Item_Class *itc);
+EAPI unsigned int elm_genlist_items_count(const Evas_Object *obj);
+
+#define ELM_GENLIST_ITEM_CLASS_VERSION 2 /* current version number */
/**
- * Get the Genlist Item class for the given Genlist Item.
+ * Add a new genlist item class in a given genlist widget.
*
- * @param it The genlist item
+ * @return New allocated a genlist item class.
*
- * This returns the Genlist_Item_Class for the given item. It can be used to
- * examine the function pointers and item_style.
+ * This adds genlist item class for the genlist widget. When adding a item,
+ * genlist_item_{append, prepend, insert} function needs item class of the item.
+ * Given callback paramters are used at retrieving {text, content} of
+ * added item. Set as NULL if it's not used.
+ * If there's no available memory, return can be NULL.
+ *
+ * @see elm_genlist_item_class_free()
+ * @see elm_genlist_item_append()
*
* @ingroup Genlist
*/
-EAPI const Elm_Genlist_Item_Class *elm_genlist_item_item_class_get(const Elm_Object_Item *it);
+EAPI Elm_Genlist_Item_Class *elm_genlist_item_class_new(void);
+
+/**
+ * Remove a item class in a given genlist widget.
+ *
+ * @param itc The itc to be removed.
+ *
+ * This removes item class from the genlist widget.
+ * Whenever it has no more references to it, item class is going to be freed.
+ * Otherwise it just decreases its reference count.
+ *
+ * @see elm_genlist_item_class_new()
+ * @see elm_genlist_item_class_ref()
+ * @see elm_genlist_item_class_unref()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_class_free(Elm_Genlist_Item_Class *itc);
+
+/**
+ * Increments object reference count for the item class.
+ *
+ * @param itc The given item class object to reference
+ *
+ * This API just increases its reference count for item class management.
+ *
+ * @see elm_genlist_item_class_unref()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_class_ref(Elm_Genlist_Item_Class *itc);
+
+/**
+ * Decrements object reference count for the item class.
+ *
+ * @param itc The given item class object to reference
+ *
+ * This API just decreases its reference count for item class management.
+ * Reference count can't be less than 0.
+ *
+ * @see elm_genlist_item_class_ref()
+ * @see elm_genlist_item_class_free()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_class_unref(Elm_Genlist_Item_Class *itc);
+
+
-//XXX: elm_genlist_item_item_class_set() ?
//XXX: Need to review tooltip & cursor APIs
/**
*
* @ingroup Genlist
*/
-//XXX: Need to review tooltip & cursor APIs
EAPI void elm_genlist_item_tooltip_content_cb_set(Elm_Object_Item *it, Elm_Tooltip_Item_Content_Cb func, const void *data, Evas_Smart_Cb del_cb);
/**
EAPI Eina_Bool elm_genlist_item_cursor_engine_only_get(const Elm_Object_Item *it);
/**
- * Get the index of the item. It is only valid once displayed.
+ * Enable/disable compress mode.
*
- * @param it a genlist item
- * @return the position inside the list of item.
+ * @param obj The genlist object
+ * @param compress The compress mode
+ * (@c EINA_TRUE = on, @c EINA_FALSE = off). Default is @c EINA_FALSE.
+ *
+ * This will enable the compress mode where items are "compressed"
+ * horizontally to fit the genlist scrollable viewport width. This is
+ * special for genlist. Do not rely on
+ * elm_genlist_horizontal_set() being set to @c ELM_LIST_COMPRESS to
+ * work as genlist needs to handle it specially.
+ *
+ * @see elm_genlist_compress_mode_get()
*
* @ingroup Genlist
*/
-EAPI int elm_genlist_item_index_get(const Elm_Object_Item *it);
+EAPI void elm_genlist_compress_mode_set(Evas_Object *obj, Eina_Bool compress);
/**
- * Update the contents of all realized items.
- *
- * @param obj The genlist 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.
+ * Get whether the compress mode is enabled.
*
- * To update just one item, use elm_genlist_item_update().
+ * @param obj The genlist object
+ * @return The compress mode
+ * (@c EINA_TRUE = on, @c EINA_FALSE = off)
*
- * @see elm_genlist_realized_items_get()
- * @see elm_genlist_item_update()
+ * @see elm_genlist_compress_mode_set()
*
* @ingroup Genlist
*/
-EAPI void elm_genlist_realized_items_update(Evas_Object *obj);
+EAPI Eina_Bool elm_genlist_compress_mode_get(const Evas_Object *obj);
/**
- * Activate a genlist mode on an item
+ * Enable/disable height-for-width mode.
*
- * @param it The genlist item
- * @param mode_type Mode name
- * @param mode_set Boolean to define set or unset mode.
+ * @param obj The genlist object
+ * @param height_for_width The height-for-width mode (@c EINA_TRUE = on,
+ * @c EINA_FALSE = off). Default is @c EINA_FALSE.
*
- * A genlist mode is a different way of selecting an item. Once a mode is
+ * 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 allows,
+ * for instance, text block to wrap lines if the Edje part is
+ * configured with "text.min: 0 1".
+ *
+ * @note This mode will make list resize slower as it will have to
+ * recalculate every item height again whenever the list width
+ * changes!
+ *
+ * @note When height-for-width mode is enabled, it also enables
+ * compress mode (see elm_genlist_compress_mode_set()) and
+ * disables homogeneous (see elm_genlist_homogeneous_set()).
+ *
+ * @ingroup Genlist
+ */
+//XXX: API name is ambiguous.. How about elm_genlist_mode_fixed_width_set?
+EAPI void elm_genlist_height_for_width_mode_set(Evas_Object *obj, Eina_Bool height_for_width);
+
+/**
+ * Get whether the height-for-width mode is enabled.
+ *
+ * @param obj The genlist object
+ * @return The height-for-width mode (@c EINA_TRUE = on, @c EINA_FALSE =
+ * off)
+ *
+ * @ingroup Genlist
+ */
+//XXX: API name is ambigious elm_genlist_mode_fixed_width_get() ?????
+EAPI Eina_Bool elm_genlist_height_for_width_mode_get(const Evas_Object *obj);
+
+/**
+ * Enable/disable homogeneous mode.
+ *
+ * @param obj The genlist object
+ * @param homogeneous Assume the items within the genlist are of the
+ * same height and width (EINA_TRUE = on, EINA_FALSE = off). Default is @c
+ * EINA_FALSE.
+ *
+ * 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 (which increases the performance for scrolling the list). This
+ * implies 'compressed' mode.
+ *
+ * @see elm_genlist_compress_mode_set()
+ * @see elm_genlist_homogeneous_get()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous);
+
+/**
+ * Get whether the homogeneous mode is enabled.
+ *
+ * @param obj The genlist object
+ * @return Assume the items within the genlist are of the same height
+ * and width (EINA_TRUE = on, EINA_FALSE = off)
+ *
+ * @see elm_genlist_homogeneous_set()
+ *
+ * @ingroup Genlist
+ */
+EAPI Eina_Bool elm_genlist_homogeneous_get(const Evas_Object *obj);
+
+/**
+ * Set the maximum number of items within an item block
+ *
+ * @param obj The genlist object
+ * @param count Maximum number of items within an item block. Default is 32.
+ *
+ * This will configure the block count to tune to the target with particular
+ * performance matrix.
+ *
+ * A block of objects will be used to reduce the number of operations due to
+ * many objects in the screen. It can determine the visibility, or if the
+ * object has changed, it theme needs to be updated, etc. doing this kind of
+ * calculation to the entire block, instead of per object.
+ *
+ * The default value for the block count is enough for most lists, so unless
+ * you know you will have a lot of objects visible in the screen at the same
+ * time, don't try to change this.
+ *
+ * @see elm_genlist_block_count_get()
+ * @see @ref Genlist_Implementation
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_block_count_set(Evas_Object *obj, int count);
+
+/**
+ * Get the maximum number of items within an item block
+ *
+ * @param obj The genlist object
+ * @return Maximum number of items within an item block
+ *
+ * @see elm_genlist_block_count_set()
+ *
+ * @ingroup Genlist
+ */
+EAPI int elm_genlist_block_count_get(const Evas_Object *obj);
+
+/**
+ * Set the timeout in seconds for the longpress event.
+ *
+ * @param obj The genlist object
+ * @param timeout timeout in seconds. Default is elm config value(1.0)
+ *
+ * This option will change how long it takes to send an event "longpressed"
+ * after the mouse down signal is sent to the list. If this event occurs, no
+ * "clicked" event will be sent.
+ *
+ * @warning If you set the longpress timeout value with this API, your genlist
+ * will not be affected by the longpress value of elementary config value
+ * later.
+ *
+ * @see elm_genlist_longpress_timeout_set()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_longpress_timeout_set(Evas_Object *obj, double timeout);
+
+/**
+ * Get the timeout in seconds for the longpress event.
+ *
+ * @param obj The genlist object
+ * @return timeout in seconds
+ *
+ * @see elm_genlist_longpress_timeout_get()
+ *
+ * @ingroup Genlist
+ */
+EAPI double elm_genlist_longpress_timeout_get(const Evas_Object *obj);
+
+/**
+ * Get the item that is at the x, y canvas coords.
+ *
+ * @param obj The genlist object.
+ * @param x The input x coordinate
+ * @param y The input y coordinate
+ * @param posret The position relative to the item returned here
+ * @return The item at the coordinates or NULL if none
+ *
+ * This returns the item at the given coordinates (which are canvas
+ * relative, not object-relative). If an item is at that coordinate,
+ * that item handle is returned, and if @p posret is not NULL, the
+ * integer pointed to is set to a value of -1, 0 or 1, depending if
+ * the coordinate is on the upper portion of that item (-1), on the
+ * middle section (0) or on the lower part (1). If NULL is returned as
+ * an item (no item found there), then posret may indicate -1 or 1
+ * based if the coordinate is above or below all items respectively in
+ * the genlist.
+ *
+ * @ingroup Genlist
+ */
+EAPI Elm_Object_Item *elm_genlist_at_xy_item_get(const Evas_Object *obj, Evas_Coord x, Evas_Coord y, int *posret);
+
+/**
+ * Get the parent item of the given item
+ *
+ * @param it The item
+ * @return The parent of the item or @c NULL if it has no parent.
+ *
+ * This returns the item that was specified as parent of the item @p it on
+ * elm_genlist_item_append() and insertion related functions.
+ *
+ * @ingroup Genlist
+ */
+EAPI Elm_Object_Item *elm_genlist_item_parent_get(const Elm_Object_Item *it);
+
+/**
+ * Remove all sub-items (children) of the given item
+ *
+ * @param it The item
+ *
+ * This removes all items that are children (and their descendants) of the
+ * given item @p it.
+ *
+ * @see elm_genlist_clear()
+ * @see elm_object_item_del()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_subitems_clear(Elm_Object_Item *it);
+
+/**
+ * Sets the expanded state of an item.
+ *
+ * @param it The item
+ * @param expanded The expanded state (@c EINA_TRUE expanded, @c EINA_FALSE not expanded).
+ *
+ * This function flags the item of type #ELM_GENLIST_ITEM_SUBITEMS as
+ * expanded or not.
+ *
+ * The theme will respond to this change visually, and a signal "expanded" or
+ * "contracted" will be sent from the genlist with a pointer to the item that
+ * has been expanded/contracted.
+ *
+ * Calling this function won't show or hide any child of this item (if it is
+ * a parent). You must manually delete and create them on the callbacks of
+ * the "expanded" or "contracted" signals.
+ *
+ * @see elm_genlist_item_expanded_get()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_expanded_set(Elm_Object_Item *it, Eina_Bool expanded);
+
+/**
+ * Get the expanded state of an item
+ *
+ * @param it The item
+ * @return The expanded state
+ *
+ * This gets the expanded state of an item.
+ *
+ * @see elm_genlist_item_expanded_set()
+ *
+ * @ingroup Genlist
+ */
+EAPI Eina_Bool elm_genlist_item_expanded_get(const Elm_Object_Item *it);
+
+/**
+ * Get the depth of expanded item
+ *
+ * @param it The genlist item object
+ * @return The depth of expanded item
+ *
+ * @ingroup Genlist
+ */
+EAPI int elm_genlist_item_expanded_depth_get(const Elm_Object_Item *it);
+
+/**
+ * Sets the display only state of an item.
+ *
+ * @param it The item
+ * @param display_only @c EINA_TRUE if the item is display only, @c
+ * EINA_FALSE otherwise.
+ *
+ * A display only item cannot be selected or unselected. It is for
+ * display only and not selecting or otherwise clicking, dragging
+ * etc. by the user, thus finger size rules will not be applied to
+ * this item.
+ *
+ * It's good to set group index items to display only state.
+ *
+ * @see elm_genlist_item_display_only_get()
+ *
+ * @ingroup Genlist
+ */
+//XXX: elm_genlist_item_event_freeze_set()?
+EAPI void elm_genlist_item_display_only_set(Elm_Object_Item *it, Eina_Bool display_only);
+
+/**
+ * Get the display only state of an item
+ *
+ * @param it The item
+ * @return @c EINA_TRUE if the item is display only, @c
+ * EINA_FALSE otherwise.
+ *
+ * @see elm_genlist_item_display_only_set()
+ *
+ * @ingroup Genlist
+ */
+//XXX: elm_genlist_item_event_freeze_get()?
+EAPI Eina_Bool elm_genlist_item_display_only_get(const Elm_Object_Item *it);
+
+/**
+ * Tells genlist to "orphan" contents fetched by the item class
+ *
+ * @param it The item
+ *
+ * This instructs genlist to release references to contents in the item,
+ * meaning that they will no longer be managed by genlist and are
+ * floating "orphans" that can be re-used elsewhere if the user wants
+ * to.
+ *
+ * @ingroup Genlist
+ */
+//XXX: elm_genlist_item_all_contents_unset() ??
+EAPI void elm_genlist_item_contents_orphan(Elm_Object_Item *it);
+
+/**
+ * Promote an item to the top of the list
+ *
+ * @param it The item
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_promote(Elm_Object_Item *it);
+
+/**
+ * Demote an item to the end of the list
+ *
+ * @param it The item
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_demote(Elm_Object_Item *it);
+
+/**
+ * Update the part of an item
+ *
+ * @param it The item
+ * @param parts The name of item's part
+ * @param itf The flags of item's part type
+ *
+ * This updates an item's part by calling item's fetching 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.
+ * Second parts argument is used for globbing to match '*', '?', and '.'
+ * It can be used at updating multi fields.
+ *
+ * Use elm_genlist_realized_items_update() to update an item's all
+ * property.
+ *
+ * @see elm_genlist_item_update()
+ *
+ * @ingroup Genlist
+ */
+EAPI void elm_genlist_item_fields_update(Elm_Object_Item *it, const char *parts, Elm_Genlist_Item_Field_Flags itf);
+
+/**
+ * Activate a genlist mode on an item
+ *
+ * @param it The genlist item
+ * @param mode_type Mode name
+ * @param mode_set Boolean to define set or unset mode.
+ *
+ * A genlist mode is a different way of selecting an item. Once a mode is
* activated on an item, any other selected item is immediately unselected.
* This feature provides an easy way of implementing a new kind of animation
* for selecting an item, without having to entirely rewrite the item style
//XXX: type would be more intuitive...
EAPI Elm_Genlist_Item_Flags elm_genlist_item_flags_get(const Elm_Object_Item *it);
-#define ELM_GENLIST_ITEM_CLASS_VERSION 2 /* current version number */
-
-/**
- * Add a new genlist item class in a given genlist widget.
- *
- * @return New allocated a genlist item class.
- *
- * This adds genlist item class for the genlist widget. When adding a item,
- * genlist_item_{append, prepend, insert} function needs item class of the item.
- * Given callback paramters are used at retrieving {text, content} of
- * added item. Set as NULL if it's not used.
- * If there's no available memory, return can be NULL.
- *
- * @see elm_genlist_item_class_free()
- * @see elm_genlist_item_append()
- *
- * @ingroup Genlist
- */
-EAPI Elm_Genlist_Item_Class *elm_genlist_item_class_new(void);
-
-/**
- * Remove a item class in a given genlist widget.
- *
- * @param itc The itc to be removed.
- *
- * This removes item class from the genlist widget.
- * Whenever it has no more references to it, item class is going to be freed.
- * Otherwise it just decreases its reference count.
- *
- * @see elm_genlist_item_class_new()
- * @see elm_genlist_item_class_ref()
- * @see elm_genlist_item_class_unref()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_item_class_free(Elm_Genlist_Item_Class *itc);
-
-/**
- * Increments object reference count for the item class.
- *
- * @param itc The given item class object to reference
- *
- * This API just increases its reference count for item class management.
- *
- * @see elm_genlist_item_class_unref()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_item_class_ref(Elm_Genlist_Item_Class *itc);
-
-/**
- * Decrements object reference count for the item class.
- *
- * @param itc The given item class object to reference
- *
- * This API just decreases its reference count for item class management.
- * Reference count can't be less than 0.
- *
- * @see elm_genlist_item_class_ref()
- * @see elm_genlist_item_class_free()
- *
- * @ingroup Genlist
- */
-EAPI void elm_genlist_item_class_unref(Elm_Genlist_Item_Class *itc);
-
-/**
- * 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 Genlist
- */
-EAPI unsigned int elm_genlist_items_count(const Evas_Object *obj);
/**
* Set Genlist edit mode
*
projects / framework / uifw / elementary.git / commitdiff