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