src/lib/elm_flipselector.h

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