teksilo_core/
modal.rs

1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4use crate::overlay::OverlayDismissCallback;
5use crate::widget_id::WidgetId;
6
7/// How the framework should present a modal surface.
8#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
9pub enum ModalPresentation {
10    /// Let the framework pick the most appropriate backend for the runtime.
11    #[default]
12    Auto,
13    /// Present inside the current widget tree using the overlay system.
14    InTree,
15    /// Present in a separate native OS window.
16    NativeWindow,
17}
18
19/// How a presented modal can be closed by framework-managed interactions.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
21pub enum ModalCloseBehavior {
22    /// Close when clicking outside the modal surface.
23    ClickOutside,
24    /// Close when pressing Escape.
25    EscapeKey,
26    /// Close on either Escape or an outside click.
27    #[default]
28    EscapeOrClickOutside,
29    /// Only close through explicit application logic.
30    Manual,
31}
32
33/// Where an in-tree modal sits in the window.
34///
35/// Read only by the in-tree presentation: a modal presented as a native
36/// window is placed by the operating system.
37#[derive(Debug, Clone, Copy, PartialEq, Default)]
38pub enum ModalPlacement {
39    /// Centred in the window: the dialog convention.
40    #[default]
41    Centered,
42    /// Centred horizontally, with its top edge `offset` logical pixels below
43    /// the top of the window. For a surface whose height changes while it
44    /// is open, such as a command palette that narrows as the user types: a
45    /// centred one would move its search field with every keystroke, while
46    /// this keeps the top edge still and lets the bottom edge follow the
47    /// content. Raised as far as needed to keep the modal inside the window.
48    Top {
49        /// Distance from the top of the window to the modal's top edge.
50        offset: f32,
51    },
52}
53
54/// Builder used to create modal content in a target widget tree later.
55pub type ModalBuilder = Box<dyn FnOnce(&mut crate::widget_tree::WidgetTree) -> WidgetId>;
56
57/// Modal content source.
58pub enum ModalContent {
59    /// Reuse an already-inserted widget subtree in the current tree.
60    ExistingWidget(WidgetId),
61    /// Build the modal content into a target widget tree on demand.
62    Deferred(ModalBuilder),
63}
64
65impl std::fmt::Debug for ModalContent {
66    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67        match self {
68            Self::ExistingWidget(id) => f.debug_tuple("ExistingWidget").field(id).finish(),
69            Self::Deferred(_) => f.write_str("Deferred(..)"),
70        }
71    }
72}
73
74/// A framework-level request to present a modal.
75pub struct ModalRequest {
76    pub content: ModalContent,
77    pub presentation: ModalPresentation,
78    pub close_behavior: ModalCloseBehavior,
79    pub title: Option<String>,
80    pub size: Option<(u32, u32)>,
81    /// Where an in-tree presentation places the modal. Ignored by a native
82    /// window.
83    pub placement: ModalPlacement,
84    /// Optional explicit initial-focus target inside the modal content
85    /// subtree. When `None`, the framework falls back to
86    /// `first_focusable_descendant(content_id)`. When `Some`, the id
87    /// is consulted first and the framework focuses it if the widget
88    /// exists and is still active in the target tree; otherwise it
89    /// falls back to `first_focusable_descendant`. Required for
90    /// `MessageBox`-style alerts where the default button may not be
91    /// the first focusable descendant in tree-walk order.
92    pub focus_target: Option<WidgetId>,
93    /// Invoked when the modal is dismissed by any path (Escape, close
94    /// button, click-outside, explicit `ctx.dismiss_modal()`), and when the
95    /// window presenting it closes with it still up (a quit, a forced
96    /// close of the window), with
97    /// [`DismissReason::Programmatic`](crate::overlay::DismissReason::Programmatic).
98    /// For a native modal window, it runs in that window's tree as the
99    /// window closes, whatever closes it.
100    pub on_dismiss: Option<OverlayDismissCallback>,
101}
102
103impl ModalRequest {
104    /// Present an existing widget subtree as modal content.
105    pub fn in_tree(content_id: WidgetId) -> Self {
106        Self {
107            content: ModalContent::ExistingWidget(content_id),
108            presentation: ModalPresentation::Auto,
109            close_behavior: ModalCloseBehavior::default(),
110            title: None,
111            size: None,
112            placement: ModalPlacement::Centered,
113            focus_target: None,
114            on_dismiss: None,
115        }
116    }
117
118    /// Build modal content on demand in the presentation target tree.
119    pub fn deferred(
120        builder: impl FnOnce(&mut crate::widget_tree::WidgetTree) -> WidgetId + 'static,
121    ) -> Self {
122        Self {
123            content: ModalContent::Deferred(Box::new(builder)),
124            presentation: ModalPresentation::Auto,
125            close_behavior: ModalCloseBehavior::default(),
126            title: None,
127            size: None,
128            placement: ModalPlacement::Centered,
129            focus_target: None,
130            on_dismiss: None,
131        }
132    }
133
134    pub fn presentation(mut self, presentation: ModalPresentation) -> Self {
135        self.presentation = presentation;
136        self
137    }
138
139    pub fn close_behavior(mut self, close_behavior: ModalCloseBehavior) -> Self {
140        self.close_behavior = close_behavior;
141        self
142    }
143
144    pub fn title(mut self, title: impl Into<String>) -> Self {
145        self.title = Some(title.into());
146        self
147    }
148
149    /// The size, in logical pixels, of the native window the modal opens
150    /// in when it is presented as one: its floor, since the window grows
151    /// on either axis to fit its content (a dialog panel's padding around
152    /// content of this width, an expander opened). It is centred over the
153    /// window it blocks on the size it first grows to; an expander opened
154    /// later keeps its corner. Ignored in-tree, where the overlay takes its
155    /// content's size.
156    pub fn size(mut self, width: u32, height: u32) -> Self {
157        self.size = Some((width, height));
158        self
159    }
160
161    /// Where an in-tree presentation places the modal. See [`ModalPlacement`].
162    pub fn placement(mut self, placement: ModalPlacement) -> Self {
163        self.placement = placement;
164        self
165    }
166
167    /// Register a callback invoked when the modal is dismissed by any
168    /// path (Escape, close button, click-outside, explicit
169    /// `ctx.dismiss_modal()`), or closed with the window presenting it, in
170    /// the tree and as a native modal window alike, with the reason it
171    /// went.
172    pub fn on_dismiss(mut self, callback: OverlayDismissCallback) -> Self {
173        self.on_dismiss = Some(callback);
174        self
175    }
176
177    /// Direct initial focus to a specific widget inside the modal
178    /// content subtree. The id must resolve to a widget that exists
179    /// and is active at the time the modal is presented; if it does
180    /// not, the framework falls back to
181    /// `first_focusable_descendant(content_id)`.
182    pub fn focus_target(mut self, id: WidgetId) -> Self {
183        self.focus_target = Some(id);
184        self
185    }
186}
187
188impl std::fmt::Debug for ModalRequest {
189    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
190        f.debug_struct("ModalRequest")
191            .field("content", &self.content)
192            .field("presentation", &self.presentation)
193            .field("close_behavior", &self.close_behavior)
194            .field("title", &self.title)
195            .field("size", &self.size)
196            .field("placement", &self.placement)
197            .field("focus_target", &self.focus_target)
198            .field(
199                "on_dismiss",
200                &self.on_dismiss.as_ref().map(|_| "<callback>"),
201            )
202            .finish()
203    }
204}
205
206/// A modal request drained from a widget tree with its originating widget.
207#[derive(Debug)]
208pub struct QueuedModalRequest {
209    pub source_widget: WidgetId,
210    pub request: ModalRequest,
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216    use crate::test_widgets::FillWidget;
217
218    #[test]
219    fn in_tree_request_defaults_to_auto() {
220        let mut tree = crate::WidgetTree::new();
221        let content_id = tree.add(FillWidget::new());
222        let request = ModalRequest::in_tree(content_id);
223        assert_eq!(request.presentation, ModalPresentation::Auto);
224        assert_eq!(
225            request.close_behavior,
226            ModalCloseBehavior::EscapeOrClickOutside
227        );
228        match request.content {
229            ModalContent::ExistingWidget(id) => assert_eq!(id, content_id),
230            ModalContent::Deferred(_) => panic!("expected ExistingWidget content"),
231        }
232    }
233
234    #[test]
235    fn deferred_request_can_override_metadata() {
236        let request =
237            ModalRequest::deferred(|tree| tree.add(crate::test_widgets::FillWidget::new()))
238                .presentation(ModalPresentation::NativeWindow)
239                .close_behavior(ModalCloseBehavior::Manual)
240                .title("Preferences")
241                .size(640, 480);
242
243        assert_eq!(request.presentation, ModalPresentation::NativeWindow);
244        assert_eq!(request.close_behavior, ModalCloseBehavior::Manual);
245        assert_eq!(request.title.as_deref(), Some("Preferences"));
246        assert_eq!(request.size, Some((640, 480)));
247        assert!(matches!(request.content, ModalContent::Deferred(_)));
248    }
249
250    #[test]
251    fn focus_target_defaults_to_none() {
252        let mut tree = crate::WidgetTree::new();
253        let content_id = tree.add(FillWidget::new());
254        let in_tree = ModalRequest::in_tree(content_id);
255        assert!(in_tree.focus_target.is_none());
256
257        let deferred =
258            ModalRequest::deferred(|tree| tree.add(crate::test_widgets::FillWidget::new()));
259        assert!(deferred.focus_target.is_none());
260    }
261
262    #[test]
263    fn focus_target_builder_sets_field() {
264        let mut tree = crate::WidgetTree::new();
265        let content_id = tree.add(FillWidget::new());
266        let target_id = tree.add(FillWidget::new());
267        let request = ModalRequest::in_tree(content_id).focus_target(target_id);
268        assert_eq!(request.focus_target, Some(target_id));
269    }
270}
teksilo_core/modal.rs

teksilo_core/
modal.rs
