summaryrefslogtreecommitdiffstats
path: root/pure/src/widget
diff options
context:
space:
mode:
Diffstat (limited to 'pure/src/widget')
-rw-r--r--pure/src/widget/button.rs36
-rw-r--r--pure/src/widget/checkbox.rs1
-rw-r--r--pure/src/widget/column.rs13
-rw-r--r--pure/src/widget/image.rs1
-rw-r--r--pure/src/widget/pane_grid.rs4
-rw-r--r--pure/src/widget/pane_grid/content.rs6
-rw-r--r--pure/src/widget/pane_grid/title_bar.rs6
-rw-r--r--pure/src/widget/pick_list.rs5
-rw-r--r--pure/src/widget/progress_bar.rs1
-rw-r--r--pure/src/widget/radio.rs1
-rw-r--r--pure/src/widget/row.rs13
-rw-r--r--pure/src/widget/rule.rs1
-rw-r--r--pure/src/widget/scrollable.rs1
-rw-r--r--pure/src/widget/slider.rs7
-rw-r--r--pure/src/widget/svg.rs1
-rw-r--r--pure/src/widget/text_input.rs20
-rw-r--r--pure/src/widget/toggler.rs1
-rw-r--r--pure/src/widget/tooltip.rs2
-rw-r--r--pure/src/widget/tree.rs48
19 files changed, 131 insertions, 37 deletions
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 34a56bcc..c532a6de 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;
@@ -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 a928b28c..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]);
@@ -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..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);
@@ -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/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/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/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 d6041d7f..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,20 +16,15 @@ pub use iced_style::text_input::{Style, StyleSheet};
///
/// # Example
/// ```
-/// # use iced_native::renderer::Null;
-/// # use iced_native::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, iced_native::renderer::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 +54,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 +81,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
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,
generated by cgit (git 2.34.1) at 2025-04-24 10:45:44 +0000