1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
use super::*;
#[derive(Clone)]
pub struct WindowHandle {
pub(super) info: WindowInfo,
pub(super) window: Window,
}
impl WindowHandle {
#[cfg(feature = "mcp")]
pub(crate) fn dialog_window(&self) -> DialogWindow {
DialogWindow(Arc::downgrade(&self.window.inner))
}
/// The file dialog broker of the window's tree, while it lives.
#[cfg(feature = "mcp")]
pub(crate) fn file_dialog_broker(&self) -> Option<crate::mcp::FileDialogBroker> {
self.window.file_dialog_broker()
}
/// The system's handles of the window, where the shell recorded them: the parent of a dialog of the system.
pub(crate) fn parent(&self) -> Option<super::parent::ParentWindow> {
self.window.parent()
}
pub fn info(&self) -> WindowInfo {
self.info
}
/// Runs `callback` once in each frame this window draws, in step with its display, for as long as it returns
/// `true`, as [`Ctx::on_frame`](crate::app::ctx::Ctx::on_frame) does for a component: for code that is not a
/// component's, such as a game loop the app keeps beside its tree. The window keeps it until it stops (it returns
/// `false`, or is cancelled); [`FrameCallback::start`](crate::app::ctx::FrameCallback::start) gives it back to the
/// window. Window callbacks run before the components' in each frame.
pub fn on_frame(
&self,
callback: impl FnMut(crate::app::ctx::Frame) -> bool + Send + 'static,
) -> crate::app::ctx::FrameCallback {
let callback = self
.window
.frames()
.add(Box::new(callback), Some(self.window.loop_waker()));
// A callback added from outside a turn of the loop is run from its next one.
(self.window.loop_waker())();
callback
}
/// Replace this window's OS/app close handler. Runs on the event-loop thread.
pub fn on_close_requested(&self, handler: impl Fn(CloseRequest) + Send + Sync + 'static) {
self.window.inner.write().unwrap().close_handler = Some(Arc::new(handler));
}
/// Replace this window's handler of what the system says of the app: that it came to the front or left it,
/// that it was opened with a link or a shortcut. Runs on the event-loop thread. What the app was started
/// with is told once a handler is there, so register it in the root component's `create`.
pub fn on_app_event(&self, handler: impl Fn(&crate::app::window::AppEvent) + Send + Sync + 'static) {
self.window.set_app_event_handler(Some(Arc::new(handler)));
}
pub fn clear_close_requested_handler(&self) {
self.window.inner.write().unwrap().close_handler = None;
}
/// Queue a vetoable request; unlike `close`, this invokes the handler.
/// Plays a tap of the device's haptic engine, where there is one.
pub fn haptic(&self, haptic: crate::app::window::Haptic) {
self.window.push_command(WindowCommand::Haptic(haptic));
}
/// Shows the system's share sheet for `share` over this window: the apps and people the system offers an
/// address to, as an iPhone's Share button does. What a handler calls, which holds the window
/// (`ctx.window()`) and has no `Ctx`; see [`Share`](crate::app::Share) for what is shared and
/// [the module](crate::app::share) for what each platform shows.
///
/// `Ok` once the sheet is asked for: it is shown by the window's shell as the handler that asked returns (a
/// browser's within the press itself), and what the person does in it is not told. An error is why nothing
/// was asked: [`ShareError::Unsupported`](crate::app::ShareError::Unsupported) where there is no sheet (Linux,
/// a browser without `navigator.share`), which an app answers by copying the address;
/// [`ShareError::NotAnAddress`](crate::app::ShareError::NotAnAddress) for what is not an address with a
/// scheme. Where the system refuses a sheet it was asked for, the log says so (`lurq::share`, at warn).
///
/// ```no_run
/// # use lurq::{app::{Share, ShareError, ctx::Ctx}, ui::Button};
/// fn share_button(ctx: &mut Ctx, address: &'static str) -> Button {
/// let window = ctx.window();
/// Button::new("Share").on_click(move |_| {
/// if window.share(Share::url(address).title("The docs")) == Err(ShareError::Unsupported) {
/// window.copy_to_clipboard(address);
/// }
/// })
/// }
/// ```
pub fn share(&self, share: crate::app::Share) -> Result<(), crate::app::ShareError> {
match crate::app::share::ask(share)? {
crate::app::share::Asked::Done => {}
crate::app::share::Asked::Shell(share) => self.window.push_command(WindowCommand::Share(share)),
}
Ok(())
}
pub fn request_close(&self) {
self
.window
.push_command(WindowCommand::RequestClose(CloseRequestSource::App));
}
/// Close unconditionally, without invoking the close handler.
pub fn close(&self) {
self.window.push_command(WindowCommand::Close);
}
pub fn set_minimized(&self, minimized: bool) {
self.window.push_command(WindowCommand::SetMinimized(minimized));
}
pub fn set_maximized(&self, maximized: bool) {
self.window.push_command(WindowCommand::SetMaximized(maximized));
}
pub fn set_full_screen(&self, full_screen: bool) {
self.window.push_command(WindowCommand::SetFullScreen(full_screen));
}
pub fn set_decorated(&self, decorated: bool) {
self.window.push_command(WindowCommand::SetDecorated(decorated));
}
pub fn set_decorations(&self, decorations: bool) {
self.set_decorated(decorations);
}
/// The window's title as last requested: by `set_title`, or the title the
/// window was created with (`WinitWindow::with_title`, `open_window`) once
/// the shell has created it. `None` before then, and in headless trees that
/// never set one. Reading it does not subscribe the component.
pub fn title(&self) -> Option<String> {
self.window.inner.read().unwrap().title.clone()
}
/// Sets the OS window title: the title bar text, and the taskbar button and
/// Alt+Tab on Windows, or the Window menu and Mission Control on macOS. Like
/// the other commands it is applied by the shell on the event-loop thread.
/// Setting the title the window already has queues nothing, so calling this
/// from `render` with an unchanged title does no work.
pub fn set_title(&self, title: impl Into<String>) {
let title = title.into();
{
let mut inner = self.window.inner.write().unwrap();
if inner.title.as_deref() == Some(title.as_str()) {
return;
}
inner.title = Some(title.clone());
}
self.window.push_command(WindowCommand::SetTitle(title));
}
pub fn set_title_bar_color(&self, color: impl Into<Option<Color>>) {
self.window.push_command(WindowCommand::SetTitleBarColor(color.into()));
}
pub fn clear_title_bar_color(&self) {
self.set_title_bar_color(None);
}
/// How much of the window's top the app draws its own title bar over: the height of the title bar of a
/// [`WindowChrome`](crate::components::WindowChrome), and `0.0` with no chrome or one that is off. The
/// window's content is laid out under the bar, and so is a modal over the whole window
/// (`Modal::target(ModalTarget::Root)`): it covers the window from the bar down.
pub fn title_bar_inset(&self) -> f32 {
self.window.inner.read().unwrap().title_bar_inset
}
/// Says how much of the window's top the app's own title bar is drawn over, so that a modal over the whole
/// window starts under it. A `WindowChrome` says it for its title bar; an app that draws a title bar
/// another way says it itself.
pub fn set_title_bar_inset(&self, inset: f32) {
self.window.set_title_bar_inset(inset.max(0.0));
}
/// The compositor border last applied by the shell.
pub fn border_color(&self) -> WindowBorderColor {
self.window.inner.read().unwrap().border_color
}
/// Sets the compositor border drawn around the window. Supported on Windows 11 (build 22000+).
pub fn set_border_color(&self, color: WindowBorderColor) {
self.window.push_command(WindowCommand::SetBorderColor(color));
}
/// Sets the window's icon, or clears it with `None`. On Windows it is both
/// the small icon (title bar) and the big one (taskbar button, Alt+Tab). On
/// macOS this does nothing: the Dock and the app switcher show the
/// application bundle's icon.
///
/// A title bar the app draws itself shows it too: `ui::WindowChrome` draws it as its icon unless told another.
pub fn set_icon(&self, icon: impl Into<Option<WindowIcon>>) {
let icon = icon.into();
self.window.set_icon(icon.clone());
self.window.push_command(WindowCommand::SetIcon(icon));
}
/// Puts `text` on the clipboard, as a copy shortcut puts the selected text there: what a copy button does. It is
/// written once the handler that asked returns (or at the next pass, asked from elsewhere), where Ctrl+C writes:
/// the OS clipboard with the `clipboard` feature, or what a test installs with
/// [`Tree::set_clipboard_writer`](crate::app::Tree::set_clipboard_writer).
pub fn copy_to_clipboard(&self, text: impl Into<String>) {
self.window.request_copy(text.into());
}
/// Runs a command of editing on what has the focus, as its key does
/// ([`EditCommand`](crate::app::events::EditCommand)): what an Edit menu's item runs, a native one's too, whose
/// handler has no `Ctx` (on macOS a native item's key equivalent, Cmd+Z, takes the key before the window sees it).
/// It is run once the handler that asked returns (or at the next pass, asked from elsewhere); see
/// [`Ctx::edit`](crate::app::ctx::Ctx::edit), which is the same from a component.
pub fn edit(&self, command: crate::app::events::EditCommand) {
self.window.request_edit(command);
}
/// Goes back, as Alt+← and the mouse's back button do: on the focused element and out from it
/// (`on_history_back`), then the router ([`NavigationCommand`](crate::app::events::NavigationCommand)). What a
/// native menu's item runs, whose handler has no `Ctx`. It is run once the handler that asked returns (or at the
/// next pass, asked from elsewhere); see [`Ctx::history_back`](crate::app::ctx::Ctx::history_back), which is the
/// same from a component.
pub fn history_back(&self) {
self.run_navigation(crate::app::events::NavigationCommand::Back);
}
/// Goes forward, as Alt+→ and the mouse's forward button do; see [`history_back`](Self::history_back).
pub fn history_forward(&self) {
self.run_navigation(crate::app::events::NavigationCommand::Forward);
}
/// Goes back or forward by `command`; see [`history_back`](Self::history_back).
pub fn run_navigation(&self, command: crate::app::events::NavigationCommand) {
self.window.request_navigation(crate::app::window::NavigationRequest {
command,
source: crate::app::events::NavigationSource::App,
origin: crate::app::window::NavigationOrigin::Focus,
done: None,
});
}
/// The window's state this handle reads and writes.
pub(crate) fn state(&self) -> Window {
self.window.clone()
}
/// The window's icon, as the app set it (`set_icon`, or the shell's `with_icon`), or `None`. Reading it in a
/// render renders again as it changes.
pub fn icon(&self) -> Option<WindowIcon> {
self.window.track_access();
self.window.icon()
}
pub fn clear_icon(&self) {
self.set_icon(None);
}
pub fn set_corner_radius(&self, radius: WindowCornerRadius) {
self.window.push_command(WindowCommand::SetCornerRadius(radius));
}
pub fn set_rounded_corners(&self, rounded: bool) {
self.set_corner_radius(if rounded {
WindowCornerRadius::Rounded
} else {
WindowCornerRadius::None
});
}
pub fn reset_corner_radius(&self) {
self.set_corner_radius(WindowCornerRadius::Default);
}
pub fn r#move(&self, x: i32, y: i32) {
self.window.push_command(WindowCommand::Move { x, y });
}
pub fn move_to(&self, x: i32, y: i32) {
self.r#move(x, y);
}
/// Request a client size in physical pixels. A minimized window is restored first, since Windows does not resize a
/// minimized window. A maximized or full-screen window stays in its mode: the resize does not take the user out of
/// it. The size takes effect asynchronously; read it back from `ctx.window()`.
pub fn resize(&self, width: u32, height: u32) {
self
.window
.push_command(WindowCommand::Resize(super::resize::ResizeRequest {
width,
height,
restore: super::resize::ResizeRestore::Minimized,
report: None,
}));
}
pub fn start_drag(&self) {
self.window.push_command(WindowCommand::StartDrag);
}
pub fn start_resize(&self, direction: WindowResizeDirection) {
self.window.push_command(WindowCommand::StartResize(direction));
}
pub fn stop_drag(&self) {
self.window.push_command(WindowCommand::StopDrag);
}
/// Shows the system's menu of the window where the pointer is: Restore, Move, Size, Minimize, Maximize and
/// Close, as a right press on a title bar the system draws does. For a title bar of the app's own. Only Windows
/// has such a menu; on macOS and Linux this does nothing.
pub fn show_system_menu(&self) {
self.window.push_command(WindowCommand::ShowSystemMenu);
}
/// Queue one synthetic input event, delivered inside the shell's event loop
/// exactly where the matching OS event would have been.
///
/// Positions are physical pixels in the window's coordinate space — the same
/// units a captured frame is measured in.
pub fn inject_input(&self, input: crate::app::synthetic_input::SyntheticInput) {
self.window.push_command(WindowCommand::InjectInput(input));
}
/// Queue several synthetic events in order; see [`Self::inject_input`].
pub fn inject_inputs(&self, inputs: impl IntoIterator<Item = crate::app::synthetic_input::SyntheticInput>) {
for input in inputs {
self.inject_input(input);
}
}
/// Pastes the OS clipboard into the focused text input, as Ctrl+V does:
/// the input's `on_paste` handlers see the content first. For an app's own
/// Paste menu item or context menu. The clipboard is read inside the
/// shell's event loop, as OS input. A request made while lurq delivers
/// synthetic input (an MCP client's click on the menu item,
/// [`is_synthetic_input`](crate::app::events::is_synthetic_input)) is
/// refused: the person's clipboard is theirs, and a synthetic paste
/// carries its own content ([`SyntheticInput::paste`](crate::app::synthetic_input::SyntheticInput::paste)).
#[cfg(feature = "clipboard")]
pub fn paste_from_clipboard(&self) {
self.window.push_command(WindowCommand::PasteFromClipboard {
synthetic: crate::app::events::is_synthetic_input(),
});
}
/// Captures the next rendered window frame to a PNG file.
#[cfg(feature = "screenshot")]
pub fn screenshot(&self, output_path: impl Into<std::path::PathBuf>) {
self
.window
.push_command(WindowCommand::Screenshot(output_path.into(), None));
}
/// Captures the next rendered frame cropped to a logical-pixel window
/// region. The region is converted to physical pixels and clamped to the
/// viewport at capture time; a region with no visible area is skipped with
/// a warning.
#[cfg(feature = "screenshot")]
pub fn screenshot_region(&self, output_path: impl Into<std::path::PathBuf>, region: ScreenshotRegion) {
self
.window
.push_command(WindowCommand::Screenshot(output_path.into(), Some(region)));
}
/// Captures the next rendered frame cropped to one element's bounds, as
/// attached with `ref_element`. The bounds are read now, from the last
/// completed layout pass — capture after the element has painted.
#[cfg(feature = "screenshot")]
pub fn screenshot_node(&self, output_path: impl Into<std::path::PathBuf>, node: &crate::core::ElementRef) {
let bounds = node.bounds();
self.screenshot_region(
output_path,
ScreenshotRegion {
x: bounds.x,
y: bounds.y,
width: bounds.width,
height: bounds.height,
},
);
}
pub fn open_devtools(&self) {
self.window.push_command(WindowCommand::OpenDevtools);
}
pub fn close_devtools(&self) {
self.window.push_command(WindowCommand::CloseDevtools);
}
pub fn toggle_devtools(&self) {
self.window.push_command(WindowCommand::ToggleDevtools);
}
}
/// A weak, immutable window identity; a same-name replacement never matches.
#[cfg(feature = "mcp")]
#[derive(Clone)]
pub(crate) struct DialogWindow(Weak<RwLock<WindowInner>>);
#[cfg(feature = "mcp")]
impl DialogWindow {
pub(crate) fn matches(&self, window: &Window) -> bool {
self.0.ptr_eq(&Arc::downgrade(&window.inner))
}
pub(crate) fn closing(&self) -> bool {
self
.0
.upgrade()
.is_none_or(|window| window.read().unwrap().accepted_close)
}
}
impl Deref for WindowHandle {
type Target = WindowInfo;
fn deref(&self) -> &Self::Target {
&self.info
}
}