From f4936344f01f592ca3b0616eff8f32e75c1e2b35 Mon Sep 17 00:00:00 2001 From: Michael Aaron Murphy Date: Mon, 20 May 2024 20:01:47 +0200 Subject: [PATCH] chore(doc): add documentation for a handful of widgets --- src/widget/aspect_ratio.rs | 6 ++-- src/widget/button/icon.rs | 2 ++ src/widget/button/image.rs | 2 ++ src/widget/button/link.rs | 3 ++ src/widget/button/mod.rs | 15 +++++++++ src/widget/button/text.rs | 5 +++ src/widget/button/widget.rs | 2 +- src/widget/calendar.rs | 3 ++ src/widget/color_picker/mod.rs | 12 +++++-- src/widget/context_drawer/mod.rs | 3 ++ src/widget/dropdown/mod.rs | 3 ++ src/widget/flex_row/mod.rs | 4 ++- src/widget/grid/mod.rs | 4 ++- src/widget/mod.rs | 56 +++++++++++++++++++++++++++++++- src/widget/spin_button/mod.rs | 3 ++ 15 files changed, 113 insertions(+), 10 deletions(-) diff --git a/src/widget/aspect_ratio.rs b/src/widget/aspect_ratio.rs index 32ef16e5..c918f8c7 100644 --- a/src/widget/aspect_ratio.rs +++ b/src/widget/aspect_ratio.rs @@ -1,3 +1,5 @@ +//! A container which constraints itself to a specific aspect ratio. + use iced::widget::Container; use iced::Size; use iced_core::alignment; @@ -21,9 +23,7 @@ where AspectRatio::new(content, ratio) } -/// An element decorating some content. -/// -/// It is normally used for alignment purposes. +/// A container which constraints itself to a specific aspect ratio. #[allow(missing_debug_implementations)] pub struct AspectRatio<'a, Message, Renderer> where diff --git a/src/widget/button/icon.rs b/src/widget/button/icon.rs index d1e10d02..c22c8cb6 100644 --- a/src/widget/button/icon.rs +++ b/src/widget/button/icon.rs @@ -13,12 +13,14 @@ use std::borrow::Cow; pub type Button<'a, Message> = Builder<'a, Message, Icon>; +/// The icon variant of a button. pub struct Icon { handle: Handle, vertical: bool, selected: bool, } +/// A button constructed from an icon handle, using icon button styling. pub fn icon<'a, Message>(handle: impl Into) -> Button<'a, Message> { Button::new(Icon { handle: handle.into(), diff --git a/src/widget/button/image.rs b/src/widget/button/image.rs index 9bfa2880..d93844cd 100644 --- a/src/widget/button/image.rs +++ b/src/widget/button/image.rs @@ -11,6 +11,7 @@ use std::borrow::Cow; pub type Button<'a, Message> = Builder<'a, Message, Image<'a, Handle, Message>>; +/// A button constructed from an image handle, using image button styling. pub fn image<'a, Message>(handle: impl Into + 'a) -> Button<'a, Message> { Button::new(Image { image: widget::image(handle).border_radius([9.0; 4]), @@ -19,6 +20,7 @@ pub fn image<'a, Message>(handle: impl Into + 'a) -> Button<'a, Message> }) } +/// The image variant of a button. pub struct Image<'a, Handle, Message> { image: widget::Image<'a, Handle>, selected: bool, diff --git a/src/widget/button/link.rs b/src/widget/button/link.rs index d1d43e90..52cc44b1 100644 --- a/src/widget/button/link.rs +++ b/src/widget/button/link.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Hyperlink button widget + use super::Builder; use super::Style; use crate::prelude::*; @@ -17,6 +19,7 @@ pub struct Hyperlink { trailing_icon: bool, } +/// A hyperlink button. pub fn link<'a, Message>(label: impl Into> + 'static) -> Button<'a, Message> { Button::new( label, diff --git a/src/widget/button/mod.rs b/src/widget/button/mod.rs index 9ba5dc2f..c9cf555a 100644 --- a/src/widget/button/mod.rs +++ b/src/widget/button/mod.rs @@ -1,29 +1,41 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Button widgets for COSMIC applications. + pub use crate::theme::Button as Style; pub mod link; use derive_setters::Setters; +#[doc(inline)] pub use link::link; +#[doc(inline)] pub use link::Button as LinkButton; mod icon; +#[doc(inline)] pub use icon::icon; +#[doc(inline)] pub use icon::Button as IconButton; mod image; +#[doc(inline)] pub use image::image; +#[doc(inline)] pub use image::Button as ImageButton; mod style; +#[doc(inline)] pub use style::{Appearance, StyleSheet}; mod text; +#[doc(inline)] pub use text::Button as TextButton; +#[doc(inline)] pub use text::{destructive, standard, suggested, text}; mod widget; +#[doc(inline)] pub use widget::{draw, focus, layout, mouse_interaction, Button}; use iced_core::font::Weight; @@ -31,10 +43,12 @@ use iced_core::widget::Id; use iced_core::{Length, Padding}; use std::borrow::Cow; +/// A button with the default style, which may contain any widget as its content. pub fn button<'a, Message>(content: impl Into>) -> Button<'a, Message> { Button::new(content) } +/// An image button which may contain any widget as its content. pub fn custom_image_button<'a, Message>( content: impl Into>, on_remove: Option, @@ -42,6 +56,7 @@ pub fn custom_image_button<'a, Message>( Button::new_image(content, on_remove) } +/// A builder for constructing a custom [`Button`]. #[must_use] #[derive(Setters)] pub struct Builder<'a, Message, Variant> { diff --git a/src/widget/button/text.rs b/src/widget/button/text.rs index 134e0623..f58b4374 100644 --- a/src/widget/button/text.rs +++ b/src/widget/button/text.rs @@ -10,26 +10,31 @@ use std::borrow::Cow; pub type Button<'a, Message> = Builder<'a, Message, Text>; +/// A text button with the destructive style pub fn destructive<'a, Message>(label: impl Into>) -> Button<'a, Message> { Button::new(Text::new()) .label(label) .style(Style::Destructive) } +/// A text button with the suggested style pub fn suggested<'a, Message>(label: impl Into>) -> Button<'a, Message> { Button::new(Text::new()) .label(label) .style(Style::Suggested) } +/// A text button with the standard style pub fn standard<'a, Message>(label: impl Into>) -> Button<'a, Message> { Button::new(Text::new()).label(label) } +/// A text button with the text style pub fn text<'a, Message>(label: impl Into>) -> Button<'a, Message> { Button::new(Text::new()).label(label).style(Style::Text) } +/// The text variant of a button. pub struct Text { pub(super) leading_icon: Option, pub(super) trailing_icon: Option, diff --git a/src/widget/button/widget.rs b/src/widget/button/widget.rs index 498a94d9..7444b212 100644 --- a/src/widget/button/widget.rs +++ b/src/widget/button/widget.rs @@ -59,7 +59,7 @@ pub struct Button<'a, Message> { impl<'a, Message> Button<'a, Message> { /// Creates a new [`Button`] with the given content. - pub fn new(content: impl Into>) -> Self { + pub(super) fn new(content: impl Into>) -> Self { Self { id: Id::unique(), #[cfg(feature = "a11y")] diff --git a/src/widget/calendar.rs b/src/widget/calendar.rs index fc47f5f3..61825ff9 100644 --- a/src/widget/calendar.rs +++ b/src/widget/calendar.rs @@ -1,6 +1,8 @@ // Copyright 2024 System76 // SPDX-License-Identifier: MPL-2.0 +//! A widget that displays an interactive calendar. + use std::cmp; use crate::iced_core::{Length, Padding}; @@ -8,6 +10,7 @@ use crate::widget::{button, column, grid, icon, row, text, Grid}; use chrono::{Datelike, Days, Months, NaiveDate, Weekday}; use iced::alignment::{Horizontal, Vertical}; +/// A widget that displays an interactive calendar. pub fn calendar( selected: &NaiveDate, on_select: impl Fn(NaiveDate) -> M + 'static, diff --git a/src/widget/color_picker/mod.rs b/src/widget/color_picker/mod.rs index 07e255cd..ff2894b1 100644 --- a/src/widget/color_picker/mod.rs +++ b/src/widget/color_picker/mod.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Widgets for selecting colors with a color picker. + use std::borrow::Cow; use std::rc::Rc; use std::sync::atomic::{AtomicBool, Ordering}; @@ -29,9 +31,12 @@ use palette::{FromColor, RgbHue}; use super::button::StyleSheet; use super::divider::horizontal; use super::icon::{self, from_name}; -use super::segmented_button::{self, Model, SingleSelect}; +use super::segmented_button::{self, SingleSelect}; use super::{button, segmented_control, text, text_input, tooltip, Icon}; +#[doc(inline)] +pub use ColorPickerModel as Model; + // TODO is this going to look correct enough? lazy_static! { pub static ref HSV_RAINBOW: Vec = (0u16..8) @@ -64,7 +69,7 @@ pub enum ColorPickerUpdate { #[derive(Setters)] pub struct ColorPickerModel { #[setters(skip)] - segmented_model: Model, + segmented_model: segmented_button::Model, #[setters(skip)] active_color: palette::Hsv, #[setters(skip)] @@ -246,7 +251,7 @@ impl ColorPickerModel { #[derive(Setters, Clone)] pub struct ColorPickerBuilder<'a, Message> { #[setters(skip)] - model: &'a Model, + model: &'a segmented_button::Model, #[setters(skip)] active_color: palette::Hsv, #[setters(skip)] @@ -757,6 +762,7 @@ fn color_to_string(c: palette::Hsv, is_hex: bool) -> String { } } +/// A button for selecting a color from a color picker. pub fn color_button<'a, Message: 'static>( on_press: Option, color: Option, diff --git a/src/widget/context_drawer/mod.rs b/src/widget/context_drawer/mod.rs index 3a3982fd..258b4f88 100644 --- a/src/widget/context_drawer/mod.rs +++ b/src/widget/context_drawer/mod.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! An overlayed widget that attaches a toggleable context drawer to the view. + mod overlay; mod widget; @@ -8,6 +10,7 @@ pub use widget::ContextDrawer; use crate::Element; +/// An overlayed widget that attaches a toggleable context drawer to the view. pub fn context_drawer<'a, Message: Clone + 'static, Content, Drawer>( header: &'a str, on_close: Message, diff --git a/src/widget/dropdown/mod.rs b/src/widget/dropdown/mod.rs index f91acb6f..6e3db648 100644 --- a/src/widget/dropdown/mod.rs +++ b/src/widget/dropdown/mod.rs @@ -2,6 +2,8 @@ // Copyright 2019 Héctor Ramón, Iced contributors // SPDX-License-Identifier: MPL-2.0 AND MIT +//! Displays a list of options in a popover menu on select. + pub mod menu; pub use menu::Menu; @@ -10,6 +12,7 @@ pub mod multi; mod widget; pub use widget::*; +/// Displays a list of options in a popover menu on select. pub fn dropdown<'a, S: AsRef, Message: 'a>( selections: &'a [S], selected: Option, diff --git a/src/widget/flex_row/mod.rs b/src/widget/flex_row/mod.rs index 95161090..4f546527 100644 --- a/src/widget/flex_row/mod.rs +++ b/src/widget/flex_row/mod.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Responsively generates rows of widgets based on the dimensions of its children. + pub mod layout; pub mod widget; @@ -8,7 +10,7 @@ pub use widget::FlexRow; use crate::Element; -/// Responsively generates rows and columns of widgets based on its dimmensions. +/// Responsively generates rows of widgets based on the dimensions of its children. pub const fn flex_row(children: Vec>) -> FlexRow { FlexRow::new(children) } diff --git a/src/widget/grid/mod.rs b/src/widget/grid/mod.rs index e561a22a..f4c8c652 100644 --- a/src/widget/grid/mod.rs +++ b/src/widget/grid/mod.rs @@ -1,12 +1,14 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Arrange widgets with a grid layout. + pub mod layout; pub mod widget; pub use widget::Grid; -/// Responsively generates rows and columns of widgets based on its dimmensions. +/// Arrange widgets with a grid layout. pub const fn grid<'a, Message>() -> Grid<'a, Message> { Grid::new() } diff --git a/src/widget/mod.rs b/src/widget/mod.rs index 94e07af0..e0745dce 100644 --- a/src/widget/mod.rs +++ b/src/widget/mod.rs @@ -1,7 +1,50 @@ // Copyright 2022 System76 // SPDX-License-Identifier: MPL-2.0 -//! Cosmic-themed widget implementations. +//! The COSMIC widget library +//! +//! This module contains a wide variety of widgets used throughout the COSMIC app ecosystem. +//! +//! # Overview +//! +//! Add widgets to your application view by calling the modules and functions below. +//! Widgets are constructed by chaining their property methods using a functional paradigm. +//! Modules may contain additional functions for constructing different variations of a widget. +//! Each module will typically have one widget with the same name as the module, which will be re-exported here. +//! +//! ```no_run +//! use cosmic::prelude::*; +//! use cosmic::{cosmic_theme, theme, widget}; +//! +//! const REPOSITORY: &str = "https://github.com/pop-os/libcosmic"; +//! +//! let cosmic_theme::Spacing { space_xxs, .. } = theme::active().cosmic().spacing; +//! +//! let link = widget::button::link(REPOSITORY) +//! .on_press(Message::LaunchUrl(REPOSITORY)) +//! .padding(0); +//! +//! let content = widget::column() +//! .push(widget::icon::from_name("my-app-icon")) +//! .push(widget::text::title3("My App Name")) +//! .push(link) +//! .align_items(Alignment::Center) +//! .spacing(space_xxs); +//! ``` +//! +//! Widgets may borrow data from your application struct, and should do so to avoid allocating. +//! +//! ```no_run +//! let text = widget::text::body(&self.cached_text); +//! ``` +//! +//! Use the [`cosmic::Apply`](crate::Apply) trait to embed widgets into other widgets which accept them. +//! +//! ```no_run +//! let button = widget::icon::from_name("printer-symbolic") +//! .apply(widget::button::icon) +//! .on_press(Message::Print); +//! ``` // Re-exports from Iced #[doc(inline)] @@ -73,19 +116,24 @@ pub use context_drawer::{context_drawer, ContextDrawer}; #[doc(inline)] pub use column::{column, Column}; pub mod column { + //! A container which aligns its children in a column. + pub type Column<'a, Message> = iced::widget::Column<'a, Message, crate::Theme, crate::Renderer>; #[must_use] + /// A container which aligns its children in a column. pub fn column<'a, Message>() -> Column<'a, Message> { Column::new() } #[must_use] + /// A pre-allocated [`column`]. pub fn with_capacity<'a, Message>(capacity: usize) -> Column<'a, Message> { Column::with_children(Vec::with_capacity(capacity)) } #[must_use] + /// A [`column`] that will be assigned a [`Vec`] of children. pub fn with_children(children: Vec>) -> Column { Column::with_children(children) } @@ -207,20 +255,26 @@ pub use rectangle_tracker::{rectangle_tracker, RectangleTracker}; #[doc(inline)] pub use row::{row, Row}; + pub mod row { + //! A container which aligns its children in a row. + pub type Row<'a, Message> = iced::widget::Row<'a, Message, crate::Theme, crate::Renderer>; #[must_use] + /// A container which aligns its children in a row. pub fn row<'a, Message>() -> Row<'a, Message> { Row::new() } #[must_use] + /// A pre-allocated [`row`]. pub fn with_capacity<'a, Message>(capacity: usize) -> Row<'a, Message> { Row::with_children(Vec::with_capacity(capacity)) } #[must_use] + /// A [`row`] that will be assigned a [`Vec`] of children. pub fn with_children(children: Vec>) -> Row { Row::with_children(children) } diff --git a/src/widget/spin_button/mod.rs b/src/widget/spin_button/mod.rs index 62c1e12d..b8806d6e 100644 --- a/src/widget/spin_button/mod.rs +++ b/src/widget/spin_button/mod.rs @@ -1,6 +1,8 @@ // Copyright 2022 System76 // SPDX-License-Identifier: MPL-2.0 +//! A control for incremental adjustments of a value. + mod model; use std::borrow::Cow; @@ -20,6 +22,7 @@ pub struct SpinButton<'a, Message> { on_change: Box Message + 'static>, } +/// A control for incremental adjustments of a value. pub fn spin_button<'a, Message: 'static>( label: impl Into>, on_change: impl Fn(model::Message) -> Message + 'static,