tauri_runtime/
window.rs

1// Copyright 2019-2024 Tauri Programme within The Commons Conservancy
2// SPDX-License-Identifier: Apache-2.0
3// SPDX-License-Identifier: MIT
4
5//! A layer between raw [`Runtime`] windows and Tauri.
6
7use crate::{
8  webview::{DetachedWebview, PendingWebview},
9  Icon, Runtime, UserEvent, WindowDispatch,
10};
11
12use dpi::PixelUnit;
13use serde::{Deserialize, Deserializer, Serialize};
14use tauri_utils::{
15  config::{Color, WindowConfig},
16  Theme,
17};
18#[cfg(windows)]
19use windows::Win32::Foundation::HWND;
20
21use std::{
22  hash::{Hash, Hasher},
23  marker::PhantomData,
24  path::PathBuf,
25  sync::mpsc::Sender,
26};
27
28/// An event from a window.
29#[derive(Debug, Clone)]
30pub enum WindowEvent {
31  /// The size of the window has changed. Contains the client area's new dimensions.
32  Resized(dpi::PhysicalSize<u32>),
33  /// The position of the window has changed. Contains the window's new position.
34  Moved(dpi::PhysicalPosition<i32>),
35  /// The window has been requested to close.
36  CloseRequested {
37    /// A signal sender. If a `true` value is emitted, the window won't be closed.
38    signal_tx: Sender<bool>,
39  },
40  /// The window has been destroyed.
41  Destroyed,
42  /// The window gained or lost focus.
43  ///
44  /// The parameter is true if the window has gained focus, and false if it has lost focus.
45  Focused(bool),
46  /// The window's scale factor has changed.
47  ///
48  /// The following user actions can cause DPI changes:
49  ///
50  /// - Changing the display's resolution.
51  /// - Changing the display's scale factor (e.g. in Control Panel on Windows).
52  /// - Moving the window to a display with a different scale factor.
53  ScaleFactorChanged {
54    /// The new scale factor.
55    scale_factor: f64,
56    /// The window inner size.
57    new_inner_size: dpi::PhysicalSize<u32>,
58  },
59  /// An event associated with the drag and drop action.
60  DragDrop(DragDropEvent),
61  /// The system window theme has changed.
62  ///
63  /// Applications might wish to react to this to change the theme of the content of the window when the system changes the window theme.
64  ThemeChanged(Theme),
65}
66
67/// An event from a window.
68#[derive(Debug, Clone)]
69pub enum WebviewEvent {
70  /// An event associated with the drag and drop action.
71  DragDrop(DragDropEvent),
72}
73
74/// The drag drop event payload.
75#[derive(Debug, Clone)]
76#[non_exhaustive]
77pub enum DragDropEvent {
78  /// A drag operation has entered the webview.
79  Enter {
80    /// List of paths that are being dragged onto the webview.
81    paths: Vec<PathBuf>,
82    /// The position of the mouse cursor.
83    position: dpi::PhysicalPosition<f64>,
84  },
85  /// A drag operation is moving over the webview.
86  Over {
87    /// The position of the mouse cursor.
88    position: dpi::PhysicalPosition<f64>,
89  },
90  /// The file(s) have been dropped onto the webview.
91  Drop {
92    /// List of paths that are being dropped onto the window.
93    paths: Vec<PathBuf>,
94    /// The position of the mouse cursor.
95    position: dpi::PhysicalPosition<f64>,
96  },
97  /// The drag operation has been cancelled or left the window.
98  Leave,
99}
100
101/// Describes the appearance of the mouse cursor.
102#[non_exhaustive]
103#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Hash)]
104pub enum CursorIcon {
105  /// The platform-dependent default cursor.
106  #[default]
107  Default,
108  /// A simple crosshair.
109  Crosshair,
110  /// A hand (often used to indicate links in web browsers).
111  Hand,
112  /// Self explanatory.
113  Arrow,
114  /// Indicates something is to be moved.
115  Move,
116  /// Indicates text that may be selected or edited.
117  Text,
118  /// Program busy indicator.
119  Wait,
120  /// Help indicator (often rendered as a "?")
121  Help,
122  /// Progress indicator. Shows that processing is being done. But in contrast
123  /// with "Wait" the user may still interact with the program. Often rendered
124  /// as a spinning beach ball, or an arrow with a watch or hourglass.
125  Progress,
126
127  /// Cursor showing that something cannot be done.
128  NotAllowed,
129  ContextMenu,
130  Cell,
131  VerticalText,
132  Alias,
133  Copy,
134  NoDrop,
135  /// Indicates something can be grabbed.
136  Grab,
137  /// Indicates something is grabbed.
138  Grabbing,
139  AllScroll,
140  ZoomIn,
141  ZoomOut,
142
143  /// Indicate that some edge is to be moved. For example, the 'SeResize' cursor
144  /// is used when the movement starts from the south-east corner of the box.
145  EResize,
146  NResize,
147  NeResize,
148  NwResize,
149  SResize,
150  SeResize,
151  SwResize,
152  WResize,
153  EwResize,
154  NsResize,
155  NeswResize,
156  NwseResize,
157  ColResize,
158  RowResize,
159}
160
161impl<'de> Deserialize<'de> for CursorIcon {
162  fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
163  where
164    D: Deserializer<'de>,
165  {
166    let s = String::deserialize(deserializer)?;
167    Ok(match s.to_lowercase().as_str() {
168      "default" => CursorIcon::Default,
169      "crosshair" => CursorIcon::Crosshair,
170      "hand" => CursorIcon::Hand,
171      "arrow" => CursorIcon::Arrow,
172      "move" => CursorIcon::Move,
173      "text" => CursorIcon::Text,
174      "wait" => CursorIcon::Wait,
175      "help" => CursorIcon::Help,
176      "progress" => CursorIcon::Progress,
177      "notallowed" => CursorIcon::NotAllowed,
178      "contextmenu" => CursorIcon::ContextMenu,
179      "cell" => CursorIcon::Cell,
180      "verticaltext" => CursorIcon::VerticalText,
181      "alias" => CursorIcon::Alias,
182      "copy" => CursorIcon::Copy,
183      "nodrop" => CursorIcon::NoDrop,
184      "grab" => CursorIcon::Grab,
185      "grabbing" => CursorIcon::Grabbing,
186      "allscroll" => CursorIcon::AllScroll,
187      "zoomin" => CursorIcon::ZoomIn,
188      "zoomout" => CursorIcon::ZoomOut,
189      "eresize" => CursorIcon::EResize,
190      "nresize" => CursorIcon::NResize,
191      "neresize" => CursorIcon::NeResize,
192      "nwresize" => CursorIcon::NwResize,
193      "sresize" => CursorIcon::SResize,
194      "seresize" => CursorIcon::SeResize,
195      "swresize" => CursorIcon::SwResize,
196      "wresize" => CursorIcon::WResize,
197      "ewresize" => CursorIcon::EwResize,
198      "nsresize" => CursorIcon::NsResize,
199      "neswresize" => CursorIcon::NeswResize,
200      "nwseresize" => CursorIcon::NwseResize,
201      "colresize" => CursorIcon::ColResize,
202      "rowresize" => CursorIcon::RowResize,
203      _ => CursorIcon::Default,
204    })
205  }
206}
207
208/// Window size constraints
209#[derive(Clone, Copy, PartialEq, Debug, Default, Serialize, Deserialize)]
210#[serde(rename_all = "camelCase")]
211pub struct WindowSizeConstraints {
212  /// The minimum width a window can be, If this is `None`, the window will have no minimum width.
213  ///
214  /// The default is `None`.
215  pub min_width: Option<PixelUnit>,
216  /// The minimum height a window can be, If this is `None`, the window will have no minimum height.
217  ///
218  /// The default is `None`.
219  pub min_height: Option<PixelUnit>,
220  /// The maximum width a window can be, If this is `None`, the window will have no maximum width.
221  ///
222  /// The default is `None`.
223  pub max_width: Option<PixelUnit>,
224  /// The maximum height a window can be, If this is `None`, the window will have no maximum height.
225  ///
226  /// The default is `None`.
227  pub max_height: Option<PixelUnit>,
228}
229
230/// Do **NOT** implement this trait except for use in a custom [`Runtime`]
231///
232/// This trait is separate from [`WindowBuilder`] to prevent "accidental" implementation.
233pub trait WindowBuilderBase: std::fmt::Debug + Clone + Sized {}
234
235/// A builder for all attributes related to a single window.
236///
237/// This trait is only meant to be implemented by a custom [`Runtime`]
238/// and not by applications.
239pub trait WindowBuilder: WindowBuilderBase {
240  /// Initializes a new window attributes builder.
241  fn new() -> Self;
242
243  /// Initializes a new window builder from a [`WindowConfig`]
244  fn with_config(config: &WindowConfig) -> Self;
245
246  /// Show window in the center of the screen.
247  #[must_use]
248  fn center(self) -> Self;
249
250  /// The initial position of the window's.
251  #[must_use]
252  fn position(self, x: f64, y: f64) -> Self;
253
254  /// Window size.
255  #[must_use]
256  fn inner_size(self, width: f64, height: f64) -> Self;
257
258  /// Window min inner size.
259  #[must_use]
260  fn min_inner_size(self, min_width: f64, min_height: f64) -> Self;
261
262  /// Window max inner size.
263  #[must_use]
264  fn max_inner_size(self, max_width: f64, max_height: f64) -> Self;
265
266  /// Window inner size constraints.
267  #[must_use]
268  fn inner_size_constraints(self, constraints: WindowSizeConstraints) -> Self;
269
270  /// Whether the window is resizable or not.
271  /// When resizable is set to false, native window's maximize button is automatically disabled.
272  #[must_use]
273  fn resizable(self, resizable: bool) -> Self;
274
275  /// Whether the window's native maximize button is enabled or not.
276  /// If resizable is set to false, this setting is ignored.
277  ///
278  /// ## Platform-specific
279  ///
280  /// - **macOS:** Disables the "zoom" button in the window titlebar, which is also used to enter fullscreen mode.
281  /// - **Linux / iOS / Android:** Unsupported.
282  #[must_use]
283  fn maximizable(self, maximizable: bool) -> Self;
284
285  /// Whether the window's native minimize button is enabled or not.
286  ///
287  /// ## Platform-specific
288  ///
289  /// - **Linux / iOS / Android:** Unsupported.
290  #[must_use]
291  fn minimizable(self, minimizable: bool) -> Self;
292
293  /// Whether the window's native close button is enabled or not.
294  ///
295  /// ## Platform-specific
296  ///
297  /// - **Linux:** "GTK+ will do its best to convince the window manager not to show a close button.
298  ///   Depending on the system, this function may not have any effect when called on a window that is already visible"
299  /// - **iOS / Android:** Unsupported.
300  #[must_use]
301  fn closable(self, closable: bool) -> Self;
302
303  /// The title of the window in the title bar.
304  #[must_use]
305  fn title<S: Into<String>>(self, title: S) -> Self;
306
307  /// Whether to start the window in fullscreen or not.
308  #[must_use]
309  fn fullscreen(self, fullscreen: bool) -> Self;
310
311  /// Whether the window will be initially focused or not.
312  #[must_use]
313  fn focused(self, focused: bool) -> Self;
314
315  /// Whether the window should be maximized upon creation.
316  #[must_use]
317  fn maximized(self, maximized: bool) -> Self;
318
319  /// Whether the window should be immediately visible upon creation.
320  #[must_use]
321  fn visible(self, visible: bool) -> Self;
322
323  /// Whether the window should be transparent. If this is true, writing colors
324  /// with alpha values different than `1.0` will produce a transparent window.
325  #[cfg(any(not(target_os = "macos"), feature = "macos-private-api"))]
326  #[cfg_attr(
327    docsrs,
328    doc(cfg(any(not(target_os = "macos"), feature = "macos-private-api")))
329  )]
330  #[must_use]
331  fn transparent(self, transparent: bool) -> Self;
332
333  /// Whether the window should have borders and bars.
334  #[must_use]
335  fn decorations(self, decorations: bool) -> Self;
336
337  /// Whether the window should always be below other windows.
338  #[must_use]
339  fn always_on_bottom(self, always_on_bottom: bool) -> Self;
340
341  /// Whether the window should always be on top of other windows.
342  #[must_use]
343  fn always_on_top(self, always_on_top: bool) -> Self;
344
345  /// Whether the window should be visible on all workspaces or virtual desktops.
346  #[must_use]
347  fn visible_on_all_workspaces(self, visible_on_all_workspaces: bool) -> Self;
348
349  /// Prevents the window contents from being captured by other apps.
350  #[must_use]
351  fn content_protected(self, protected: bool) -> Self;
352
353  /// Sets the window icon.
354  fn icon(self, icon: Icon) -> crate::Result<Self>;
355
356  /// Sets whether or not the window icon should be added to the taskbar.
357  #[must_use]
358  fn skip_taskbar(self, skip: bool) -> Self;
359
360  /// Set the window background color.
361  #[must_use]
362  fn background_color(self, color: Color) -> Self;
363
364  /// Sets whether or not the window has shadow.
365  ///
366  /// ## Platform-specific
367  ///
368  /// - **Windows:**
369  ///   - `false` has no effect on decorated window, shadows are always ON.
370  ///   - `true` will make undecorated window have a 1px white border,
371  ///     and on Windows 11, it will have a rounded corners.
372  /// - **Linux:** Unsupported.
373  #[must_use]
374  fn shadow(self, enable: bool) -> Self;
375
376  /// Set an owner to the window to be created.
377  ///
378  /// From MSDN:
379  /// - An owned window is always above its owner in the z-order.
380  /// - The system automatically destroys an owned window when its owner is destroyed.
381  /// - An owned window is hidden when its owner is minimized.
382  ///
383  /// For more information, see <https://docs.microsoft.com/en-us/windows/win32/winmsg/window-features#owned-windows>
384  #[cfg(windows)]
385  #[must_use]
386  fn owner(self, owner: HWND) -> Self;
387
388  /// Sets a parent to the window to be created.
389  ///
390  /// A child window has the WS_CHILD style and is confined to the client area of its parent window.
391  ///
392  /// For more information, see <https://docs.microsoft.com/en-us/windows/win32/winmsg/window-features#child-windows>
393  #[cfg(windows)]
394  #[must_use]
395  fn parent(self, parent: HWND) -> Self;
396
397  /// Sets a parent to the window to be created.
398  ///
399  /// See <https://developer.apple.com/documentation/appkit/nswindow/1419152-addchildwindow?language=objc>
400  #[cfg(target_os = "macos")]
401  #[must_use]
402  fn parent(self, parent: *mut std::ffi::c_void) -> Self;
403
404  /// Sets the window to be created transient for parent.
405  ///
406  /// See <https://docs.gtk.org/gtk3/method.Window.set_transient_for.html>
407  #[cfg(any(
408    target_os = "linux",
409    target_os = "dragonfly",
410    target_os = "freebsd",
411    target_os = "netbsd",
412    target_os = "openbsd"
413  ))]
414  fn transient_for(self, parent: &impl gtk::glib::IsA<gtk::Window>) -> Self;
415
416  /// Enables or disables drag and drop support.
417  #[cfg(windows)]
418  #[must_use]
419  fn drag_and_drop(self, enabled: bool) -> Self;
420
421  /// Hide the titlebar. Titlebar buttons will still be visible.
422  #[cfg(target_os = "macos")]
423  #[must_use]
424  fn title_bar_style(self, style: tauri_utils::TitleBarStyle) -> Self;
425
426  /// Hide the window title.
427  #[cfg(target_os = "macos")]
428  #[must_use]
429  fn hidden_title(self, hidden: bool) -> Self;
430
431  /// Defines the window [tabbing identifier] for macOS.
432  ///
433  /// Windows with matching tabbing identifiers will be grouped together.
434  /// If the tabbing identifier is not set, automatic tabbing will be disabled.
435  ///
436  /// [tabbing identifier]: <https://developer.apple.com/documentation/appkit/nswindow/1644704-tabbingidentifier>
437  #[cfg(target_os = "macos")]
438  #[must_use]
439  fn tabbing_identifier(self, identifier: &str) -> Self;
440
441  /// Forces a theme or uses the system settings if None was provided.
442  fn theme(self, theme: Option<Theme>) -> Self;
443
444  /// Whether the icon was set or not.
445  fn has_icon(&self) -> bool;
446
447  fn get_theme(&self) -> Option<Theme>;
448
449  /// Sets custom name for Windows' window class. **Windows only**.
450  #[must_use]
451  fn window_classname<S: Into<String>>(self, window_classname: S) -> Self;
452}
453
454/// A window that has yet to be built.
455pub struct PendingWindow<T: UserEvent, R: Runtime<T>> {
456  /// The label that the window will be named.
457  pub label: String,
458
459  /// The [`WindowBuilder`] that the window will be created with.
460  pub window_builder: <R::WindowDispatcher as WindowDispatch<T>>::WindowBuilder,
461
462  /// The webview that gets added to the window. Optional in case you want to use child webviews or other window content instead.
463  pub webview: Option<PendingWebview<T, R>>,
464}
465
466pub fn is_label_valid(label: &str) -> bool {
467  label
468    .chars()
469    .all(|c| char::is_alphanumeric(c) || c == '-' || c == '/' || c == ':' || c == '_')
470}
471
472pub fn assert_label_is_valid(label: &str) {
473  assert!(
474    is_label_valid(label),
475    "Window label must include only alphanumeric characters, `-`, `/`, `:` and `_`."
476  );
477}
478
479impl<T: UserEvent, R: Runtime<T>> PendingWindow<T, R> {
480  /// Create a new [`PendingWindow`] with a label from the given [`WindowBuilder`].
481  pub fn new(
482    window_builder: <R::WindowDispatcher as WindowDispatch<T>>::WindowBuilder,
483    label: impl Into<String>,
484  ) -> crate::Result<Self> {
485    let label = label.into();
486    if !is_label_valid(&label) {
487      Err(crate::Error::InvalidWindowLabel)
488    } else {
489      Ok(Self {
490        window_builder,
491        label,
492        webview: None,
493      })
494    }
495  }
496
497  /// Sets a webview to be created on the window.
498  pub fn set_webview(&mut self, webview: PendingWebview<T, R>) -> &mut Self {
499    self.webview.replace(webview);
500    self
501  }
502}
503
504/// Identifier of a window.
505#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, Ord, PartialOrd)]
506pub struct WindowId(u32);
507
508impl From<u32> for WindowId {
509  fn from(value: u32) -> Self {
510    Self(value)
511  }
512}
513
514/// A window that is not yet managed by Tauri.
515#[derive(Debug)]
516pub struct DetachedWindow<T: UserEvent, R: Runtime<T>> {
517  /// The identifier of the window.
518  pub id: WindowId,
519  /// Name of the window
520  pub label: String,
521
522  /// The [`WindowDispatch`] associated with the window.
523  pub dispatcher: R::WindowDispatcher,
524
525  /// The webview dispatcher in case this window has an attached webview.
526  pub webview: Option<DetachedWindowWebview<T, R>>,
527}
528
529/// A detached webview associated with a window.
530#[derive(Debug)]
531pub struct DetachedWindowWebview<T: UserEvent, R: Runtime<T>> {
532  pub webview: DetachedWebview<T, R>,
533  pub use_https_scheme: bool,
534}
535
536impl<T: UserEvent, R: Runtime<T>> Clone for DetachedWindowWebview<T, R> {
537  fn clone(&self) -> Self {
538    Self {
539      webview: self.webview.clone(),
540      use_https_scheme: self.use_https_scheme,
541    }
542  }
543}
544
545impl<T: UserEvent, R: Runtime<T>> Clone for DetachedWindow<T, R> {
546  fn clone(&self) -> Self {
547    Self {
548      id: self.id,
549      label: self.label.clone(),
550      dispatcher: self.dispatcher.clone(),
551      webview: self.webview.clone(),
552    }
553  }
554}
555
556impl<T: UserEvent, R: Runtime<T>> Hash for DetachedWindow<T, R> {
557  /// Only use the [`DetachedWindow`]'s label to represent its hash.
558  fn hash<H: Hasher>(&self, state: &mut H) {
559    self.label.hash(state)
560  }
561}
562
563impl<T: UserEvent, R: Runtime<T>> Eq for DetachedWindow<T, R> {}
564impl<T: UserEvent, R: Runtime<T>> PartialEq for DetachedWindow<T, R> {
565  /// Only use the [`DetachedWindow`]'s label to compare equality.
566  fn eq(&self, other: &Self) -> bool {
567    self.label.eq(&other.label)
568  }
569}
570
571/// A raw window type that contains fields to access
572/// the HWND on Windows, gtk::ApplicationWindow on Linux and
573/// NSView on macOS.
574pub struct RawWindow<'a> {
575  #[cfg(windows)]
576  pub hwnd: isize,
577  #[cfg(any(
578    target_os = "linux",
579    target_os = "dragonfly",
580    target_os = "freebsd",
581    target_os = "netbsd",
582    target_os = "openbsd"
583  ))]
584  pub gtk_window: &'a gtk::ApplicationWindow,
585  #[cfg(any(
586    target_os = "linux",
587    target_os = "dragonfly",
588    target_os = "freebsd",
589    target_os = "netbsd",
590    target_os = "openbsd"
591  ))]
592  pub default_vbox: Option<&'a gtk::Box>,
593  pub _marker: &'a PhantomData<()>,
594}
tauri_runtime/window.rs

tauri_runtime/
window.rs
