monitor: refactor MonitorHandle to store dyn object

This also alters `VideoMode` to be a regular object and not reference
the `MonitorHandle`, since it's a static data.

Given that `VideoMode` set may change during runtime keeping the
reference as a some sort of validity may not be idea and propagating
errors when changing video mode could be more reliable.

examples/window.rs

@@ -21,6 +21,7 @@ use winit::error::RequestError;
 use winit::event::{DeviceEvent, DeviceId, Ime, MouseButton, MouseScrollDelta, WindowEvent};
 use winit::event_loop::{ActiveEventLoop, EventLoop};
 use winit::keyboard::{Key, ModifiersState};
+use winit::monitor::Fullscreen;
 #[cfg(macos_platform)]
 use winit::platform::macos::{
     ApplicationHandlerExtMacOS, OptionAsAlt, WindowAttributesExtMacOS, WindowExtMacOS,
@@ -34,8 +35,8 @@ use winit::platform::web::{ActiveEventLoopExtWeb, CustomCursorExtWeb, WindowAttr
 #[cfg(x11_platform)]
 use winit::platform::x11::WindowAttributesExtX11;
 use winit::window::{
-    Cursor, CursorGrabMode, CustomCursor, CustomCursorSource, Fullscreen, Icon, ResizeDirection,
-    Theme, Window, WindowAttributes, WindowId,
+    Cursor, CursorGrabMode, CustomCursor, CustomCursorSource, Icon, ResizeDirection, Theme, Window,
+    WindowAttributes, WindowId,
 };
 
 #[path = "util/tracing.rs"]

src/application.rs

@@ -2,7 +2,7 @@
 
 use crate::event::{DeviceEvent, DeviceId, StartCause, WindowEvent};
 use crate::event_loop::ActiveEventLoop;
-#[cfg(any(docsrs, macos_platform))]
+#[cfg(macos_platform)]
 use crate::platform::macos::ApplicationHandlerExtMacOS;
 use crate::window::WindowId;
 
@@ -349,7 +349,7 @@ pub trait ApplicationHandler {
     /// The macOS-specific handler.
     ///
     /// The return value from this should not change at runtime.
-    #[cfg(any(docsrs, macos_platform))]
+    #[cfg(macos_platform)]
     #[inline(always)]
     fn macos_handler(&mut self) -> Option<&mut dyn ApplicationHandlerExtMacOS> {
         None
@@ -423,7 +423,7 @@ impl<A: ?Sized + ApplicationHandler> ApplicationHandler for &mut A {
         (**self).memory_warning(event_loop);
     }
 
-    #[cfg(any(docsrs, macos_platform))]
+    #[cfg(macos_platform)]
     #[inline]
     fn macos_handler(&mut self) -> Option<&mut dyn ApplicationHandlerExtMacOS> {
         (**self).macos_handler()
@@ -497,7 +497,7 @@ impl<A: ?Sized + ApplicationHandler> ApplicationHandler for Box<A> {
         (**self).memory_warning(event_loop);
     }
 
-    #[cfg(any(docsrs, macos_platform))]
+    #[cfg(macos_platform)]
     #[inline]
     fn macos_handler(&mut self) -> Option<&mut dyn ApplicationHandlerExtMacOS> {
         (**self).macos_handler()

src/changelog/unreleased.md

@@ -158,6 +158,8 @@ changelog entry.
   - In the same spirit rename `DeviceEvent::MouseMotion` to `PointerMotion`.
   - Remove `Force::Calibrated::altitude_angle`.
   - On X11, use bottom-right corner for IME hotspot in `Window::set_ime_cursor_area`.
+- `VideoModeHandle` to `VideoMode` which stores plain data.
+- `Fullscreen::Exclusive` to take `(MonitorHandle, VideoMode)`.
 
 ### Removed
 

src/event_loop.rs

@@ -209,10 +209,10 @@ impl EventLoop {
     ///
     ///   Web applications are recommended to use
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "  [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]"
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "  `EventLoopExtWeb::spawn_app()`")]
+    #[cfg_attr(not(web_platform), doc = "  `EventLoopExtWeb::spawn_app()`")]
     ///   [^1] instead of [`run_app()`] to avoid the need for the Javascript exception trick, and to
     ///   make   it clearer that the event loop runs asynchronously (via the browser's own,
     ///   internal, event   loop) and doesn't block the current thread of execution like it does
@@ -343,10 +343,10 @@ pub trait ActiveEventLoop: AsAny {
     ///
     /// **Web:** Only returns the current monitor without
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "detailed monitor permissions.")]
+    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
     fn available_monitors(&self) -> Box<dyn Iterator<Item = MonitorHandle>>;
 
     /// Returns the primary monitor of the system.
@@ -358,10 +358,10 @@ pub trait ActiveEventLoop: AsAny {
     /// - **Wayland:** Always returns `None`.
     /// - **Web:** Always returns `None` without
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "  detailed monitor permissions.")]
+    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions.")]
     fn primary_monitor(&self) -> Option<MonitorHandle>;
 
     /// Change if or when [`DeviceEvent`]s are captured.

src/monitor.rs

@@ -5,90 +5,14 @@
 //! methods, which return an iterator of [`MonitorHandle`]:
 //! - [`ActiveEventLoop::available_monitors`][crate::event_loop::ActiveEventLoop::available_monitors].
 //! - [`Window::available_monitors`][crate::window::Window::available_monitors].
+use std::borrow::Cow;
+use std::fmt;
 use std::num::{NonZeroU16, NonZeroU32};
+use std::ops::Deref;
+use std::sync::Arc;
 
 use crate::dpi::{PhysicalPosition, PhysicalSize};
-use crate::platform_impl;
-
-/// Describes a fullscreen video mode of a monitor.
-///
-/// Can be acquired with [`MonitorHandle::video_modes`].
-#[derive(Clone, PartialEq, Eq, Hash)]
-pub struct VideoModeHandle {
-    pub(crate) video_mode: platform_impl::VideoModeHandle,
-}
-
-impl std::fmt::Debug for VideoModeHandle {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        self.video_mode.fmt(f)
-    }
-}
-
-impl PartialOrd for VideoModeHandle {
-    fn partial_cmp(&self, other: &VideoModeHandle) -> Option<std::cmp::Ordering> {
-        Some(self.cmp(other))
-    }
-}
-
-impl Ord for VideoModeHandle {
-    fn cmp(&self, other: &VideoModeHandle) -> std::cmp::Ordering {
-        self.monitor().cmp(&other.monitor()).then(
-            self.size()
-                .cmp(&other.size())
-                .then(
-                    self.refresh_rate_millihertz()
-                        .cmp(&other.refresh_rate_millihertz())
-                        .then(self.bit_depth().cmp(&other.bit_depth())),
-                )
-                .reverse(),
-        )
-    }
-}
-
-impl VideoModeHandle {
-    /// Returns the resolution of this video mode. This **must not** be used to create your
-    /// rendering surface. Use [`Window::surface_size()`] instead.
-    ///
-    /// [`Window::surface_size()`]: crate::window::Window::surface_size
-    #[inline]
-    pub fn size(&self) -> PhysicalSize<u32> {
-        self.video_mode.size()
-    }
-
-    /// Returns the bit depth of this video mode, as in how many bits you have
-    /// available per color. This is generally 24 bits or 32 bits on modern
-    /// systems, depending on whether the alpha channel is counted or not.
-    #[inline]
-    pub fn bit_depth(&self) -> Option<NonZeroU16> {
-        self.video_mode.bit_depth()
-    }
-
-    /// Returns the refresh rate of this video mode in mHz.
-    #[inline]
-    pub fn refresh_rate_millihertz(&self) -> Option<NonZeroU32> {
-        self.video_mode.refresh_rate_millihertz()
-    }
-
-    /// Returns the monitor that this video mode is valid for. Each monitor has
-    /// a separate set of valid video modes.
-    #[inline]
-    pub fn monitor(&self) -> MonitorHandle {
-        MonitorHandle { inner: self.video_mode.monitor() }
-    }
-}
-
-impl std::fmt::Display for VideoModeHandle {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(
-            f,
-            "{}x{} {}{}",
-            self.size().width,
-            self.size().height,
-            self.refresh_rate_millihertz().map(|rate| format!("@ {rate} mHz ")).unwrap_or_default(),
-            self.bit_depth().map(|bit_depth| format!("({bit_depth} bpp)")).unwrap_or_default(),
-        )
-    }
-}
+use crate::utils::AsAny;
 
 /// Handle to a monitor.
 ///
@@ -98,48 +22,57 @@ impl std::fmt::Display for VideoModeHandle {
 ///
 /// **Web:** A [`MonitorHandle`] created without
 #[cfg_attr(
-    any(web_platform, docsrs),
+    web_platform,
     doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
 )]
-#[cfg_attr(not(any(web_platform, docsrs)), doc = "detailed monitor permissions.")]
+#[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
 /// will always represent the current monitor the browser window is in instead of a specific
 /// monitor. See
 #[cfg_attr(
-    any(web_platform, docsrs),
+    web_platform,
     doc = "[`MonitorHandleExtWeb::is_detailed()`][crate::platform::web::MonitorHandleExtWeb::is_detailed]"
 )]
-#[cfg_attr(not(any(web_platform, docsrs)), doc = "`MonitorHandleExtWeb::is_detailed()`")]
+#[cfg_attr(not(web_platform), doc = "`MonitorHandleExtWeb::is_detailed()`")]
 /// to check.
 ///
 /// [`Window`]: crate::window::Window
-#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
-pub struct MonitorHandle {
-    pub(crate) inner: platform_impl::MonitorHandle,
+#[derive(Debug, Clone)]
+pub struct MonitorHandle(pub(crate) Arc<dyn MonitorHandleProvider>);
+
+impl Deref for MonitorHandle {
+    type Target = dyn MonitorHandleProvider;
+
+    fn deref(&self) -> &Self::Target {
+        self.0.as_ref()
+    }
 }
 
-impl std::fmt::Debug for MonitorHandle {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        self.inner.fmt(f)
+impl PartialEq for MonitorHandle {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.as_ref().eq(other.0.as_ref())
     }
 }
 
-impl MonitorHandle {
+impl Eq for MonitorHandle {}
+
+/// Provider of the [`MonitorHandle`].
+pub trait MonitorHandleProvider: AsAny + fmt::Debug + Send + Sync {
+    /// Native platform identifier of this monitor.
+    fn native_id(&self) -> u64;
+
     /// Returns a human-readable name of the monitor.
     ///
-    /// Returns `None` if the monitor doesn't exist anymore.
+    /// Returns `None` if the monitor doesn't exist anymore or the name couldn't be obtained.
     ///
     /// ## Platform-specific
     ///
     /// **Web:** Always returns [`None`] without
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "detailed monitor permissions.")]
-    #[inline]
-    pub fn name(&self) -> Option<String> {
-        self.inner.name()
-    }
+    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
+    fn name(&self) -> Option<Cow<'_, str>>;
 
     /// Returns the top-left corner position of the monitor relative to the larger full
     /// screen area.
@@ -148,14 +81,11 @@ impl MonitorHandle {
     ///
     /// **Web:** Always returns [`None`] without
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "detailed monitor permissions.")]
-    #[inline]
-    pub fn position(&self) -> Option<PhysicalPosition<i32>> {
-        self.inner.position()
-    }
+    #[cfg_attr(not(web_platform), doc = "detailed monitor permissions.")]
+    fn position(&self) -> Option<PhysicalPosition<i32>>;
 
     /// Returns the scale factor of the underlying monitor. To map logical pixels to physical
     /// pixels and vice versa, use [`Window::scale_factor`].
@@ -169,27 +99,80 @@ impl MonitorHandle {
     /// - **Android:** Always returns 1.0.
     /// - **Web:** Always returns `0.0` without
     #[cfg_attr(
-        any(web_platform, docsrs),
+        web_platform,
         doc = "  [detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
     )]
-    #[cfg_attr(not(any(web_platform, docsrs)), doc = "  detailed monitor permissions.")]
+    #[cfg_attr(not(web_platform), doc = "  detailed monitor permissions.")]
     ///
     #[rustfmt::skip]
     /// [`Window::scale_factor`]: crate::window::Window::scale_factor
-    #[inline]
-    pub fn scale_factor(&self) -> f64 {
-        self.inner.scale_factor()
-    }
+    fn scale_factor(&self) -> f64;
 
     /// Returns the currently active video mode of this monitor.
-    #[inline]
-    pub fn current_video_mode(&self) -> Option<VideoModeHandle> {
-        self.inner.current_video_mode().map(|video_mode| VideoModeHandle { video_mode })
-    }
+    fn current_video_mode(&self) -> Option<VideoMode>;
 
     /// Returns all fullscreen video modes supported by this monitor.
-    #[inline]
-    pub fn video_modes(&self) -> impl Iterator<Item = VideoModeHandle> {
-        self.inner.video_modes().map(|video_mode| VideoModeHandle { video_mode })
+    fn video_modes(&self) -> Box<dyn Iterator<Item = VideoMode>>;
+}
+
+impl PartialEq for dyn MonitorHandleProvider + '_ {
+    fn eq(&self, other: &Self) -> bool {
+        self.native_id() == other.native_id()
+    }
+}
+
+impl Eq for dyn MonitorHandleProvider + '_ {}
+
+/// Describes a fullscreen video mode of a monitor.
+///
+/// Can be acquired with [`MonitorHandleProvider::video_modes`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct VideoMode {
+    pub(crate) size: PhysicalSize<u32>,
+    pub(crate) bit_depth: Option<NonZeroU16>,
+    pub(crate) refresh_rate_millihertz: Option<NonZeroU32>,
+}
+
+impl VideoMode {
+    /// Returns the resolution of this video mode. This **must not** be used to create your
+    /// rendering surface. Use [`Window::surface_size()`] instead.
+    ///
+    /// [`Window::surface_size()`]: crate::window::Window::surface_size
+    pub fn size(&self) -> PhysicalSize<u32> {
+        self.size
+    }
+
+    /// Returns the bit depth of this video mode, as in how many bits you have
+    /// available per color. This is generally 24 bits or 32 bits on modern
+    /// systems, depending on whether the alpha channel is counted or not.
+    pub fn bit_depth(&self) -> Option<NonZeroU16> {
+        self.bit_depth
+    }
+
+    /// Returns the refresh rate of this video mode in mHz.
+    pub fn refresh_rate_millihertz(&self) -> Option<NonZeroU32> {
+        self.refresh_rate_millihertz
     }
 }
+
+impl fmt::Display for VideoMode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}x{} {}{}",
+            self.size.width,
+            self.size.height,
+            self.refresh_rate_millihertz.map(|rate| format!("@ {rate} mHz ")).unwrap_or_default(),
+            self.bit_depth.map(|bit_depth| format!("({bit_depth} bpp)")).unwrap_or_default(),
+        )
+    }
+}
+
+/// Fullscreen modes.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Fullscreen {
+    Exclusive(MonitorHandle, VideoMode),
+
+    /// Providing `None` to `Borderless` will fullscreen on the current monitor.
+    Borderless(Option<MonitorHandle>),
+}