iced_widget/
vertical_slider.rs

1//! Sliders let users set a value by moving an indicator.
2//!
3//! # Example
4//! ```no_run
5//! # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
6//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
7//! #
8//! use iced::widget::slider;
9//!
10//! struct State {
11//!    value: f32,
12//! }
13//!
14//! #[derive(Debug, Clone)]
15//! enum Message {
16//!     ValueChanged(f32),
17//! }
18//!
19//! fn view(state: &State) -> Element<'_, Message> {
20//!     slider(0.0..=100.0, state.value, Message::ValueChanged).into()
21//! }
22//!
23//! fn update(state: &mut State, message: Message) {
24//!     match message {
25//!         Message::ValueChanged(value) => {
26//!             state.value = value;
27//!         }
28//!     }
29//! }
30//! ```
31use std::ops::RangeInclusive;
32
33pub use crate::slider::{Catalog, Handle, HandleShape, Status, Style, StyleFn, default};
34
35use crate::core::border::Border;
36use crate::core::keyboard;
37use crate::core::keyboard::key::{self, Key};
38use crate::core::layout::{self, Layout};
39use crate::core::mouse;
40use crate::core::renderer;
41use crate::core::touch;
42use crate::core::widget::tree::{self, Tree};
43use crate::core::window;
44use crate::core::{self, Element, Event, Length, Pixels, Point, Rectangle, Shell, Size, Widget};
45
46/// An vertical bar and a handle that selects a single value from a range of
47/// values.
48///
49/// A [`VerticalSlider`] will try to fill the vertical space of its container.
50///
51/// The [`VerticalSlider`] range of numeric values is generic and its step size defaults
52/// to 1 unit.
53///
54/// Note: Under the hood values are converted to/from f64 so only values representable exactly as an f64
55/// are possible to select via the slider. However it is likely that the precision of the slider at these
56/// scales is already less than the precision lost from the f64 representation.
57///
58/// # Example
59/// ```no_run
60/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
61/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
62/// #
63/// use iced::widget::vertical_slider;
64///
65/// struct State {
66///    value: f32,
67/// }
68///
69/// #[derive(Debug, Clone)]
70/// enum Message {
71///     ValueChanged(f32),
72/// }
73///
74/// fn view(state: &State) -> Element<'_, Message> {
75///     vertical_slider(0.0..=100.0, state.value, Message::ValueChanged).into()
76/// }
77///
78/// fn update(state: &mut State, message: Message) {
79///     match message {
80///         Message::ValueChanged(value) => {
81///             state.value = value;
82///         }
83///     }
84/// }
85/// ```
86pub struct VerticalSlider<'a, T, Message, Theme = crate::Theme>
87where
88    Theme: Catalog,
89{
90    range: RangeInclusive<T>,
91    step: T,
92    shift_step: Option<T>,
93    value: T,
94    default: Option<T>,
95    on_change: Box<dyn Fn(T) -> Message + 'a>,
96    on_release: Option<Message>,
97    width: f32,
98    height: Length,
99    class: Theme::Class<'a>,
100    status: Option<Status>,
101}
102
103impl<'a, T, Message, Theme> VerticalSlider<'a, T, Message, Theme>
104where
105    T: Copy + From<u8> + std::cmp::PartialOrd,
106    Message: Clone,
107    Theme: Catalog,
108{
109    /// The default width of a [`VerticalSlider`].
110    pub const DEFAULT_WIDTH: f32 = 16.0;
111
112    /// Creates a new [`VerticalSlider`].
113    ///
114    /// It expects:
115    ///   * an inclusive range of possible values
116    ///   * the current value of the [`VerticalSlider`]
117    ///   * a function that will be called when the [`VerticalSlider`] is dragged.
118    ///     It receives the new value of the [`VerticalSlider`] and must produce a
119    ///     `Message`.
120    pub fn new<F>(range: RangeInclusive<T>, value: T, on_change: F) -> Self
121    where
122        F: 'a + Fn(T) -> Message,
123    {
124        let value = if value >= *range.start() {
125            value
126        } else {
127            *range.start()
128        };
129
130        let value = if value <= *range.end() {
131            value
132        } else {
133            *range.end()
134        };
135
136        VerticalSlider {
137            value,
138            default: None,
139            range,
140            step: T::from(1),
141            shift_step: None,
142            on_change: Box::new(on_change),
143            on_release: None,
144            width: Self::DEFAULT_WIDTH,
145            height: Length::Fill,
146            class: Theme::default(),
147            status: None,
148        }
149    }
150
151    /// Sets the optional default value for the [`VerticalSlider`].
152    ///
153    /// If set, the [`VerticalSlider`] will reset to this value when ctrl-clicked or command-clicked.
154    pub fn default(mut self, default: impl Into<T>) -> Self {
155        self.default = Some(default.into());
156        self
157    }
158
159    /// Sets the release message of the [`VerticalSlider`].
160    /// This is called when the mouse is released from the slider.
161    ///
162    /// Typically, the user's interaction with the slider is finished when this message is produced.
163    /// This is useful if you need to spawn a long-running task from the slider's result, where
164    /// the default on_change message could create too many events.
165    pub fn on_release(mut self, on_release: Message) -> Self {
166        self.on_release = Some(on_release);
167        self
168    }
169
170    /// Sets the width of the [`VerticalSlider`].
171    pub fn width(mut self, width: impl Into<Pixels>) -> Self {
172        self.width = width.into().0;
173        self
174    }
175
176    /// Sets the height of the [`VerticalSlider`].
177    pub fn height(mut self, height: impl Into<Length>) -> Self {
178        self.height = height.into();
179        self
180    }
181
182    /// Sets the step size of the [`VerticalSlider`].
183    pub fn step(mut self, step: T) -> Self {
184        self.step = step;
185        self
186    }
187
188    /// Sets the optional "shift" step for the [`VerticalSlider`].
189    ///
190    /// If set, this value is used as the step while the shift key is pressed.
191    pub fn shift_step(mut self, shift_step: impl Into<T>) -> Self {
192        self.shift_step = Some(shift_step.into());
193        self
194    }
195
196    /// Sets the style of the [`VerticalSlider`].
197    #[must_use]
198    pub fn style(mut self, style: impl Fn(&Theme, Status) -> Style + 'a) -> Self
199    where
200        Theme::Class<'a>: From<StyleFn<'a, Theme>>,
201    {
202        self.class = (Box::new(style) as StyleFn<'a, Theme>).into();
203        self
204    }
205
206    /// Sets the style class of the [`VerticalSlider`].
207    #[cfg(feature = "advanced")]
208    #[must_use]
209    pub fn class(mut self, class: impl Into<Theme::Class<'a>>) -> Self {
210        self.class = class.into();
211        self
212    }
213}
214
215impl<T, Message, Theme, Renderer> Widget<Message, Theme, Renderer>
216    for VerticalSlider<'_, T, Message, Theme>
217where
218    T: Copy + num_traits::AsPrimitive<f64> + num_traits::FromPrimitive,
219    Message: Clone,
220    Theme: Catalog,
221    Renderer: core::Renderer,
222{
223    fn tag(&self) -> tree::Tag {
224        tree::Tag::of::<State>()
225    }
226
227    fn state(&self) -> tree::State {
228        tree::State::new(State::default())
229    }
230
231    fn size(&self) -> Size<Length> {
232        Size {
233            width: Length::Shrink,
234            height: self.height,
235        }
236    }
237
238    fn layout(
239        &mut self,
240        _tree: &mut Tree,
241        _renderer: &Renderer,
242        limits: &layout::Limits,
243    ) -> layout::Node {
244        layout::atomic(limits, self.width, self.height)
245    }
246
247    fn update(
248        &mut self,
249        tree: &mut Tree,
250        event: &Event,
251        layout: Layout<'_>,
252        cursor: mouse::Cursor,
253        _renderer: &Renderer,
254        shell: &mut Shell<'_, Message>,
255        _viewport: &Rectangle,
256    ) {
257        let state = tree.state.downcast_mut::<State>();
258        let is_dragging = state.is_dragging;
259        let current_value = self.value;
260
261        let locate = |cursor_position: Point| -> Option<T> {
262            let bounds = layout.bounds();
263
264            if cursor_position.y >= bounds.y + bounds.height {
265                Some(*self.range.start())
266            } else if cursor_position.y <= bounds.y {
267                Some(*self.range.end())
268            } else {
269                let step = if state.keyboard_modifiers.shift() {
270                    self.shift_step.unwrap_or(self.step)
271                } else {
272                    self.step
273                }
274                .as_();
275
276                let start = (*self.range.start()).as_();
277                let end = (*self.range.end()).as_();
278
279                let percent =
280                    1.0 - f64::from(cursor_position.y - bounds.y) / f64::from(bounds.height);
281
282                let steps = (percent * (end - start) / step).round();
283                let value = steps * step + start;
284
285                T::from_f64(value.min(end))
286            }
287        };
288
289        let increment = |value: T| -> Option<T> {
290            let step = if state.keyboard_modifiers.shift() {
291                self.shift_step.unwrap_or(self.step)
292            } else {
293                self.step
294            }
295            .as_();
296
297            let steps = (value.as_() / step).round();
298            let new_value = step * (steps + 1.0);
299
300            if new_value > (*self.range.end()).as_() {
301                return Some(*self.range.end());
302            }
303
304            T::from_f64(new_value)
305        };
306
307        let decrement = |value: T| -> Option<T> {
308            let step = if state.keyboard_modifiers.shift() {
309                self.shift_step.unwrap_or(self.step)
310            } else {
311                self.step
312            }
313            .as_();
314
315            let steps = (value.as_() / step).round();
316            let new_value = step * (steps - 1.0);
317
318            if new_value < (*self.range.start()).as_() {
319                return Some(*self.range.start());
320            }
321
322            T::from_f64(new_value)
323        };
324
325        let change = |new_value: T| {
326            if (self.value.as_() - new_value.as_()).abs() > f64::EPSILON {
327                shell.publish((self.on_change)(new_value));
328
329                self.value = new_value;
330            }
331        };
332
333        match event {
334            Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left))
335            | Event::Touch(touch::Event::FingerPressed { .. }) => {
336                if let Some(cursor_position) = cursor.position_over(layout.bounds()) {
337                    if state.keyboard_modifiers.control() || state.keyboard_modifiers.command() {
338                        let _ = self.default.map(change);
339                        state.is_dragging = false;
340                    } else {
341                        let _ = locate(cursor_position).map(change);
342                        state.is_dragging = true;
343                    }
344
345                    shell.capture_event();
346                }
347            }
348            Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left))
349            | Event::Touch(touch::Event::FingerLifted { .. })
350            | Event::Touch(touch::Event::FingerLost { .. })
351                if is_dragging =>
352            {
353                if let Some(on_release) = self.on_release.clone() {
354                    shell.publish(on_release);
355                }
356                state.is_dragging = false;
357            }
358            Event::Mouse(mouse::Event::CursorMoved { .. })
359            | Event::Touch(touch::Event::FingerMoved { .. })
360                if is_dragging =>
361            {
362                let _ = cursor.land().position().and_then(locate).map(change);
363
364                shell.capture_event();
365            }
366            Event::Mouse(mouse::Event::WheelScrolled { delta })
367                if state.keyboard_modifiers.control() && cursor.is_over(layout.bounds()) =>
368            {
369                let delta = match *delta {
370                    mouse::ScrollDelta::Lines { x: _, y } => y,
371                    mouse::ScrollDelta::Pixels { x: _, y } => y,
372                };
373
374                if delta < 0.0 {
375                    let _ = decrement(current_value).map(change);
376                } else {
377                    let _ = increment(current_value).map(change);
378                }
379
380                shell.capture_event();
381            }
382            Event::Keyboard(keyboard::Event::KeyPressed { key, .. })
383                if cursor.is_over(layout.bounds()) =>
384            {
385                match key {
386                    Key::Named(key::Named::ArrowUp) => {
387                        let _ = increment(current_value).map(change);
388                        shell.capture_event();
389                    }
390                    Key::Named(key::Named::ArrowDown) => {
391                        let _ = decrement(current_value).map(change);
392                        shell.capture_event();
393                    }
394                    _ => (),
395                }
396            }
397            Event::Keyboard(keyboard::Event::ModifiersChanged(modifiers)) => {
398                state.keyboard_modifiers = *modifiers;
399            }
400            _ => {}
401        }
402
403        let current_status = if state.is_dragging {
404            Status::Dragged
405        } else if cursor.is_over(layout.bounds()) {
406            Status::Hovered
407        } else {
408            Status::Active
409        };
410
411        if let Event::Window(window::Event::RedrawRequested(_now)) = event {
412            self.status = Some(current_status);
413        } else if self.status.is_some_and(|status| status != current_status) {
414            shell.request_redraw();
415        }
416    }
417
418    fn draw(
419        &self,
420        _tree: &Tree,
421        renderer: &mut Renderer,
422        theme: &Theme,
423        _style: &renderer::Style,
424        layout: Layout<'_>,
425        _cursor: mouse::Cursor,
426        _viewport: &Rectangle,
427    ) {
428        let bounds = layout.bounds();
429
430        let style = theme.style(&self.class, self.status.unwrap_or(Status::Active));
431
432        let (handle_width, handle_height, handle_border_radius) = match style.handle.shape {
433            HandleShape::Circle { radius } => (radius * 2.0, radius * 2.0, radius.into()),
434            HandleShape::Rectangle {
435                width,
436                border_radius,
437            } => (f32::from(width), bounds.width, border_radius),
438        };
439
440        let value = self.value.as_() as f32;
441        let (range_start, range_end) = {
442            let (start, end) = self.range.clone().into_inner();
443
444            (start.as_() as f32, end.as_() as f32)
445        };
446
447        let offset = if range_start >= range_end {
448            0.0
449        } else {
450            (bounds.height - handle_width) * (value - range_end) / (range_start - range_end)
451        };
452
453        let rail_x = bounds.x + bounds.width / 2.0;
454
455        renderer.fill_quad(
456            renderer::Quad {
457                bounds: Rectangle {
458                    x: rail_x - style.rail.width / 2.0,
459                    y: bounds.y,
460                    width: style.rail.width,
461                    height: offset + handle_width / 2.0,
462                },
463                border: style.rail.border,
464                ..renderer::Quad::default()
465            },
466            style.rail.backgrounds.1,
467        );
468
469        renderer.fill_quad(
470            renderer::Quad {
471                bounds: Rectangle {
472                    x: rail_x - style.rail.width / 2.0,
473                    y: bounds.y + offset + handle_width / 2.0,
474                    width: style.rail.width,
475                    height: bounds.height - offset - handle_width / 2.0,
476                },
477                border: style.rail.border,
478                ..renderer::Quad::default()
479            },
480            style.rail.backgrounds.0,
481        );
482
483        renderer.fill_quad(
484            renderer::Quad {
485                bounds: Rectangle {
486                    x: rail_x - handle_height / 2.0,
487                    y: bounds.y + offset,
488                    width: handle_height,
489                    height: handle_width,
490                },
491                border: Border {
492                    radius: handle_border_radius,
493                    width: style.handle.border_width,
494                    color: style.handle.border_color,
495                },
496                ..renderer::Quad::default()
497            },
498            style.handle.background,
499        );
500    }
501
502    fn mouse_interaction(
503        &self,
504        tree: &Tree,
505        layout: Layout<'_>,
506        cursor: mouse::Cursor,
507        _viewport: &Rectangle,
508        _renderer: &Renderer,
509    ) -> mouse::Interaction {
510        let state = tree.state.downcast_ref::<State>();
511
512        if state.is_dragging {
513            // FIXME: Fall back to `Pointer` on Windows
514            // See https://github.com/rust-windowing/winit/issues/1043
515            if cfg!(target_os = "windows") {
516                mouse::Interaction::Pointer
517            } else {
518                mouse::Interaction::Grabbing
519            }
520        } else if cursor.is_over(layout.bounds()) {
521            if cfg!(target_os = "windows") {
522                mouse::Interaction::Pointer
523            } else {
524                mouse::Interaction::Grab
525            }
526        } else {
527            mouse::Interaction::default()
528        }
529    }
530}
531
532impl<'a, T, Message, Theme, Renderer> From<VerticalSlider<'a, T, Message, Theme>>
533    for Element<'a, Message, Theme, Renderer>
534where
535    T: Copy + num_traits::AsPrimitive<f64> + num_traits::FromPrimitive + 'a,
536    Message: Clone + 'a,
537    Theme: Catalog + 'a,
538    Renderer: core::Renderer + 'a,
539{
540    fn from(
541        slider: VerticalSlider<'a, T, Message, Theme>,
542    ) -> Element<'a, Message, Theme, Renderer> {
543        Element::new(slider)
544    }
545}
546
547#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
548struct State {
549    is_dragging: bool,
550    keyboard_modifiers: keyboard::Modifiers,
551}
iced_widget/vertical_slider.rs

iced_widget/
vertical_slider.rs
