Skip to main content

max / quasi

7.4 KB · 204 lines History Blame Raw
1 //! The immediate-mode renderer for [`quasi_router`]: a described screen in, an
2 //! egui frame out.
3 //!
4 //! <!-- wiki: quasi-overview -->
5 //!
6 //! The third renderer, and the one the stack was missing. `quasi-webview` and
7 //! `quasi-tui` have consumed a [`Screen`] since the beginning; nothing did in
8 //! egui, so an egui app describing a screen had nowhere to send it. What looked
9 //! like the egui renderer was `makeover-immediate`, which draws described
10 //! *nodes* and takes no dependency on `quasi-router` at all: it is the peer of
11 //! `makeover-webview` and `makeover-tui`, one layer below this.
12 //!
13 //! | Layer | webview | terminal | egui |
14 //! |---|---|---|---|
15 //! | nodes, from `makeover-layout` | `makeover-webview` | `makeover-tui` | `makeover-immediate` |
16 //! | screens, from `quasi-router` | `quasi-webview` | `quasi-tui` | **this crate** |
17 //!
18 //! Named for the mode and not the library, the way `makeover-immediate` is: what
19 //! separates this renderer from the other two is that there is no retained tree
20 //! and no cascade, and egui is the backend it is written against.
21 //!
22 //! # What immediate mode gives this renderer for free
23 //!
24 //! `quasi-tui` holds five things a browser provides quietly: what is typed, what
25 //! has focus, how far a pane is scrolled, what is ticked, and where back goes.
26 //! egui provides three of them, so this crate is smaller than the terminal's
27 //! rather than larger:
28 //!
29 //! - **Reach and focus are egui's**, entirely. Its own id stack decides what is
30 //! reachable and its own state decides what holds the keyboard, which is the
31 //! rule `makeover-immediate`'s header already states for the ring. There is no
32 //! `focus.rs` here and there should not be one.
33 //! - **Scroll is egui's**, through `ScrollArea`.
34 //! - **What is typed and what is ticked are not.** A described field is built
35 //! from the description every frame, so the buffer behind it has to outlive
36 //! the frame and belongs to the app. That is [`View`], and it is the same
37 //! discovery the terminal made for the same reason.
38 //!
39 //! # Where a description stops being enough
40 //!
41 //! The three findings `quasi-tui`'s `region` module records apply here unchanged,
42 //! because they are about the description rather than about terminals: a tabbed
43 //! arrangement does not say which tab is showing, a tab has no label, and
44 //! nothing says a region's share beyond [`Arrangement::share`]. Nothing new is
45 //! invented here to paper over them; the same guesses are made and named.
46
47 #![forbid(unsafe_code)]
48
49 mod node;
50 mod region;
51 mod runtime;
52 mod view;
53
54 #[cfg(test)]
55 mod tests;
56
57 pub use runtime::{Runtime, Step};
58 pub use view::View;
59
60 use egui::Ui;
61 use makeover_immediate::table::TableStyle;
62 use makeover_immediate::widget::WidgetStyle;
63 use makeover_immediate::{FieldStyle, FrameStyle, Palette};
64 use quasi_router::{Action, Message, Params, Screen, layout};
65
66 /// A banner this renderer raises about itself.
67 ///
68 /// A description bug reported to the user rather than swallowed: a fragment
69 /// naming a region that is not there would otherwise look like a control that
70 /// does nothing.
71 pub(crate) fn layout_notice(text: String) -> Message {
72 Message {
73 kind: layout::Notice::Banner,
74 tone: layout::Tone::Danger,
75 text,
76 undo: None,
77 }
78 }
79
80 /// An egui renderer for a described screen.
81 ///
82 /// Holds what a drawing needs and no screen state: the resolved palette and the
83 /// styles derived from it. A host makes one and keeps it, the same way it keeps
84 /// a `Tui`.
85 #[derive(Debug, Clone)]
86 pub struct Immediate {
87 palette: Palette,
88 frame: FrameStyle,
89 field: FieldStyle,
90 widget: WidgetStyle,
91 table: TableStyle,
92 }
93
94 impl Immediate {
95 /// A renderer drawing in this palette, with default styling.
96 #[must_use]
97 pub fn new(palette: Palette) -> Self {
98 Self {
99 palette,
100 frame: FrameStyle::default(),
101 field: FieldStyle::default(),
102 widget: WidgetStyle::default(),
103 table: TableStyle::default(),
104 }
105 }
106
107 /// The colours this renderer draws in.
108 #[must_use]
109 pub const fn palette(&self) -> &Palette {
110 &self.palette
111 }
112
113 /// Use these frame, field, widget and table styles, chaining.
114 #[must_use]
115 pub fn styled(
116 mut self,
117 frame: FrameStyle,
118 field: FieldStyle,
119 widget: WidgetStyle,
120 table: TableStyle,
121 ) -> Self {
122 self.frame = frame;
123 self.field = field;
124 self.widget = widget;
125 self.table = table;
126 self
127 }
128
129 /// Draw a whole screen, and answer what the user did to it.
130 ///
131 /// The title is not drawn, for the reason `quasi-tui` gives: a window title
132 /// is the host's to set, the same way a webview host puts it in `<title>`
133 /// rather than in the document. [`Screen::discovery`] is declined outright,
134 /// since nothing crawls a desktop window.
135 ///
136 /// `None` is the ordinary frame. egui redraws continuously, so most frames
137 /// are a user doing nothing, and a renderer that answered a request per
138 /// frame would call the router sixty times a second.
139 pub fn screen(&self, ui: &mut Ui, screen: &Screen, view: &mut View) -> Option<Fired> {
140 let mut pass = Pass {
141 immediate: self,
142 view,
143 fired: None,
144 };
145
146 // Notices first and at the top, because a notice belongs to the screen
147 // rather than to a place in it. A webview leaves where they land to the
148 // stylesheet; egui has none, so this is the renderer deciding, and the
149 // top is the one place a message about the whole screen can go without
150 // claiming a region.
151 for notice in &screen.notices {
152 node::draw(&mut pass, ui, notice);
153 }
154
155 region::screen_regions(&mut pass, ui, screen);
156 pass.fired
157 }
158 }
159
160 /// What the user set off this frame.
161 ///
162 /// An action and everything gathered to send with it. Separate from
163 /// [`Step`](runtime::Step) because a drawing does not know whether an action
164 /// needs asking about first: that is [`Act::confirm`](quasi_router::Act), and
165 /// the runtime is what holds the question while it is answered.
166 #[derive(Debug, Clone, PartialEq, Eq)]
167 pub struct Fired {
168 /// What to call.
169 pub action: Action,
170 /// What to send with it: a form's values, a selection's members.
171 pub payload: Params,
172 /// What to ask before doing it, if the description said to ask.
173 pub confirm: Option<String>,
174 }
175
176 /// One frame's drawing, and what came out of it.
177 ///
178 /// Threaded through the walk rather than returned up it: a press can happen at
179 /// any depth, and every level returning an `Option` would make each node's
180 /// drawing responsible for propagating one.
181 pub(crate) struct Pass<'a> {
182 pub(crate) immediate: &'a Immediate,
183 pub(crate) view: &'a mut View,
184 pub(crate) fired: Option<Fired>,
185 }
186
187 impl Pass<'_> {
188 /// Record what the user set off.
189 ///
190 /// First press wins. Two controls cannot be activated in one frame by a
191 /// user, so a second one here is a description that put two `Response`s
192 /// under one click, and taking the first is the same rule
193 /// `Chrome::bound` uses for a key claimed twice.
194 pub(crate) fn fire(&mut self, action: &Action, payload: Params, confirm: Option<&str>) {
195 if self.fired.is_none() {
196 self.fired = Some(Fired {
197 action: action.clone(),
198 payload,
199 confirm: confirm.map(ToOwned::to_owned),
200 });
201 }
202 }
203 }
204