Make scrollable programmatically scrollable for some use cases, add s…

…nap_to_bottom by default

native/src/widget/scrollable.rs

@@ -4,7 +4,7 @@ use crate::{
     Hasher, Layout, Length, Point, Rectangle, Size, Vector, Widget,
 };
 
-use std::{f32, hash::Hash, u32};
+use std::{cell::RefCell, f32, hash::Hash, u32};
 
 /// A widget that can vertically display an infinite amount of content with a
 /// scrollbar.
@@ -18,6 +18,8 @@ pub struct Scrollable<'a, Message, Renderer: self::Renderer> {
     scroller_width: u16,
     content: Column<'a, Message, Renderer>,
     style: Renderer::Style,
+    on_scroll: Option<Box<dyn Fn(f32, f32) -> Message>>,
+    snap_to_bottom: bool,
 }
 
 impl<'a, Message, Renderer: self::Renderer> Scrollable<'a, Message, Renderer> {
@@ -35,9 +37,36 @@ impl<'a, Message, Renderer: self::Renderer> Scrollable<'a, Message, Renderer> {
             scroller_width: 10,
             content: Column::new(),
             style: Renderer::Style::default(),
+            on_scroll: None,
+            snap_to_bottom: false,
         }
     }
 
+    /// Whether to set the [`Scrollable`] to snap to bottom when the user
+    /// scrolls to bottom or not. This will keep the scrollable at the bottom
+    /// even if new content is added to the scrollable.
+    ///
+    /// [`Scrollable`]: struct.Scrollable.html
+    pub fn snap_to_bottom(mut self, snap: bool) -> Self {
+        self.snap_to_bottom = snap;
+        self
+    }
+
+    /// Sets a function to call when the [`Scrollable`] is scrolled.
+    ///
+    /// The function takes two `f32` as arguments. First is the percentage of
+    /// where the scrollable is at right now. Second is the percentage of where
+    /// the scrollable was *before*. `0.0` means top and `1.0` means bottom.
+    ///
+    /// [`Scrollable`]: struct.Scrollable.html
+    pub fn on_scroll<F>(mut self, message_constructor: F) -> Self
+    where
+        F: 'static + Fn(f32, f32) -> Message,
+    {
+        self.on_scroll = Some(Box::new(message_constructor));
+        self
+    }
+
     /// Sets the vertical spacing _between_ elements.
     ///
     /// Custom margins per element do not exist in Iced. You should use this
@@ -191,6 +220,9 @@ where
         let content = layout.children().next().unwrap();
         let content_bounds = content.bounds();
 
+        self.state.prev_offset = self.state.offset(bounds, content_bounds);
+        let mut did_scroll = false;
+
         // TODO: Event capture. Nested scrollables should capture scroll events.
         if is_mouse_over {
             match event {
@@ -204,6 +236,7 @@ where
                             self.state.scroll(y, bounds, content_bounds);
                         }
                     }
+                    did_scroll = true;
                 }
                 _ => {}
             }
@@ -232,7 +265,7 @@ where
                 }
                 Event::Mouse(mouse::Event::CursorMoved { .. }) => {
                     if let (Some(scrollbar), Some(scroller_grabbed_at)) =
-                        (scrollbar, self.state.scroller_grabbed_at)
+                        (&scrollbar, self.state.scroller_grabbed_at)
                     {
                         self.state.scroll_to(
                             scrollbar.scroll_percentage(
@@ -242,6 +275,7 @@ where
                             bounds,
                             content_bounds,
                         );
+                        did_scroll = true;
                     }
                 }
                 _ => {}
@@ -251,7 +285,7 @@ where
                 Event::Mouse(mouse::Event::ButtonPressed(
                     mouse::Button::Left,
                 )) => {
-                    if let Some(scrollbar) = scrollbar {
+                    if let Some(scrollbar) = &scrollbar {
                         if let Some(scroller_grabbed_at) =
                             scrollbar.grab_scroller(cursor_position)
                         {
@@ -264,6 +298,8 @@ where
                                 content_bounds,
                             );
 
+                            did_scroll = true;
+
                             self.state.scroller_grabbed_at =
                                 Some(scroller_grabbed_at);
                         }
@@ -273,6 +309,32 @@ where
             }
         }
 
+        if did_scroll {
+            if self.snap_to_bottom {
+                let new_offset = self.state.offset(bounds, content_bounds);
+
+                if new_offset < self.state.prev_offset {
+                    self.state.snap_to_bottom = false;
+                } else {
+                    let scroll_perc = new_offset as f32
+                        / (content_bounds.height - bounds.height);
+
+                    if scroll_perc >= 1.0 - f32::EPSILON {
+                        self.state.snap_to_bottom = true;
+                    }
+                }
+            }
+
+            if let Some(on_scroll) = &self.on_scroll {
+                messages.push(on_scroll(
+                    self.state.offset(bounds, content_bounds) as f32
+                        / (content_bounds.height - bounds.height),
+                    self.state.prev_offset as f32
+                        / (content_bounds.height - bounds.height),
+                ));
+            }
+        }
+
         let cursor_position = if is_mouse_over && !is_mouse_over_scrollbar {
             Point::new(
                 cursor_position.x,
@@ -308,6 +370,15 @@ where
         let bounds = layout.bounds();
         let content_layout = layout.children().next().unwrap();
         let content_bounds = content_layout.bounds();
+
+        if self.state.snap_to_bottom {
+            self.state.scroll_to(1.0, bounds, content_bounds);
+        }
+
+        if let Some(scroll_to) = self.state.scroll_to.borrow_mut().take() {
+            self.state.scroll_to(scroll_to, bounds, content_bounds);
+        }
+
         let offset = self.state.offset(bounds, content_bounds);
         let scrollbar = renderer.scrollbar(
             bounds,
@@ -389,10 +460,13 @@ where
 /// The local state of a [`Scrollable`].
 ///
 /// [`Scrollable`]: struct.Scrollable.html
-#[derive(Debug, Clone, Copy, Default)]
+#[derive(Debug, Default, Clone)]
 pub struct State {
     scroller_grabbed_at: Option<f32>,
-    offset: f32,
+    prev_offset: u32,
+    snap_to_bottom: bool,
+    offset: RefCell<f32>,
+    scroll_to: RefCell<Option<f32>>,
 }
 
 impl State {
@@ -418,7 +492,8 @@ impl State {
             return;
         }
 
-        self.offset = (self.offset - delta_y)
+        let offset_val = *self.offset.borrow();
+        *self.offset.borrow_mut() = (offset_val - delta_y)
             .max(0.0)
             .min((content_bounds.height - bounds.height) as f32);
     }
@@ -432,15 +507,32 @@ impl State {
     /// [`Scrollable`]: struct.Scrollable.html
     /// [`State`]: struct.State.html
     pub fn scroll_to(
-        &mut self,
+        &self,
         percentage: f32,
         bounds: Rectangle,
         content_bounds: Rectangle,
     ) {
-        self.offset =
+        *self.offset.borrow_mut() =
             ((content_bounds.height - bounds.height) * percentage).max(0.0);
     }
 
+    /// Marks the scrollable to scroll to `perc` percentage (between 0.0 and 1.0)
+    /// in the next `draw` call.
+    ///
+    /// [`Scrollable`]: struct.Scrollable.html
+    /// [`State`]: struct.State.html
+    pub fn scroll_to_percentage(&mut self, perc: f32) {
+        *self.scroll_to.borrow_mut() = Some(perc.max(0.0).min(1.0));
+    }
+
+    /// Marks the scrollable to scroll to bottom in the next `draw` call.
+    ///
+    /// [`Scrollable`]: struct.Scrollable.html
+    /// [`State`]: struct.State.html
+    pub fn scroll_to_bottom(&mut self) {
+        self.scroll_to_percentage(1.0);
+    }
+
     /// Returns the current scrolling offset of the [`State`], given the bounds
     /// of the [`Scrollable`] and its contents.
     ///
@@ -450,7 +542,7 @@ impl State {
         let hidden_content =
             (content_bounds.height - bounds.height).max(0.0).round() as u32;
 
-        self.offset.min(hidden_content as f32) as u32
+        self.offset.borrow().min(hidden_content as f32) as u32
     }
 
     /// Returns whether the scroller is currently grabbed or not.