From 5d67f9988c14adfca4a7e67dc7a9ddcd860b1c78 Mon Sep 17 00:00:00 2001
From: Casper Rogild Storm <2248455+casperstorm@users.noreply.github.com>
Date: Fri, 22 Apr 2022 13:35:53 +0200
Subject: Implemented Tooltip as Pure

---
 pure/src/widget/tooltip.rs | 310 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 310 insertions(+)
 create mode 100644 pure/src/widget/tooltip.rs

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/tooltip.rs b/pure/src/widget/tooltip.rs
new file mode 100644
index 00000000..f0667e41
--- /dev/null
+++ b/pure/src/widget/tooltip.rs
@@ -0,0 +1,310 @@
+//! Display a widget over another.
+use crate::widget::Tree;
+use crate::{Element, Widget};
+use iced_native::event::{self, Event};
+use iced_native::widget::container;
+pub use iced_native::widget::Text;
+use iced_native::{layout, mouse, overlay};
+use iced_native::{renderer, Size};
+use iced_native::{text, Vector};
+use iced_native::{
+    Clipboard, Layout, Length, Padding, Point, Rectangle, Shell,
+};
+
+pub use iced_style::container::{Style, StyleSheet};
+
+/// An element to display a widget over another.
+#[allow(missing_debug_implementations)]
+pub struct Tooltip<'a, Message, Renderer: text::Renderer> {
+    content: Element<'a, Message, Renderer>,
+    tooltip: Text<Renderer>,
+    position: Position,
+    style_sheet: Box<dyn StyleSheet + 'a>,
+    gap: u16,
+    padding: u16,
+}
+
+impl<'a, Message, Renderer> Tooltip<'a, Message, Renderer>
+where
+    Renderer: text::Renderer,
+{
+    /// The default padding of a [`Tooltip`] drawn by this renderer.
+    const DEFAULT_PADDING: u16 = 5;
+
+    /// Creates an empty [`Tooltip`].
+    ///
+    /// [`Tooltip`]: struct.Tooltip.html
+    pub fn new(
+        content: impl Into<Element<'a, Message, Renderer>>,
+        tooltip: impl ToString,
+        position: Position,
+    ) -> Self {
+        Tooltip {
+            content: content.into(),
+            tooltip: Text::new(tooltip.to_string()),
+            position,
+            style_sheet: Default::default(),
+            gap: 0,
+            padding: Self::DEFAULT_PADDING,
+        }
+    }
+
+    /// Sets the size of the text of the [`Tooltip`].
+    pub fn size(mut self, size: u16) -> Self {
+        self.tooltip = self.tooltip.size(size);
+        self
+    }
+
+    /// Sets the font of the [`Tooltip`].
+    ///
+    /// [`Font`]: Renderer::Font
+    pub fn font(mut self, font: impl Into<Renderer::Font>) -> Self {
+        self.tooltip = self.tooltip.font(font);
+        self
+    }
+
+    /// Sets the gap between the content and its [`Tooltip`].
+    pub fn gap(mut self, gap: u16) -> Self {
+        self.gap = gap;
+        self
+    }
+
+    /// Sets the padding of the [`Tooltip`].
+    pub fn padding(mut self, padding: u16) -> Self {
+        self.padding = padding;
+        self
+    }
+
+    /// Sets the style of the [`Tooltip`].
+    pub fn style(
+        mut self,
+        style_sheet: impl Into<Box<dyn StyleSheet + 'a>>,
+    ) -> Self {
+        self.style_sheet = style_sheet.into();
+        self
+    }
+}
+
+/// The position of the tooltip. Defaults to following the cursor.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Position {
+    /// The tooltip will follow the cursor.
+    FollowCursor,
+    /// The tooltip will appear on the top of the widget.
+    Top,
+    /// The tooltip will appear on the bottom of the widget.
+    Bottom,
+    /// The tooltip will appear on the left of the widget.
+    Left,
+    /// The tooltip will appear on the right of the widget.
+    Right,
+}
+
+impl<'a, Message, Renderer> Widget<Message, Renderer>
+    for Tooltip<'a, Message, Renderer>
+where
+    Renderer: text::Renderer,
+{
+    fn children(&self) -> Vec<Tree> {
+        vec![Tree::new(&self.content)]
+    }
+
+    fn diff(&self, tree: &mut Tree) {
+        tree.diff_children(std::slice::from_ref(&self.content))
+    }
+
+    fn width(&self) -> Length {
+        self.content.as_widget().width()
+    }
+
+    fn height(&self) -> Length {
+        self.content.as_widget().height()
+    }
+
+    fn layout(
+        &self,
+        renderer: &Renderer,
+        limits: &layout::Limits,
+    ) -> layout::Node {
+        self.content.as_widget().layout(renderer, limits)
+    }
+
+    fn on_event(
+        &mut self,
+        tree: &mut Tree,
+        event: Event,
+        layout: Layout<'_>,
+        cursor_position: Point,
+        renderer: &Renderer,
+        clipboard: &mut dyn Clipboard,
+        shell: &mut Shell<'_, Message>,
+    ) -> event::Status {
+        self.content.as_widget_mut().on_event(
+            &mut tree.children[0],
+            event,
+            layout,
+            cursor_position,
+            renderer,
+            clipboard,
+            shell,
+        )
+    }
+
+    fn mouse_interaction(
+        &self,
+        tree: &Tree,
+        layout: Layout<'_>,
+        cursor_position: Point,
+        viewport: &Rectangle,
+        renderer: &Renderer,
+    ) -> mouse::Interaction {
+        self.content.as_widget().mouse_interaction(
+            &tree.children[0],
+            layout.children().next().unwrap(),
+            cursor_position,
+            viewport,
+            renderer,
+        )
+    }
+
+    fn draw(
+        &self,
+        tree: &Tree,
+        renderer: &mut Renderer,
+        inherited_style: &renderer::Style,
+        layout: Layout<'_>,
+        cursor_position: Point,
+        viewport: &Rectangle,
+    ) {
+        self.content.as_widget().draw(
+            &tree.children[0],
+            renderer,
+            inherited_style,
+            layout,
+            cursor_position,
+            viewport,
+        );
+
+        let bounds = layout.bounds();
+
+        if bounds.contains(cursor_position) {
+            let gap = f32::from(self.gap);
+            let style = self.style_sheet.style();
+
+            let defaults = renderer::Style {
+                text_color: style
+                    .text_color
+                    .unwrap_or(inherited_style.text_color),
+            };
+
+            let text_layout = Widget::<(), Renderer>::layout(
+                &self.tooltip,
+                renderer,
+                &layout::Limits::new(Size::ZERO, viewport.size())
+                    .pad(Padding::new(self.padding)),
+            );
+
+            let padding = f32::from(self.padding);
+            let text_bounds = text_layout.bounds();
+            let x_center = bounds.x + (bounds.width - text_bounds.width) / 2.0;
+            let y_center =
+                bounds.y + (bounds.height - text_bounds.height) / 2.0;
+
+            let mut tooltip_bounds = {
+                let offset = match self.position {
+                    Position::Top => Vector::new(
+                        x_center,
+                        bounds.y - text_bounds.height - gap - padding,
+                    ),
+                    Position::Bottom => Vector::new(
+                        x_center,
+                        bounds.y + bounds.height + gap + padding,
+                    ),
+                    Position::Left => Vector::new(
+                        bounds.x - text_bounds.width - gap - padding,
+                        y_center,
+                    ),
+                    Position::Right => Vector::new(
+                        bounds.x + bounds.width + gap + padding,
+                        y_center,
+                    ),
+                    Position::FollowCursor => Vector::new(
+                        cursor_position.x,
+                        cursor_position.y - text_bounds.height,
+                    ),
+                };
+
+                Rectangle {
+                    x: offset.x - padding,
+                    y: offset.y - padding,
+                    width: text_bounds.width + padding * 2.0,
+                    height: text_bounds.height + padding * 2.0,
+                }
+            };
+
+            if tooltip_bounds.x < viewport.x {
+                tooltip_bounds.x = viewport.x;
+            } else if viewport.x + viewport.width
+                < tooltip_bounds.x + tooltip_bounds.width
+            {
+                tooltip_bounds.x =
+                    viewport.x + viewport.width - tooltip_bounds.width;
+            }
+
+            if tooltip_bounds.y < viewport.y {
+                tooltip_bounds.y = viewport.y;
+            } else if viewport.y + viewport.height
+                < tooltip_bounds.y + tooltip_bounds.height
+            {
+                tooltip_bounds.y =
+                    viewport.y + viewport.height - tooltip_bounds.height;
+            }
+
+            renderer.with_layer(*viewport, |renderer| {
+                container::draw_background(renderer, &style, tooltip_bounds);
+
+                Widget::<(), Renderer>::draw(
+                    &self.tooltip,
+                    &tree.children[0],
+                    renderer,
+                    &defaults,
+                    Layout::with_offset(
+                        Vector::new(
+                            tooltip_bounds.x + padding,
+                            tooltip_bounds.y + padding,
+                        ),
+                        &text_layout,
+                    ),
+                    cursor_position,
+                    viewport,
+                );
+            });
+        }
+    }
+
+    fn overlay<'b>(
+        &'b self,
+        tree: &'b mut Tree,
+        layout: Layout<'_>,
+        renderer: &Renderer,
+    ) -> Option<overlay::Element<'b, Message, Renderer>> {
+        self.content.as_widget().overlay(
+            &mut tree.children[0],
+            layout,
+            renderer,
+        )
+    }
+}
+
+impl<'a, Message, Renderer> From<Tooltip<'a, Message, Renderer>>
+    for Element<'a, Message, Renderer>
+where
+    Renderer: 'a + text::Renderer,
+    Message: 'a,
+{
+    fn from(
+        tooltip: Tooltip<'a, Message, Renderer>,
+    ) -> Element<'a, Message, Renderer> {
+        Element::new(tooltip)
+    }
+}
-- 
cgit 


From 011b7d11126404eaeff1562e49d81693d4d852b2 Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Sun, 24 Apr 2022 20:25:49 +0700
Subject: Reuse `tooltip::Position` from `iced_native` in `iced_pure`

---
 pure/src/widget/tooltip.rs | 28 ++++++++--------------------
 1 file changed, 8 insertions(+), 20 deletions(-)

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/tooltip.rs b/pure/src/widget/tooltip.rs
index f0667e41..0155034b 100644
--- a/pure/src/widget/tooltip.rs
+++ b/pure/src/widget/tooltip.rs
@@ -2,15 +2,18 @@
 use crate::widget::Tree;
 use crate::{Element, Widget};
 use iced_native::event::{self, Event};
+use iced_native::layout;
+use iced_native::mouse;
+use iced_native::overlay;
+use iced_native::renderer;
+use iced_native::text;
 use iced_native::widget::container;
-pub use iced_native::widget::Text;
-use iced_native::{layout, mouse, overlay};
-use iced_native::{renderer, Size};
-use iced_native::{text, Vector};
+use iced_native::widget::Text;
 use iced_native::{
-    Clipboard, Layout, Length, Padding, Point, Rectangle, Shell,
+    Clipboard, Layout, Length, Padding, Point, Rectangle, Shell, Size, Vector,
 };
 
+pub use iced_native::widget::tooltip::Position;
 pub use iced_style::container::{Style, StyleSheet};
 
 /// An element to display a widget over another.
@@ -85,21 +88,6 @@ where
     }
 }
 
-/// The position of the tooltip. Defaults to following the cursor.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum Position {
-    /// The tooltip will follow the cursor.
-    FollowCursor,
-    /// The tooltip will appear on the top of the widget.
-    Top,
-    /// The tooltip will appear on the bottom of the widget.
-    Bottom,
-    /// The tooltip will appear on the left of the widget.
-    Left,
-    /// The tooltip will appear on the right of the widget.
-    Right,
-}
-
 impl<'a, Message, Renderer> Widget<Message, Renderer>
     for Tooltip<'a, Message, Renderer>
 where
-- 
cgit 


From e33f43af31888b8b0795c2287aed9f26b4e1d699 Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Sun, 24 Apr 2022 20:45:43 +0700
Subject: Reuse `Tooltip` draw logic in `iced_pure`

---
 pure/src/widget/tooltip.rs | 118 +++++++++------------------------------------
 1 file changed, 24 insertions(+), 94 deletions(-)

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/tooltip.rs b/pure/src/widget/tooltip.rs
index 0155034b..75c4d856 100644
--- a/pure/src/widget/tooltip.rs
+++ b/pure/src/widget/tooltip.rs
@@ -7,14 +7,12 @@ use iced_native::mouse;
 use iced_native::overlay;
 use iced_native::renderer;
 use iced_native::text;
-use iced_native::widget::container;
+use iced_native::widget::tooltip;
 use iced_native::widget::Text;
-use iced_native::{
-    Clipboard, Layout, Length, Padding, Point, Rectangle, Shell, Size, Vector,
-};
+use iced_native::{Clipboard, Layout, Length, Point, Rectangle, Shell};
 
-pub use iced_native::widget::tooltip::Position;
 pub use iced_style::container::{Style, StyleSheet};
+pub use tooltip::Position;
 
 /// An element to display a widget over another.
 #[allow(missing_debug_implementations)]
@@ -173,101 +171,33 @@ where
             viewport,
         );
 
-        let bounds = layout.bounds();
-
-        if bounds.contains(cursor_position) {
-            let gap = f32::from(self.gap);
-            let style = self.style_sheet.style();
-
-            let defaults = renderer::Style {
-                text_color: style
-                    .text_color
-                    .unwrap_or(inherited_style.text_color),
-            };
-
-            let text_layout = Widget::<(), Renderer>::layout(
-                &self.tooltip,
-                renderer,
-                &layout::Limits::new(Size::ZERO, viewport.size())
-                    .pad(Padding::new(self.padding)),
-            );
-
-            let padding = f32::from(self.padding);
-            let text_bounds = text_layout.bounds();
-            let x_center = bounds.x + (bounds.width - text_bounds.width) / 2.0;
-            let y_center =
-                bounds.y + (bounds.height - text_bounds.height) / 2.0;
-
-            let mut tooltip_bounds = {
-                let offset = match self.position {
-                    Position::Top => Vector::new(
-                        x_center,
-                        bounds.y - text_bounds.height - gap - padding,
-                    ),
-                    Position::Bottom => Vector::new(
-                        x_center,
-                        bounds.y + bounds.height + gap + padding,
-                    ),
-                    Position::Left => Vector::new(
-                        bounds.x - text_bounds.width - gap - padding,
-                        y_center,
-                    ),
-                    Position::Right => Vector::new(
-                        bounds.x + bounds.width + gap + padding,
-                        y_center,
-                    ),
-                    Position::FollowCursor => Vector::new(
-                        cursor_position.x,
-                        cursor_position.y - text_bounds.height,
-                    ),
-                };
-
-                Rectangle {
-                    x: offset.x - padding,
-                    y: offset.y - padding,
-                    width: text_bounds.width + padding * 2.0,
-                    height: text_bounds.height + padding * 2.0,
-                }
-            };
-
-            if tooltip_bounds.x < viewport.x {
-                tooltip_bounds.x = viewport.x;
-            } else if viewport.x + viewport.width
-                < tooltip_bounds.x + tooltip_bounds.width
-            {
-                tooltip_bounds.x =
-                    viewport.x + viewport.width - tooltip_bounds.width;
-            }
-
-            if tooltip_bounds.y < viewport.y {
-                tooltip_bounds.y = viewport.y;
-            } else if viewport.y + viewport.height
-                < tooltip_bounds.y + tooltip_bounds.height
-            {
-                tooltip_bounds.y =
-                    viewport.y + viewport.height - tooltip_bounds.height;
-            }
-
-            renderer.with_layer(*viewport, |renderer| {
-                container::draw_background(renderer, &style, tooltip_bounds);
+        let tooltip = &self.tooltip;
 
+        tooltip::draw(
+            renderer,
+            inherited_style,
+            layout,
+            cursor_position,
+            viewport,
+            self.position,
+            self.gap,
+            self.padding,
+            self.style_sheet.as_ref(),
+            |renderer, limits| {
+                Widget::<(), Renderer>::layout(tooltip, renderer, limits)
+            },
+            |renderer, defaults, layout, cursor_position, viewport| {
                 Widget::<(), Renderer>::draw(
-                    &self.tooltip,
-                    &tree.children[0],
+                    tooltip,
+                    &Tree::empty(),
                     renderer,
-                    &defaults,
-                    Layout::with_offset(
-                        Vector::new(
-                            tooltip_bounds.x + padding,
-                            tooltip_bounds.y + padding,
-                        ),
-                        &text_layout,
-                    ),
+                    defaults,
+                    layout,
                     cursor_position,
                     viewport,
                 );
-            });
-        }
+            },
+        );
     }
 
     fn overlay<'b>(
-- 
cgit 


From ac35fe3edf78c1674fe85b37549002e006b0ff13 Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Sat, 30 Apr 2022 13:54:07 +0200
Subject: Point repository links to `0.4` branch in documentation

---
 pure/src/widget/pane_grid.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/pane_grid.rs b/pure/src/widget/pane_grid.rs
index 34a56bcc..b361664b 100644
--- a/pure/src/widget/pane_grid.rs
+++ b/pure/src/widget/pane_grid.rs
@@ -6,7 +6,7 @@
 //! The [`pane_grid` example] showcases how to use a [`PaneGrid`] with resizing,
 //! drag and drop, and hotkey support.
 //!
-//! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.3/examples/pane_grid
+//! [`pane_grid` example]: https://github.com/iced-rs/iced/tree/0.4/examples/pane_grid
 mod content;
 mod title_bar;
 
-- 
cgit 


From 68e9eb0a9b45b86713ce5d0e9c2273a60f2cc11c Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Sat, 30 Apr 2022 14:20:52 +0200
Subject: Fix broken intra-doc links in documentation

---
 pure/src/widget/pane_grid/content.rs   |  2 +-
 pure/src/widget/pane_grid/title_bar.rs |  2 +-
 pure/src/widget/pick_list.rs           |  5 ++---
 pure/src/widget/slider.rs              |  7 ++-----
 pure/src/widget/text_input.rs          | 18 +++++++-----------
 5 files changed, 13 insertions(+), 21 deletions(-)

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/pane_grid/content.rs b/pure/src/widget/pane_grid/content.rs
index a928b28c..6388b016 100644
--- a/pure/src/widget/pane_grid/content.rs
+++ b/pure/src/widget/pane_grid/content.rs
@@ -84,7 +84,7 @@ where
 
     /// Draws the [`Content`] with the provided [`Renderer`] and [`Layout`].
     ///
-    /// [`Renderer`]: crate::widget::pane_grid::Renderer
+    /// [`Renderer`]: iced_native::Renderer
     pub fn draw(
         &self,
         tree: &Tree,
diff --git a/pure/src/widget/pane_grid/title_bar.rs b/pure/src/widget/pane_grid/title_bar.rs
index dd68b073..567db913 100644
--- a/pure/src/widget/pane_grid/title_bar.rs
+++ b/pure/src/widget/pane_grid/title_bar.rs
@@ -108,7 +108,7 @@ where
 
     /// Draws the [`TitleBar`] with the provided [`Renderer`] and [`Layout`].
     ///
-    /// [`Renderer`]: crate::widget::pane_grid::Renderer
+    /// [`Renderer`]: iced_native::Renderer
     pub fn draw(
         &self,
         tree: &Tree,
diff --git a/pure/src/widget/pick_list.rs b/pure/src/widget/pick_list.rs
index 45bb289e..255e3681 100644
--- a/pure/src/widget/pick_list.rs
+++ b/pure/src/widget/pick_list.rs
@@ -43,9 +43,8 @@ where
     /// The default padding of a [`PickList`].
     pub const DEFAULT_PADDING: Padding = Padding::new(5);
 
-    /// Creates a new [`PickList`] with the given [`State`], a list of options,
-    /// the current selected value, and the message to produce when an option is
-    /// selected.
+    /// Creates a new [`PickList`] with the given list of options, the current
+    /// selected value, and the message to produce when an option is selected.
     pub fn new(
         options: impl Into<Cow<'a, [T]>>,
         selected: Option<T>,
diff --git a/pure/src/widget/slider.rs b/pure/src/widget/slider.rs
index 1107bdc1..4d8bbce4 100644
--- a/pure/src/widget/slider.rs
+++ b/pure/src/widget/slider.rs
@@ -1,6 +1,4 @@
 //! Display an interactive selector of a single value from a range of values.
-//!
-//! A [`Slider`] has some local [`State`].
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
 
@@ -25,17 +23,16 @@ pub use iced_style::slider::{Handle, HandleShape, Style, StyleSheet};
 ///
 /// # Example
 /// ```
-/// # use iced_native::widget::slider::{self, Slider};
+/// # use iced_pure::widget::Slider;
 /// #
 /// #[derive(Clone)]
 /// pub enum Message {
 ///     SliderChanged(f32),
 /// }
 ///
-/// let state = &mut slider::State::new();
 /// let value = 50.0;
 ///
-/// Slider::new(state, 0.0..=100.0, value, Message::SliderChanged);
+/// Slider::new(0.0..=100.0, value, Message::SliderChanged);
 /// ```
 ///
 /// ![Slider drawn by Coffee's renderer](https://github.com/hecrj/coffee/blob/bda9818f823dfcb8a7ad0ff4940b4d4b387b5208/images/ui/slider.png?raw=true)
diff --git a/pure/src/widget/text_input.rs b/pure/src/widget/text_input.rs
index d6041d7f..11e93b44 100644
--- a/pure/src/widget/text_input.rs
+++ b/pure/src/widget/text_input.rs
@@ -16,19 +16,17 @@ pub use iced_style::text_input::{Style, StyleSheet};
 /// # Example
 /// ```
 /// # use iced_native::renderer::Null;
-/// # use iced_native::widget::text_input;
+/// # use iced_pure::widget::text_input;
 /// #
-/// # pub type TextInput<'a, Message> = iced_native::widget::TextInput<'a, Message, Null>;
+/// # pub type TextInput<'a, Message> = iced_pure::widget::TextInput<'a, Message, Null>;
 /// #[derive(Debug, Clone)]
 /// enum Message {
 ///     TextInputChanged(String),
 /// }
 ///
-/// let mut state = text_input::State::new();
 /// let value = "Some text";
 ///
 /// let input = TextInput::new(
-///     &mut state,
 ///     "This is the placeholder...",
 ///     value,
 ///     Message::TextInputChanged,
@@ -58,10 +56,9 @@ where
     /// Creates a new [`TextInput`].
     ///
     /// It expects:
-    /// - some [`State`]
-    /// - a placeholder
-    /// - the current value
-    /// - a function that produces a message when the [`TextInput`] changes
+    /// - a placeholder,
+    /// - the current value, and
+    /// - a function that produces a message when the [`TextInput`] changes.
     pub fn new<F>(placeholder: &str, value: &str, on_change: F) -> Self
     where
         F: 'a + Fn(String) -> Message,
@@ -86,10 +83,9 @@ where
         self
     }
 
-    /// Sets the [`Font`] of the [`Text`].
+    /// Sets the [`Font`] of the [`TextInput`].
     ///
-    /// [`Font`]: crate::widget::text::Renderer::Font
-    /// [`Text`]: crate::widget::Text
+    /// [`Font`]: iced_native::text::Renderer::Font
     pub fn font(mut self, font: Renderer::Font) -> Self {
         self.font = font;
         self
-- 
cgit 


From e7d595c7de3854e165fd68f05ab2292cae69dbc4 Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Mon, 2 May 2022 20:16:00 +0200
Subject: Write documentation for `iced_pure`

---
 pure/src/widget/button.rs              | 36 +++++++++++++++++++++++++
 pure/src/widget/checkbox.rs            |  1 +
 pure/src/widget/column.rs              | 13 +++++++++
 pure/src/widget/image.rs               |  1 +
 pure/src/widget/pane_grid.rs           |  2 +-
 pure/src/widget/pane_grid/content.rs   |  4 +--
 pure/src/widget/pane_grid/title_bar.rs |  4 +--
 pure/src/widget/progress_bar.rs        |  1 +
 pure/src/widget/radio.rs               |  1 +
 pure/src/widget/row.rs                 | 13 +++++++++
 pure/src/widget/rule.rs                |  1 +
 pure/src/widget/scrollable.rs          |  1 +
 pure/src/widget/svg.rs                 |  1 +
 pure/src/widget/text_input.rs          |  6 ++---
 pure/src/widget/toggler.rs             |  1 +
 pure/src/widget/tooltip.rs             |  2 +-
 pure/src/widget/tree.rs                | 48 +++++++++++++++++++++++++++++-----
 17 files changed, 119 insertions(+), 17 deletions(-)

(limited to 'pure/src/widget')

diff --git a/pure/src/widget/button.rs b/pure/src/widget/button.rs
index e083ea73..456c2509 100644
--- a/pure/src/widget/button.rs
+++ b/pure/src/widget/button.rs
@@ -1,3 +1,4 @@
+//! Allow your users to perform actions by pressing a button.
 use crate::overlay;
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
@@ -15,6 +16,40 @@ pub use iced_style::button::{Style, StyleSheet};
 
 use button::State;
 
+/// A generic widget that produces a message when pressed.
+///
+/// ```
+/// # type Button<'a, Message> =
+/// #     iced_pure::widget::Button<'a, Message, iced_native::renderer::Null>;
+/// #
+/// #[derive(Clone)]
+/// enum Message {
+///     ButtonPressed,
+/// }
+///
+/// let button = Button::new("Press me!").on_press(Message::ButtonPressed);
+/// ```
+///
+/// If a [`Button::on_press`] handler is not set, the resulting [`Button`] will
+/// be disabled:
+///
+/// ```
+/// # type Button<'a, Message> =
+/// #     iced_pure::widget::Button<'a, Message, iced_native::renderer::Null>;
+/// #
+/// #[derive(Clone)]
+/// enum Message {
+///     ButtonPressed,
+/// }
+///
+/// fn disabled_button<'a>() -> Button<'a, Message> {
+///     Button::new("I'm disabled!")
+/// }
+///
+/// fn enabled_button<'a>() -> Button<'a, Message> {
+///     disabled_button().on_press(Message::ButtonPressed)
+/// }
+/// ```
 pub struct Button<'a, Message, Renderer> {
     content: Element<'a, Message, Renderer>,
     on_press: Option<Message>,
@@ -25,6 +60,7 @@ pub struct Button<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Button<'a, Message, Renderer> {
+    /// Creates a new [`Button`] with the given content.
     pub fn new(content: impl Into<Element<'a, Message, Renderer>>) -> Self {
         Button {
             content: content.into(),
diff --git a/pure/src/widget/checkbox.rs b/pure/src/widget/checkbox.rs
index 971980e3..98f55a56 100644
--- a/pure/src/widget/checkbox.rs
+++ b/pure/src/widget/checkbox.rs
@@ -1,3 +1,4 @@
+//! Show toggle controls using checkboxes.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 
diff --git a/pure/src/widget/column.rs b/pure/src/widget/column.rs
index a4c0987b..7256f474 100644
--- a/pure/src/widget/column.rs
+++ b/pure/src/widget/column.rs
@@ -13,6 +13,7 @@ use iced_native::{
 
 use std::u32;
 
+/// A container that distributes its contents vertically.
 pub struct Column<'a, Message, Renderer> {
     spacing: u16,
     padding: Padding,
@@ -24,10 +25,12 @@ pub struct Column<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
+    /// Creates an empty [`Column`].
     pub fn new() -> Self {
         Self::with_children(Vec::new())
     }
 
+    /// Creates a [`Column`] with the given elements.
     pub fn with_children(
         children: Vec<Element<'a, Message, Renderer>>,
     ) -> Self {
@@ -42,21 +45,29 @@ impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
         }
     }
 
+    /// Sets the vertical spacing _between_ elements.
+    ///
+    /// Custom margins per element do not exist in iced. You should use this
+    /// method instead! While less flexible, it helps you keep spacing between
+    /// elements consistent.
     pub fn spacing(mut self, units: u16) -> Self {
         self.spacing = units;
         self
     }
 
+    /// Sets the [`Padding`] of the [`Column`].
     pub fn padding<P: Into<Padding>>(mut self, padding: P) -> Self {
         self.padding = padding.into();
         self
     }
 
+    /// Sets the width of the [`Column`].
     pub fn width(mut self, width: Length) -> Self {
         self.width = width;
         self
     }
 
+    /// Sets the height of the [`Column`].
     pub fn height(mut self, height: Length) -> Self {
         self.height = height;
         self
@@ -68,11 +79,13 @@ impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
         self
     }
 
+    /// Sets the horizontal alignment of the contents of the [`Column`] .
     pub fn align_items(mut self, align: Alignment) -> Self {
         self.align_items = align;
         self
     }
 
+    /// Adds an element to the [`Column`].
     pub fn push(
         mut self,
         child: impl Into<Element<'a, Message, Renderer>>,
diff --git a/pure/src/widget/image.rs b/pure/src/widget/image.rs
index a5bca5a0..ef764ec2 100644
--- a/pure/src/widget/image.rs
+++ b/pure/src/widget/image.rs
@@ -1,3 +1,4 @@
+//! Display images in your user interface.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 
diff --git a/pure/src/widget/pane_grid.rs b/pure/src/widget/pane_grid.rs
index b361664b..c532a6de 100644
--- a/pure/src/widget/pane_grid.rs
+++ b/pure/src/widget/pane_grid.rs
@@ -213,7 +213,7 @@ where
     fn diff(&self, tree: &mut Tree) {
         tree.diff_children_custom(
             &self.elements,
-            |(_, content), state| content.diff(state),
+            |state, (_, content)| content.diff(state),
             |(_, content)| content.state(),
         )
     }
diff --git a/pure/src/widget/pane_grid/content.rs b/pure/src/widget/pane_grid/content.rs
index 6388b016..e66ac40b 100644
--- a/pure/src/widget/pane_grid/content.rs
+++ b/pure/src/widget/pane_grid/content.rs
@@ -57,7 +57,7 @@ impl<'a, Message, Renderer> Content<'a, Message, Renderer>
 where
     Renderer: iced_native::Renderer,
 {
-    pub fn state(&self) -> Tree {
+    pub(super) fn state(&self) -> Tree {
         let children = if let Some(title_bar) = self.title_bar.as_ref() {
             vec![Tree::new(&self.body), title_bar.state()]
         } else {
@@ -70,7 +70,7 @@ where
         }
     }
 
-    pub fn diff(&self, tree: &mut Tree) {
+    pub(super) fn diff(&self, tree: &mut Tree) {
         if tree.children.len() == 2 {
             if let Some(title_bar) = self.title_bar.as_ref() {
                 title_bar.diff(&mut tree.children[1]);
diff --git a/pure/src/widget/pane_grid/title_bar.rs b/pure/src/widget/pane_grid/title_bar.rs
index 567db913..4a7c8c17 100644
--- a/pure/src/widget/pane_grid/title_bar.rs
+++ b/pure/src/widget/pane_grid/title_bar.rs
@@ -81,7 +81,7 @@ impl<'a, Message, Renderer> TitleBar<'a, Message, Renderer>
 where
     Renderer: iced_native::Renderer,
 {
-    pub fn state(&self) -> Tree {
+    pub(super) fn state(&self) -> Tree {
         let children = if let Some(controls) = self.controls.as_ref() {
             vec![Tree::new(&self.content), Tree::new(controls)]
         } else {
@@ -94,7 +94,7 @@ where
         }
     }
 
-    pub fn diff(&self, tree: &mut Tree) {
+    pub(super) fn diff(&self, tree: &mut Tree) {
         if tree.children.len() == 2 {
             if let Some(controls) = self.controls.as_ref() {
                 tree.children[1].diff(controls);
diff --git a/pure/src/widget/progress_bar.rs b/pure/src/widget/progress_bar.rs
index 3f4ffd55..3016a81a 100644
--- a/pure/src/widget/progress_bar.rs
+++ b/pure/src/widget/progress_bar.rs
@@ -1,3 +1,4 @@
+//! Provide progress feedback to your users.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 
diff --git a/pure/src/widget/radio.rs b/pure/src/widget/radio.rs
index c20f8f3e..7c98c937 100644
--- a/pure/src/widget/radio.rs
+++ b/pure/src/widget/radio.rs
@@ -1,3 +1,4 @@
+//! Create choices using radio buttons.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 
diff --git a/pure/src/widget/row.rs b/pure/src/widget/row.rs
index 92812d27..0385b8bd 100644
--- a/pure/src/widget/row.rs
+++ b/pure/src/widget/row.rs
@@ -11,6 +11,7 @@ use iced_native::{
     Alignment, Clipboard, Length, Padding, Point, Rectangle, Shell,
 };
 
+/// A container that distributes its contents horizontally.
 pub struct Row<'a, Message, Renderer> {
     spacing: u16,
     padding: Padding,
@@ -21,10 +22,12 @@ pub struct Row<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Row<'a, Message, Renderer> {
+    /// Creates an empty [`Row`].
     pub fn new() -> Self {
         Self::with_children(Vec::new())
     }
 
+    /// Creates a [`Row`] with the given elements.
     pub fn with_children(
         children: Vec<Element<'a, Message, Renderer>>,
     ) -> Self {
@@ -38,31 +41,41 @@ impl<'a, Message, Renderer> Row<'a, Message, Renderer> {
         }
     }
 
+    /// Sets the horizontal spacing _between_ elements.
+    ///
+    /// Custom margins per element do not exist in iced. You should use this
+    /// method instead! While less flexible, it helps you keep spacing between
+    /// elements consistent.
     pub fn spacing(mut self, units: u16) -> Self {
         self.spacing = units;
         self
     }
 
+    /// Sets the [`Padding`] of the [`Row`].
     pub fn padding<P: Into<Padding>>(mut self, padding: P) -> Self {
         self.padding = padding.into();
         self
     }
 
+    /// Sets the width of the [`Row`].
     pub fn width(mut self, width: Length) -> Self {
         self.width = width;
         self
     }
 
+    /// Sets the height of the [`Row`].
     pub fn height(mut self, height: Length) -> Self {
         self.height = height;
         self
     }
 
+    /// Sets the vertical alignment of the contents of the [`Row`] .
     pub fn align_items(mut self, align: Alignment) -> Self {
         self.align_items = align;
         self
     }
 
+    /// Adds an [`Element`] to the [`Row`].
     pub fn push(
         mut self,
         child: impl Into<Element<'a, Message, Renderer>>,
diff --git a/pure/src/widget/rule.rs b/pure/src/widget/rule.rs
index 40b1fc90..ab8537ae 100644
--- a/pure/src/widget/rule.rs
+++ b/pure/src/widget/rule.rs
@@ -1,3 +1,4 @@
+//! Display a horizontal or vertical rule for dividing content.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 
diff --git a/pure/src/widget/scrollable.rs b/pure/src/widget/scrollable.rs
index 24263c95..70e951ef 100644
--- a/pure/src/widget/scrollable.rs
+++ b/pure/src/widget/scrollable.rs
@@ -1,3 +1,4 @@
+//! Navigate an endless amount of content with a scrollbar.
 use crate::overlay;
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
diff --git a/pure/src/widget/svg.rs b/pure/src/widget/svg.rs
index 2758c5b1..14180097 100644
--- a/pure/src/widget/svg.rs
+++ b/pure/src/widget/svg.rs
@@ -1,3 +1,4 @@
+//! Display vector graphics in your application.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 
diff --git a/pure/src/widget/text_input.rs b/pure/src/widget/text_input.rs
index 11e93b44..57ad26d9 100644
--- a/pure/src/widget/text_input.rs
+++ b/pure/src/widget/text_input.rs
@@ -1,3 +1,4 @@
+//! Display fields that can be filled with text.
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
 
@@ -15,10 +16,7 @@ pub use iced_style::text_input::{Style, StyleSheet};
 ///
 /// # Example
 /// ```
-/// # use iced_native::renderer::Null;
-/// # use iced_pure::widget::text_input;
-/// #
-/// # pub type TextInput<'a, Message> = iced_pure::widget::TextInput<'a, Message, Null>;
+/// # pub type TextInput<'a, Message> = iced_pure::widget::TextInput<'a, Message, iced_native::renderer::Null>;
 /// #[derive(Debug, Clone)]
 /// enum Message {
 ///     TextInputChanged(String),
diff --git a/pure/src/widget/toggler.rs b/pure/src/widget/toggler.rs
index 1b3367a4..b9c5ec02 100644
--- a/pure/src/widget/toggler.rs
+++ b/pure/src/widget/toggler.rs
@@ -1,3 +1,4 @@
+//! Show toggle controls using togglers.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 
diff --git a/pure/src/widget/tooltip.rs b/pure/src/widget/tooltip.rs
index 75c4d856..3887732a 100644
--- a/pure/src/widget/tooltip.rs
+++ b/pure/src/widget/tooltip.rs
@@ -32,7 +32,7 @@ where
     /// The default padding of a [`Tooltip`] drawn by this renderer.
     const DEFAULT_PADDING: u16 = 5;
 
-    /// Creates an empty [`Tooltip`].
+    /// Creates a new [`Tooltip`].
     ///
     /// [`Tooltip`]: struct.Tooltip.html
     pub fn new(
diff --git a/pure/src/widget/tree.rs b/pure/src/widget/tree.rs
index bd7c259c..d81dd02c 100644
--- a/pure/src/widget/tree.rs
+++ b/pure/src/widget/tree.rs
@@ -1,14 +1,24 @@
+//! Store internal widget state in a state tree to ensure continuity.
 use crate::Element;
 
 use std::any::{self, Any};
 
+/// A persistent state widget tree.
+///
+/// A [`Tree`] is normally associated with a specific widget in the widget tree.
 pub struct Tree {
+    /// The tag of the [`Tree`].
     pub tag: Tag,
+
+    /// The [`State`] of the [`Tree`].
     pub state: State,
+
+    /// The children of the root widget of the [`Tree`].
     pub children: Vec<Tree>,
 }
 
 impl Tree {
+    /// Creates an empty, stateless [`Tree`] with no children.
     pub fn empty() -> Self {
         Self {
             tag: Tag::stateless(),
@@ -17,6 +27,7 @@ impl Tree {
         }
     }
 
+    /// Creates a new [`Tree`] for the provided [`Element`].
     pub fn new<Message, Renderer>(
         element: &Element<'_, Message, Renderer>,
     ) -> Self {
@@ -27,6 +38,14 @@ impl Tree {
         }
     }
 
+    /// Reconciliates the current tree with the provided [`Element`].
+    ///
+    /// If the tag of the [`Element`] matches the tag of the [`Tree`], then the
+    /// [`Element`] proceeds with the reconciliation (i.e. [`Widget::diff`] is called).
+    ///
+    /// Otherwise, the whole [`Tree`] is recreated.
+    ///
+    /// [`Widget::diff`]: crate::Widget::diff
     pub fn diff<Message, Renderer>(
         &mut self,
         new: &Element<'_, Message, Renderer>,
@@ -38,21 +57,20 @@ impl Tree {
         }
     }
 
+    /// Reconciliates the children of the tree with the provided list of [`Element`].
     pub fn diff_children<Message, Renderer>(
         &mut self,
         new_children: &[Element<'_, Message, Renderer>],
     ) {
-        self.diff_children_custom(
-            new_children,
-            |new, child_state| child_state.diff(new),
-            Self::new,
-        )
+        self.diff_children_custom(new_children, Self::diff, Self::new)
     }
 
+    /// Reconciliates the children of the tree with the provided list of [`Element`] using custom
+    /// logic both for diffing and creating new widget state.
     pub fn diff_children_custom<T>(
         &mut self,
         new_children: &[T],
-        diff: impl Fn(&T, &mut Tree),
+        diff: impl Fn(&mut Tree, &T),
         new_state: impl Fn(&T) -> Self,
     ) {
         if self.children.len() > new_children.len() {
@@ -62,7 +80,7 @@ impl Tree {
         for (child_state, new) in
             self.children.iter_mut().zip(new_children.iter())
         {
-            diff(new, child_state);
+            diff(child_state, new);
         }
 
         if self.children.len() < new_children.len() {
@@ -73,10 +91,12 @@ impl Tree {
     }
 }
 
+/// The identifier of some widget state.
 #[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash)]
 pub struct Tag(any::TypeId);
 
 impl Tag {
+    /// Creates a [`Tag`] for a state of type `T`.
     pub fn of<T>() -> Self
     where
         T: 'static,
@@ -84,17 +104,23 @@ impl Tag {
         Self(any::TypeId::of::<T>())
     }
 
+    /// Creates a [`Tag`] for a stateless widget.
     pub fn stateless() -> Self {
         Self::of::<()>()
     }
 }
 
+/// The internal [`State`] of a widget.
 pub enum State {
+    /// No meaningful internal state.
     None,
+
+    /// Some meaningful internal state.
     Some(Box<dyn Any>),
 }
 
 impl State {
+    /// Creates a new [`State`].
     pub fn new<T>(state: T) -> Self
     where
         T: 'static,
@@ -102,6 +128,10 @@ impl State {
         State::Some(Box::new(state))
     }
 
+    /// Downcasts the [`State`] to `T` and returns a reference to it.
+    ///
+    /// # Panics
+    /// This method will panic if the downcast fails or the [`State`] is [`State::None`].
     pub fn downcast_ref<T>(&self) -> &T
     where
         T: 'static,
@@ -114,6 +144,10 @@ impl State {
         }
     }
 
+    /// Downcasts the [`State`] to `T` and returns a mutable reference to it.
+    ///
+    /// # Panics
+    /// This method will panic if the downcast fails or the [`State`] is [`State::None`].
     pub fn downcast_mut<T>(&mut self) -> &mut T
     where
         T: 'static,
-- 
cgit