src/lib/elm_flipselector.h

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