makeover_immediate/lib.rs
1//! The immediate-mode renderer for [`makeover_layout`], written against egui.
2//!
3//! <!-- wiki: makeover-immediate -->
4//!
5//! egui's `Visuals.widgets.*.bg_stroke` is one stroke with no per-side
6//! control, so the two-tone lit edge is painted here by hand
7//! ([`paint_bevel`]).
8//!
9//! # What this crate draws
10//!
11//! The parts of the description that carry no vocabulary member: depth
12//! ([`frame`], [`paint_bevel`]), the resolved colours ([`Palette`]), a table's
13//! per-frame facts and cell tones ([`table`]), the token and the waiting
14//! marks ([`piece`]), and the egui visuals and metrics a host starts from
15//! ([`host`]).
16//!
17//! The vocabulary members (fields, columns, meters, controls, facts, figures
18//! and charts) are drawn by `quasi-immediate`, which owns those types through
19//! `quasi-router` and calls into this crate for everything above. The style
20//! types it draws them with stay here: [`FieldStyle`], [`Editing`],
21//! [`piece::PieceStyle`] and [`table::TableStyle`].
22//!
23//! # What this crate does and does not own
24//!
25//! It owns the expression: two mitred polylines for a bevel and a `Frame` for
26//! a filled region. It owns no colours and makes no substitutions: the caller
27//! supplies [`Palette`] already resolved.
28//!
29//! Every radius, margin, stroke width and floor arrives in a style type
30//! ([`FrameStyle`], [`FieldStyle`], [`piece::PieceStyle`],
31//! [`table::TableStyle`], [`host::Metrics`]). The focus ring and target floor
32//! in [`host::Metrics`] default to what `makeover-webview` emits.
33//!
34//! `makeover` itself is linked only by the `theme` feature, for
35//! `Palette::from_theme`; it embeds every shipped theme file.
36//!
37//! # Pressed state
38//!
39//! There is no cascade to carry a pressed state, so each call site asks
40//! [`makeover_layout::Depth::pressed`] for the depth a pressed region takes.
41//!
42//! # Overlays
43//!
44//! [`frame`] hands [`Palette::cast`] to the `egui::Frame` for any depth whose
45//! fill is [`Fill::Overlay`], keyed off the fill rather than the variant.
46//!
47//! # Focus and chrome
48//!
49//! egui decides what is reachable and what holds the keyboard, and paints the
50//! one focus ring; this crate draws no ring of its own. The terms are defined
51//! in `makeover_layout`'s crate header, "Reach, focus and the focus ring".
52//!
53//! App-level chrome is not drawn here. `quasi-router` names the affordances
54//! that outlive one screen and `quasi-immediate` answers them; this crate
55//! depends on `makeover-layout` and not on `quasi-router`.
56
57#![forbid(unsafe_code)]
58
59use egui::{Color32, CornerRadius, Margin, Painter, Rect, Shape, Stroke, Ui};
60use makeover_layout::{Bevel, Depth, Edge, Fill, HEAT_BANDS, Heat, Tone};
61
62pub mod host;
63pub mod piece;
64pub mod table;
65
66/// The resolved colours this renderer needs, as flat values.
67///
68/// Built by the app from whatever it already uses to resolve a theme, then
69/// held and reused.
70///
71/// `#[non_exhaustive]`, so a colour added here is not a breaking change: build
72/// one with `Palette::from_theme` (the `theme` feature), or start from
73/// [`Palette::two_tone`] and set every colour the app resolves.
74#[derive(Debug, Clone, Copy, PartialEq, Eq)]
75#[non_exhaustive]
76pub struct Palette {
77 /// `surface-page`.
78 pub page: Color32,
79 /// `surface-raised`.
80 pub raised: Color32,
81 /// `surface-overlay`.
82 pub overlay: Color32,
83 /// `surface-well`. Required: makeover derives it for every theme.
84 pub well: Color32,
85 /// `surface-sunken`.
86 ///
87 /// A surface set back from the one it sits on, by colour and with no edge;
88 /// a well has an edge. Required: every theme makeover embeds authors it.
89 pub sunken: Color32,
90 /// `bevel-light`.
91 pub bevel_light: Color32,
92 /// `bevel-dark`.
93 pub bevel_dark: Color32,
94 /// `elevation`.
95 ///
96 /// The colour a surface that floats over the page (a menu, a tooltip, a
97 /// modal) is cast onto it with: a translucent near-black on every theme.
98 /// A surface in the layout takes a bevel instead. [`Palette::cast`] is the
99 /// shadow to hand an [`egui::Frame`].
100 pub elevation: Color32,
101 /// `content`.
102 ///
103 /// Ordinary text.
104 pub content: Color32,
105 /// `content-secondary`.
106 ///
107 /// Inactive but usable: it still answers a press. The middle tone of the
108 /// three (wiki `three-tone-convention`), and the one an unchosen option in
109 /// a choice field takes. Distinct from
110 /// [`content_disabled`](Self::content_disabled), which
111 /// `State::Disabled` resolves to.
112 ///
113 /// A step of `content` toward the page, derived at load by `makeover` and
114 /// read off the resolved theme like any other token.
115 pub content_secondary: Color32,
116 /// `content-muted`.
117 ///
118 /// A field's hint, a caption, a reading: text that was never a control.
119 /// Held to body text's floor.
120 pub content_muted: Color32,
121 /// `content-disabled`.
122 ///
123 /// What [`makeover_layout::State::Disabled`] resolves to, by token: the
124 /// label of a control that will not answer, fainter than any hint.
125 pub content_disabled: Color32,
126 /// `action-primary`.
127 ///
128 /// What a control is drawn in, and the intent
129 /// [`CellPart`](makeover_layout::CellPart) separates from a cell's text.
130 pub action: Color32,
131 /// `content-on-action`: ink that stays readable on [`action`](Self::action).
132 ///
133 /// Resolved by makeover: the theme's page or content where one reads at
134 /// 4.5:1 on the accent, black or white otherwise. The label of the leading
135 /// control, the one control filled with `action`.
136 pub content_on_action: Color32,
137 /// `danger`.
138 ///
139 /// A field's error message, a destructive control, a bar that has run over.
140 pub danger: Color32,
141 /// `success`.
142 pub success: Color32,
143 /// `warning`.
144 pub warning: Color32,
145 /// `info`.
146 pub info: Color32,
147 /// `border`, the authored line colour.
148 ///
149 /// A neutral badge's edge.
150 pub border: Color32,
151 /// `info-surface`: raised with 12 percent of `info`. A badge's fill.
152 pub info_surface: Color32,
153 /// `success-surface`.
154 pub success_surface: Color32,
155 /// `warning-surface`.
156 pub warning_surface: Color32,
157 /// `danger-surface`.
158 pub danger_surface: Color32,
159 /// `row-hover`: the row under the pointer, at 9 percent.
160 pub row_hover: Color32,
161 /// `row-rule`: the hairline between rows and around a table, at 26
162 /// percent.
163 pub row_rule: Color32,
164 /// `row-selected`: a selected row, raised with 18 percent of the content
165 /// ink (a neutral-ramp step). A fill and never a foreground.
166 pub row_selected: Color32,
167 /// `heat-0` to `heat-4`: the measure ramp, quietest first, from the
168 /// raised ground to the cursor row's mix. Read through
169 /// [`heat`](Self::heat).
170 pub heats: [Color32; HEAT_BANDS as usize],
171}
172
173impl Palette {
174 /// Every surface `page` and every ink `ink`, with no cast shadow.
175 ///
176 /// A starting point for the setters: an app that resolves its own colours
177 /// starts here and sets each one. A colour added to this type later
178 /// starts at one of these two.
179 #[must_use]
180 pub const fn two_tone(page: Color32, ink: Color32) -> Self {
181 Self {
182 page,
183 raised: page,
184 overlay: page,
185 well: page,
186 sunken: page,
187 bevel_light: page,
188 bevel_dark: ink,
189 elevation: Color32::TRANSPARENT,
190 content: ink,
191 content_secondary: ink,
192 content_muted: ink,
193 content_disabled: ink,
194 action: ink,
195 content_on_action: page,
196 danger: ink,
197 success: ink,
198 warning: ink,
199 info: ink,
200 border: ink,
201 info_surface: page,
202 success_surface: page,
203 warning_surface: page,
204 danger_surface: page,
205 row_hover: page,
206 row_rule: ink,
207 row_selected: page,
208 heats: [page; HEAT_BANDS as usize],
209 }
210 }
211
212 /// Set [`page`](Self::page).
213 #[must_use]
214 pub const fn page(mut self, colour: Color32) -> Self {
215 self.page = colour;
216 self
217 }
218
219 /// Set [`raised`](Self::raised).
220 #[must_use]
221 pub const fn raised(mut self, colour: Color32) -> Self {
222 self.raised = colour;
223 self
224 }
225
226 /// Set [`overlay`](Self::overlay).
227 #[must_use]
228 pub const fn overlay(mut self, colour: Color32) -> Self {
229 self.overlay = colour;
230 self
231 }
232
233 /// Set [`well`](Self::well).
234 #[must_use]
235 pub const fn well(mut self, colour: Color32) -> Self {
236 self.well = colour;
237 self
238 }
239
240 /// Set [`sunken`](Self::sunken).
241 #[must_use]
242 pub const fn sunken(mut self, colour: Color32) -> Self {
243 self.sunken = colour;
244 self
245 }
246
247 /// Set [`bevel_light`](Self::bevel_light).
248 #[must_use]
249 pub const fn bevel_light(mut self, colour: Color32) -> Self {
250 self.bevel_light = colour;
251 self
252 }
253
254 /// Set [`bevel_dark`](Self::bevel_dark).
255 #[must_use]
256 pub const fn bevel_dark(mut self, colour: Color32) -> Self {
257 self.bevel_dark = colour;
258 self
259 }
260
261 /// Set [`elevation`](Self::elevation).
262 #[must_use]
263 pub const fn elevation(mut self, colour: Color32) -> Self {
264 self.elevation = colour;
265 self
266 }
267
268 /// Set [`content`](Self::content).
269 #[must_use]
270 pub const fn content(mut self, colour: Color32) -> Self {
271 self.content = colour;
272 self
273 }
274
275 /// Set [`content_secondary`](Self::content_secondary).
276 #[must_use]
277 pub const fn content_secondary(mut self, colour: Color32) -> Self {
278 self.content_secondary = colour;
279 self
280 }
281
282 /// Set [`content_muted`](Self::content_muted).
283 #[must_use]
284 pub const fn content_muted(mut self, colour: Color32) -> Self {
285 self.content_muted = colour;
286 self
287 }
288
289 /// Set [`content_disabled`](Self::content_disabled).
290 #[must_use]
291 pub const fn content_disabled(mut self, colour: Color32) -> Self {
292 self.content_disabled = colour;
293 self
294 }
295
296 /// Set [`action`](Self::action).
297 #[must_use]
298 pub const fn action(mut self, colour: Color32) -> Self {
299 self.action = colour;
300 self
301 }
302
303 /// Set [`content_on_action`](Self::content_on_action).
304 #[must_use]
305 pub const fn content_on_action(mut self, colour: Color32) -> Self {
306 self.content_on_action = colour;
307 self
308 }
309
310 /// Set [`danger`](Self::danger).
311 #[must_use]
312 pub const fn danger(mut self, colour: Color32) -> Self {
313 self.danger = colour;
314 self
315 }
316
317 /// Set [`success`](Self::success).
318 #[must_use]
319 pub const fn success(mut self, colour: Color32) -> Self {
320 self.success = colour;
321 self
322 }
323
324 /// Set [`warning`](Self::warning).
325 #[must_use]
326 pub const fn warning(mut self, colour: Color32) -> Self {
327 self.warning = colour;
328 self
329 }
330
331 /// Set [`info`](Self::info).
332 #[must_use]
333 pub const fn info(mut self, colour: Color32) -> Self {
334 self.info = colour;
335 self
336 }
337
338 /// Set [`border`](Self::border).
339 #[must_use]
340 pub const fn border(mut self, colour: Color32) -> Self {
341 self.border = colour;
342 self
343 }
344
345 /// Set [`info_surface`](Self::info_surface).
346 #[must_use]
347 pub const fn info_surface(mut self, colour: Color32) -> Self {
348 self.info_surface = colour;
349 self
350 }
351
352 /// Set [`success_surface`](Self::success_surface).
353 #[must_use]
354 pub const fn success_surface(mut self, colour: Color32) -> Self {
355 self.success_surface = colour;
356 self
357 }
358
359 /// Set [`warning_surface`](Self::warning_surface).
360 #[must_use]
361 pub const fn warning_surface(mut self, colour: Color32) -> Self {
362 self.warning_surface = colour;
363 self
364 }
365
366 /// Set [`danger_surface`](Self::danger_surface).
367 #[must_use]
368 pub const fn danger_surface(mut self, colour: Color32) -> Self {
369 self.danger_surface = colour;
370 self
371 }
372
373 /// Set [`row_hover`](Self::row_hover).
374 #[must_use]
375 pub const fn row_hover(mut self, colour: Color32) -> Self {
376 self.row_hover = colour;
377 self
378 }
379
380 /// Set [`row_rule`](Self::row_rule).
381 #[must_use]
382 pub const fn row_rule(mut self, colour: Color32) -> Self {
383 self.row_rule = colour;
384 self
385 }
386
387 /// Set [`row_selected`](Self::row_selected).
388 #[must_use]
389 pub const fn row_selected(mut self, colour: Color32) -> Self {
390 self.row_selected = colour;
391 self
392 }
393
394 /// Set [`heats`](Self::heats).
395 #[must_use]
396 pub const fn heats(mut self, ramp: [Color32; HEAT_BANDS as usize]) -> Self {
397 self.heats = ramp;
398 self
399 }
400
401 /// Every colour, read from a resolved makeover theme.
402 ///
403 /// # Errors
404 ///
405 /// [`MissingToken`] naming the first token the theme does not resolve.
406 /// makeover derives every one of these for every shipped theme, so this
407 /// fails only on a theme file missing a base intent.
408 #[cfg(feature = "theme")]
409 pub fn from_theme(tokens: &makeover::SemanticTokens) -> Result<Self, MissingToken> {
410 use makeover::Token;
411 let colour = |token: Token| {
412 tokens
413 .rgba(token)
414 .map(|(r, g, b, a)| Color32::from_rgba_unmultiplied(r, g, b, a))
415 .ok_or(MissingToken(token))
416 };
417 Ok(Self {
418 page: colour(Token::SurfacePage)?,
419 raised: colour(Token::SurfaceRaised)?,
420 overlay: colour(Token::SurfaceOverlay)?,
421 well: colour(Token::SurfaceWell)?,
422 sunken: colour(Token::SurfaceSunken)?,
423 bevel_light: colour(Token::BevelLight)?,
424 bevel_dark: colour(Token::BevelDark)?,
425 elevation: colour(Token::Elevation)?,
426 content: colour(Token::Content)?,
427 content_secondary: colour(Token::ContentSecondary)?,
428 content_muted: colour(Token::ContentMuted)?,
429 content_disabled: colour(Token::ContentDisabled)?,
430 action: colour(Token::Action)?,
431 content_on_action: colour(Token::ContentOnAction)?,
432 danger: colour(Token::Danger)?,
433 success: colour(Token::Success)?,
434 warning: colour(Token::Warning)?,
435 info: colour(Token::Info)?,
436 border: colour(Token::Border)?,
437 info_surface: colour(Token::InfoSurface)?,
438 success_surface: colour(Token::SuccessSurface)?,
439 warning_surface: colour(Token::WarningSurface)?,
440 danger_surface: colour(Token::DangerSurface)?,
441 row_hover: colour(Token::RowHover)?,
442 row_rule: colour(Token::RowRule)?,
443 row_selected: colour(Token::RowSelected)?,
444 heats: [
445 colour(Token::Heat0)?,
446 colour(Token::Heat1)?,
447 colour(Token::Heat2)?,
448 colour(Token::Heat3)?,
449 colour(Token::Heat4)?,
450 ],
451 })
452 }
453}
454
455/// A token `Palette::from_theme` needed and the theme did not resolve.
456#[cfg(feature = "theme")]
457#[derive(Debug, Clone, Copy, PartialEq, Eq)]
458pub struct MissingToken(pub makeover::Token);
459
460#[cfg(feature = "theme")]
461impl std::fmt::Display for MissingToken {
462 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
463 write!(f, "the theme resolves no `{}`", self.0.as_str())
464 }
465}
466
467#[cfg(feature = "theme")]
468impl std::error::Error for MissingToken {}
469
470impl Palette {
471 /// Resolve a surface intent, or `None` for one this renderer does not know.
472 ///
473 /// A plain lookup with no substitution. Every [`Fill`] this renderer
474 /// knows, `Fill::Sunken` included, is answered with `Some`.
475 #[must_use]
476 pub const fn fill(&self, fill: Fill) -> Option<Color32> {
477 match fill {
478 Fill::Page => Some(self.page),
479 Fill::Raised => Some(self.raised),
480 Fill::Overlay => Some(self.overlay),
481 Fill::Well => Some(self.well),
482 Fill::Sunken => Some(self.sunken),
483 _ => None,
484 }
485 }
486
487 /// The colour a [`Tone`] reads as.
488 ///
489 /// [`Tone::Neutral`] and a tone this renderer has not learnt (`Tone` is
490 /// `#[non_exhaustive]`) read as [`content`](Self::content).
491 #[must_use]
492 pub const fn tone(&self, tone: Tone) -> Color32 {
493 match tone {
494 Tone::Neutral => self.content,
495 Tone::Info => self.info,
496 Tone::Success => self.success,
497 Tone::Warning => self.warning,
498 Tone::Danger => self.danger,
499 // A tone this renderer has not learnt yet reads as an ordinary
500 // fact rather than as a status it might misstate.
501 _ => self.content,
502 }
503 }
504
505 /// The fill a measure band sits on, or `None` at band 0, which is the
506 /// ground and draws nothing. A band past the last reads as the last.
507 #[must_use]
508 pub const fn heat(&self, heat: Heat) -> Option<Color32> {
509 let band = heat.0 as usize;
510 if band == 0 {
511 None
512 } else if band < self.heats.len() {
513 Some(self.heats[band])
514 } else {
515 Some(self.heats[self.heats.len() - 1])
516 }
517 }
518
519 /// What a badge of this tone is filled with: its tone surface, or the
520 /// raised surface for [`Tone::Neutral`], as `makeover-webview` fills one.
521 #[must_use]
522 pub const fn tone_surface(&self, tone: Tone) -> Color32 {
523 match tone {
524 Tone::Neutral => self.raised,
525 Tone::Info => self.info_surface,
526 Tone::Success => self.success_surface,
527 Tone::Warning => self.warning_surface,
528 Tone::Danger => self.danger_surface,
529 _ => self.raised,
530 }
531 }
532
533 /// What a badge of this tone is edged with: its tone, or
534 /// [`border`](Self::border) for [`Tone::Neutral`], whose tone is the ink.
535 #[must_use]
536 pub const fn tone_edge(&self, tone: Tone) -> Color32 {
537 match tone {
538 Tone::Neutral => self.border,
539 other => self.tone(other),
540 }
541 }
542
543 /// The cast shadow for a surface that overlays the page.
544 ///
545 /// An [`egui::Shadow`] in [`elevation`](Self::elevation), for
546 /// [`egui::Frame::shadow`]: `makeover-webview`'s overlay cast, a hard
547 /// offset of `[3, 3]` down and right with no blur and no spread.
548 /// [`host::visuals`] gives egui's own windows and popups the same shadow.
549 ///
550 /// ```no_run
551 /// # let palette: makeover_immediate::Palette = unimplemented!();
552 /// # let ui: &mut egui::Ui = unimplemented!();
553 /// egui::Frame::popup(ui.style())
554 /// .shadow(palette.cast())
555 /// .show(ui, |ui| { ui.label("over the page"); });
556 /// ```
557 #[must_use]
558 pub const fn cast(&self) -> egui::Shadow {
559 egui::Shadow {
560 offset: [3, 3],
561 blur: 0,
562 spread: 0,
563 color: self.elevation,
564 }
565 }
566
567 /// Resolve a bevel edge intent.
568 #[must_use]
569 pub const fn edge(&self, edge: Edge) -> Color32 {
570 match edge {
571 Edge::Light => self.bevel_light,
572 Edge::Dark => self.bevel_dark,
573 // An edge this renderer has not learnt is drawn as the border, the
574 // one line every surface already has.
575 _ => self.border,
576 }
577 }
578}
579
580/// The geometry a framed region is drawn with.
581///
582/// Every field is a value the caller resolves: radius and border width from
583/// `makeover-geometry`, margins from its relational gaps.
584#[derive(Debug, Clone, Copy, PartialEq)]
585pub struct FrameStyle {
586 /// Corner radius. Square under the Platinum default.
587 pub radius: CornerRadius,
588 /// Inner margin between the frame and its contents.
589 pub margin: Margin,
590 /// Bevel stroke width, in points.
591 pub stroke: f32,
592}
593
594impl Default for FrameStyle {
595 /// A one-point square frame with no inner margin.
596 fn default() -> Self {
597 Self {
598 radius: CornerRadius::ZERO,
599 margin: Margin::ZERO,
600 stroke: f32::from(makeover_geometry::Stroke::Hairline.px()),
601 }
602 }
603}
604
605/// Paint a two-tone edge just inside `rect`.
606///
607/// Adds two polylines and nothing else, so it composes over what is already
608/// painted: over an [`egui::TextEdit`] after `ui.add`, for one.
609///
610/// The polylines are inset by half a stroke. The first, in the tone
611/// [`Bevel::edges`] gives the top and left, runs bottom-left, top-left,
612/// top-right; the second, in the other tone, runs top-right, bottom-right,
613/// bottom-left, and stops at bottom-right for a bevel that does not draw its
614/// bottom. Each is one three-point line, so egui mitres its corner. The second
615/// is drawn over the first, so the two corners where they meet take its tone.
616pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
617 let (top_left, bottom_right) = bevel.edges();
618
619 // Inset by half a stroke so the line lands inside `rect` rather than
620 // straddling its edge, which on a fractional-scale display is the
621 // difference between one crisp pixel and two dim ones.
622 let r = rect.shrink(stroke / 2.0);
623
624 painter.add(Shape::line(
625 vec![r.left_bottom(), r.left_top(), r.right_top()],
626 Stroke::new(stroke, palette.edge(top_left)),
627 ));
628 // Three points close the box, two leave the bottom open: the shaded run
629 // comes down the right side and stops. That is the folder tab, and it is
630 // the same edge the browser draws by dropping the shadow's vertical
631 // offset. The lit polyline is untouched either way, so the join is the
632 // only thing that changes.
633 let shaded = if bevel.draws_bottom() {
634 vec![r.right_top(), r.right_bottom(), r.left_bottom()]
635 } else {
636 vec![r.right_top(), r.right_bottom()]
637 };
638 painter.add(Shape::line(
639 shaded,
640 Stroke::new(stroke, palette.edge(bottom_right)),
641 ));
642}
643
644/// Draw a region at a given [`Depth`]: its fill and its edge, together.
645///
646/// [`Depth::Flat`] gets neither and shows whatever it sits on. A depth whose
647/// fill this palette does not resolve goes unfilled and keeps its bevel. An
648/// overlay fill also takes [`Palette::cast`].
649pub fn frame<R>(
650 ui: &mut Ui,
651 depth: Depth,
652 palette: &Palette,
653 style: FrameStyle,
654 add_contents: impl FnOnce(&mut Ui) -> R,
655) -> R {
656 let mut f = egui::Frame::new()
657 .corner_radius(style.radius)
658 .inner_margin(style.margin);
659 // Two ways there is no fill to paint, and they collapse to the same
660 // outcome: the depth names none (Depth::Flat), or it names one this
661 // renderer cannot resolve. Either way the frame goes unfilled and the
662 // bevel below carries the depth on its own, which is the rule this
663 // module already documents for Flat.
664 if let Some(fill) = depth.fill().and_then(|f| palette.fill(f)) {
665 f = f.fill(fill);
666 }
667 // A surface that overlays the page is cast onto it, with
668 // [`Palette::cast`]. Keyed off the fill rather than the variant, so it stays right for whatever else the description calls an
669 // overlay later.
670 if depth.fill() == Some(Fill::Overlay) {
671 f = f.shadow(palette.cast());
672 }
673 let framed = f.show(ui, add_contents);
674 if let Some(bevel) = depth.bevel() {
675 paint_bevel(
676 ui.painter(),
677 framed.response.rect,
678 bevel,
679 palette,
680 style.stroke,
681 );
682 }
683 framed.inner
684}
685
686/// The geometry a field group is drawn with.
687///
688/// The fields themselves are drawn by `quasi-immediate`. Every number here is
689/// a `makeover-geometry` value the caller resolves, as in [`FrameStyle`],
690/// which it embeds.
691#[derive(Debug, Clone, Copy, PartialEq)]
692pub struct FieldStyle {
693 /// The well a text control sits in.
694 pub frame: FrameStyle,
695 /// Between a field's own parts: its label, its control, its hint and its
696 /// error.
697 pub gap: f32,
698 /// Between one field and the next.
699 pub group_gap: f32,
700 /// What marks a required field, appended to its label. `"*"` by default.
701 pub required_marker: &'static str,
702}
703
704impl Default for FieldStyle {
705 /// The default frame, no gaps, and an asterisk.
706 fn default() -> Self {
707 Self {
708 frame: FrameStyle::default(),
709 gap: 0.0,
710 group_gap: 0.0,
711 required_marker: "*",
712 }
713 }
714}
715
716/// What the field currently holds, borrowed from wherever the app keeps it.
717///
718/// Handed to `quasi-immediate`'s field, which writes through it as the user
719/// edits.
720///
721/// The editable counterpart of [`makeover_layout::Value`], which the other
722/// renderers read back after the fact. The description carries neither.
723///
724/// `#[non_exhaustive]`: a host builds these and does not match on them.
725#[derive(Debug, Default)]
726#[non_exhaustive]
727pub enum Editing<'a> {
728 /// Nothing to edit. The control is drawn and does not answer.
729 #[default]
730 Absent,
731 /// The buffer behind anything that takes typed text, a select included:
732 /// what a select holds is the `value` of one of its options.
733 Text(&'a mut String),
734 /// A checkbox, on or off.
735 On(&'a mut bool),
736 /// The values of a [`FieldKind::Checklist`](makeover_layout::FieldKind::Checklist)'s ticked options.
737 ///
738 /// Ticking pushes the option's value and unticking removes it, so the
739 /// order is the order things were ticked in.
740 Ticked(&'a mut Vec<String>),
741 /// The two buffers behind a [`FieldKind::Interval`](makeover_layout::FieldKind::Interval), lower first.
742 ///
743 /// Either end may be empty while the other stands: an open end
744 /// ("over 120 BPM").
745 Between {
746 /// The lower end's buffer.
747 lower: &'a mut String,
748 /// The upper end's buffer.
749 upper: &'a mut String,
750 },
751}
752
753#[cfg(test)]
754mod tests;