src/lib/elm_slider.h

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