iced_widget/
slider.rs

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

iced_widget/
slider.rs
