/**
 * @defgroup Flipselector Flip Selector
 *
 * @image html img/widget/flipselector/preview-00.png
 * @image latex img/widget/flipselector/preview-00.eps
 *
 * A flip selector is a widget to show a set of @b text items, one
 * at a time, with the same sheet switching style as the @ref Clock
 * "clock" widget, when one changes the current displaying sheet
 * (thus, the "flip" in the name).
 *
 * User clicks to flip sheets which are @b held for some time will
 * make the flip selector to flip continuosly and automatically for
 * the user. The interval between flips will keep growing in time,
 * so that it helps the user to reach an item which is distant from
 * the current selection.
 *
 * Smart callbacks one can register to:
 * - @c "selected" - when the widget's selected text item is changed
 * - @c "overflowed" - when the widget's current selection is changed
 *   from the first item in its list to the last
 * - @c "underflowed" - when the widget's current selection is changed
 *   from the last item in its list to the first
 *
 * Available styles for it:
 * - @c "default"
 *
 * To set/get the label of the flipselector item, you can use
 * elm_object_item_text_set/get APIs.
 * Once the text is set, a previously set one will be deleted.
 *
 * Here is an example on its usage:
 * @li @ref flipselector_example
 */

/**
 * @addtogroup Flipselector
 * @{
 */

/**
 * Add a new flip selector widget to the given parent Elementary
 * (container) widget
 *
 * @param parent The parent object
 * @return a new flip selector widget handle or @c NULL, on errors
 *
 * This function inserts a new flip selector widget on the canvas.
 *
 * @ingroup Flipselector
 */
EAPI Evas_Object                *elm_flipselector_add(Evas_Object *parent);

/**
 * Programmatically select the next item of a flip selector widget
 *
 * @param obj The flipselector object
 *
 * @note The selection will be animated. Also, if it reaches the
 * end of its list of member items, it will continue with the first
 * one onwards.
 *
 * @ingroup Flipselector
 */
EAPI void                        elm_flipselector_flip_next(Evas_Object *obj);

/**
 * Programmatically select the previous item of a flip selector
 * widget
 *
 * @param obj The flipselector object
 *
 * @note The selection will be animated.  Also, if it reaches the
 * beginning of its list of member items, it will continue with the
 * last one backwards.
 *
 * @ingroup Flipselector
 */
EAPI void                        elm_flipselector_flip_prev(Evas_Object *obj);

/**
 * Append a (text) item to a flip selector widget
 *
 * @param obj The flipselector object
 * @param label The (text) label of the new item
 * @param func Convenience callback function to take place when
 * item is selected
 * @param data Data passed to @p func, above
 * @return A handle to the item added or @c NULL, on errors
 *
 * The widget's list of labels to show will be appended with the
 * given value. If the user wishes so, a callback function pointer
 * can be passed, which will get called when this same item is
 * selected.
 *
 * @note The current selection @b won't be modified by appending an
 * element to the list.
 *
 * @note The maximum length of the text label is going to be
 * determined <b>by the widget's theme</b>. Strings larger than
 * that value are going to be @b truncated.
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);

/**
 * Prepend a (text) item to a flip selector widget
 *
 * @param obj The flipselector object
 * @param label The (text) label of the new item
 * @param func Convenience callback function to take place when
 * item is selected
 * @param data Data passed to @p func, above
 * @return A handle to the item added or @c NULL, on errors
 *
 * The widget's list of labels to show will be prepended with the
 * given value. If the user wishes so, a callback function pointer
 * can be passed, which will get called when this same item is
 * selected.
 *
 * @note The current selection @b won't be modified by prepending
 * an element to the list.
 *
 * @note The maximum length of the text label is going to be
 * determined <b>by the widget's theme</b>. Strings larger than
 * that value are going to be @b truncated.
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);

/**
 * Get the internal list of items in a given flip selector widget.
 *
 * @param obj The flipselector object
 * @return The list of items (#Elm_Object_Item as data) or
 * @c NULL on errors.
 *
 * This list is @b not to be modified in any way and must not be
 * freed. Use the list members with functions like
 * elm_object_item_text_set(),
 * elm_object_item_text_get(),
 * elm_flipselector_item_del(),
 * elm_flipselector_item_selected_get(),
 * elm_flipselector_item_selected_set().
 *
 * @warning This list is only valid until @p obj object's internal
 * items list is changed. It should be fetched again with another
 * call to this function when changes happen.
 *
 * @ingroup Flipselector
 */
EAPI const Eina_List            *elm_flipselector_items_get(const Evas_Object *obj);

/**
 * Get the first item in the given flip selector widget's list of
 * items.
 *
 * @param obj The flipselector object
 * @return The first item or @c NULL, if it has no items (and on
 * errors)
 *
 * @see elm_flipselector_item_append()
 * @see elm_flipselector_last_item_get()
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_first_item_get(const Evas_Object *obj);

/**
 * Get the last item in the given flip selector widget's list of
 * items.
 *
 * @param obj The flipselector object
 * @return The last item or @c NULL, if it has no items (and on
 * errors)
 *
 * @see elm_flipselector_item_prepend()
 * @see elm_flipselector_first_item_get()
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_last_item_get(const Evas_Object *obj);

/**
 * Get the currently selected item in a flip selector widget.
 *
 * @param obj The flipselector object
 * @return The selected item or @c NULL, if the widget has no items
 * (and on erros)
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_selected_item_get(const Evas_Object *obj);

/**
 * Set whether a given flip selector widget's item should be the
 * currently selected one.
 *
 * @param it The flip selector item
 * @param selected @c EINA_TRUE to select it, @c EINA_FALSE to unselect.
 *
 * This sets whether @p item is or not the selected (thus, under
 * display) one. If @p item is different than one under display,
 * the latter will be unselected. If the @p item is set to be
 * unselected, on the other hand, the @b first item in the widget's
 * internal members list will be the new selected one.
 *
 * @see elm_flipselector_item_selected_get()
 *
 * @ingroup Flipselector
 */
EAPI void                        elm_flipselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);

/**
 * Get whether a given flip selector widget's item is the currently
 * selected one.
 *
 * @param it The flip selector item
 * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
 * (or on errors).
 *
 * @see elm_flipselector_item_selected_set()
 *
 * @ingroup Flipselector
 */
EAPI Eina_Bool                   elm_flipselector_item_selected_get(const Elm_Object_Item *it);

/**
 * Delete a given item from a flip selector widget.
 *
 * @param it The item to delete
 *
 * @ingroup Flipselector
 */
EAPI void                        elm_flipselector_item_del(Elm_Object_Item *it);

/**
 * Gets the item before @p item in a flip selector widget's
 * internal list of items.
 *
 * @param it The item to fetch previous from
 * @return The item before the @p item, in its parent's list. If
 *         there is no previous item for @p item or there's an
 *         error, @c NULL is returned.
 *
 * @see elm_flipselector_item_next_get()
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_item_prev_get(Elm_Object_Item *it);

/**
 * Gets the item after @p item in a flip selector widget's
 * internal list of items.
 *
 * @param it The item to fetch next from
 * @return The item after the @p item, in its parent's list. If
 *         there is no next item for @p item or there's an
 *         error, @c NULL is returned.
 *
 * @see elm_flipselector_item_next_get()
 *
 * @ingroup Flipselector
 */
EAPI Elm_Object_Item            *elm_flipselector_item_next_get(Elm_Object_Item *it);

/**
 * Set the interval on time updates for an user mouse button hold
 * on a flip selector widget.
 *
 * @param obj The flip selector object
 * @param interval The (first) interval value in seconds
 *
 * This interval value is @b decreased while the user holds the
 * mouse pointer either flipping up or flipping doww a given flip
 * selector.
 *
 * This helps the user to get to a given item distant from the
 * current one easier/faster, as it will start to flip quicker and
 * quicker on mouse button holds.
 *
 * The calculation for the next flip interval value, starting from
 * the one set with this call, is the previous interval divided by
 * 1.05, so it decreases a little bit.
 *
 * The default starting interval value for automatic flips is
 * @b 0.85 seconds.
 *
 * @see elm_flipselector_interval_get()
 *
 * @ingroup Flipselector
 */
EAPI void                        elm_flipselector_interval_set(Evas_Object *obj, double interval);

/**
 * Get the interval on time updates for an user mouse button hold
 * on a flip selector widget.
 *
 * @param obj The flip selector object
 * @return The (first) interval value, in seconds, set on it
 *
 * @see elm_flipselector_interval_set() for more details
 *
 * @ingroup Flipselector
 */
EAPI double                      elm_flipselector_interval_get(const Evas_Object *obj);
/**
 * @}
 */