From db8de03142c3a36d9417a0a5f06f90b549123bfe Mon Sep 17 00:00:00 2001 From: daxpedda Date: Mon, 10 Jul 2023 12:50:28 +0200 Subject: [PATCH] Improve Web specific documentation for various APIs (#2941) Co-authored-by: Kirill Chibisov --- src/event.rs | 41 ++++++++++++++++++++++++++++++++++++++--- src/platform/web.rs | 22 ++++++++++++++++++++++ src/window.rs | 8 +++++--- 3 files changed, 65 insertions(+), 6 deletions(-) diff --git a/src/event.rs b/src/event.rs index 8d06cd7f..e419110a 100644 --- a/src/event.rs +++ b/src/event.rs @@ -84,7 +84,7 @@ pub enum Event<'a, T: 'static> { /// /// Not all platforms support the notion of suspending applications, and there may be no /// technical way to guarantee being able to emit a `Suspended` event if the OS has - /// no formal application lifecycle (currently only Android and iOS do). For this reason, + /// no formal application lifecycle (currently only Android, iOS, and Web do). For this reason, /// Winit does not currently try to emit pseudo `Suspended` events before the application /// quits on platforms without an application lifecycle. /// @@ -430,6 +430,14 @@ pub enum WindowEvent<'a> { Ime(Ime), /// The cursor has moved on the window. + /// + /// ## Platform-specific + /// + /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. + /// + /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border + /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform CursorMoved { device_id: DeviceId, @@ -440,9 +448,25 @@ pub enum WindowEvent<'a> { }, /// The cursor has entered the window. + /// + /// ## Platform-specific + /// + /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. + /// + /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border + /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform CursorEntered { device_id: DeviceId }, /// The cursor has left the window. + /// + /// ## Platform-specific + /// + /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. + /// + /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border + /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform CursorLeft { device_id: DeviceId }, /// A mouse wheel movement or touchpad scroll occurred. @@ -528,7 +552,12 @@ pub enum WindowEvent<'a> { /// /// ## Platform-specific /// + /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. /// - **macOS:** Unsupported. + /// + /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border + /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform Touch(Touch), /// The window's scale factor has changed. @@ -566,11 +595,12 @@ pub enum WindowEvent<'a> { /// /// Platform-specific behavior: /// - /// - **Web:** Doesn't take into account CSS [`border`] or [`padding`]. + /// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. /// - **iOS / Android / Wayland / Windows / Orbital:** Unsupported. /// /// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border /// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform Occluded(bool), } @@ -1142,7 +1172,12 @@ pub enum TouchPhase { /// /// ## Platform-specific /// +/// - **Web:** Doesn't take into account CSS [`border`], [`padding`], or [`transform`]. /// - **macOS:** Unsupported. +/// +/// [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border +/// [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding +/// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform #[derive(Debug, Clone, Copy, PartialEq)] pub struct Touch { pub device_id: DeviceId, @@ -1153,7 +1188,7 @@ pub struct Touch { /// /// ## Platform-specific /// - /// - Only available on **iOS** 9.0+ and **Windows** 8+. + /// - Only available on **iOS** 9.0+, **Windows** 8+, and **Web**. pub force: Option, /// Unique identifier of a finger. pub id: u64, diff --git a/src/platform/web.rs b/src/platform/web.rs index fbbba9f4..b6f6b519 100644 --- a/src/platform/web.rs +++ b/src/platform/web.rs @@ -2,6 +2,28 @@ //! allow end users to determine how the page should be laid out. Use the [`WindowExtWebSys`] trait //! to retrieve the canvas from the Window. Alternatively, use the [`WindowBuilderExtWebSys`] trait //! to provide your own canvas. +//! +//! It is recommended **not** to apply certain CSS properties to the canvas: +//! - [`transform`] +//! - [`border`] +//! - [`padding`] +//! +//! The following APIs can't take them into account and will therefore provide inaccurate results: +//! - [`WindowEvent::Resized`] and [`Window::(set_)inner_size()`] +//! - [`WindowEvent::Occluded`] +//! - [`WindowEvent::CursorMoved`], [`WindowEvent::CursorEntered`], [`WindowEvent::CursorLeft`], +//! and [`WindowEvent::Touch`]. +//! +//! [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized +//! [`Window::(set_)inner_size()`]: crate::window::Window::inner_size() +//! [`WindowEvent::Occluded`]: crate::event::WindowEvent::Occluded +//! [`WindowEvent::CursorMoved`]: crate::event::WindowEvent::CursorMoved +//! [`WindowEvent::CursorEntered`]: crate::event::WindowEvent::CursorEntered +//! [`WindowEvent::CursorLeft`]: crate::event::WindowEvent::CursorLeft +//! [`WindowEvent::Touch`]: crate::event::WindowEvent::Touch +//! [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform +//! [`border`]: https://developer.mozilla.org/en-US/docs/Web/CSS/border +//! [`padding`]: https://developer.mozilla.org/en-US/docs/Web/CSS/padding use crate::event::Event; use crate::event_loop::ControlFlow; diff --git a/src/window.rs b/src/window.rs index 9e3f1690..b0066ed9 100644 --- a/src/window.rs +++ b/src/window.rs @@ -644,9 +644,10 @@ impl Window { /// /// - **iOS:** Can only be called on the main thread. Returns the `PhysicalSize` of the window's /// [safe area] in screen space coordinates. - /// - **Web:** Returns the size of the canvas element. + /// - **Web:** Returns the size of the canvas element. Doesn't account for CSS [`transform`]. /// /// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform #[inline] pub fn inner_size(&self) -> PhysicalSize { self.window.inner_size() @@ -683,9 +684,10 @@ impl Window { /// /// ## Platform-specific /// - /// - **Web:** Sets the size of the canvas element. + /// - **Web:** Sets the size of the canvas element. Doesn't account for CSS [`transform`]. /// - /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized. + /// [`WindowEvent::Resized`]: crate::event::WindowEvent::Resized + /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform #[inline] #[must_use] pub fn request_inner_size>(&self, size: S) -> Option> {