src/lib/elm_slider.h

   1 /**
   2  * @defgroup Slider Slider
   3  * @ingroup Elementary
   4  *
   5  * @image html img/widget/slider/preview-00.png
   6  * @image latex img/widget/slider/preview-00.eps width=\textwidth
   7  *
   8  * The slider adds a draggable “slider” widget for selecting the value of
   9  * something within a range.
  10  *
  11  * A slider can be horizontal or vertical. It can contain an Icon and has a
  12  * primary label as well as a units label (that is formatted with floating
  13  * point values and thus accepts a printf-style format string, like
  14  * “%1.2f units”. There is also an indicator string that may be somewhere
  15  * else (like on the slider itself) that also accepts a format string like
  16  * units. Label, Icon Unit and Indicator strings/objects are optional.
  17  *
  18  * A slider may be inverted which means values invert, with high vales being
  19  * on the left or top and low values on the right or bottom (as opposed to
  20  * normally being low on the left or top and high on the bottom and right).
  21  *
  22  * The slider should have its minimum and maximum values set by the
  23  * application with  elm_slider_min_max_set() and value should also be set by
  24  * the application before use with  elm_slider_value_set(). The span of the
  25  * slider is its length (horizontally or vertically). This will be scaled by
  26  * the object or applications scaling factor. At any point code can query the
  27  * slider for its value with elm_slider_value_get().
  28  *
  29  * Smart callbacks one can listen to:
  30  * - "changed" - Whenever the slider value is changed by the user.
  31  * - "slider,drag,start" - dragging the slider indicator around has started.
  32  * - "slider,drag,stop" - dragging the slider indicator around has stopped.
  33  * - "delay,changed" - A short time after the value is changed by the user.
  34  * This will be called only when the user stops dragging for
  35  * a very short period or when they release their
  36  * finger/mouse, so it avoids possibly expensive reactions to
  37  * the value change.
  38  *
  39  * Available styles for it:
  40  * - @c "default"
  41  *
  42  * Default content parts of the slider widget that you can use for are:
  43  * @li "icon" - An icon of the slider
  44  * @li "end" - A end part content of the slider
  45  *
  46  * Default text parts of the slider widget that you can use for are:
  47  * @li "default" - Label of the slider
  48  *
  49  * Supported elm_object common APIs.
  50  * @li @ref elm_object_disabled_set
  51  * @li @ref elm_object_disabled_get
  52  * @li @ref elm_object_part_text_set
  53  * @li @ref elm_object_part_text_get
  54  * @li @ref elm_object_part_content_set
  55  * @li @ref elm_object_part_content_get
  56  * @li @ref elm_object_part_content_unset
  57  *
  58  * Here is an example on its usage:
  59  * @li @ref slider_example
  60  */
  61
  62 /**
  63  * @addtogroup Slider
  64  * @{
  65  */
  66
  67 /**
  68  * Add a new slider widget to the given parent Elementary
  69  * (container) object.
  70  *
  71  * @param parent The parent object.
  72  * @return a new slider widget handle or @c NULL, on errors.
  73  *
  74  * This function inserts a new slider widget on the canvas.
  75  *
  76  * @ingroup Slider
  77  */
  78 EAPI Evas_Object                 *elm_slider_add(Evas_Object *parent);
  79
  80 /**
  81  * Set the (exact) length of the bar region of a given slider widget.
  82  *
  83  * @param obj The slider object.
  84  * @param size The length of the slider's bar region.
  85  *
  86  * This sets the minimum width (when in horizontal mode) or height
  87  * (when in vertical mode) of the actual bar area of the slider
  88  * @p obj. This in turn affects the object's minimum size. Use
  89  * this when you're not setting other size hints expanding on the
  90  * given direction (like weight and alignment hints) and you would
  91  * like it to have a specific size.
  92  *
  93  * @note Icon, end, label, indicator and unit text around @p obj
  94  * will require their
  95  * own space, which will make @p obj to require more the @p size,
  96  * actually.
  97  *
  98  * @see elm_slider_span_size_get()
  99  *
 100  * @ingroup Slider
 101  */
 102 EAPI void                         elm_slider_span_size_set(Evas_Object *obj, Evas_Coord size);
 103
 104 /**
 105  * Get the length set for the bar region of a given slider widget
 106  *
 107  * @param obj The slider object.
 108  * @return The length of the slider's bar region.
 109  *
 110  * If that size was not set previously, with
 111  * elm_slider_span_size_set(), this call will return @c 0.
 112  *
 113  * @ingroup Slider
 114  */
 115 EAPI Evas_Coord                   elm_slider_span_size_get(const Evas_Object *obj);
 116
 117 /**
 118  * Set the format string for the unit label.
 119  *
 120  * @param obj The slider object.
 121  * @param format The format string for the unit display.
 122  *
 123  * Unit label is displayed all the time, if set, after slider's bar.
 124  * In horizontal mode, at right and in vertical mode, at bottom.
 125  *
 126  * If @c NULL, unit label won't be visible. If not it sets the format
 127  * string for the label text. To the label text is provided a floating point
 128  * value, so the label text can display up to 1 floating point value.
 129  * Note that this is optional.
 130  *
 131  * Use a format string such as "%1.2f meters" for example, and it will
 132  * display values like: "3.14 meters" for a value equal to 3.14159.
 133  *
 134  * Default is unit label disabled.
 135  *
 136  * @see elm_slider_indicator_format_get()
 137  *
 138  * @ingroup Slider
 139  */
 140 EAPI void                         elm_slider_unit_format_set(Evas_Object *obj, const char *format);
 141
 142 /**
 143  * Get the unit label format of the slider.
 144  *
 145  * @param obj The slider object.
 146  * @return The unit label format string in UTF-8.
 147  *
 148  * Unit label is displayed all the time, if set, after slider's bar.
 149  * In horizontal mode, at right and in vertical mode, at bottom.
 150  *
 151  * @see elm_slider_unit_format_set() for more
 152  * information on how this works.
 153  *
 154  * @ingroup Slider
 155  */
 156 EAPI const char                  *elm_slider_unit_format_get(const Evas_Object *obj);
 157
 158 /**
 159  * Set the format string for the indicator label.
 160  *
 161  * @param obj The slider object.
 162  * @param indicator The format string for the indicator display.
 163  *
 164  * The slider may display its value somewhere else then unit label,
 165  * for example, above the slider knob that is dragged around. This function
 166  * sets the format string used for this.
 167  *
 168  * If @c NULL, indicator label won't be visible. If not it sets the format
 169  * string for the label text. To the label text is provided a floating point
 170  * value, so the label text can display up to 1 floating point value.
 171  * Note that this is optional.
 172  *
 173  * Use a format string such as "%1.2f meters" for example, and it will
 174  * display values like: "3.14 meters" for a value equal to 3.14159.
 175  *
 176  * Default is indicator label disabled.
 177  *
 178  * @see elm_slider_indicator_format_get()
 179  *
 180  * @ingroup Slider
 181  */
 182 EAPI void                         elm_slider_indicator_format_set(Evas_Object *obj, const char *indicator);
 183
 184 /**
 185  * Get the indicator label format of the slider.
 186  *
 187  * @param obj The slider object.
 188  * @return The indicator label format string in UTF-8.
 189  *
 190  * The slider may display its value somewhere else then unit label,
 191  * for example, above the slider knob that is dragged around. This function
 192  * gets the format string used for this.
 193  *
 194  * @see elm_slider_indicator_format_set() for more
 195  * information on how this works.
 196  *
 197  * @ingroup Slider
 198  */
 199 EAPI const char                  *elm_slider_indicator_format_get(const Evas_Object *obj);
 200
 201 /**
 202  * Set the format function pointer for the indicator label
 203  *
 204  * @param obj The slider object.
 205  * @param func The indicator format function.
 206  * @param free_func The freeing function for the format string.
 207  *
 208  * Set the callback function to format the indicator string.
 209  *
 210  * @see elm_slider_indicator_format_set() for more info on how this works.
 211  *
 212  * @ingroup Slider
 213  */
 214 EAPI void                         elm_slider_indicator_format_function_set(Evas_Object *obj, char *(*func)(double val), void (*free_func)(char *str));
 215
 216 /**
 217  * Set the format function pointer for the units label
 218  *
 219  * @param obj The slider object.
 220  * @param func The units format function.
 221  * @param free_func The freeing function for the format string.
 222  *
 223  * Set the callback function to format the indicator string.
 224  *
 225  * @see elm_slider_units_format_set() for more info on how this works.
 226  *
 227  * @ingroup Slider
 228  */
 229 EAPI void                         elm_slider_units_format_function_set(Evas_Object *obj, char *(*func)(double val), void (*free_func)(char *str));
 230
 231 /**
 232  * Set the orientation of a given slider widget.
 233  *
 234  * @param obj The slider object.
 235  * @param horizontal Use @c EINA_TRUE to make @p obj to be
 236  * @b horizontal, @c EINA_FALSE to make it @b vertical.
 237  *
 238  * Use this function to change how your slider is to be
 239  * disposed: vertically or horizontally.
 240  *
 241  * By default it's displayed horizontally.
 242  *
 243  * @see elm_slider_horizontal_get()
 244  *
 245  * @ingroup Slider
 246  */
 247 EAPI void                         elm_slider_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 248
 249 /**
 250  * Retrieve the orientation of a given slider widget
 251  *
 252  * @param obj The slider object.
 253  * @return @c EINA_TRUE, if @p obj is set to be @b horizontal,
 254  * @c EINA_FALSE if it's @b vertical (and on errors).
 255  *
 256  * @see elm_slider_horizontal_set() for more details.
 257  *
 258  * @ingroup Slider
 259  */
 260 EAPI Eina_Bool                    elm_slider_horizontal_get(const Evas_Object *obj);
 261
 262 /**
 263  * Set the minimum and maximum values for the slider.
 264  *
 265  * @param obj The slider object.
 266  * @param min The minimum value.
 267  * @param max The maximum value.
 268  *
 269  * Define the allowed range of values to be selected by the user.
 270  *
 271  * If actual value is less than @p min, it will be updated to @p min. If it
 272  * is bigger then @p max, will be updated to @p max. Actual value can be
 273  * get with elm_slider_value_get().
 274  *
 275  * By default, min is equal to 0.0, and max is equal to 1.0.
 276  *
 277  * @warning Maximum must be greater than minimum, otherwise behavior
 278  * is undefined.
 279  *
 280  * @see elm_slider_min_max_get()
 281  *
 282  * @ingroup Slider
 283  */
 284 EAPI void                         elm_slider_min_max_set(Evas_Object *obj, double min, double max);
 285
 286 /**
 287  * Get the minimum and maximum values of the slider.
 288  *
 289  * @param obj The slider object.
 290  * @param min Pointer to store the minimum value.
 291  * @param max Pointer to store the maximum value.
 292  *
 293  * @note If only one value is needed, the other pointer can be passed
 294  * as @c NULL.
 295  *
 296  * @see elm_slider_min_max_set() for details.
 297  *
 298  * @ingroup Slider
 299  */
 300 EAPI void                         elm_slider_min_max_get(const Evas_Object *obj, double *min, double *max);
 301
 302 /**
 303  * Set the value the slider displays.
 304  *
 305  * @param obj The slider object.
 306  * @param val The value to be displayed.
 307  *
 308  * Value will be presented on the unit label following format specified with
 309  * elm_slider_unit_format_set() and on indicator with
 310  * elm_slider_indicator_format_set().
 311  *
 312  * @warning The value must to be between min and max values. This values
 313  * are set by elm_slider_min_max_set().
 314  *
 315  * @see elm_slider_value_get()
 316  * @see elm_slider_unit_format_set()
 317  * @see elm_slider_indicator_format_set()
 318  * @see elm_slider_min_max_set()
 319  *
 320  * @ingroup Slider
 321  */
 322 EAPI void                         elm_slider_value_set(Evas_Object *obj, double val);
 323
 324 /**
 325  * Get the value displayed by the spinner.
 326  *
 327  * @param obj The spinner object.
 328  * @return The value displayed.
 329  *
 330  * @see elm_spinner_value_set() for details.
 331  *
 332  * @ingroup Slider
 333  */
 334 EAPI double                       elm_slider_value_get(const Evas_Object *obj);
 335
 336 /**
 337  * Invert a given slider widget's displaying values order
 338  *
 339  * @param obj The slider object.
 340  * @param inverted Use @c EINA_TRUE to make @p obj inverted,
 341  * @c EINA_FALSE to bring it back to default, non-inverted values.
 342  *
 343  * A slider may be @b inverted, in which state it gets its
 344  * values inverted, with high vales being on the left or top and
 345  * low values on the right or bottom, as opposed to normally have
 346  * the low values on the former and high values on the latter,
 347  * respectively, for horizontal and vertical modes.
 348  *
 349  * @see elm_slider_inverted_get()
 350  *
 351  * @ingroup Slider
 352  */
 353 EAPI void                         elm_slider_inverted_set(Evas_Object *obj, Eina_Bool inverted);
 354
 355 /**
 356  * Get whether a given slider widget's displaying values are
 357  * inverted or not.
 358  *
 359  * @param obj The slider object.
 360  * @return @c EINA_TRUE, if @p obj has inverted values,
 361  * @c EINA_FALSE otherwise (and on errors).
 362  *
 363  * @see elm_slider_inverted_set() for more details.
 364  *
 365  * @ingroup Slider
 366  */
 367 EAPI Eina_Bool                    elm_slider_inverted_get(const Evas_Object *obj);
 368
 369 /**
 370  * Set whether to enlarge slider indicator (augmented knob) or not.
 371  *
 372  * @param obj The slider object.
 373  * @param show @c EINA_TRUE will make it enlarge, @c EINA_FALSE will
 374  * let the knob always at default size.
 375  *
 376  * By default, indicator will be bigger while dragged by the user.
 377  *
 378  * @warning It won't display values set with
 379  * elm_slider_indicator_format_set() if you disable indicator.
 380  *
 381  * @ingroup Slider
 382  */
 383 EAPI void                         elm_slider_indicator_show_set(Evas_Object *obj, Eina_Bool show);
 384
 385 /**
 386  * Get whether a given slider widget's enlarging indicator or not.
 387  *
 388  * @param obj The slider object.
 389  * @return @c EINA_TRUE, if @p obj is enlarging indicator, or
 390  * @c EINA_FALSE otherwise (and on errors).
 391  *
 392  * @see elm_slider_indicator_show_set() for details.
 393  *
 394  * @ingroup Slider
 395  */
 396 EAPI Eina_Bool                    elm_slider_indicator_show_get(const Evas_Object *obj);
 397
 398 /**
 399  * @}
 400  */