src/lib/elm_flipselector.h

   1 /**
   2  * @defgroup Flipselector Flip Selector
   3  *
   4  * @image html img/widget/flipselector/preview-00.png
   5  * @image latex img/widget/flipselector/preview-00.eps
   6  *
   7  * A flip selector is a widget to show a set of @b text items, one
   8  * at a time, with the same sheet switching style as the @ref Clock
   9  * "clock" widget, when one changes the current displaying sheet
  10  * (thus, the "flip" in the name).
  11  *
  12  * User clicks to flip sheets which are @b held for some time will
  13  * make the flip selector to flip continuously and automatically for
  14  * the user. The interval between flips will keep growing in time,
  15  * so that it helps the user to reach an item which is distant from
  16  * the current selection.
  17  *
  18  * Smart callbacks one can register to:
  19  * - @c "selected" - when the widget's selected text item is changed
  20  * - @c "overflowed" - when the widget's current selection is changed
  21  *   from the first item in its list to the last
  22  * - @c "underflowed" - when the widget's current selection is changed
  23  *   from the last item in its list to the first
  24  *
  25  * Available styles for it:
  26  * - @c "default"
  27  *
  28  * Default text parts of the flipselector items that you can use for are:
  29  * @li "default" - label of the flipselector item
  30  *
  31  * Supported elm_object common APIs.
  32  * @li elm_object_disabled_set
  33  * @li elm_object_disabled_get
  34  *
  35  * Supported elm_object_item common APIs.
  36  * @li elm_object_item_text_set
  37  * @li elm_object_item_part_text_set
  38  * @li elm_object_item_signal_emit
  39  *
  40  * Here is an example on its usage:
  41  * @li @ref flipselector_example
  42  */
  43
  44 /**
  45  * @addtogroup Flipselector
  46  * @{
  47  */
  48
  49 /**
  50  * Add a new flip selector widget to the given parent Elementary
  51  * (container) widget
  52  *
  53  * @param parent The parent object
  54  * @return a new flip selector widget handle or @c NULL, on errors
  55  *
  56  * This function inserts a new flip selector widget on the canvas.
  57  *
  58  * @ingroup Flipselector
  59  */
  60 EAPI Evas_Object                *elm_flipselector_add(Evas_Object *parent);
  61
  62 /**
  63  * Programmatically select the next item of a flip selector widget
  64  *
  65  * @param obj The flipselector object
  66  *
  67  * @note The selection will be animated. Also, if it reaches the
  68  * end of its list of member items, it will continue with the first
  69  * one onwards.
  70  *
  71  * @ingroup Flipselector
  72  */
  73 EAPI void                        elm_flipselector_flip_next(Evas_Object *obj);
  74
  75 /**
  76  * Programmatically select the previous item of a flip selector
  77  * widget
  78  *
  79  * @param obj The flipselector object
  80  *
  81  * @note The selection will be animated.  Also, if it reaches the
  82  * beginning of its list of member items, it will continue with the
  83  * last one backwards.
  84  *
  85  * @ingroup Flipselector
  86  */
  87 EAPI void                        elm_flipselector_flip_prev(Evas_Object *obj);
  88
  89 /**
  90  * Append a (text) item to a flip selector widget
  91  *
  92  * @param obj The flipselector object
  93  * @param label The (text) label of the new item
  94  * @param func Convenience callback function to take place when
  95  * item is selected
  96  * @param data Data passed to @p func, above
  97  * @return A handle to the item added or @c NULL, on errors
  98  *
  99  * The widget's list of labels to show will be appended with the
 100  * given value. If the user wishes so, a callback function pointer
 101  * can be passed, which will get called when this same item is
 102  * selected.
 103  *
 104  * @note The current selection @b won't be modified by appending an
 105  * element to the list.
 106  *
 107  * @note The maximum length of the text label is going to be
 108  * determined <b>by the widget's theme</b>. Strings larger than
 109  * that value are going to be @b truncated.
 110  *
 111  * @ingroup Flipselector
 112  */
 113 EAPI Elm_Object_Item            *elm_flipselector_item_append(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 114
 115 /**
 116  * Prepend a (text) item to a flip selector widget
 117  *
 118  * @param obj The flipselector object
 119  * @param label The (text) label of the new item
 120  * @param func Convenience callback function to take place when
 121  * item is selected
 122  * @param data Data passed to @p func, above
 123  * @return A handle to the item added or @c NULL, on errors
 124  *
 125  * The widget's list of labels to show will be prepended with the
 126  * given value. If the user wishes so, a callback function pointer
 127  * can be passed, which will get called when this same item is
 128  * selected.
 129  *
 130  * @note The current selection @b won't be modified by prepending
 131  * an element to the list.
 132  *
 133  * @note The maximum length of the text label is going to be
 134  * determined <b>by the widget's theme</b>. Strings larger than
 135  * that value are going to be @b truncated.
 136  *
 137  * @ingroup Flipselector
 138  */
 139 EAPI Elm_Object_Item            *elm_flipselector_item_prepend(Evas_Object *obj, const char *label, Evas_Smart_Cb func, void *data);
 140
 141 /**
 142  * Get the internal list of items in a given flip selector widget.
 143  *
 144  * @param obj The flipselector object
 145  * @return The list of items (#Elm_Object_Item as data) or
 146  * @c NULL on errors.
 147  *
 148  * This list is @b not to be modified in any way and must not be
 149  * freed. Use the list members with functions like
 150  * elm_object_item_text_set(),
 151  * elm_object_item_text_get(),
 152  * elm_object_item_del(),
 153  * elm_flipselector_item_selected_get(),
 154  * elm_flipselector_item_selected_set().
 155  *
 156  * @warning This list is only valid until @p obj object's internal
 157  * items list is changed. It should be fetched again with another
 158  * call to this function when changes happen.
 159  *
 160  * @ingroup Flipselector
 161  */
 162 EAPI const Eina_List            *elm_flipselector_items_get(const Evas_Object *obj);
 163
 164 /**
 165  * Get the first item in the given flip selector widget's list of
 166  * items.
 167  *
 168  * @param obj The flipselector object
 169  * @return The first item or @c NULL, if it has no items (and on
 170  * errors)
 171  *
 172  * @see elm_flipselector_item_append()
 173  * @see elm_flipselector_last_item_get()
 174  *
 175  * @ingroup Flipselector
 176  */
 177 EAPI Elm_Object_Item            *elm_flipselector_first_item_get(const Evas_Object *obj);
 178
 179 /**
 180  * Get the last item in the given flip selector widget's list of
 181  * items.
 182  *
 183  * @param obj The flipselector object
 184  * @return The last item or @c NULL, if it has no items (and on
 185  * errors)
 186  *
 187  * @see elm_flipselector_item_prepend()
 188  * @see elm_flipselector_first_item_get()
 189  *
 190  * @ingroup Flipselector
 191  */
 192 EAPI Elm_Object_Item            *elm_flipselector_last_item_get(const Evas_Object *obj);
 193
 194 /**
 195  * Get the currently selected item in a flip selector widget.
 196  *
 197  * @param obj The flipselector object
 198  * @return The selected item or @c NULL, if the widget has no items
 199  * (and on errors)
 200  *
 201  * @ingroup Flipselector
 202  */
 203 EAPI Elm_Object_Item            *elm_flipselector_selected_item_get(const Evas_Object *obj);
 204
 205 /**
 206  * Set whether a given flip selector widget's item should be the
 207  * currently selected one.
 208  *
 209  * @param it The flip selector item
 210  * @param selected @c EINA_TRUE to select it, @c EINA_FALSE to unselect.
 211  *
 212  * This sets whether @p item is or not the selected (thus, under
 213  * display) one. If @p item is different than the one under display,
 214  * the latter will be unselected. If the @p item is set to be
 215  * unselected, on the other hand, the @b first item in the widget's
 216  * internal members list will be the new selected one.
 217  *
 218  * @see elm_flipselector_item_selected_get()
 219  *
 220  * @ingroup Flipselector
 221  */
 222 EAPI void                        elm_flipselector_item_selected_set(Elm_Object_Item *it, Eina_Bool selected);
 223
 224 /**
 225  * Get whether a given flip selector widget's item is the currently
 226  * selected one.
 227  *
 228  * @param it The flip selector item
 229  * @return @c EINA_TRUE, if it's selected, @c EINA_FALSE otherwise
 230  * (or on errors).
 231  *
 232  * @see elm_flipselector_item_selected_set()
 233  *
 234  * @ingroup Flipselector
 235  */
 236 EAPI Eina_Bool  elm_flipselector_item_selected_get(const Elm_Object_Item *it);
 237
 238 /**
 239  * Gets the item before @p item in a flip selector widget's internal list of
 240  * items.
 241  *
 242  * @param it The item to fetch previous from
 243  * @return The item before the @p item, in its parent's list. If there is no
 244  *         previous item for @p item or there's an error, @c NULL is returned.
 245  *
 246  * @see elm_flipselector_item_next_get()
 247  *
 248  * @ingroup Flipselector
 249  */
 250 EAPI Elm_Object_Item *elm_flipselector_item_prev_get(const Elm_Object_Item *it);
 251
 252 /**
 253  * Gets the item after @p item in a flip selector widget's
 254  * internal list of items.
 255  *
 256  * @param it The item to fetch next from
 257  * @return The item after the @p item, in its parent's list. If there is no next
 258  *         item for @p item or there's an error, @c NULL is returned.
 259  *
 260  * @see elm_flipselector_item_prev_get()
 261  *
 262  * @ingroup Flipselector
 263  */
 264 EAPI Elm_Object_Item            *elm_flipselector_item_next_get(const Elm_Object_Item *it);
 265
 266 /**
 267  * Set the interval on time updates for a user mouse button hold
 268  * on a flip selector widget.
 269  *
 270  * @param obj The flip selector object
 271  * @param interval The (first) interval value in seconds
 272  *
 273  * This interval value is @b decreased while the user holds the
 274  * mouse pointer either flipping up or flipping down a given flip
 275  * selector.
 276  *
 277  * This helps the user to get to a given item distant from the
 278  * current one easier/faster, as it will start to flip quicker and
 279  * quicker on mouse button holds.
 280  *
 281  * The calculation for the next flip interval value, starting from
 282  * the one set with this call, is the previous interval divided by
 283  * 1.05, so it decreases a little bit.
 284  *
 285  * The default starting interval value for automatic flips is
 286  * @b 0.85 seconds.
 287  *
 288  * @see elm_flipselector_first_interval_get()
 289  *
 290  * @ingroup Flipselector
 291  */
 292 EAPI void                        elm_flipselector_first_interval_set(Evas_Object *obj, double interval);
 293
 294 /**
 295  * Get the interval on time updates for an user mouse button hold
 296  * on a flip selector widget.
 297  *
 298  * @param obj The flip selector object
 299  * @return The (first) interval value, in seconds, set on it
 300  *
 301  * @see elm_flipselector_first_interval_set() for more details
 302  *
 303  * @ingroup Flipselector
 304  */
 305 EAPI double                      elm_flipselector_first_interval_get(const Evas_Object *obj);
 306
 307 /**
 308  * @}
 309  */