iced_widget/
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 crate::core::border::{self, Border};
32use crate::core::keyboard;
33use crate::core::keyboard::key::{self, Key};
34use crate::core::layout;
35use crate::core::mouse;
36use crate::core::renderer;
37use crate::core::touch;
38use crate::core::widget::tree::{self, Tree};
39use crate::core::window;
40use crate::core::{
41    self, Background, Color, Element, Event, Layout, Length, Pixels, Point, Rectangle, Shell, Size,
42    Theme, Widget,
43};
44
45use std::ops::RangeInclusive;
46
47/// An horizontal bar and a handle that selects a single value from a range of
48/// values.
49///
50/// A [`Slider`] will try to fill the horizontal space of its container.
51///
52/// The [`Slider`] range of numeric values is generic and its step size defaults
53/// to 1 unit.
54///
55/// Note: Under the hood values are converted to/from f64 so only values representable exactly as an f64
56/// are possible to select via the slider. However it is likely that the precision of the slider at these
57/// scales is already less than the precision lost from the f64 representation.
58///
59/// # Example
60/// ```no_run
61/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
62/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
63/// #
64/// use iced::widget::slider;
65///
66/// struct State {
67///    value: f32,
68/// }
69///
70/// #[derive(Debug, Clone)]
71/// enum Message {
72///     ValueChanged(f32),
73/// }
74///
75/// fn view(state: &State) -> Element<'_, Message> {
76///     slider(0.0..=100.0, state.value, Message::ValueChanged).into()
77/// }
78///
79/// fn update(state: &mut State, message: Message) {
80///     match message {
81///         Message::ValueChanged(value) => {
82///             state.value = value;
83///         }
84///     }
85/// }
86/// ```
87pub struct Slider<'a, T, Message, Theme = crate::Theme>
88where
89    Theme: Catalog,
90{
91    range: RangeInclusive<T>,
92    step: f64,
93    shift_step: Option<f64>,
94    value: T,
95    default: Option<T>,
96    on_change: Box<dyn Fn(T) -> Message + 'a>,
97    on_release: Option<Message>,
98    width: Length,
99    height: f32,
100    class: Theme::Class<'a>,
101    status: Option<Status>,
102}
103
104impl<'a, T, Message, Theme> Slider<'a, T, Message, Theme>
105where
106    T: Copy + PartialOrd,
107    Message: Clone,
108    Theme: Catalog,
109{
110    /// The default height of a [`Slider`].
111    pub const DEFAULT_HEIGHT: f32 = 16.0;
112
113    /// Creates a new [`Slider`].
114    ///
115    /// It expects:
116    ///   * an inclusive range of possible values
117    ///   * the current value of the [`Slider`]
118    ///   * a function that will be called when the [`Slider`] is dragged.
119    ///     It receives the new value of the [`Slider`] and must produce a
120    ///     `Message`.
121    pub fn new<F>(range: RangeInclusive<T>, value: T, on_change: F) -> Self
122    where
123        F: 'a + Fn(T) -> Message,
124    {
125        let value = if value >= *range.start() {
126            value
127        } else {
128            *range.start()
129        };
130
131        let value = if value <= *range.end() {
132            value
133        } else {
134            *range.end()
135        };
136
137        Slider {
138            value,
139            default: None,
140            range,
141            step: 1.0,
142            shift_step: None,
143            on_change: Box::new(on_change),
144            on_release: None,
145            width: Length::Fill,
146            height: Self::DEFAULT_HEIGHT,
147            class: Theme::default(),
148            status: None,
149        }
150    }
151
152    /// Sets the optional default value for the [`Slider`].
153    ///
154    /// If set, the [`Slider`] will reset to this value when ctrl-clicked or command-clicked.
155    pub fn default(mut self, default: impl Into<T>) -> Self {
156        self.default = Some(default.into());
157        self
158    }
159
160    /// Sets the release message of the [`Slider`].
161    /// This is called when the mouse is released from the slider.
162    ///
163    /// Typically, the user's interaction with the slider is finished when this message is produced.
164    /// This is useful if you need to spawn a long-running task from the slider's result, where
165    /// the default on_change message could create too many events.
166    pub fn on_release(mut self, on_release: Message) -> Self {
167        self.on_release = Some(on_release);
168        self
169    }
170
171    /// Sets the width of the [`Slider`].
172    pub fn width(mut self, width: impl Into<Length>) -> Self {
173        self.width = width.into();
174        self
175    }
176
177    /// Sets the height of the [`Slider`].
178    pub fn height(mut self, height: impl Into<Pixels>) -> Self {
179        self.height = height.into().0;
180        self
181    }
182
183    /// Sets the step size of the [`Slider`].
184    pub fn step(mut self, step: impl num_traits::AsPrimitive<f64>) -> Self {
185        self.step = step.as_();
186        self
187    }
188
189    /// Sets the optional "shift" step for the [`Slider`].
190    ///
191    /// If set, this value is used as the step while the shift key is pressed.
192    pub fn shift_step(mut self, shift_step: impl num_traits::AsPrimitive<f64>) -> Self {
193        self.shift_step = Some(shift_step.as_());
194        self
195    }
196
197    /// Sets the style of the [`Slider`].
198    #[must_use]
199    pub fn style(mut self, style: impl Fn(&Theme, Status) -> Style + 'a) -> Self
200    where
201        Theme::Class<'a>: From<StyleFn<'a, Theme>>,
202    {
203        self.class = (Box::new(style) as StyleFn<'a, Theme>).into();
204        self
205    }
206
207    /// Sets the style class of the [`Slider`].
208    #[cfg(feature = "advanced")]
209    #[must_use]
210    pub fn class(mut self, class: impl Into<Theme::Class<'a>>) -> Self {
211        self.class = class.into();
212        self
213    }
214}
215
216impl<T, Message, Theme, Renderer> Widget<Message, Theme, Renderer> for Slider<'_, 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: self.width,
234            height: Length::Shrink,
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
259        let mut update = || {
260            let current_value = self.value;
261
262            let locate = |cursor_position: Point| -> Option<T> {
263                let bounds = layout.bounds();
264
265                if cursor_position.x <= bounds.x {
266                    Some(*self.range.start())
267                } else if cursor_position.x >= bounds.x + bounds.width {
268                    Some(*self.range.end())
269                } else {
270                    let step = if state.keyboard_modifiers.shift() {
271                        self.shift_step.unwrap_or(self.step)
272                    } else {
273                        self.step
274                    };
275
276                    let start = (*self.range.start()).as_();
277                    let end = (*self.range.end()).as_();
278
279                    let percent = f64::from(cursor_position.x - bounds.x) / f64::from(bounds.width);
280
281                    let steps = (percent * (end - start) / step).round();
282                    let value = steps * step + start;
283
284                    T::from_f64(value.min(end))
285                }
286            };
287
288            let increment = |value: T| -> Option<T> {
289                let step = if state.keyboard_modifiers.shift() {
290                    self.shift_step.unwrap_or(self.step)
291                } else {
292                    self.step
293                };
294
295                let steps = (value.as_() / step).round();
296                let new_value = step * (steps + 1.0);
297
298                if new_value > (*self.range.end()).as_() {
299                    return Some(*self.range.end());
300                }
301
302                T::from_f64(new_value)
303            };
304
305            let decrement = |value: T| -> Option<T> {
306                let step = if state.keyboard_modifiers.shift() {
307                    self.shift_step.unwrap_or(self.step)
308                } else {
309                    self.step
310                };
311
312                let steps = (value.as_() / step).round();
313                let new_value = step * (steps - 1.0);
314
315                if new_value < (*self.range.start()).as_() {
316                    return Some(*self.range.start());
317                }
318
319                T::from_f64(new_value)
320            };
321
322            let change = |new_value: T| {
323                if (self.value.as_() - new_value.as_()).abs() > f64::EPSILON {
324                    shell.publish((self.on_change)(new_value));
325
326                    self.value = new_value;
327                }
328            };
329
330            match &event {
331                Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left))
332                | Event::Touch(touch::Event::FingerPressed { .. }) => {
333                    if let Some(cursor_position) = cursor.position_over(layout.bounds()) {
334                        if state.keyboard_modifiers.command() {
335                            let _ = self.default.map(change);
336                            state.is_dragging = false;
337                        } else {
338                            let _ = locate(cursor_position).map(change);
339                            state.is_dragging = true;
340                        }
341
342                        shell.capture_event();
343                    }
344                }
345                Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left))
346                | Event::Touch(touch::Event::FingerLifted { .. })
347                | Event::Touch(touch::Event::FingerLost { .. })
348                    if state.is_dragging =>
349                {
350                    if let Some(on_release) = self.on_release.clone() {
351                        shell.publish(on_release);
352                    }
353                    state.is_dragging = false;
354                }
355                Event::Mouse(mouse::Event::CursorMoved { .. })
356                | Event::Touch(touch::Event::FingerMoved { .. })
357                    if state.is_dragging =>
358                {
359                    let _ = cursor.land().position().and_then(locate).map(change);
360
361                    shell.capture_event();
362                }
363                Event::Mouse(mouse::Event::WheelScrolled { delta })
364                    if state.keyboard_modifiers.control() && cursor.is_over(layout.bounds()) =>
365                {
366                    let delta = match delta {
367                        mouse::ScrollDelta::Lines { x: _, y } => y,
368                        mouse::ScrollDelta::Pixels { x: _, y } => y,
369                    };
370
371                    if *delta < 0.0 {
372                        let _ = decrement(current_value).map(change);
373                    } else {
374                        let _ = increment(current_value).map(change);
375                    }
376
377                    shell.capture_event();
378                }
379                Event::Keyboard(keyboard::Event::KeyPressed { key, .. })
380                    if cursor.is_over(layout.bounds()) =>
381                {
382                    match key {
383                        Key::Named(key::Named::ArrowUp) => {
384                            let _ = increment(current_value).map(change);
385                            shell.capture_event();
386                        }
387                        Key::Named(key::Named::ArrowDown) => {
388                            let _ = decrement(current_value).map(change);
389                            shell.capture_event();
390                        }
391                        _ => (),
392                    }
393                }
394                Event::Keyboard(keyboard::Event::ModifiersChanged(modifiers)) => {
395                    state.keyboard_modifiers = *modifiers;
396                }
397                _ => {}
398            }
399        };
400
401        update();
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.height, 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.width - handle_width) * (value - range_start) / (range_end - range_start)
451        };
452
453        let rail_y = bounds.y + bounds.height / 2.0;
454
455        renderer.fill_quad(
456            renderer::Quad {
457                bounds: Rectangle {
458                    x: bounds.x,
459                    y: rail_y - style.rail.width / 2.0,
460                    width: offset + handle_width / 2.0,
461                    height: style.rail.width,
462                },
463                border: style.rail.border,
464                ..renderer::Quad::default()
465            },
466            style.rail.backgrounds.0,
467        );
468
469        renderer.fill_quad(
470            renderer::Quad {
471                bounds: Rectangle {
472                    x: bounds.x + offset + handle_width / 2.0,
473                    y: rail_y - style.rail.width / 2.0,
474                    width: bounds.width - offset - handle_width / 2.0,
475                    height: style.rail.width,
476                },
477                border: style.rail.border,
478                ..renderer::Quad::default()
479            },
480            style.rail.backgrounds.1,
481        );
482
483        renderer.fill_quad(
484            renderer::Quad {
485                bounds: Rectangle {
486                    x: bounds.x + offset,
487                    y: rail_y - handle_height / 2.0,
488                    width: handle_width,
489                    height: handle_height,
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<Slider<'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(slider: Slider<'a, T, Message, Theme>) -> Element<'a, Message, Theme, Renderer> {
541        Element::new(slider)
542    }
543}
544
545#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
546struct State {
547    is_dragging: bool,
548    keyboard_modifiers: keyboard::Modifiers,
549}
550
551/// The possible status of a [`Slider`].
552#[derive(Debug, Clone, Copy, PartialEq, Eq)]
553pub enum Status {
554    /// The [`Slider`] can be interacted with.
555    Active,
556    /// The [`Slider`] is being hovered.
557    Hovered,
558    /// The [`Slider`] is being dragged.
559    Dragged,
560}
561
562/// The appearance of a slider.
563#[derive(Debug, Clone, Copy, PartialEq)]
564pub struct Style {
565    /// The colors of the rail of the slider.
566    pub rail: Rail,
567    /// The appearance of the [`Handle`] of the slider.
568    pub handle: Handle,
569}
570
571impl Style {
572    /// Changes the [`HandleShape`] of the [`Style`] to a circle
573    /// with the given radius.
574    pub fn with_circular_handle(mut self, radius: impl Into<Pixels>) -> Self {
575        self.handle.shape = HandleShape::Circle {
576            radius: radius.into().0,
577        };
578        self
579    }
580}
581
582/// The appearance of a slider rail
583#[derive(Debug, Clone, Copy, PartialEq)]
584pub struct Rail {
585    /// The backgrounds of the rail of the slider.
586    pub backgrounds: (Background, Background),
587    /// The width of the stroke of a slider rail.
588    pub width: f32,
589    /// The border of the rail.
590    pub border: Border,
591}
592
593/// The appearance of the handle of a slider.
594#[derive(Debug, Clone, Copy, PartialEq)]
595pub struct Handle {
596    /// The shape of the handle.
597    pub shape: HandleShape,
598    /// The [`Background`] of the handle.
599    pub background: Background,
600    /// The border width of the handle.
601    pub border_width: f32,
602    /// The border [`Color`] of the handle.
603    pub border_color: Color,
604}
605
606/// The shape of the handle of a slider.
607#[derive(Debug, Clone, Copy, PartialEq)]
608pub enum HandleShape {
609    /// A circular handle.
610    Circle {
611        /// The radius of the circle.
612        radius: f32,
613    },
614    /// A rectangular shape.
615    Rectangle {
616        /// The width of the rectangle.
617        width: u16,
618        /// The border radius of the corners of the rectangle.
619        border_radius: border::Radius,
620    },
621}
622
623/// The theme catalog of a [`Slider`].
624pub trait Catalog: Sized {
625    /// The item class of the [`Catalog`].
626    type Class<'a>;
627
628    /// The default class produced by the [`Catalog`].
629    fn default<'a>() -> Self::Class<'a>;
630
631    /// The [`Style`] of a class with the given status.
632    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style;
633}
634
635/// A styling function for a [`Slider`].
636pub type StyleFn<'a, Theme> = Box<dyn Fn(&Theme, Status) -> Style + 'a>;
637
638impl Catalog for Theme {
639    type Class<'a> = StyleFn<'a, Self>;
640
641    fn default<'a>() -> Self::Class<'a> {
642        Box::new(default)
643    }
644
645    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style {
646        class(self, status)
647    }
648}
649
650/// The default style of a [`Slider`].
651pub fn default(theme: &Theme, status: Status) -> Style {
652    let palette = theme.palette();
653
654    let color = match status {
655        Status::Active => palette.primary.base.color,
656        Status::Hovered => palette.primary.strong.color,
657        Status::Dragged => palette.primary.weak.color,
658    };
659
660    Style {
661        rail: Rail {
662            backgrounds: (color.into(), palette.background.strong.color.into()),
663            width: 4.0,
664            border: Border {
665                radius: 2.0.into(),
666                width: 0.0,
667                color: Color::TRANSPARENT,
668            },
669        },
670        handle: Handle {
671            shape: HandleShape::Circle { radius: 7.0 },
672            background: color.into(),
673            border_color: Color::TRANSPARENT,
674            border_width: 0.0,
675        },
676    }
677}
iced_widget/slider.rs

iced_widget/
slider.rs
