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