Skip to main content

max / makeover-immediate

41.0 KB · 1003 lines History Blame Raw
1 //! The immediate-mode renderer for [`makeover_layout`].
2 //!
3 //! <!-- wiki: makeover-immediate -->
4 //!
5 //! Named for the mode, not the library, the way `makeover-tui` is named for
6 //! the target and not for ratatui. Immediate mode is the constraint that
7 //! actually separates this renderer from the other two, and egui is the
8 //! backend it is written against.
9 //!
10 //! It is the harshest renderer the description has to survive: no
11 //! `box-shadow`, no `inset`, no cascade, no retained tree to mutate, and
12 //! `Visuals.widgets.*.bg_stroke` is a single stroke with no per-side control.
13 //! A two-tone lit edge is not something egui can be configured into producing,
14 //! so it gets painted by hand here, once, instead of in every consuming app.
15 //!
16 //! # What this crate does and does not own
17 //!
18 //! It owns the *expression*: two mitred polylines for a bevel and a `Frame`
19 //! for a filled region. It owns no colours and no sizes, and no longer owns a
20 //! substitution: it briefly supplied the page for a well, which was a stand-in
21 //! for `surface-well` before makeover derived it, and every consumer reads the
22 //! real token now. [`Palette`] is supplied by the caller,
23 //! already resolved, and every radius, margin and stroke width arrives in
24 //! [`FrameStyle`].
25 //!
26 //! That split is why the crate has no dependency on `makeover` itself: the app
27 //! already resolves a theme, and coupling a renderer to a colour crate's
28 //! version would buy nothing.
29 //!
30 //! # The cascade is the real difference
31 //!
32 //! A stylesheet can say "a pressed button inverts its bevel" once and let the
33 //! cascade carry it. An immediate-mode renderer has nowhere to put that, so
34 //! every call site decides. [`makeover_layout::Depth::pressed`] is what keeps
35 //! the decision from being re-derived per widget.
36 //!
37 //! # 0.11.0: the overlay becomes reachable
38 //!
39 //! 0.10.0 answered what overlaying means in immediate mode with
40 //! [`Palette::cast`], and nothing could ask: the description had no
41 //! `Depth::Overlay` until `makeover-layout` 0.14.0, so the answer sat beside a
42 //! question that could not be posed. [`frame`] now hands the cast shadow to the
43 //! `egui::Frame` for any depth whose fill is [`Fill::Overlay`], keyed off the
44 //! fill rather than the variant.
45 //!
46 //! The same release brings `makeover_layout::CellPart`, which 0.11.0 carried
47 //! and did not draw. [`table`] draws it, below.
48 //!
49 //! # 0.12.0: the table
50 //!
51 //! [`table`] is the vocabulary 0.11.0 took without using. The consumer is
52 //! audiofiles, whose file list is the only table in the tree exercising all four
53 //! of what the description says about one at once: sortable headings with
54 //! carets, fixed and remainder tracks, and buttons inside cells.
55 //!
56 //! Two things it forces, both named where they land:
57 //!
58 //! - **`egui_extras`**, this crate's first dependency past egui. egui has no
59 //! table, and `Grid` gives no per-column sizing, no sticky header and no
60 //! scroll sync, which is why audiofiles reached for `egui_extras` rather than
61 //! building on `Grid`. A third answer here would reimplement that crate worse.
62 //! - **[`Palette::action`]**, on the footing [`Palette::content`] arrived on: a
63 //! link in a cell is the first thing here needing the action intent.
64 //!
65 //! Narrowing works differently from the terminal's and the module header says
66 //! why: a content column cannot be measured before the app's closure has drawn
67 //! it, so `egui_extras` sizes it and the declared floor budgets it.
68 //!
69 //! # 0.13.0: what the adoption found missing
70 //!
71 //! 0.12.0 shipped [`table`] before audiofiles had taken it, and taking it found
72 //! three things the file list already did that the function could not say. All
73 //! three are host idiom rather than description, which is why they land here and
74 //! not in `makeover-layout`, and all three are answered on a handle the app
75 //! never sees: the `egui_extras` row and builder this crate owns. That is
76 //! [`table::cell`]'s reasoning again: what the app cannot reach, the renderer
77 //! owes it.
78 //!
79 //! - **A selected row.** [`table::Body::selected`], a predicate asked per row,
80 //! because `set_selected` is a method on the row. Without it a file list has
81 //! no way to show what is selected, which is most of what a file list does.
82 //! - **Scrolling a row into view.** [`table::Body::scroll_to`], because
83 //! `scroll_to_row` is a method on the builder. A keyboard cursor that moves
84 //! off-screen and stays there is the bug this prevents.
85 //! - **Dragging a divider.** [`table::TableStyle::resizable`], which passes the
86 //! test `sticky_header` failed in 0.12.0: egui_extras offers two settings here
87 //! and a renderer can honestly make either choice.
88 //!
89 //! A fourth was found and is not a knob. Cells are centred on the row's centre
90 //! line, always, because there is no second honest answer and egui's own default
91 //! (top-aligned) is the one thing it cannot be.
92 //!
93 //! [`table::Body`] is also what splits a table's per-frame facts from its
94 //! description and from its style. A row count, a selection and a scroll request
95 //! are none of them style, and none of them survive the frame.
96 //!
97 //! # Forms
98 //!
99 //! 0.5.0 adds the field vocabulary on top of the depth vocabulary:
100 //! [`makeover_layout::Field`] rendered to egui widgets, in [`field`], and a set
101 //! of them laid down a column in [`group`]. Before it, a description saying
102 //! "text field, labelled, required, with this hint" had no way to become a
103 //! widget here, and audiofiles' forms stayed hand-rolled.
104 //!
105 //! `makeover-webview` got there first and its form emitter is the precedent
106 //! followed rather than re-derived, including the parts that are bug fixes: a
107 //! select handed a value none of its options carries keeps that value visible
108 //! instead of silently reading as the first option, which is a save-the-wrong-
109 //! thing bug goingson hit for real.
110 //!
111 //! What differs is forced by the mode and not chosen:
112 //!
113 //! - **The value arrives as a `&mut`.** [`Filling`] borrows the app's own field
114 //! and the widget writes through it. There is no DOM to read back out of,
115 //! which is also why the description deliberately does not carry the value.
116 //! - **A text control is drawn as a well and a select is not.** The description
117 //! holds that a well is for anything the user looks *into*, and a text field
118 //! is its own example; a select and a checkbox are pressed rather than looked
119 //! into, so they keep egui's own control painting.
120 //! - **Focus is not describable, and egui owns all of it here.** **Reach**,
121 //! **focus** and the **focus ring** are this renderer's three answers and
122 //! egui already has all three: its own id stack decides what is reachable,
123 //! its own state decides what holds the keyboard, and it paints exactly one
124 //! ring. A description states none of them — `makeover_layout` removed the
125 //! member that used to try in 0.19.0 — and drawing a second ring on top of
126 //! egui's would break the one-ring rule it would have come from. The terms
127 //! are defined once in `makeover_layout`'s crate header, "Reach, focus and
128 //! the focus ring". [`makeover_layout::State::Disabled`] *is* drawn, because
129 //! egui has no opinion about it until told.
130
131 #![forbid(unsafe_code)]
132
133 use egui::{
134 Color32, ComboBox, CornerRadius, Margin, Painter, Rect, Response, RichText, Shape, Stroke,
135 TextEdit, Ui,
136 };
137 use makeover_layout::{Bevel, Choice, Depth, Edge, Field, FieldKind, Fill, State};
138
139 /// Columns, narrowing, cell parts and the sort caret, over `egui_extras`.
140 pub mod table;
141
142 /// The resolved colours this renderer needs, as flat values.
143 ///
144 /// Built by the app from whatever it already uses to resolve a theme, then
145 /// held and reused. Deliberately not a trait and not string-keyed: a bevel is
146 /// painted per widget per frame, and a map lookup per edge is a cost with
147 /// nothing to show for it.
148 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
149 pub struct Palette {
150 /// `surface-page`.
151 pub page: Color32,
152 /// `surface-raised`.
153 pub raised: Color32,
154 /// `surface-overlay`.
155 pub overlay: Color32,
156 /// `surface-well`.
157 ///
158 /// Required, not optional. makeover derives it for every theme from 2.3.0,
159 /// so a resolved palette without a well is not a thing that exists here.
160 /// It was an `Option` while that was untrue, and this renderer substituted
161 /// the page; `makeover-tui` keeps its own `Option` for a different reason,
162 /// since a terminal can have the colour and still be unable to show it.
163 pub well: Color32,
164 /// `surface-sunken`.
165 ///
166 /// A surface set back from the one it sits on, by colour and nothing else.
167 /// Not a well: a well is a hole with an edge, and this has no edge. An
168 /// immediate-mode renderer paints an arbitrary rect, so unlike
169 /// `makeover-tui` it has no excuse for declining this one.
170 ///
171 /// Required rather than optional, on the same footing as `well`: all 31
172 /// themes makeover embeds author it.
173 pub sunken: Color32,
174 /// `bevel-light`.
175 pub bevel_light: Color32,
176 /// `bevel-dark`.
177 pub bevel_dark: Color32,
178 /// `elevation`.
179 ///
180 /// What a surface that floats OVER the page is cast onto it with. The one
181 /// intent here that is about a surface's relationship to the page rather
182 /// than about the surface, which is why it is a translucent near-black on
183 /// every theme rather than something read off the palette's own ramp.
184 ///
185 /// **Only for a surface that overlays.** A menu, a tooltip, a modal. A
186 /// surface *in* the layout takes a bevel, and reaching for this on a panel
187 /// or a card is how a pre-Platinum look survives a conversion under a new
188 /// name.
189 ///
190 /// egui has a real answer for this where a terminal does not: see
191 /// [`Palette::cast`], which is the shadow to hand an
192 /// [`egui::Frame`](egui::Frame).
193 pub elevation: Color32,
194 /// `content`.
195 ///
196 /// Ordinary text. Added 0.5.0 with the field renderer, which is the first
197 /// thing here that draws any: until then this crate painted surfaces and
198 /// edges and let the caller's own egui visuals answer for text.
199 pub content: Color32,
200 /// `content-muted`.
201 ///
202 /// A field's hint, and what
203 /// [`makeover_layout::State::Disabled`](makeover_layout::State::Disabled)
204 /// resolves to. Both readings come from the description rather than from
205 /// here: `State::Disabled` names this intent by token.
206 pub content_muted: Color32,
207 /// `action-primary`.
208 ///
209 /// What a control is drawn in. Added 0.12.0 with the table renderer, for the
210 /// reason `content` was added 0.5.0 with the field renderer: a link in a
211 /// cell is the first thing here that needs the action intent, and a palette
212 /// should carry what is used.
213 ///
214 /// This is the intent [`CellPart`](makeover_layout::CellPart) exists to
215 /// separate. A cell holding a control took the cell's text colour until the
216 /// description could say otherwise, which is the drift `makeover-layout`
217 /// 0.14.0 named and `makeover-webview` 0.25.0 fixed on its own side.
218 pub action: Color32,
219 /// `danger`.
220 ///
221 /// A field's error message. The one [`makeover_layout::Tone`] this renderer
222 /// needs so far, and it is here rather than as a whole resolved tone set
223 /// because notices are not drawn here yet and a palette should carry what
224 /// is used.
225 pub danger: Color32,
226 }
227
228 impl Palette {
229 /// Resolve a surface intent, or `None` for one this renderer does not know.
230 ///
231 /// A plain lookup. There is still no substitution: the old one existed only
232 /// while `surface-well` was underived, and every consumer reads the real
233 /// token now.
234 ///
235 /// `Option` since 0.3.0, because [`Fill`] became `#[non_exhaustive]` in
236 /// `makeover-layout` 0.4.0 and a total function over an open enum can only
237 /// stay total by inventing a colour for a member it has never heard of.
238 /// That is the substitution this crate spent 0.2.0 removing, so the return
239 /// type moved instead. Every member the description has today is answered
240 /// with `Some`.
241 #[must_use]
242 pub const fn fill(&self, fill: Fill) -> Option<Color32> {
243 match fill {
244 Fill::Page => Some(self.page),
245 Fill::Raised => Some(self.raised),
246 Fill::Overlay => Some(self.overlay),
247 Fill::Well => Some(self.well),
248 Fill::Sunken => Some(self.sunken),
249 _ => None,
250 }
251 }
252
253 /// The cast shadow for a surface that overlays the page.
254 ///
255 /// What "overlaying" means in immediate mode, answered rather than skipped.
256 /// egui already paints shadows for its menus and windows through
257 /// [`egui::Frame::shadow`], so the honest port is to hand that machinery the
258 /// theme's tone instead of egui's own default, not to invent a painter here
259 /// the way [`paint_bevel`] had to.
260 ///
261 /// The geometry matches what `makeover-webview` composes, in points rather
262 /// than pixels: a small downward offset and a wide soft blur. A Platinum-era
263 /// menu sits just off the page rather than hovering above it.
264 ///
265 /// ```no_run
266 /// # let palette: makeover_immediate::Palette = unimplemented!();
267 /// # let ui: &mut egui::Ui = unimplemented!();
268 /// egui::Frame::popup(ui.style())
269 /// .shadow(palette.cast())
270 /// .show(ui, |ui| { ui.label("over the page"); });
271 /// ```
272 #[must_use]
273 pub const fn cast(&self) -> egui::Shadow {
274 egui::Shadow {
275 offset: [0, 2],
276 blur: 24,
277 spread: 0,
278 color: self.elevation,
279 }
280 }
281
282 /// Resolve a bevel edge intent.
283 #[must_use]
284 pub const fn edge(&self, edge: Edge) -> Color32 {
285 match edge {
286 Edge::Light => self.bevel_light,
287 Edge::Dark => self.bevel_dark,
288 }
289 }
290 }
291
292 /// The geometry a framed region is drawn with.
293 ///
294 /// Every field is a value, which is why they all arrive from the caller:
295 /// radius and border width belong to `makeover-geometry`, and margins come
296 /// from its relational gaps.
297 #[derive(Debug, Clone, Copy, PartialEq)]
298 pub struct FrameStyle {
299 /// Corner radius. Square under the Platinum default.
300 pub radius: CornerRadius,
301 /// Inner margin between the frame and its contents.
302 pub margin: Margin,
303 /// Bevel stroke width, in points.
304 pub stroke: f32,
305 }
306
307 impl Default for FrameStyle {
308 /// A one-point square frame with no inner margin.
309 fn default() -> Self {
310 Self {
311 radius: CornerRadius::ZERO,
312 margin: Margin::ZERO,
313 stroke: 1.0,
314 }
315 }
316 }
317
318 /// Paint a two-tone edge just inside `rect`.
319 ///
320 /// Fill first, bevel after: this adds two polylines and nothing else, so it
321 /// composes over whatever is already there. That is what lets it go over an
322 /// [`egui::TextEdit`] after `ui.add`, where the widget's own fill has landed.
323 ///
324 /// Two three-point polylines meeting at opposite corners, rather than four
325 /// segments, so egui mitres the corner joins instead of leaving a notch.
326 ///
327 /// The dark polyline is drawn second, so the two corners where the runs meet
328 /// take its tone. That is the right answer here rather than a concession.
329 /// [`makeover_layout::Bevel`] holds those corners to belong to both edges, and
330 /// a renderer with room to divide one should; at the default one-point stroke
331 /// the corner is a one-point square, so the division is sub-pixel and
332 /// antialiasing resolves it to the same blend the mitre already gives. Splitting
333 /// it would add a seam and no information. `makeover-tui` does split, because a
334 /// terminal cell is large enough that not splitting costs a visible cell of edge
335 /// weight — the same rule, at a resolution where it has something to say.
336 pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
337 let (top_left, bottom_right) = bevel.edges();
338
339 // Inset by half a stroke so the line lands inside `rect` rather than
340 // straddling its edge, which on a fractional-scale display is the
341 // difference between one crisp pixel and two dim ones.
342 let r = rect.shrink(stroke / 2.0);
343
344 painter.add(Shape::line(
345 vec![r.left_bottom(), r.left_top(), r.right_top()],
346 Stroke::new(stroke, palette.edge(top_left)),
347 ));
348 painter.add(Shape::line(
349 vec![r.right_top(), r.right_bottom(), r.left_bottom()],
350 Stroke::new(stroke, palette.edge(bottom_right)),
351 ));
352 }
353
354 /// Draw a region at a given [`Depth`]: its fill and its edge, together.
355 ///
356 /// [`Depth::Flat`] gets neither, and inherits whatever it sits on. That is the
357 /// difference between level-with and painted-the-same-colour, and it is the
358 /// reason `Depth::fill` returns an [`Option`] rather than defaulting to the
359 /// page.
360 pub fn frame<R>(
361 ui: &mut Ui,
362 depth: Depth,
363 palette: &Palette,
364 style: FrameStyle,
365 add_contents: impl FnOnce(&mut Ui) -> R,
366 ) -> R {
367 let mut f = egui::Frame::new()
368 .corner_radius(style.radius)
369 .inner_margin(style.margin);
370 // Two ways there is no fill to paint, and they collapse to the same
371 // outcome: the depth names none (Depth::Flat), or it names one this
372 // renderer cannot resolve. Either way the frame goes unfilled and the
373 // bevel below carries the depth on its own, which is the rule this
374 // module already documents for Flat.
375 if let Some(fill) = depth.fill().and_then(|f| palette.fill(f)) {
376 f = f.fill(fill);
377 }
378 // A surface that overlays the page is cast onto it. [`Palette::cast`] has
379 // answered what that means here since 0.10.0 and nothing could reach it: a
380 // description had no way to say Overlay until makeover-layout 0.14.0, so
381 // the answer sat beside the question. Keyed off the fill rather than the
382 // variant, so it stays right for whatever else the description calls an
383 // overlay later.
384 if depth.fill() == Some(Fill::Overlay) {
385 f = f.shadow(palette.cast());
386 }
387 let framed = f.show(ui, add_contents);
388 if let Some(bevel) = depth.bevel() {
389 paint_bevel(
390 ui.painter(),
391 framed.response.rect,
392 bevel,
393 palette,
394 style.stroke,
395 );
396 }
397 framed.inner
398 }
399
400 /// The geometry a field group is drawn with.
401 ///
402 /// Values again, for the reason [`FrameStyle`] is: every number here belongs to
403 /// `makeover-geometry` and arrives already resolved.
404 #[derive(Debug, Clone, Copy, PartialEq)]
405 pub struct FieldStyle {
406 /// The well a text control sits in.
407 pub frame: FrameStyle,
408 /// Between a field's own parts: its label, its control, its hint and its
409 /// error.
410 pub gap: f32,
411 /// Between one field and the next.
412 pub group_gap: f32,
413 /// What marks a required field, appended to its label.
414 ///
415 /// A knob rather than a constant, because it is the one piece of *copy* in
416 /// this crate and copy is not a renderer's call. A webview does not need it
417 /// at all — it emits the `required` attribute and the browser answers — so
418 /// this renderer is the first place where a compulsory field either shows
419 /// that it is or silently does not.
420 pub required_marker: &'static str,
421 }
422
423 impl Default for FieldStyle {
424 /// The default frame, no gaps, and an asterisk.
425 fn default() -> Self {
426 Self {
427 frame: FrameStyle::default(),
428 gap: 0.0,
429 group_gap: 0.0,
430 required_marker: "*",
431 }
432 }
433 }
434
435 /// What the field currently holds, borrowed from wherever the app keeps it.
436 ///
437 /// The immediate-mode counterpart of `makeover_webview::form::Value`, and the
438 /// place the two renderers are forced apart: there the value is read back out
439 /// of the DOM after the fact, and here the widget writes through this borrow as
440 /// it is edited. Same reason the description carries neither.
441 ///
442 /// An enum rather than a bag of options, on the reasoning
443 /// `makeover_webview::form::Value` records: a checkbox holding a string is
444 /// unsayable here, where a struct would let it be said and then have to cope.
445 #[derive(Debug, Default)]
446 pub enum Filling<'a> {
447 /// Nothing to edit. The control is drawn and does not answer.
448 #[default]
449 Absent,
450 /// The buffer behind anything that takes typed text, a select included:
451 /// what a select holds is the `value` of one of its [`Choice`]s.
452 ///
453 /// [`Choice`]: makeover_layout::Choice
454 Text(&'a mut String),
455 /// A checkbox, on or off.
456 On(&'a mut bool),
457 }
458
459 /// The label, marked if the field is compulsory.
460 fn label_text(field: &Field<'_>, style: &FieldStyle) -> String {
461 if field.required {
462 format!("{} {}", field.label, style.required_marker)
463 } else {
464 field.label.to_owned()
465 }
466 }
467
468 /// The four shapes a control comes in here, which is fewer than there are
469 /// kinds.
470 ///
471 /// [`FieldKind`] is `#[non_exhaustive]` and grows; this does not, because the
472 /// ways egui has of asking for a value do not. Reducing the open set to this
473 /// closed one in one total function is what keeps a new kind from needing a new
474 /// arm at every match below.
475 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
476 enum Control {
477 /// Typed into, so it is drawn as a well: the user looks into it.
478 Typed,
479 /// Picked from a control that shows one option at a time. Pressed rather
480 /// than looked into, so egui's own control painting stands.
481 Chosen,
482 /// Picked from options that are all on screen at once.
483 ///
484 /// Apart from [`Chosen`](Self::Chosen) because the description holds them
485 /// apart, and holding them apart is the whole content of
486 /// [`FieldKind::Radio`]: same question, and an answer the user can read
487 /// without opening anything.
488 Listed,
489 /// Held on or off.
490 Toggled,
491 }
492
493 /// Which shape a kind takes.
494 ///
495 /// The wildcard falls to [`Control::Typed`] on purpose: a kind added to the
496 /// description since this renderer was built degrades to a text box, which
497 /// accepts any value the others would, rather than to nothing drawn at all.
498 ///
499 /// `FieldKind::File` lands there as of makeover-layout 0.11.0, and it is left
500 /// there rather than grown a shape of its own. egui's honest answer is a button
501 /// that opens a native picker, which is a fifth control and a file-dialog
502 /// dependency; no consumer of this crate asks for a file field yet. Same
503 /// position this crate took on `Meter` at 0.10.0: the membership test is that
504 /// every renderer *could* answer honestly, not that each one does on the day.
505 /// A path in a text box is not nothing, and it is what an app that needs this
506 /// tomorrow gets today.
507 ///
508 /// `FieldKind::Date` and `FieldKind::DateTime` land there too, as of
509 /// makeover-layout 0.15.0, on the same footing and with one thing owed. A
510 /// calendar is a sixth control and bare `egui` has none, so a typed value is
511 /// the honest answer here; what the app gets is the format the description
512 /// names, `makeover_layout::DATE_FORMAT` and `DATETIME_FORMAT`, which is why
513 /// those are constants rather than a sentence. audiofiles is the only consumer
514 /// of this crate and asks for neither today. A calendar popup is the upgrade
515 /// whenever one does.
516 const fn control_shape(kind: FieldKind) -> Control {
517 match kind {
518 FieldKind::Select => Control::Chosen,
519 FieldKind::Radio => Control::Listed,
520 FieldKind::Checkbox => Control::Toggled,
521 _ => Control::Typed,
522 }
523 }
524
525 /// What a select shows for the value it currently holds.
526 ///
527 /// A value no option carries stays on screen as itself rather than reading as
528 /// whichever option happens to be first. goingson saved a backup retention of
529 /// 10 against a 1/3/7/14/0 list and the browser silently showed it as 1, so the
530 /// next save wrote a value nobody chose; `makeover-webview` grew the fix as a
531 /// stray `<option>` and this is the same fix in the shape egui allows.
532 fn shown_label<'a>(options: &'a [Choice<'a>], value: &'a str) -> &'a str {
533 options
534 .iter()
535 .find(|opt| opt.value == value)
536 .map_or(value, |opt| opt.label)
537 }
538
539 /// The control alone, without its label, hint or error.
540 fn control(
541 ui: &mut Ui,
542 field: &Field<'_>,
543 filling: Filling<'_>,
544 palette: &Palette,
545 style: &FieldStyle,
546 ) -> Response {
547 // The mismatch path: described as one thing and filled as another. Nothing
548 // here can fix it, so it is drawn as the empty, inert version of what was
549 // described — visible on screen, in the way an empty select is at the
550 // webview renderer, rather than reported in a log nobody reads.
551 let mut discard = String::new();
552 let mut off = false;
553
554 match control_shape(field.kind) {
555 Control::Typed => {
556 let text = match filling {
557 Filling::Text(text) => text,
558 _ => &mut discard,
559 };
560 // An empty frame and no margin: the well is this crate's, and egui's
561 // own control background and padding would sit underneath it saying
562 // something different about both.
563 let mut edit = if matches!(field.kind, FieldKind::Textarea) {
564 TextEdit::multiline(text)
565 } else {
566 TextEdit::singleline(text)
567 }
568 .frame(egui::Frame::NONE)
569 .margin(Margin::ZERO)
570 .text_color(palette.content)
571 .password(field.kind.confidential());
572 if let Some(ghost) = field.placeholder {
573 edit = edit.hint_text(RichText::new(ghost).color(palette.content_muted));
574 }
575 frame(ui, Depth::Well, palette, style.frame, |ui| ui.add(edit))
576 }
577 Control::Toggled => {
578 let on = match filling {
579 Filling::On(on) => on,
580 _ => &mut off,
581 };
582 ui.checkbox(on, RichText::new(field.label).color(palette.content))
583 }
584 Control::Listed => {
585 let value = match filling {
586 Filling::Text(text) => text,
587 _ => &mut discard,
588 };
589 // No `shown_label` counterpart, and none is needed: a value no
590 // option carries leaves every button unfilled, which is already
591 // the honest report on screen. The select needs the fix because it
592 // has one slot and must put *something* in it.
593 let group = ui.vertical(|ui| {
594 let mut answered: Option<Response> = None;
595 for opt in field.options {
596 let picked = ui.radio_value(
597 value,
598 opt.value.to_owned(),
599 RichText::new(opt.label).color(palette.content),
600 );
601 answered = Some(match answered {
602 Some(prev) => prev.union(picked),
603 None => picked,
604 });
605 }
606 answered
607 });
608 // A group described with no options answers as its own empty area
609 // rather than as no response at all, which keeps the caller's
610 // `.changed()` chain working on a field whose option list has not
611 // loaded yet.
612 group.inner.unwrap_or(group.response)
613 }
614 Control::Chosen => {
615 let value = match filling {
616 Filling::Text(text) => text,
617 _ => &mut discard,
618 };
619 let shown = shown_label(field.options, value);
620 ComboBox::from_id_salt(field.name)
621 .selected_text(RichText::new(shown).color(palette.content))
622 .show_ui(ui, |ui| {
623 for opt in field.options {
624 ui.selectable_value(
625 value,
626 opt.value.to_owned(),
627 RichText::new(opt.label).color(palette.content),
628 );
629 }
630 })
631 .response
632 }
633 }
634 }
635
636 /// One field, as the column the app drops into its form.
637 ///
638 /// The anatomy is `makeover-webview`'s, so the two renderers put a form
639 /// together the same way: label, control, hint, error, top to bottom, with a
640 /// checkbox labelling itself instead of taking a label above.
641 ///
642 /// Returns [`None`] for a [`FieldKind::Hidden`] field, which is what
643 /// [`FieldKind::visible`] means and is the honest answer here: a webview still
644 /// emits an input for it because the form submits, and an immediate-mode
645 /// renderer has no form and no submission, so a hidden field is a value the app
646 /// already holds and there is nothing to draw or to respond to.
647 ///
648 /// `state` is the description's interaction axis.
649 /// [`State::Disabled`] greys the field and stops it answering, through
650 /// [`State::suppresses_interaction`] rather than through a second reading of
651 /// what disabled means. Focus is not on that axis and never reaches here: egui
652 /// owns reach, focus and the ring for this renderer, and one ring means not a
653 /// second one per renderer that happens to have opinions.
654 pub fn field(
655 ui: &mut Ui,
656 field: &Field<'_>,
657 filling: Filling<'_>,
658 state: Option<State>,
659 palette: &Palette,
660 style: &FieldStyle,
661 ) -> Option<Response> {
662 if !field.kind.visible() {
663 return None;
664 }
665 let enabled = !state.is_some_and(State::suppresses_interaction);
666 let text = if enabled {
667 palette.content
668 } else {
669 palette.content_muted
670 };
671
672 let response = ui
673 .vertical(|ui| {
674 ui.spacing_mut().item_spacing.y = style.gap;
675
676 // A checkbox labels itself, on the right of the box.
677 // `FieldKind::labels_itself` is the description saying so, and both
678 // webview apps special-cased it inline before it did.
679 if !field.kind.labels_itself() {
680 ui.label(RichText::new(label_text(field, style)).color(text));
681 }
682
683 let response = ui
684 .add_enabled_ui(enabled, |ui| control(ui, field, filling, palette, style))
685 .inner;
686
687 // Standing help first, then what is wrong now. Both, in that order,
688 // for the reason the webview renderer names both in
689 // `aria-describedby`: an error appearing must not take the hint
690 // away with it.
691 if let Some(hint) = field.hint {
692 ui.label(RichText::new(hint).color(palette.content_muted));
693 }
694 if let Some(error) = field.error {
695 ui.label(RichText::new(error).color(palette.danger));
696 }
697 response
698 })
699 .inner;
700
701 Some(response)
702 }
703
704 /// A set of fields, laid down a column.
705 ///
706 /// `show_extended` is the disclosure, and it is a parameter rather than state
707 /// held here because the disclosure belongs to the *form* and not to any field:
708 /// [`Field::extended`] marks which fields are behind one, and the app owns
709 /// whether it is open. That is the same division `makeover-webview` draws when
710 /// it marks the group `data-extended` and emits no control to toggle it.
711 ///
712 /// `draw` is called once per field that should be visible, in order. Taking a
713 /// callback rather than a slice of [`Filling`]s is what keeps the app's own
714 /// values borrowed one at a time: a form's fields usually live in different
715 /// structs, and a parallel array would have to be built each frame and kept in
716 /// step with the description by hand.
717 pub fn group<'a>(
718 ui: &mut Ui,
719 fields: &'a [Field<'a>],
720 show_extended: bool,
721 style: &FieldStyle,
722 mut draw: impl FnMut(&mut Ui, &'a Field<'a>),
723 ) {
724 ui.vertical(|ui| {
725 ui.spacing_mut().item_spacing.y = style.group_gap;
726 for f in fields {
727 if f.extended && !show_extended {
728 continue;
729 }
730 draw(ui, f);
731 }
732 });
733 }
734
735 #[cfg(test)]
736 mod tests {
737 use super::*;
738
739 fn palette(well: Color32) -> Palette {
740 Palette {
741 page: Color32::from_rgb(1, 1, 1),
742 raised: Color32::from_rgb(2, 2, 2),
743 overlay: Color32::from_rgb(3, 3, 3),
744 well,
745 sunken: Color32::from_rgb(4, 4, 4),
746 bevel_light: Color32::WHITE,
747 bevel_dark: Color32::BLACK,
748 elevation: Color32::from_black_alpha(46),
749 content: Color32::from_rgb(5, 5, 5),
750 content_muted: Color32::from_rgb(6, 6, 6),
751 action: Color32::from_rgb(7, 7, 7),
752 danger: Color32::from_rgb(8, 8, 8),
753 }
754 }
755
756 /// The cast is egui's own shadow type carrying the theme's tone, which is
757 /// the whole of what this crate had to decide for it: unlike a bevel, egui
758 /// already knows how to paint one.
759 #[test]
760 fn the_cast_hands_egui_the_themes_tone() {
761 let p = palette(Color32::from_rgb(9, 9, 9));
762 let cast = p.cast();
763 assert_eq!(cast.color, p.elevation);
764 assert!(cast.blur > 0, "a cast shadow is soft");
765 assert_eq!(cast.offset, [0, 2], "it falls downward and only a little");
766 }
767
768 #[test]
769 fn a_well_resolves_to_its_own_token() {
770 // No substitution left. The page-filled well was a stand-in for a
771 // token that did not exist yet; it exists now.
772 let w = Color32::from_rgb(9, 9, 9);
773 let p = palette(w);
774 assert_eq!(p.fill(Fill::Well), Some(w));
775 assert_ne!(p.fill(Fill::Well), Some(p.page));
776 }
777
778 #[test]
779 fn every_intent_is_a_plain_lookup() {
780 let p = palette(Color32::from_rgb(9, 9, 9));
781 assert_eq!(p.fill(Fill::Page), Some(p.page));
782 assert_eq!(p.fill(Fill::Raised), Some(p.raised));
783 assert_eq!(p.fill(Fill::Overlay), Some(p.overlay));
784 }
785
786 /// Sunken is its own colour, not the well's and not the page's. The two
787 /// are authored in opposite directions and an earlier cut of the
788 /// description conflated them.
789 #[test]
790 fn sunken_is_neither_the_well_nor_the_page() {
791 let p = palette(Color32::from_rgb(9, 9, 9));
792 assert_eq!(p.fill(Fill::Sunken), Some(p.sunken));
793 assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Well));
794 assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Page));
795 }
796
797 #[test]
798 fn a_raised_region_never_resolves_to_the_well_fill() {
799 // The cross-app bug, asserted at the renderer boundary this time.
800 let p = palette(Color32::from_rgb(9, 9, 9));
801 let raised = Depth::Raised.fill().and_then(|f| p.fill(f));
802 let well = Depth::Well.fill().and_then(|f| p.fill(f));
803 assert_eq!(raised, Some(p.raised));
804 assert_ne!(raised, well);
805 }
806
807 #[test]
808 fn an_overlay_is_cast_onto_the_page_and_takes_no_edge() {
809 // makeover-layout 0.14.0 is what made this reachable. The answer was
810 // already here at 0.10.0 and the question could not be asked.
811 let p = palette(Color32::from_rgb(9, 9, 9));
812 assert_eq!(
813 Depth::Overlay.fill().and_then(|f| p.fill(f)),
814 Some(p.overlay)
815 );
816 assert_eq!(Depth::Overlay.bevel(), None);
817 // The shadow `frame` reaches for is the theme's tone rather than
818 // egui's default, which is the whole reason `cast` exists.
819 assert_eq!(p.cast().color, p.elevation);
820 }
821
822 #[test]
823 fn the_lit_edge_swaps_when_a_card_is_pressed() {
824 let p = palette(Color32::from_rgb(9, 9, 9));
825 let (tl, _) = Depth::Raised.bevel().unwrap().edges();
826 let (ptl, _) = Depth::Raised.pressed().bevel().unwrap().edges();
827 assert_eq!(p.edge(tl), p.bevel_light);
828 assert_eq!(p.edge(ptl), p.bevel_dark);
829 }
830
831 #[test]
832 fn flat_asks_for_neither_fill_nor_edge() {
833 assert!(Depth::Flat.fill().is_none());
834 assert!(Depth::Flat.bevel().is_none());
835 }
836
837 #[test]
838 fn a_select_keeps_a_value_none_of_its_options_carries() {
839 // The save-the-wrong-thing bug, asserted at the second renderer so it
840 // is not re-found there. goingson's own numbers.
841 let options = [
842 Choice::plain("1"),
843 Choice::plain("3"),
844 Choice::plain("7"),
845 Choice::plain("14"),
846 ];
847 assert_eq!(shown_label(&options, "10"), "10");
848 // And a value that does match reads as its label, not as itself.
849 let spelled = [Choice {
850 value: "7",
851 label: "One week",
852 }];
853 assert_eq!(shown_label(&spelled, "7"), "One week");
854 }
855
856 #[test]
857 fn only_a_required_field_is_marked() {
858 let style = FieldStyle::default();
859 let plain = Field::new(FieldKind::Text, "title", "Title");
860 assert_eq!(label_text(&plain, &style), "Title");
861
862 let required = Field {
863 required: true,
864 ..plain
865 };
866 assert_eq!(label_text(&required, &style), "Title *");
867
868 // The marker is copy and the app owns it, which is why it is a knob.
869 let house = FieldStyle {
870 required_marker: "(required)",
871 ..style
872 };
873 assert_eq!(label_text(&required, &house), "Title (required)");
874 }
875
876 #[test]
877 fn a_select_and_a_checkbox_are_pressed_and_everything_else_is_typed_into() {
878 // What decides whether the control gets a well. A well is for what the
879 // user looks into, and only one of these is.
880 assert_eq!(control_shape(FieldKind::Select), Control::Chosen);
881 assert_eq!(control_shape(FieldKind::Radio), Control::Listed);
882 assert_eq!(control_shape(FieldKind::Checkbox), Control::Toggled);
883 for k in [
884 FieldKind::Text,
885 FieldKind::Secret,
886 FieldKind::Number,
887 FieldKind::Email,
888 FieldKind::Url,
889 FieldKind::Tel,
890 FieldKind::Textarea,
891 ] {
892 assert_eq!(control_shape(k), Control::Typed, "{k:?} is typed into");
893 }
894 }
895
896 #[test]
897 fn the_two_option_taking_kinds_are_drawn_differently_on_purpose() {
898 // The description holds Select and Radio apart, and a renderer that
899 // collapsed them would silently answer a question the app did not ask:
900 // audiofiles' storage style is irreversible and its alternatives have
901 // to be readable without opening anything. Asserting the two shapes
902 // differ is asserting that distinction survives the trip.
903 assert!(FieldKind::Select.offers_options());
904 assert!(FieldKind::Radio.offers_options());
905 assert_ne!(
906 control_shape(FieldKind::Select),
907 control_shape(FieldKind::Radio)
908 );
909 }
910
911 #[test]
912 fn a_hidden_field_draws_nothing_and_answers_nothing() {
913 // Where the two renderers legitimately part: a webview still emits an
914 // input because the form submits, and there is no form here.
915 let f = Field::new(FieldKind::Hidden, "id", "Id");
916 let p = palette(Color32::from_rgb(9, 9, 9));
917 egui::__run_test_ui(|ui| {
918 let drawn = field(ui, &f, Filling::Absent, None, &p, &FieldStyle::default());
919 assert!(drawn.is_none());
920 });
921 }
922
923 #[test]
924 fn a_disabled_field_stops_answering_and_an_unstated_one_does_not() {
925 let f = Field::new(FieldKind::Text, "title", "Title");
926 let p = palette(Color32::from_rgb(9, 9, 9));
927 let style = FieldStyle::default();
928 egui::__run_test_ui(|ui| {
929 let mut text = String::from("x");
930 let disabled = field(
931 ui,
932 &f,
933 Filling::Text(&mut text),
934 Some(State::Disabled),
935 &p,
936 &style,
937 )
938 .unwrap();
939 assert!(!disabled.enabled());
940
941 // Stating no state is the ordinary case and answers. Focus used to
942 // be the counter-example here; it is egui's now and a description
943 // cannot state it at all.
944 let mut text = String::from("x");
945 let plain = field(ui, &f, Filling::Text(&mut text), None, &p, &style).unwrap();
946 assert!(plain.enabled(), "an unstated field still answers");
947 });
948 }
949
950 #[test]
951 fn a_field_described_one_way_and_filled_another_is_drawn_inert() {
952 // No panic and no write-through. A checkbox handed a string cannot be
953 // filled, so it is drawn off and left alone.
954 let f = Field::new(FieldKind::Checkbox, "done", "Done");
955 let p = palette(Color32::from_rgb(9, 9, 9));
956 let mut text = String::from("untouched");
957 egui::__run_test_ui(|ui| {
958 let drawn = field(
959 ui,
960 &f,
961 Filling::Text(&mut text),
962 None,
963 &p,
964 &FieldStyle::default(),
965 );
966 assert!(drawn.is_some());
967 });
968 assert_eq!(text, "untouched");
969 }
970
971 #[test]
972 fn the_disclosure_belongs_to_the_form_and_not_to_the_field() {
973 let fields = [
974 Field::new(FieldKind::Text, "title", "Title"),
975 Field {
976 extended: true,
977 ..Field::new(FieldKind::Text, "notes", "Notes")
978 },
979 ];
980 let style = FieldStyle::default();
981
982 let mut closed = Vec::new();
983 egui::__run_test_ui(|ui| {
984 group(ui, &fields, false, &style, |_, f| closed.push(f.name));
985 });
986 assert_eq!(closed, ["title"]);
987
988 let mut open = Vec::new();
989 egui::__run_test_ui(|ui| {
990 group(ui, &fields, true, &style, |_, f| open.push(f.name));
991 });
992 assert_eq!(open, ["title", "notes"]);
993 }
994
995 #[test]
996 fn the_default_frame_is_square_and_one_point() {
997 let d = FrameStyle::default();
998 assert_eq!(d.radius, CornerRadius::ZERO);
999 assert_eq!(d.margin, Margin::ZERO);
1000 assert!((d.stroke - 1.0).abs() < f32::EPSILON);
1001 }
1002 }
1003