me/iced
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix documentation of markdown and rich_text

Browse source
This commit is contained in:
Héctor Ramón Jiménez 2025-02-04 19:07:24 +01:00
parent 5655998761
commit 24cf355e96
No known key found for this signature in database
GPG key ID: 7CC46565708259A7
6 changed files with 87 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

9
core/src/lib.rs
View file

@ -84,3 +84,12 @@ pub use vector::Vector;
pub use widget::Widget;
pub use smol_str::SmolStr;
/// A function that can _never_ be called.
///
/// This is useful to turn generic types into anything
/// you want by coercing them into a type with no possible
/// values.
pub fn never<T>(never: std::convert::Infallible) -> T {
match never {}
}

8
examples/changelog/src/main.rs
View file

@ -280,7 +280,7 @@ impl Generator {
.font(Font::MONOSPACE);
let description =
markdown::view(&self.theme(), description)
markdown(description, self.theme())
.map(Message::UrlClicked);
let labels =
@ -344,12 +344,12 @@ impl Generator {
} else {
container(
scrollable(
markdown::view(
markdown(
preview,
markdown::Settings::with_text_size(
12,
&self.theme(),
self.theme(),
),
preview,
)
.map(Message::UrlClicked),
)

4
examples/markdown/src/main.rs
View file

@ -164,11 +164,11 @@ impl Markdown {
};
let preview = markdown::view_with(
items,
&self.theme,
&MarkdownViewer {
images: &self.images,
},
&self.theme,
items,
);
row![

6
src/lib.rs
View file

@ -505,9 +505,9 @@ pub use crate::core::gradient;
pub use crate::core::padding;
pub use crate::core::theme;
pub use crate::core::{
Alignment, Animation, Background, Border, Color, ContentFit, Degrees,
Gradient, Length, Padding, Pixels, Point, Radians, Rectangle, Rotation,
Settings, Shadow, Size, Theme, Transformation, Vector,
never, Alignment, Animation, Background, Border, Color, ContentFit,
Degrees, Gradient, Length, Padding, Pixels, Point, Radians, Rectangle,
Rotation, Settings, Shadow, Size, Theme, Transformation, Vector,
};
pub use crate::runtime::exit;
pub use iced_futures::Subscription;

12
widget/src/helpers.rs
View file

@ -167,7 +167,7 @@ macro_rules! text {
/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
/// use iced::font;
/// use iced::widget::{rich_text, span};
/// use iced::{color, Font};
/// use iced::{color, never, Font};
///
/// #[derive(Debug, Clone)]
/// enum Message {
@ -177,9 +177,10 @@ macro_rules! text {
/// fn view(state: &State) -> Element<'_, Message> {
/// rich_text![
/// span("I am red!").color(color!(0xff0000)),
/// " ",
/// span(" "),
/// span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
/// ]
/// .on_link_clicked(never)
/// .size(20)
/// .into()
/// }
@ -1138,10 +1139,11 @@ where
/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
/// use iced::font;
/// use iced::widget::{rich_text, span};
/// use iced::{color, Font};
/// use iced::{color, never, Font};
///
/// #[derive(Debug, Clone)]
/// enum Message {
/// LinkClicked(&'static str),
/// // ...
/// }
///
@ -1151,6 +1153,7 @@ where
/// span(" "),
/// span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
/// ])
/// .on_link_clicked(never)
/// .size(20)
/// .into()
/// }
@ -1181,7 +1184,7 @@ where
/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
/// use iced::font;
/// use iced::widget::{rich_text, span};
/// use iced::{color, Font};
/// use iced::{color, never, Font};
///
/// #[derive(Debug, Clone)]
/// enum Message {
@ -1194,6 +1197,7 @@ where
/// " ",
/// span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
/// ]
/// .on_link_clicked(never)
/// .size(20)
/// .into()
/// }

99
widget/src/markdown.rs
View file

@ -29,13 +29,9 @@
//! }
//!
//! fn view(&self) -> Element<'_, Message> {
//! markdown::view(
//! &self.markdown,
//! markdown::Settings::default(),
//! markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
//! )
//! .map(Message::LinkClicked)
//! .into()
//! markdown::view(&self.markdown, Theme::TokyoNight)
//! .map(Message::LinkClicked)
//! .into()
//! }
//!
//! fn update(state: &mut State, message: Message) {
@ -47,7 +43,6 @@
//! }
//! }
//! ```
#![allow(missing_docs)]
use crate::core::border;
use crate::core::font::{self, Font};
use crate::core::padding;
@ -334,13 +329,9 @@ impl Span {
/// }
///
/// fn view(&self) -> Element<'_, Message> {
/// markdown::view(
/// &self.markdown,
/// markdown::Settings::default(),
/// markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
/// )
/// .map(Message::LinkClicked)
/// .into()
/// markdown::view(&self.markdown, Theme::TokyoNight)
/// .map(Message::LinkClicked)
/// .into()
/// }
///
/// fn update(state: &mut State, message: Message) {
@ -867,6 +858,12 @@ impl From<&Theme> for Settings {
}
}
impl From<Theme> for Settings {
fn from(theme: Theme) -> Self {
Self::with_style(Style::from(theme))
}
}
/// The text styling of some Markdown rendering in [`view`].
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Style {
@ -907,6 +904,12 @@ impl From<&Theme> for Style {
}
}
impl From<Theme> for Style {
fn from(theme: Theme) -> Self {
Self::from_palette(theme.palette())
}
}
/// Display a bunch of Markdown items.
///
/// You can obtain the items with [`parse`].
@ -935,13 +938,9 @@ impl From<&Theme> for Style {
/// }
///
/// fn view(&self) -> Element<'_, Message> {
/// markdown::view(
/// &self.markdown,
/// markdown::Settings::default(),
/// markdown::Style::from_palette(Theme::TokyoNightStorm.palette()),
/// )
/// .map(Message::LinkClicked)
/// .into()
/// markdown::view(&self.markdown, Theme::TokyoNight)
/// .map(Message::LinkClicked)
/// .into()
/// }
///
/// fn update(state: &mut State, message: Message) {
@ -954,28 +953,25 @@ impl From<&Theme> for Style {
/// }
/// ```
pub fn view<'a, Theme, Renderer>(
settings: impl Into<Settings>,
items: impl IntoIterator<Item = &'a Item>,
settings: impl Into<Settings>,
) -> Element<'a, Url, Theme, Renderer>
where
Theme: Catalog + 'a,
Renderer: core::text::Renderer<Font = Font> + 'a,
{
view_with(&DefaultViewer, settings, items)
view_with(items, settings, &DefaultViewer)
}
/// Runs [`view`] but with a custom [`View`] to turn an [`Item`] into
/// Runs [`view`] but with a custom [`Viewer`] to turn an [`Item`] into
/// an [`Element`].
///
/// This is useful if you want to customize the look of certain Markdown
/// elements.
///
/// You can use [`Item::view`] and [`Item::view_with`] for the default
/// look.
pub fn view_with<'a, Message, Theme, Renderer>(
viewer: &impl Viewer<'a, Message, Theme, Renderer>,
settings: impl Into<Settings>,
items: impl IntoIterator<Item = &'a Item>,
settings: impl Into<Settings>,
viewer: &impl Viewer<'a, Message, Theme, Renderer>,
) -> Element<'a, Message, Theme, Renderer>
where
Message: 'a,
@ -992,6 +988,7 @@ where
Element::new(column(blocks).spacing(settings.spacing))
}
/// Displays an [`Item`] using the given [`Viewer`].
pub fn item<'a, Message, Theme, Renderer>(
viewer: &impl Viewer<'a, Message, Theme, Renderer>,
settings: Settings,
@ -1006,7 +1003,7 @@ where
match item {
Item::Image { title, url } => viewer.image(settings, title, url),
Item::Heading(level, text) => {
viewer.heading(settings, index, level, text)
viewer.heading(settings, level, text, index)
}
Item::Paragraph(text) => viewer.paragraph(settings, text),
Item::CodeBlock(lines) => viewer.code_block(settings, lines),
@ -1020,11 +1017,12 @@ where
}
}
/// Displays a heading using the default look.
pub fn heading<'a, Message, Theme, Renderer>(
settings: Settings,
index: usize,
level: &'a HeadingLevel,
text: &'a Text,
index: usize,
on_link_clicked: impl Fn(Url) -> Message + 'a,
) -> Element<'a, Message, Theme, Renderer>
where
@ -1063,6 +1061,7 @@ where
.into()
}
/// Displays a paragraph using the default look.
pub fn paragraph<'a, Message, Theme, Renderer>(
settings: Settings,
text: &'a Text,
@ -1079,6 +1078,8 @@ where
.into()
}
/// Displays an unordered list using the default look and
/// calling the [`Viewer`] for each bullet point item.
pub fn unordered_list<'a, Message, Theme, Renderer>(
viewer: &impl Viewer<'a, Message, Theme, Renderer>,
settings: Settings,
@ -1093,12 +1094,12 @@ where
row![
text("•").size(settings.text_size),
view_with(
viewer,
items,
Settings {
spacing: settings.spacing * 0.6,
..settings
},
items,
viewer,
)
]
.spacing(settings.spacing)
@ -1109,6 +1110,8 @@ where
.into()
}
/// Displays an ordered list using the default look and
/// calling the [`Viewer`] for each numbered item.
pub fn ordered_list<'a, Message, Theme, Renderer>(
viewer: &impl Viewer<'a, Message, Theme, Renderer>,
settings: Settings,
@ -1124,12 +1127,12 @@ where
row![
text!("{}.", i as u64 + start).size(settings.text_size),
view_with(
viewer,
items,
Settings {
spacing: settings.spacing * 0.6,
..settings
},
items,
viewer,
)
]
.spacing(settings.spacing)
@ -1140,6 +1143,7 @@ where
.into()
}
/// Displays a code block using the default look.
pub fn code_block<'a, Message, Theme, Renderer>(
settings: Settings,
lines: &'a [Text],
@ -1181,8 +1185,12 @@ where
Theme: Catalog + 'a,
Renderer: core::text::Renderer<Font = Font> + 'a,
{
/// Produces a message when a link is clicked with the given [`Url`].
fn on_link_clicked(url: Url) -> Message;
/// Displays an image.
///
/// By default, it will show a container with the image title.
fn image(
&self,
settings: Settings,
@ -1200,16 +1208,22 @@ where
.into()
}
/// Displays a heading.
///
/// By default, it calls [`heading`].
fn heading(
&self,
settings: Settings,
index: usize,
level: &'a HeadingLevel,
text: &'a Text,
index: usize,
) -> Element<'a, Message, Theme, Renderer> {
heading(settings, index, level, text, Self::on_link_clicked)
heading(settings, level, text, index, Self::on_link_clicked)
}
/// Displays a paragraph.
///
/// By default, it calls [`paragraph`].
fn paragraph(
&self,
settings: Settings,
@ -1218,6 +1232,9 @@ where
paragraph(settings, text, Self::on_link_clicked)
}
/// Displays a code block.
///
/// By default, it calls [`code_block`].
fn code_block(
&self,
settings: Settings,
@ -1226,6 +1243,9 @@ where
code_block(settings, lines, Self::on_link_clicked)
}
/// Displays an unordered list.
///
/// By default, it calls [`unordered_list`].
fn unordered_list(
&self,
settings: Settings,
@ -1234,6 +1254,9 @@ where
unordered_list(self, settings, items)
}
/// Displays an ordered list.
///
/// By default, it calls [`ordered_list`].
fn ordered_list(
&self,
settings: Settings,