Replace Window::safe_area with Window::insets

examples/window.rs

@@ -33,6 +33,8 @@ use winit::platform::startup_notify::{
 use winit::platform::web::{ActiveEventLoopExtWeb, CustomCursorExtWeb, WindowAttributesExtWeb};
 #[cfg(x11_platform)]
 use winit::platform::x11::WindowAttributesExtX11;
+#[cfg(not(android_platform))]
+use winit::window::InsetKind;
 use winit::window::{
     Cursor, CursorGrabMode, CustomCursor, CustomCursorSource, Fullscreen, Icon, ResizeDirection,
     Theme, Window, WindowAttributes, WindowId,
@@ -949,7 +951,7 @@ impl WindowState {
 
         // Draw a different color inside the safe area
         let surface_size = self.window.surface_size();
-        let insets = self.window.safe_area();
+        let insets = self.window.insets(InsetKind::SafeArea);
         for y in 0..surface_size.height {
             for x in 0..surface_size.width {
                 let index = y as usize * surface_size.width as usize + x as usize;

src/changelog/unreleased.md

@@ -74,7 +74,8 @@ changelog entry.
 - On X11, the `window` example now understands the `X11_VISUAL_ID` and `X11_SCREEN_ID` env
   variables to test the respective modifiers of window creation.
 - Added `Window::surface_position`, which is the position of the surface inside the window.
-- Added `Window::safe_area`, which describes the area of the surface that is unobstructed.
+- Added `Window::insets`, which lets you read the distance from the edge of the window taken by a certain `InsetKind`.
+- Added `InsetKind::SafeArea`, used with `Window::insets`, which describes the area of the surface that is unobstructed.
 
 ### Changed
 

src/event.rs

@@ -480,7 +480,7 @@ pub enum WindowEvent {
     /// Winit will aggregate duplicate redraw requests into a single event, to
     /// help avoid duplicating rendering work.
     ///
-    /// [the safe area]: crate::window::Window::safe_area
+    /// [the safe area]: crate::window::InsetKind::SafeArea
     RedrawRequested,
 }
 

src/lib.rs

@@ -124,12 +124,14 @@
 //! the window visible only once you're ready to render into it.
 //!
 //! There is another important concept you need to know about when drawing: the "safe area". This
-//! can be accessed with [`Window::safe_area`], and describes a rectangle in the surface that is not
-//! obscured by notches, the status bar, and so on. You should be drawing your background and
-//! non-important content on the entire surface, but restrict important content (such as
-//! interactable UIs, text, etc.) to only being drawn inside the safe area.
-//!
-//! [`Window::safe_area`]: crate::window::Window::safe_area
+//! can be accessed by querying [`Window::insets`] with [`InsetKind::SafeArea`], and describes a
+//! rectangle in the surface that is not obscured by notches, the status bar, and so on. You should
+//! be drawing your background and non-important content on the entire surface, but restrict
+//! important content (such as interactable UIs, text, etc.) to only being drawn inside the safe
+//! area.
+//!
+//! [`Window::insets`]: crate::window::Window::insets
+//! [`InsetKind::SafeArea`]: crate::window::InsetKind::SafeArea
 //!
 //! # Coordinate systems
 //!

src/platform/macos.rs

@@ -94,7 +94,7 @@ pub trait WindowExtMacOS {
     /// space or taking control over the entire monitor.
     ///
     /// Make sure you only draw your important content inside the safe area so that it does not
-    /// overlap with the notch on newer devices, see [`Window::safe_area`] for details.
+    /// overlap with the notch on newer devices; see [`Window::insets`] for details.
     fn set_simple_fullscreen(&self, fullscreen: bool) -> bool;
 
     /// Returns whether or not the window has shadow.

src/platform_impl/android/mod.rs

@@ -24,7 +24,7 @@ use crate::event_loop::{
 use crate::monitor::MonitorHandle as RootMonitorHandle;
 use crate::platform::pump_events::PumpStatus;
 use crate::window::{
-    self, CursorGrabMode, CustomCursor, CustomCursorSource, Fullscreen, ImePurpose,
+    self, CursorGrabMode, CustomCursor, CustomCursorSource, Fullscreen, ImePurpose, InsetKind,
     ResizeDirection, Theme, Window as CoreWindow, WindowAttributes, WindowButtons, WindowId,
     WindowLevel,
 };
@@ -857,7 +857,7 @@ impl CoreWindow for Window {
         screen_size(&self.app)
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
+    fn insets(&self, _kind: InsetKind) -> PhysicalInsets<u32> {
         PhysicalInsets::new(0, 0, 0, 0)
     }
 

src/platform_impl/apple/appkit/window.rs

@@ -11,8 +11,8 @@ use super::window_delegate::WindowDelegate;
 use crate::error::RequestError;
 use crate::monitor::MonitorHandle as CoreMonitorHandle;
 use crate::window::{
-    Cursor, Fullscreen, Icon, ImePurpose, Theme, UserAttentionType, Window as CoreWindow,
-    WindowAttributes, WindowButtons, WindowId, WindowLevel,
+    Cursor, Fullscreen, Icon, ImePurpose, InsetKind, Theme, UserAttentionType,
+    Window as CoreWindow, WindowAttributes, WindowButtons, WindowId, WindowLevel,
 };
 
 pub(crate) struct Window {
@@ -131,8 +131,8 @@ impl CoreWindow for Window {
         self.maybe_wait_on_main(|delegate| delegate.outer_size())
     }
 
-    fn safe_area(&self) -> dpi::PhysicalInsets<u32> {
-        self.maybe_wait_on_main(|delegate| delegate.safe_area())
+    fn insets(&self, kind: InsetKind) -> dpi::PhysicalInsets<u32> {
+        self.maybe_wait_on_main(|delegate| delegate.insets(kind))
     }
 
     fn set_min_surface_size(&self, min_size: Option<Size>) {

src/platform_impl/apple/appkit/window_delegate.rs

@@ -43,7 +43,7 @@ use crate::error::{NotSupportedError, RequestError};
 use crate::event::{SurfaceSizeWriter, WindowEvent};
 use crate::platform::macos::{OptionAsAlt, WindowExtMacOS};
 use crate::window::{
-    Cursor, CursorGrabMode, Icon, ImePurpose, ResizeDirection, Theme, UserAttentionType,
+    Cursor, CursorGrabMode, Icon, ImePurpose, InsetKind, ResizeDirection, Theme, UserAttentionType,
     WindowAttributes, WindowButtons, WindowId, WindowLevel,
 };
 
@@ -983,7 +983,13 @@ impl WindowDelegate {
         logical.to_physical(self.scale_factor())
     }
 
-    pub fn safe_area(&self) -> PhysicalInsets<u32> {
+    pub fn insets(&self, kind: InsetKind) -> PhysicalInsets<u32> {
+        match kind {
+            InsetKind::SafeArea => self.safe_area(),
+        }
+    }
+
+    fn safe_area(&self) -> PhysicalInsets<u32> {
         // Only available on macOS 11.0
         let insets = if self.view().respondsToSelector(sel!(safeAreaInsets)) {
             // Includes NSWindowStyleMask::FullSizeContentView by default, and the notch because

src/platform_impl/apple/uikit/window.rs

@@ -28,8 +28,8 @@ use crate::icon::Icon;
 use crate::monitor::MonitorHandle as CoreMonitorHandle;
 use crate::platform::ios::{ScreenEdge, StatusBarStyle, ValidOrientations};
 use crate::window::{
-    CursorGrabMode, ImePurpose, ResizeDirection, Theme, UserAttentionType, Window as CoreWindow,
-    WindowAttributes, WindowButtons, WindowId, WindowLevel,
+    CursorGrabMode, ImePurpose, InsetKind, ResizeDirection, Theme, UserAttentionType,
+    Window as CoreWindow, WindowAttributes, WindowButtons, WindowId, WindowLevel,
 };
 
 declare_class!(
@@ -204,7 +204,13 @@ impl Inner {
         Some(self.surface_size())
     }
 
-    pub fn safe_area(&self) -> PhysicalInsets<u32> {
+    pub fn insets(&self, kind: InsetKind) -> PhysicalInsets<u32> {
+        match kind {
+            InsetKind::SafeArea => self.safe_area(),
+        }
+    }
+
+    fn safe_area(&self) -> PhysicalInsets<u32> {
         // Only available on iOS 11.0
         let insets = if app_state::os_capabilities().safe_area {
             self.view.safeAreaInsets()
@@ -627,8 +633,8 @@ impl CoreWindow for Window {
         self.maybe_wait_on_main(|delegate| delegate.outer_size())
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
-        self.maybe_wait_on_main(|delegate| delegate.safe_area())
+    fn insets(&self, kind: InsetKind) -> PhysicalInsets<u32> {
+        self.maybe_wait_on_main(|delegate| delegate.insets(kind))
     }
 
     fn set_min_surface_size(&self, min_size: Option<Size>) {

src/platform_impl/linux/wayland/window/mod.rs

@@ -24,8 +24,8 @@ use crate::event_loop::AsyncRequestSerial;
 use crate::monitor::MonitorHandle as CoreMonitorHandle;
 use crate::platform_impl::{Fullscreen, MonitorHandle as PlatformMonitorHandle};
 use crate::window::{
-    Cursor, CursorGrabMode, Fullscreen as CoreFullscreen, ImePurpose, ResizeDirection, Theme,
-    UserAttentionType, Window as CoreWindow, WindowAttributes, WindowButtons, WindowId,
+    Cursor, CursorGrabMode, Fullscreen as CoreFullscreen, ImePurpose, InsetKind, ResizeDirection,
+    Theme, UserAttentionType, Window as CoreWindow, WindowAttributes, WindowButtons, WindowId,
     WindowLevel,
 };
 
@@ -335,7 +335,7 @@ impl CoreWindow for Window {
         super::logical_to_physical_rounded(window_state.outer_size(), scale_factor)
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
+    fn insets(&self, _kind: InsetKind) -> PhysicalInsets<u32> {
         PhysicalInsets::new(0, 0, 0, 0)
     }
 

src/platform_impl/linux/x11/window.rs

@@ -35,8 +35,8 @@ use crate::platform_impl::{
     VideoModeHandle as PlatformVideoModeHandle,
 };
 use crate::window::{
-    CursorGrabMode, ImePurpose, ResizeDirection, Theme, UserAttentionType, Window as CoreWindow,
-    WindowAttributes, WindowButtons, WindowId, WindowLevel,
+    CursorGrabMode, ImePurpose, InsetKind, ResizeDirection, Theme, UserAttentionType,
+    Window as CoreWindow, WindowAttributes, WindowButtons, WindowId, WindowLevel,
 };
 
 pub(crate) struct Window(Arc<UnownedWindow>);
@@ -106,8 +106,8 @@ impl CoreWindow for Window {
         self.0.outer_size()
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
-        self.0.safe_area()
+    fn insets(&self, kind: InsetKind) -> PhysicalInsets<u32> {
+        self.0.insets(kind)
     }
 
     fn set_min_surface_size(&self, min_size: Option<Size>) {
@@ -1592,7 +1592,7 @@ impl UnownedWindow {
         }
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
+    fn insets(&self, _kind: InsetKind) -> PhysicalInsets<u32> {
         PhysicalInsets::new(0, 0, 0, 0)
     }
 

src/platform_impl/orbital/window.rs

@@ -7,7 +7,7 @@ use crate::cursor::Cursor;
 use crate::dpi::{PhysicalInsets, PhysicalPosition, PhysicalSize, Position, Size};
 use crate::error::{NotSupportedError, RequestError};
 use crate::monitor::MonitorHandle as CoreMonitorHandle;
-use crate::window::{self, Fullscreen, ImePurpose, Window as CoreWindow, WindowId};
+use crate::window::{self, Fullscreen, ImePurpose, InsetKind, Window as CoreWindow, WindowId};
 
 // These values match the values uses in the `window_new` function in orbital:
 // https://gitlab.redox-os.org/redox-os/orbital/-/blob/master/src/scheme.rs
@@ -239,7 +239,7 @@ impl CoreWindow for Window {
         self.surface_size()
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
+    fn insets(&self, _kind: InsetKind) -> PhysicalInsets<u32> {
         PhysicalInsets::new(0, 0, 0, 0)
     }
 

src/platform_impl/web/window.rs

@@ -14,8 +14,8 @@ use crate::error::{NotSupportedError, RequestError};
 use crate::icon::Icon;
 use crate::monitor::MonitorHandle as RootMonitorHandle;
 use crate::window::{
-    Cursor, CursorGrabMode, Fullscreen as RootFullscreen, ImePurpose, ResizeDirection, Theme,
-    UserAttentionType, Window as RootWindow, WindowAttributes, WindowButtons, WindowId,
+    Cursor, CursorGrabMode, Fullscreen as RootFullscreen, ImePurpose, InsetKind, ResizeDirection,
+    Theme, UserAttentionType, Window as RootWindow, WindowAttributes, WindowButtons, WindowId,
     WindowLevel,
 };
 
@@ -91,6 +91,34 @@ impl Window {
             lock::is_cursor_lock_raw(inner.canvas.navigator(), inner.canvas.document())
         })
     }
+
+    fn safe_area(&self) -> PhysicalInsets<u32> {
+        self.inner.queue(|inner| {
+            let (safe_start_pos, safe_size) = inner.safe_area.get();
+            let safe_end_pos = LogicalPosition::new(
+                safe_start_pos.x + safe_size.width,
+                safe_start_pos.y + safe_size.height,
+            );
+
+            let surface_start_pos = inner.canvas.position();
+            let surface_size = LogicalSize::new(
+                backend::style_size_property(inner.canvas.style(), "width"),
+                backend::style_size_property(inner.canvas.style(), "height"),
+            );
+            let surface_end_pos = LogicalPosition::new(
+                surface_start_pos.x + surface_size.width,
+                surface_start_pos.y + surface_size.height,
+            );
+
+            let top = f64::max(safe_start_pos.y - surface_start_pos.y, 0.);
+            let left = f64::max(safe_start_pos.x - surface_start_pos.x, 0.);
+            let bottom = f64::max(surface_end_pos.y - safe_end_pos.y, 0.);
+            let right = f64::max(surface_end_pos.x - safe_end_pos.x, 0.);
+
+            let insets = LogicalInsets::new(top, left, bottom, right);
+            insets.to_physical(inner.scale_factor())
+        })
+    }
 }
 
 impl RootWindow for Window {
@@ -155,32 +183,10 @@ impl RootWindow for Window {
         self.surface_size()
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
-        self.inner.queue(|inner| {
-            let (safe_start_pos, safe_size) = inner.safe_area.get();
-            let safe_end_pos = LogicalPosition::new(
-                safe_start_pos.x + safe_size.width,
-                safe_start_pos.y + safe_size.height,
-            );
-
-            let surface_start_pos = inner.canvas.position();
-            let surface_size = LogicalSize::new(
-                backend::style_size_property(inner.canvas.style(), "width"),
-                backend::style_size_property(inner.canvas.style(), "height"),
-            );
-            let surface_end_pos = LogicalPosition::new(
-                surface_start_pos.x + surface_size.width,
-                surface_start_pos.y + surface_size.height,
-            );
-
-            let top = f64::max(safe_start_pos.y - surface_start_pos.y, 0.);
-            let left = f64::max(safe_start_pos.x - surface_start_pos.x, 0.);
-            let bottom = f64::max(surface_end_pos.y - safe_end_pos.y, 0.);
-            let right = f64::max(surface_end_pos.x - safe_end_pos.x, 0.);
-
-            let insets = LogicalInsets::new(top, left, bottom, right);
-            insets.to_physical(inner.scale_factor())
-        })
+    fn insets(&self, kind: InsetKind) -> PhysicalInsets<u32> {
+        match kind {
+            InsetKind::SafeArea => self.safe_area(),
+        }
     }
 
     fn set_min_surface_size(&self, min_size: Option<Size>) {

src/platform_impl/windows/window.rs

@@ -68,7 +68,7 @@ use crate::platform_impl::platform::window_state::{
 };
 use crate::platform_impl::platform::{monitor, util, Fullscreen, SelectedCursor};
 use crate::window::{
-    CursorGrabMode, Fullscreen as CoreFullscreen, ImePurpose, ResizeDirection, Theme,
+    CursorGrabMode, Fullscreen as CoreFullscreen, ImePurpose, InsetKind, ResizeDirection, Theme,
     UserAttentionType, Window as CoreWindow, WindowAttributes, WindowButtons, WindowId,
     WindowLevel,
 };
@@ -494,7 +494,7 @@ impl CoreWindow for Window {
         None
     }
 
-    fn safe_area(&self) -> PhysicalInsets<u32> {
+    fn insets(&self, _kind: InsetKind) -> PhysicalInsets<u32> {
         PhysicalInsets::new(0, 0, 0, 0)
     }