Web: monitor API improvements (#3847)

- Improved the documentation to point users into the right direction from all kinds of methods and types.
- De-duplicated some code and added more comments.
- Implement an ID system to correctly and efficiently implement `Eq`, `Hash`, `Ord`, `PartialEq` and `PartialOrd`.
- Fixed screen locking support being cached thread local, ergo calling from a different thread would require to make the check again, not fulfilling its purpose as a fast-path at all.

src/monitor.rs

@@ -98,6 +98,23 @@ impl std::fmt::Display for VideoModeHandle {
 ///
 /// Allows you to retrieve information about a given monitor and can be used in [`Window`] creation.
 ///
+/// ## Platform-specific
+///
+/// **Web:** A [`MonitorHandle`] created without
+#[cfg_attr(
+ any(web_platform, docsrs),
+ doc = "[detailed monitor permissions][crate::platform::web::ActiveEventLoopExtWeb::request_detailed_monitor_permission]."
+)]
+#[cfg_attr(not(any(web_platform, docsrs)), 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),
+ doc = "[`MonitorHandleExtWeb::is_detailed()`][crate::platform::web::MonitorHandleExtWeb::is_detailed]"
+)]
+#[cfg_attr(not(any(web_platform, docsrs)), doc = "`MonitorHandleExtWeb::is_detailed()`")]
+/// to check.
+///
 /// [`Window`]: crate::window::Window
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct MonitorHandle {

src/platform/web.rs

@@ -226,19 +226,26 @@ pub trait EventLoopExtWeb {
  /// [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
  fn wait_until_strategy(&self) -> WaitUntilStrategy;
 
- /// Returns if the users device has multiple screens.
+ /// Returns if the users device has multiple screens. Useful to check before prompting the user
+ /// with [`EventLoopExtWeb::request_detailed_monitor_permission()`].
  ///
  /// Browsers might always return [`false`] to reduce fingerprinting.
  fn has_multiple_screens(&self) -> Result<bool, NotSupportedError>;
 
  /// Prompts the user for permission to query detailed information about available monitors. The
  /// returned [`MonitorPermissionFuture`] can be dropped without aborting the request.
  ///
+ /// Check [`EventLoopExtWeb::has_multiple_screens()`] before unnecessarily prompting the user
+ /// for such permissions.
+ ///
  /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
  /// [`MonitorHandle`]s have to be created instead.
  fn request_detailed_monitor_permission(&self) -> MonitorPermissionFuture;
 
  /// Returns whether the user has given permission to access detailed monitor information.
+ ///
+ /// [`MonitorHandle`]s don't automatically make use of detailed monitor information after
+ /// permission is granted. New [`MonitorHandle`]s have to be created instead.
  fn has_detailed_monitor_permission(&self) -> HasMonitorPermissionFuture;
 }
 
@@ -314,22 +321,26 @@ pub trait ActiveEventLoopExtWeb {
  /// [`CursorGrabMode::Locked`]: crate::window::CursorGrabMode::Locked
  fn is_cursor_lock_raw(&self) -> bool;
 
- /// Returns if the users device has multiple screens.
+ /// Returns if the users device has multiple screens. Useful to check before prompting the user
+ /// with [`EventLoopExtWeb::request_detailed_monitor_permission()`].
  ///
  /// Browsers might always return [`false`] to reduce fingerprinting.
  fn has_multiple_screens(&self) -> Result<bool, NotSupportedError>;
 
  /// Prompts the user for permission to query detailed information about available monitors. The
  /// returned [`MonitorPermissionFuture`] can be dropped without aborting the request.
  ///
+ /// Check [`EventLoopExtWeb::has_multiple_screens()`] before unnecessarily prompting the user
+ /// for such permissions.
+ ///
  /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
  /// [`MonitorHandle`]s have to be created instead.
  fn request_detailed_monitor_permission(&self) -> MonitorPermissionFuture;
 
  /// Returns whether the user has given permission to access detailed monitor information.
  ///
- /// [`MonitorHandle`]s don't automatically make use of this after permission is granted. New
- /// [`MonitorHandle`]s have to be created instead.
+ /// [`MonitorHandle`]s don't automatically make use of detailed monitor information after
+ /// permission is granted. New [`MonitorHandle`]s have to be created instead.
  fn has_detailed_monitor_permission(&self) -> bool;
 }
 
@@ -608,7 +619,9 @@ pub trait MonitorHandleExtWeb {
  /// Will fail if a locking call is in progress.
  fn unlock(&self) -> Result<(), OrientationLockError>;
 
- /// Returns whether this [`MonitorHandle`] was created using detailed monitor permissions.
+ /// Returns whether this [`MonitorHandle`] was created using detailed monitor permissions. If
+ /// [`false`] will always represent the current monitor the browser window is in instead of a
+ /// specific monitor.
  ///
  /// See [`ActiveEventLoop::request_detailed_monitor_permission()`].
  fn is_detailed(&self) -> bool;

src/platform_impl/web/event_loop/window_target.rs

@@ -652,7 +652,7 @@ impl ActiveEventLoop {
  }
 
  pub(crate) fn request_detailed_monitor_permission(&self) -> MonitorPermissionFuture {
- self.runner.monitor().request_detailed_monitor_permission(self.runner.weak())
+ self.runner.monitor().request_detailed_monitor_permission()
  }
 
  pub(crate) fn has_detailed_monitor_permission(&self) -> bool {