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, Clipboard, Color, Element, Event, Layout, Length, Pixels,
42    Point, Rectangle, Shell, Size, 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/// # Example
56/// ```no_run
57/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
58/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
59/// #
60/// use iced::widget::slider;
61///
62/// struct State {
63///    value: f32,
64/// }
65///
66/// #[derive(Debug, Clone)]
67/// enum Message {
68///     ValueChanged(f32),
69/// }
70///
71/// fn view(state: &State) -> Element<'_, Message> {
72///     slider(0.0..=100.0, state.value, Message::ValueChanged).into()
73/// }
74///
75/// fn update(state: &mut State, message: Message) {
76///     match message {
77///         Message::ValueChanged(value) => {
78///             state.value = value;
79///         }
80///     }
81/// }
82/// ```
83pub struct Slider<'a, T, Message, Theme = crate::Theme>
84where
85    Theme: Catalog,
86{
87    range: RangeInclusive<T>,
88    step: T,
89    shift_step: Option<T>,
90    value: T,
91    default: Option<T>,
92    on_change: Box<dyn Fn(T) -> Message + 'a>,
93    on_release: Option<Message>,
94    width: Length,
95    height: f32,
96    class: Theme::Class<'a>,
97    status: Option<Status>,
98}
99
100impl<'a, T, Message, Theme> Slider<'a, T, Message, Theme>
101where
102    T: Copy + From<u8> + PartialOrd,
103    Message: Clone,
104    Theme: Catalog,
105{
106    /// The default height of a [`Slider`].
107    pub const DEFAULT_HEIGHT: f32 = 16.0;
108
109    /// Creates a new [`Slider`].
110    ///
111    /// It expects:
112    ///   * an inclusive range of possible values
113    ///   * the current value of the [`Slider`]
114    ///   * a function that will be called when the [`Slider`] is dragged.
115    ///     It receives the new value of the [`Slider`] and must produce a
116    ///     `Message`.
117    pub fn new<F>(range: RangeInclusive<T>, value: T, on_change: F) -> Self
118    where
119        F: 'a + Fn(T) -> Message,
120    {
121        let value = if value >= *range.start() {
122            value
123        } else {
124            *range.start()
125        };
126
127        let value = if value <= *range.end() {
128            value
129        } else {
130            *range.end()
131        };
132
133        Slider {
134            value,
135            default: None,
136            range,
137            step: T::from(1),
138            shift_step: None,
139            on_change: Box::new(on_change),
140            on_release: None,
141            width: Length::Fill,
142            height: Self::DEFAULT_HEIGHT,
143            class: Theme::default(),
144            status: None,
145        }
146    }
147
148    /// Sets the optional default value for the [`Slider`].
149    ///
150    /// If set, the [`Slider`] will reset to this value when ctrl-clicked or command-clicked.
151    pub fn default(mut self, default: impl Into<T>) -> Self {
152        self.default = Some(default.into());
153        self
154    }
155
156    /// Sets the release message of the [`Slider`].
157    /// This is called when the mouse is released from the slider.
158    ///
159    /// Typically, the user's interaction with the slider is finished when this message is produced.
160    /// This is useful if you need to spawn a long-running task from the slider's result, where
161    /// the default on_change message could create too many events.
162    pub fn on_release(mut self, on_release: Message) -> Self {
163        self.on_release = Some(on_release);
164        self
165    }
166
167    /// Sets the width of the [`Slider`].
168    pub fn width(mut self, width: impl Into<Length>) -> Self {
169        self.width = width.into();
170        self
171    }
172
173    /// Sets the height of the [`Slider`].
174    pub fn height(mut self, height: impl Into<Pixels>) -> Self {
175        self.height = height.into().0;
176        self
177    }
178
179    /// Sets the step size of the [`Slider`].
180    pub fn step(mut self, step: impl Into<T>) -> Self {
181        self.step = step.into();
182        self
183    }
184
185    /// Sets the optional "shift" step for the [`Slider`].
186    ///
187    /// If set, this value is used as the step while the shift key is pressed.
188    pub fn shift_step(mut self, shift_step: impl Into<T>) -> Self {
189        self.shift_step = Some(shift_step.into());
190        self
191    }
192
193    /// Sets the style of the [`Slider`].
194    #[must_use]
195    pub fn style(mut self, style: impl Fn(&Theme, Status) -> Style + 'a) -> Self
196    where
197        Theme::Class<'a>: From<StyleFn<'a, Theme>>,
198    {
199        self.class = (Box::new(style) as StyleFn<'a, Theme>).into();
200        self
201    }
202
203    /// Sets the style class of the [`Slider`].
204    #[cfg(feature = "advanced")]
205    #[must_use]
206    pub fn class(mut self, class: impl Into<Theme::Class<'a>>) -> Self {
207        self.class = class.into();
208        self
209    }
210}
211
212impl<T, Message, Theme, Renderer> Widget<Message, Theme, Renderer>
213    for Slider<'_, T, Message, Theme>
214where
215    T: Copy + Into<f64> + num_traits::FromPrimitive,
216    Message: Clone,
217    Theme: Catalog,
218    Renderer: core::Renderer,
219{
220    fn tag(&self) -> tree::Tag {
221        tree::Tag::of::<State>()
222    }
223
224    fn state(&self) -> tree::State {
225        tree::State::new(State::default())
226    }
227
228    fn size(&self) -> Size<Length> {
229        Size {
230            width: self.width,
231            height: Length::Shrink,
232        }
233    }
234
235    fn layout(
236        &mut self,
237        _tree: &mut Tree,
238        _renderer: &Renderer,
239        limits: &layout::Limits,
240    ) -> layout::Node {
241        layout::atomic(limits, self.width, self.height)
242    }
243
244    fn update(
245        &mut self,
246        tree: &mut Tree,
247        event: &Event,
248        layout: Layout<'_>,
249        cursor: mouse::Cursor,
250        _renderer: &Renderer,
251        _clipboard: &mut dyn Clipboard,
252        shell: &mut Shell<'_, Message>,
253        _viewport: &Rectangle,
254    ) {
255        let state = tree.state.downcast_mut::<State>();
256
257        let mut update = || {
258            let current_value = self.value;
259
260            let locate = |cursor_position: Point| -> Option<T> {
261                let bounds = layout.bounds();
262
263                if cursor_position.x <= bounds.x {
264                    Some(*self.range.start())
265                } else if cursor_position.x >= bounds.x + bounds.width {
266                    Some(*self.range.end())
267                } else {
268                    let step = if state.keyboard_modifiers.shift() {
269                        self.shift_step.unwrap_or(self.step)
270                    } else {
271                        self.step
272                    }
273                    .into();
274
275                    let start = (*self.range.start()).into();
276                    let end = (*self.range.end()).into();
277
278                    let percent = f64::from(cursor_position.x - bounds.x)
279                        / 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                .into();
295
296                let steps = (value.into() / step).round();
297                let new_value = step * (steps + 1.0);
298
299                if new_value > (*self.range.end()).into() {
300                    return Some(*self.range.end());
301                }
302
303                T::from_f64(new_value)
304            };
305
306            let decrement = |value: T| -> Option<T> {
307                let step = if state.keyboard_modifiers.shift() {
308                    self.shift_step.unwrap_or(self.step)
309                } else {
310                    self.step
311                }
312                .into();
313
314                let steps = (value.into() / step).round();
315                let new_value = step * (steps - 1.0);
316
317                if new_value < (*self.range.start()).into() {
318                    return Some(*self.range.start());
319                }
320
321                T::from_f64(new_value)
322            };
323
324            let change = |new_value: T| {
325                if (self.value.into() - new_value.into()).abs() > f64::EPSILON {
326                    shell.publish((self.on_change)(new_value));
327
328                    self.value = new_value;
329                }
330            };
331
332            match &event {
333                Event::Mouse(mouse::Event::ButtonPressed(
334                    mouse::Button::Left,
335                ))
336                | Event::Touch(touch::Event::FingerPressed { .. }) => {
337                    if let Some(cursor_position) =
338                        cursor.position_over(layout.bounds())
339                    {
340                        if state.keyboard_modifiers.command() {
341                            let _ = self.default.map(change);
342                            state.is_dragging = false;
343                        } else {
344                            let _ = locate(cursor_position).map(change);
345                            state.is_dragging = true;
346                        }
347
348                        shell.capture_event();
349                    }
350                }
351                Event::Mouse(mouse::Event::ButtonReleased(
352                    mouse::Button::Left,
353                ))
354                | Event::Touch(touch::Event::FingerLifted { .. })
355                | Event::Touch(touch::Event::FingerLost { .. }) => {
356                    if state.is_dragging {
357                        if let Some(on_release) = self.on_release.clone() {
358                            shell.publish(on_release);
359                        }
360                        state.is_dragging = false;
361
362                        shell.capture_event();
363                    }
364                }
365                Event::Mouse(mouse::Event::CursorMoved { .. })
366                | Event::Touch(touch::Event::FingerMoved { .. }) => {
367                    if state.is_dragging {
368                        let _ = cursor.position().and_then(locate).map(change);
369
370                        shell.capture_event();
371                    }
372                }
373                Event::Mouse(mouse::Event::WheelScrolled { delta })
374                    if state.keyboard_modifiers.control() =>
375                {
376                    if cursor.is_over(layout.bounds()) {
377                        let delta = match delta {
378                            mouse::ScrollDelta::Lines { x: _, y } => y,
379                            mouse::ScrollDelta::Pixels { x: _, y } => y,
380                        };
381
382                        if *delta < 0.0 {
383                            let _ = decrement(current_value).map(change);
384                        } else {
385                            let _ = increment(current_value).map(change);
386                        }
387
388                        shell.capture_event();
389                    }
390                }
391                Event::Keyboard(keyboard::Event::KeyPressed {
392                    key, ..
393                }) => {
394                    if cursor.is_over(layout.bounds()) {
395                        match key {
396                            Key::Named(key::Named::ArrowUp) => {
397                                let _ = increment(current_value).map(change);
398                            }
399                            Key::Named(key::Named::ArrowDown) => {
400                                let _ = decrement(current_value).map(change);
401                            }
402                            _ => (),
403                        }
404
405                        shell.capture_event();
406                    }
407                }
408                Event::Keyboard(keyboard::Event::ModifiersChanged(
409                    modifiers,
410                )) => {
411                    state.keyboard_modifiers = *modifiers;
412                }
413                _ => {}
414            }
415        };
416
417        update();
418
419        let current_status = if state.is_dragging {
420            Status::Dragged
421        } else if cursor.is_over(layout.bounds()) {
422            Status::Hovered
423        } else {
424            Status::Active
425        };
426
427        if let Event::Window(window::Event::RedrawRequested(_now)) = event {
428            self.status = Some(current_status);
429        } else if self.status.is_some_and(|status| status != current_status) {
430            shell.request_redraw();
431        }
432    }
433
434    fn draw(
435        &self,
436        _tree: &Tree,
437        renderer: &mut Renderer,
438        theme: &Theme,
439        _style: &renderer::Style,
440        layout: Layout<'_>,
441        _cursor: mouse::Cursor,
442        _viewport: &Rectangle,
443    ) {
444        let bounds = layout.bounds();
445
446        let style =
447            theme.style(&self.class, self.status.unwrap_or(Status::Active));
448
449        let (handle_width, handle_height, handle_border_radius) =
450            match style.handle.shape {
451                HandleShape::Circle { radius } => {
452                    (radius * 2.0, radius * 2.0, radius.into())
453                }
454                HandleShape::Rectangle {
455                    width,
456                    border_radius,
457                } => (f32::from(width), bounds.height, border_radius),
458            };
459
460        let value = self.value.into() as f32;
461        let (range_start, range_end) = {
462            let (start, end) = self.range.clone().into_inner();
463
464            (start.into() as f32, end.into() as f32)
465        };
466
467        let offset = if range_start >= range_end {
468            0.0
469        } else {
470            (bounds.width - handle_width) * (value - range_start)
471                / (range_end - range_start)
472        };
473
474        let rail_y = bounds.y + bounds.height / 2.0;
475
476        renderer.fill_quad(
477            renderer::Quad {
478                bounds: Rectangle {
479                    x: bounds.x,
480                    y: rail_y - style.rail.width / 2.0,
481                    width: offset + handle_width / 2.0,
482                    height: style.rail.width,
483                },
484                border: style.rail.border,
485                ..renderer::Quad::default()
486            },
487            style.rail.backgrounds.0,
488        );
489
490        renderer.fill_quad(
491            renderer::Quad {
492                bounds: Rectangle {
493                    x: bounds.x + offset + handle_width / 2.0,
494                    y: rail_y - style.rail.width / 2.0,
495                    width: bounds.width - offset - handle_width / 2.0,
496                    height: style.rail.width,
497                },
498                border: style.rail.border,
499                ..renderer::Quad::default()
500            },
501            style.rail.backgrounds.1,
502        );
503
504        renderer.fill_quad(
505            renderer::Quad {
506                bounds: Rectangle {
507                    x: bounds.x + offset,
508                    y: rail_y - handle_height / 2.0,
509                    width: handle_width,
510                    height: handle_height,
511                },
512                border: Border {
513                    radius: handle_border_radius,
514                    width: style.handle.border_width,
515                    color: style.handle.border_color,
516                },
517                ..renderer::Quad::default()
518            },
519            style.handle.background,
520        );
521    }
522
523    fn mouse_interaction(
524        &self,
525        tree: &Tree,
526        layout: Layout<'_>,
527        cursor: mouse::Cursor,
528        _viewport: &Rectangle,
529        _renderer: &Renderer,
530    ) -> mouse::Interaction {
531        let state = tree.state.downcast_ref::<State>();
532        let bounds = layout.bounds();
533        let is_mouse_over = cursor.is_over(bounds);
534
535        if state.is_dragging {
536            mouse::Interaction::Grabbing
537        } else if is_mouse_over {
538            mouse::Interaction::Grab
539        } else {
540            mouse::Interaction::default()
541        }
542    }
543}
544
545impl<'a, T, Message, Theme, Renderer> From<Slider<'a, T, Message, Theme>>
546    for Element<'a, Message, Theme, Renderer>
547where
548    T: Copy + Into<f64> + num_traits::FromPrimitive + 'a,
549    Message: Clone + 'a,
550    Theme: Catalog + 'a,
551    Renderer: core::Renderer + 'a,
552{
553    fn from(
554        slider: Slider<'a, T, Message, Theme>,
555    ) -> Element<'a, Message, Theme, Renderer> {
556        Element::new(slider)
557    }
558}
559
560#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
561struct State {
562    is_dragging: bool,
563    keyboard_modifiers: keyboard::Modifiers,
564}
565
566/// The possible status of a [`Slider`].
567#[derive(Debug, Clone, Copy, PartialEq, Eq)]
568pub enum Status {
569    /// The [`Slider`] can be interacted with.
570    Active,
571    /// The [`Slider`] is being hovered.
572    Hovered,
573    /// The [`Slider`] is being dragged.
574    Dragged,
575}
576
577/// The appearance of a slider.
578#[derive(Debug, Clone, Copy, PartialEq)]
579pub struct Style {
580    /// The colors of the rail of the slider.
581    pub rail: Rail,
582    /// The appearance of the [`Handle`] of the slider.
583    pub handle: Handle,
584}
585
586impl Style {
587    /// Changes the [`HandleShape`] of the [`Style`] to a circle
588    /// with the given radius.
589    pub fn with_circular_handle(mut self, radius: impl Into<Pixels>) -> Self {
590        self.handle.shape = HandleShape::Circle {
591            radius: radius.into().0,
592        };
593        self
594    }
595}
596
597/// The appearance of a slider rail
598#[derive(Debug, Clone, Copy, PartialEq)]
599pub struct Rail {
600    /// The backgrounds of the rail of the slider.
601    pub backgrounds: (Background, Background),
602    /// The width of the stroke of a slider rail.
603    pub width: f32,
604    /// The border of the rail.
605    pub border: Border,
606}
607
608/// The appearance of the handle of a slider.
609#[derive(Debug, Clone, Copy, PartialEq)]
610pub struct Handle {
611    /// The shape of the handle.
612    pub shape: HandleShape,
613    /// The [`Background`] of the handle.
614    pub background: Background,
615    /// The border width of the handle.
616    pub border_width: f32,
617    /// The border [`Color`] of the handle.
618    pub border_color: Color,
619}
620
621/// The shape of the handle of a slider.
622#[derive(Debug, Clone, Copy, PartialEq)]
623pub enum HandleShape {
624    /// A circular handle.
625    Circle {
626        /// The radius of the circle.
627        radius: f32,
628    },
629    /// A rectangular shape.
630    Rectangle {
631        /// The width of the rectangle.
632        width: u16,
633        /// The border radius of the corners of the rectangle.
634        border_radius: border::Radius,
635    },
636}
637
638/// The theme catalog of a [`Slider`].
639pub trait Catalog: Sized {
640    /// The item class of the [`Catalog`].
641    type Class<'a>;
642
643    /// The default class produced by the [`Catalog`].
644    fn default<'a>() -> Self::Class<'a>;
645
646    /// The [`Style`] of a class with the given status.
647    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style;
648}
649
650/// A styling function for a [`Slider`].
651pub type StyleFn<'a, Theme> = Box<dyn Fn(&Theme, Status) -> Style + 'a>;
652
653impl Catalog for Theme {
654    type Class<'a> = StyleFn<'a, Self>;
655
656    fn default<'a>() -> Self::Class<'a> {
657        Box::new(default)
658    }
659
660    fn style(&self, class: &Self::Class<'_>, status: Status) -> Style {
661        class(self, status)
662    }
663}
664
665/// The default style of a [`Slider`].
666pub fn default(theme: &Theme, status: Status) -> Style {
667    let palette = theme.extended_palette();
668
669    let color = match status {
670        Status::Active => palette.primary.base.color,
671        Status::Hovered => palette.primary.strong.color,
672        Status::Dragged => palette.primary.weak.color,
673    };
674
675    Style {
676        rail: Rail {
677            backgrounds: (color.into(), palette.background.strong.color.into()),
678            width: 4.0,
679            border: Border {
680                radius: 2.0.into(),
681                width: 0.0,
682                color: Color::TRANSPARENT,
683            },
684        },
685        handle: Handle {
686            shape: HandleShape::Circle { radius: 7.0 },
687            background: color.into(),
688            border_color: Color::TRANSPARENT,
689            border_width: 0.0,
690        },
691    }
692}
iced_widget/slider.rs

iced_widget/
slider.rs
