iced_widget/
rule.rs

1//! Rules divide space horizontally or vertically.
2//!
3//! # Example
4//! ```no_run
5//! # mod iced { pub mod widget { pub use iced_widget::*; } }
6//! # pub type State = ();
7//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
8//! use iced::widget::horizontal_rule;
9//!
10//! #[derive(Clone)]
11//! enum Message {
12//!     // ...,
13//! }
14//!
15//! fn view(state: &State) -> Element<'_, Message> {
16//!     horizontal_rule(2).into()
17//! }
18//! ```
19use crate::core;
20use crate::core::border;
21use crate::core::layout;
22use crate::core::mouse;
23use crate::core::renderer;
24use crate::core::widget::Tree;
25use crate::core::{
26    Color, Element, Layout, Length, Pixels, Rectangle, Size, Theme, Widget,
27};
28
29/// Display a horizontal or vertical rule for dividing content.
30///
31/// # Example
32/// ```no_run
33/// # mod iced { pub mod widget { pub use iced_widget::*; } }
34/// # pub type State = ();
35/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
36/// use iced::widget::horizontal_rule;
37///
38/// #[derive(Clone)]
39/// enum Message {
40///     // ...,
41/// }
42///
43/// fn view(state: &State) -> Element<'_, Message> {
44///     horizontal_rule(2).into()
45/// }
46/// ```
47#[allow(missing_debug_implementations)]
48pub struct Rule<'a, Theme = crate::Theme>
49where
50    Theme: Catalog,
51{
52    width: Length,
53    height: Length,
54    is_horizontal: bool,
55    class: Theme::Class<'a>,
56}
57
58impl<'a, Theme> Rule<'a, Theme>
59where
60    Theme: Catalog,
61{
62    /// Creates a horizontal [`Rule`] with the given height.
63    pub fn horizontal(height: impl Into<Pixels>) -> Self {
64        Rule {
65            width: Length::Fill,
66            height: Length::Fixed(height.into().0),
67            is_horizontal: true,
68            class: Theme::default(),
69        }
70    }
71
72    /// Creates a vertical [`Rule`] with the given width.
73    pub fn vertical(width: impl Into<Pixels>) -> Self {
74        Rule {
75            width: Length::Fixed(width.into().0),
76            height: Length::Fill,
77            is_horizontal: false,
78            class: Theme::default(),
79        }
80    }
81
82    /// Sets the style of the [`Rule`].
83    #[must_use]
84    pub fn style(mut self, style: impl Fn(&Theme) -> Style + 'a) -> Self
85    where
86        Theme::Class<'a>: From<StyleFn<'a, Theme>>,
87    {
88        self.class = (Box::new(style) as StyleFn<'a, Theme>).into();
89        self
90    }
91
92    /// Sets the style class of the [`Rule`].
93    #[cfg(feature = "advanced")]
94    #[must_use]
95    pub fn class(mut self, class: impl Into<Theme::Class<'a>>) -> Self {
96        self.class = class.into();
97        self
98    }
99}
100
101impl<Message, Theme, Renderer> Widget<Message, Theme, Renderer>
102    for Rule<'_, Theme>
103where
104    Renderer: core::Renderer,
105    Theme: Catalog,
106{
107    fn size(&self) -> Size<Length> {
108        Size {
109            width: self.width,
110            height: self.height,
111        }
112    }
113
114    fn layout(
115        &mut self,
116        _tree: &mut Tree,
117        _renderer: &Renderer,
118        limits: &layout::Limits,
119    ) -> layout::Node {
120        layout::atomic(limits, self.width, self.height)
121    }
122
123    fn draw(
124        &self,
125        _state: &Tree,
126        renderer: &mut Renderer,
127        theme: &Theme,
128        _style: &renderer::Style,
129        layout: Layout<'_>,
130        _cursor: mouse::Cursor,
131        _viewport: &Rectangle,
132    ) {
133        let bounds = layout.bounds();
134        let style = theme.style(&self.class);
135
136        let bounds = if self.is_horizontal {
137            let line_y = bounds.y.round();
138
139            let (offset, line_width) = style.fill_mode.fill(bounds.width);
140            let line_x = bounds.x + offset;
141
142            Rectangle {
143                x: line_x,
144                y: line_y,
145                width: line_width,
146                height: bounds.height,
147            }
148        } else {
149            let line_x = bounds.x.round();
150
151            let (offset, line_height) = style.fill_mode.fill(bounds.height);
152            let line_y = bounds.y + offset;
153
154            Rectangle {
155                x: line_x,
156                y: line_y,
157                width: bounds.width,
158                height: line_height,
159            }
160        };
161
162        renderer.fill_quad(
163            renderer::Quad {
164                bounds,
165                border: border::rounded(style.radius),
166                snap: style.snap,
167                ..renderer::Quad::default()
168            },
169            style.color,
170        );
171    }
172}
173
174impl<'a, Message, Theme, Renderer> From<Rule<'a, Theme>>
175    for Element<'a, Message, Theme, Renderer>
176where
177    Message: 'a,
178    Theme: 'a + Catalog,
179    Renderer: 'a + core::Renderer,
180{
181    fn from(rule: Rule<'a, Theme>) -> Element<'a, Message, Theme, Renderer> {
182        Element::new(rule)
183    }
184}
185
186/// The appearance of a rule.
187#[derive(Debug, Clone, Copy, PartialEq)]
188pub struct Style {
189    /// The color of the rule.
190    pub color: Color,
191    /// The radius of the line corners.
192    pub radius: border::Radius,
193    /// The [`FillMode`] of the rule.
194    pub fill_mode: FillMode,
195    /// Whether the rule should be snapped to the pixel grid.
196    pub snap: bool,
197}
198
199/// The fill mode of a rule.
200#[derive(Debug, Clone, Copy, PartialEq)]
201pub enum FillMode {
202    /// Fill the whole length of the container.
203    Full,
204    /// Fill a percent of the length of the container. The rule
205    /// will be centered in that container.
206    ///
207    /// The range is `[0.0, 100.0]`.
208    Percent(f32),
209    /// Uniform offset from each end, length units.
210    Padded(u16),
211    /// Different offset on each end of the rule, length units.
212    /// First = top or left.
213    AsymmetricPadding(u16, u16),
214}
215
216impl FillMode {
217    /// Return the starting offset and length of the rule.
218    ///
219    /// * `space` - The space to fill.
220    ///
221    /// # Returns
222    ///
223    /// * (`starting_offset`, `length`)
224    pub fn fill(&self, space: f32) -> (f32, f32) {
225        match *self {
226            FillMode::Full => (0.0, space),
227            FillMode::Percent(percent) => {
228                if percent >= 100.0 {
229                    (0.0, space)
230                } else {
231                    let percent_width = (space * percent / 100.0).round();
232
233                    (((space - percent_width) / 2.0).round(), percent_width)
234                }
235            }
236            FillMode::Padded(padding) => {
237                if padding == 0 {
238                    (0.0, space)
239                } else {
240                    let padding = padding as f32;
241                    let mut line_width = space - (padding * 2.0);
242                    if line_width < 0.0 {
243                        line_width = 0.0;
244                    }
245
246                    (padding, line_width)
247                }
248            }
249            FillMode::AsymmetricPadding(first_pad, second_pad) => {
250                let first_pad = first_pad as f32;
251                let second_pad = second_pad as f32;
252                let mut line_width = space - first_pad - second_pad;
253                if line_width < 0.0 {
254                    line_width = 0.0;
255                }
256
257                (first_pad, line_width)
258            }
259        }
260    }
261}
262
263/// The theme catalog of a [`Rule`].
264pub trait Catalog: Sized {
265    /// The item class of the [`Catalog`].
266    type Class<'a>;
267
268    /// The default class produced by the [`Catalog`].
269    fn default<'a>() -> Self::Class<'a>;
270
271    /// The [`Style`] of a class with the given status.
272    fn style(&self, class: &Self::Class<'_>) -> Style;
273}
274
275/// A styling function for a [`Rule`].
276///
277/// This is just a boxed closure: `Fn(&Theme, Status) -> Style`.
278pub type StyleFn<'a, Theme> = Box<dyn Fn(&Theme) -> Style + 'a>;
279
280impl Catalog for Theme {
281    type Class<'a> = StyleFn<'a, Self>;
282
283    fn default<'a>() -> Self::Class<'a> {
284        Box::new(default)
285    }
286
287    fn style(&self, class: &Self::Class<'_>) -> Style {
288        class(self)
289    }
290}
291
292/// The default styling of a [`Rule`].
293pub fn default(theme: &Theme) -> Style {
294    let palette = theme.extended_palette();
295
296    Style {
297        color: palette.background.strong.color,
298        radius: 0.0.into(),
299        fill_mode: FillMode::Full,
300        snap: true,
301    }
302}
303
304/// A [`Rule`] styling using the weak background color.
305pub fn weak(theme: &Theme) -> Style {
306    let palette = theme.extended_palette();
307
308    Style {
309        color: palette.background.weak.color,
310        radius: 0.0.into(),
311        fill_mode: FillMode::Full,
312        snap: true,
313    }
314}
iced_widget/rule.rs

iced_widget/
rule.rs
