mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
108 lines
3.6 KiB
ReStructuredText
108 lines
3.6 KiB
ReStructuredText
.. _slider:
|
|
|
|
Slider (lv_slider)
|
|
==================
|
|
|
|
Overview
|
|
********
|
|
|
|
The Slider object looks like a `Bar </widgets/bar>`__ supplemented with
|
|
a knob. The knob can be dragged to set a value. Just like Bar, Slider
|
|
can be vertical or horizontal.
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` The background of the slider. Uses all the typical
|
|
background style properties. ``padding`` makes the indicator smaller
|
|
in the respective direction.
|
|
- :cpp:enumerator:`LV_PART_INDICATOR` The indicator that shows the current state of
|
|
the slider. Also uses all the typical background style properties.
|
|
- :cpp:enumerator:`LV_PART_KNOB` A rectangle (or circle) drawn at the current value.
|
|
Also uses all the typical background properties to describe the
|
|
knob(s). By default, the knob is square (with an optional corner
|
|
radius) with side length equal to the smaller side of the slider. The
|
|
knob can be made larger with the ``padding`` values. Padding values
|
|
can be asymmetric too.
|
|
|
|
Usage
|
|
*****
|
|
|
|
Value and range
|
|
---------------
|
|
|
|
To set an initial value use :cpp:expr:`lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)`. The
|
|
animation time is set by the styles' ``anim_time`` property.
|
|
|
|
To specify the range (min, max values), :cpp:expr:`lv_slider_set_range(slider, min , max)` can be used.
|
|
|
|
Modes
|
|
-----
|
|
|
|
The slider can be one of the following modes:
|
|
|
|
- :cpp:enumerator:`LV_SLIDER_MODE_NORMAL` A normal slider as described above
|
|
- :cpp:enumerator:`LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to
|
|
current value. Requires negative minimum range and positive maximum range.
|
|
- :cpp:enumerator:`LV_SLIDER_RANGE` Allows setting the start value too by
|
|
:cpp:expr:`lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start
|
|
value has to be always smaller than the end value.
|
|
|
|
The mode can be changed with :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
|
|
|
|
Knob-only mode
|
|
--------------
|
|
|
|
Normally, the slider can be adjusted either by dragging the knob, or by
|
|
clicking on the slider bar. In the latter case the knob moves to the
|
|
point clicked and slider value changes accordingly. In some cases it is
|
|
desirable to set the slider to react on dragging the knob only. This
|
|
feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`:
|
|
:cpp:expr:`lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`.
|
|
|
|
The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area.
|
|
|
|
Events
|
|
******
|
|
|
|
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent while the slider is being dragged or
|
|
changed with keys. The event is sent continuously while the slider is
|
|
being dragged.
|
|
- :cpp:enumerator:`LV_EVENT_RELEASED` Sent when the slider has just been released.
|
|
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent
|
|
for the following parts.
|
|
|
|
- :cpp:enumerator:`LV_SLIDER_DRAW_PART_KNOB` The main (right) knob of the slider
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_KNOB`
|
|
- ``draw_area``: area of the indicator
|
|
- ``rect_dsc``
|
|
- ``id``: 0
|
|
|
|
- :cpp:enumerator:`LV_SLIDER_DRAW_PART_KNOB` The left knob of the slider
|
|
|
|
- ``part``: :cpp:enumerator:`LV_PART_KNOB`
|
|
- ``draw_area``: area of the indicator
|
|
- ``rect_dsc``
|
|
- ``id``: 1
|
|
|
|
See the events of the `Bar </widgets/bar>`__ too.
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
Keys
|
|
****
|
|
|
|
- ``LV_KEY_UP/RIGHT`` Increment the slider's value by 1
|
|
- ``LV_KEY_DOWN/LEFT`` Decrement the slider's value by 1
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../examples/widgets/slider/index.rst
|
|
|
|
API
|
|
***
|