From 27e7303ebe1ccca44873813a3f684cba12de973e Mon Sep 17 00:00:00 2001
From: Brandon Li <48413902+aspiringLich@users.noreply.github.com>
Date: Thu, 20 Feb 2025 13:32:34 -0500
Subject: [PATCH] Clarify platform-specific details for `Viewport` positioning
 (#5715)

On Wayland (and android apparently) it is not possible for applications
to position their windows or request the window position (for some
reason). This is not specified in the documentation.

proof: [`winit::set_outer_position`], [`winit::outer_position`],
[`winit::inner_position`] all specify that Android / Wayland are not
supported.

[`winit::set_outer_position`]:
https://docs.rs/winit/latest/winit/window/struct.Window.html#method.set_outer_position
[`winit::outer_position`]:
https://docs.rs/winit/latest/winit/window/struct.Window.html#method.outer_position
[`winit::inner_position`]:
https://docs.rs/winit/latest/winit/window/struct.Window.html#method.inner_position

* Maybe closes #4469
* the lack of support makes me sad. I believe this makes some items in
#3556 impossible on Wayland. Oh well!

---------

Co-authored-by: lucasmerlin <lucasmeurer96@gmail.com>
---
 crates/egui/src/data/input.rs | 10 ++++++++++
 crates/egui/src/viewport.rs   |  9 +++++++++
 2 files changed, 19 insertions(+)

diff --git a/crates/egui/src/data/input.rs b/crates/egui/src/data/input.rs
index d781d243..6b22ee7b 100644
--- a/crates/egui/src/data/input.rs
+++ b/crates/egui/src/data/input.rs
@@ -214,11 +214,21 @@ pub struct ViewportInfo {
     /// The inner rectangle of the native window, in monitor space and ui points scale.
     ///
     /// This is the content rectangle of the viewport.
+    ///
+    /// **`eframe` notes**:
+    ///
+    /// On Android / Wayland, this will always be `None` since getting the
+    /// position of the window is not possible.
     pub inner_rect: Option<Rect>,
 
     /// The outer rectangle of the native window, in monitor space and ui points scale.
     ///
     /// This is the content rectangle plus decoration chrome.
+    ///
+    /// **`eframe` notes**:
+    ///
+    /// On Android / Wayland, this will always be `None` since getting the
+    /// position of the window is not possible.
     pub outer_rect: Option<Rect>,
 
     /// Are we minimized?
diff --git a/crates/egui/src/viewport.rs b/crates/egui/src/viewport.rs
index d3f1c389..791b34c7 100644
--- a/crates/egui/src/viewport.rs
+++ b/crates/egui/src/viewport.rs
@@ -543,6 +543,15 @@ impl ViewportBuilder {
 
     /// The initial "outer" position of the window,
     /// i.e. where the top-left corner of the frame/chrome should be.
+    ///
+    /// **`eframe` notes**:
+    ///
+    /// - **iOS:** Sets the top left coordinates of the window in the screen space coordinate system.
+    /// - **Web:** Sets the top-left coordinates relative to the viewport. Doesn't account for CSS
+    ///   [`transform`].
+    /// - **Android / Wayland:** Unsupported.
+    ///
+    /// [`transform`]: https://developer.mozilla.org/en-US/docs/Web/CSS/transform
     #[inline]
     pub fn with_position(mut self, pos: impl Into<Pos2>) -> Self {
         self.position = Some(pos.into());