Add documentation for pointer events

rust-windowing · Jul 10, 2023 · 4c75c17 · 4c75c17
1 parent b562854
commit 4c75c17
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 5 deletions.
diff --git a/src/event.rs b/src/event.rs
@@ -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,

diff --git a/src/platform/web.rs b/src/platform/web.rs
@@ -4,14 +4,23 @@
 //! to provide your own canvas.
 //!
 //! It is recommended **not** to apply certain CSS properties to the canvas:
-//! - [`transform`] - which causes [`WindowEvent::Resized`] and [`Window::(set_)inner_size()`] to
-//!   be inaccurate.
-//! - [`border`] - which causes [`WindowEvent::Occluded`] to be inaccurate.
-//! - [`padding`] - which causes [`WindowEvent::Occluded`] to be inaccurate.
+//! - [`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