Skip to main content

crabshell_ui/
prop.rs

1//! Widget properties that take either a plain value or a closure.
2
3use std::cell::RefCell;
4use std::path::{Path, PathBuf};
5use std::rc::Rc;
6use std::time::Duration;
7
8use crate::animation::Transition;
9use crate::image::ImageTransition;
10use crate::input::CursorShape;
11use crate::menu::MenuEntry;
12use crate::popup::Adjust;
13use crate::region::Region;
14use crate::rich::Span;
15use crate::screencopy::CaptureSource;
16use crate::style::{Color, Style};
17use crate::widgets::{Align, Elide, Fit, IconSource, Justify};
18use crate::window::{Anchors, Edge, KeyboardFocus, Layer, Margins};
19
20/// A widget property: either a value set once, or a binding that reruns
21/// whenever a signal it read changes.
22///
23/// You never build one yourself. Widget methods take `impl IntoProp<T>`, so
24/// `.height(30)` sets a value and `.height(move || ...)` makes a binding.
25pub struct Prop<T>(pub(crate) PropKind<T>);
26
27impl<T: Clone + 'static> Prop<T> {
28  /// The property as a closure that can be called again and shared, as a
29  /// widget built from other widgets hands one property to many of them.
30  /// A binding stays one: whatever calls it subscribes to the signals it
31  /// reads.
32  pub fn shared(self) -> Rc<dyn Fn() -> T> {
33    match self.0 {
34      PropKind::Value(value) => Rc::new(move || value.clone()),
35      PropKind::Binding(compute) => {
36        let compute = RefCell::new(compute);
37        Rc::new(move || (compute.borrow_mut())())
38      }
39    }
40  }
41}
42
43impl<T: 'static> Prop<T> {
44  /// The property with `f` applied to each value it takes.
45  pub(crate) fn map<U>(self, f: impl Fn(T) -> U + 'static) -> Prop<U> {
46    Prop(match self.0 {
47      PropKind::Value(value) => PropKind::Value(f(value)),
48      PropKind::Binding(mut compute) => PropKind::Binding(Box::new(move || f(compute()))),
49    })
50  }
51}
52
53pub(crate) enum PropKind<T> {
54  Value(T),
55  Binding(Box<dyn FnMut() -> T>),
56}
57
58/// Anything a widget property accepts: a value of type `T`, or a closure
59/// that returns one.
60///
61/// Plain values work for the property types this crate uses, and a string
62/// slice works where a `String` is expected. Any `FnMut() -> T` closure
63/// works too: it runs in an effect, so it reruns when a signal it read
64/// changes.
65pub trait IntoProp<T> {
66  /// Wraps the value or closure.
67  fn into_prop(self) -> Prop<T>;
68}
69
70// A closure is a binding. This impl can sit next to the value impls below
71// because Rust knows that no plain type like `u32` implements `FnMut`.
72impl<T, F> IntoProp<T> for F
73where
74  F: FnMut() -> T + 'static,
75{
76  fn into_prop(self) -> Prop<T> {
77    Prop(PropKind::Binding(Box::new(self)))
78  }
79}
80
81/// A property taken from one widget can be handed to another, as a widget
82/// built from others passes its own on.
83impl<T> IntoProp<T> for Prop<T> {
84  fn into_prop(self) -> Prop<T> {
85    self
86  }
87}
88
89/// Any `Option` passes as a plain value, as `None` or `Some(value)`. It
90/// can sit beside the closure impl for the same reason the ones below do.
91impl<T> IntoProp<Option<T>> for Option<T> {
92  fn into_prop(self) -> Prop<Option<T>> {
93    Prop(PropKind::Value(self))
94  }
95}
96
97/// Lets each listed type be passed as a plain value.
98macro_rules! value_props {
99    ($($ty:ty),* $(,)?) => {
100        $(
101            impl IntoProp<$ty> for $ty {
102                fn into_prop(self) -> Prop<$ty> {
103                    Prop(PropKind::Value(self))
104                }
105            }
106        )*
107    };
108}
109
110value_props!(
111  bool,
112  u32,
113  i32,
114  f32,
115  String,
116  Style,
117  Align,
118  Elide,
119  Justify,
120  Anchors,
121  Layer,
122  Margins,
123  KeyboardFocus,
124  PathBuf,
125  Fit,
126  (u32, u32),
127  Adjust,
128  IconSource,
129  CaptureSource,
130  Vec<MenuEntry>,
131  Vec<Span>,
132  Duration,
133  CursorShape,
134  Transition,
135  ImageTransition,
136);
137
138impl IntoProp<String> for &str {
139  fn into_prop(self) -> Prop<String> {
140    Prop(PropKind::Value(self.to_owned()))
141  }
142}
143
144impl IntoProp<Option<Region>> for Region {
145  fn into_prop(self) -> Prop<Option<Region>> {
146    Prop(PropKind::Value(Some(self)))
147  }
148}
149
150impl IntoProp<Option<Color>> for Color {
151  fn into_prop(self) -> Prop<Option<Color>> {
152    Prop(PropKind::Value(Some(self)))
153  }
154}
155
156impl IntoProp<Option<Style>> for Style {
157  fn into_prop(self) -> Prop<Option<Style>> {
158    Prop(PropKind::Value(Some(self)))
159  }
160}
161
162impl IntoProp<Anchors> for Edge {
163  fn into_prop(self) -> Prop<Anchors> {
164    Prop(PropKind::Value(Anchors::from(self)))
165  }
166}
167
168/// An icon name, such as `"audio-volume-high"`.
169impl IntoProp<IconSource> for &str {
170  fn into_prop(self) -> Prop<IconSource> {
171    Prop(PropKind::Value(IconSource::Name(self.to_owned())))
172  }
173}
174
175/// An icon name, as tray items send them.
176impl IntoProp<IconSource> for String {
177  fn into_prop(self) -> Prop<IconSource> {
178    Prop(PropKind::Value(IconSource::Name(self)))
179  }
180}
181
182impl IntoProp<PathBuf> for &Path {
183  fn into_prop(self) -> Prop<PathBuf> {
184    Prop(PropKind::Value(self.to_owned()))
185  }
186}
187
188impl IntoProp<PathBuf> for &PathBuf {
189  fn into_prop(self) -> Prop<PathBuf> {
190    Prop(PropKind::Value(self.clone()))
191  }
192}
193
194impl IntoProp<PathBuf> for &str {
195  fn into_prop(self) -> Prop<PathBuf> {
196    Prop(PropKind::Value(PathBuf::from(self)))
197  }
198}
199
200impl IntoProp<PathBuf> for String {
201  fn into_prop(self) -> Prop<PathBuf> {
202    Prop(PropKind::Value(PathBuf::from(self)))
203  }
204}
205
206/// An SVG or PNG file.
207impl IntoProp<IconSource> for &Path {
208  fn into_prop(self) -> Prop<IconSource> {
209    Prop(PropKind::Value(IconSource::File(self.to_owned())))
210  }
211}
212
213/// An SVG or PNG file.
214impl IntoProp<IconSource> for PathBuf {
215  fn into_prop(self) -> Prop<IconSource> {
216    Prop(PropKind::Value(IconSource::File(self)))
217  }
218}
219
220#[cfg(test)]
221mod tests {
222  use std::path::PathBuf;
223
224  use super::{IntoProp, PropKind};
225
226  fn value(prop: impl IntoProp<PathBuf>) -> Option<PathBuf> {
227    match prop.into_prop().0 {
228      PropKind::Value(value) => Some(value),
229      PropKind::Binding(_) => None,
230    }
231  }
232
233  #[test]
234  fn a_path_buf_by_reference_is_a_plain_value() {
235    let path = PathBuf::from("/walls");
236    assert_eq!(value(&path), Some(path.clone()));
237    assert_eq!(value(path.as_path()), Some(path.clone()));
238    assert_eq!(value("/walls"), Some(path));
239  }
240}