Fix Window platform support documentation

This resolves various problems with the documentation about platform
support on the Window struct.

It also completely removes pointless runtime errors in favor of
consistent no-ops on all platforms that do not support a certain
features.

CHANGELOG.md

@@ -49,6 +49,10 @@
 - on macOS, fix incorrect ReceivedCharacter events for some key combinations.
 - **Breaking:** Use `i32` instead of `u32` for position type in `WindowEvent::Moved`.
 - On macOS, a mouse motion event is now generated before every mouse click.
+- On Windows, `set_ime_position` is now a no-op instead of a runtime crash.
+- On Android, `set_fullscreen` is now a no-op instead of a runtime crash.
+- On iOS and Android, `set_inner_size` is now a no-op instead of a runtime crash.
+- **Breaking:** On Web, `set_cursor_position` and `set_cursor_grab` will now always return an error.
 
 # 0.21.0 (2020-02-04)
 

src/platform_impl/android/mod.rs

@@ -419,7 +419,7 @@ impl Window {
     }
 
     pub fn set_inner_size(&self, _size: Size) {
-        panic!("Cannot set window size on Android");
+        warn!("Cannot set window size on Android");
     }
 
     pub fn outer_size(&self) -> PhysicalSize<u32> {
@@ -441,7 +441,7 @@ impl Window {
     pub fn set_maximized(&self, _maximized: bool) {}
 
     pub fn set_fullscreen(&self, _monitor: Option<window::Fullscreen>) {
-        panic!("Cannot set fullscreen on Android");
+        warn!("Cannot set fullscreen on Android");
     }
 
     pub fn fullscreen(&self) -> Option<window::Fullscreen> {

src/platform_impl/ios/window.rs

@@ -142,7 +142,7 @@ impl Inner {
     }
 
     pub fn set_inner_size(&self, _size: Size) {
-        unimplemented!("not clear what `Window::set_inner_size` means on iOS");
+        warn!("not clear what `Window::set_inner_size` means on iOS");
     }
 
     pub fn set_min_inner_size(&self, _dimensions: Option<Size>) {

src/platform_impl/web/window.rs

@@ -171,14 +171,12 @@ impl Window {
 
     #[inline]
     pub fn set_cursor_position(&self, _position: Position) -> Result<(), ExternalError> {
-        // Intentionally a no-op, as the web does not support setting cursor positions
+        Err(ExternalError::NotSupported(NotSupportedError::new()))
-        Ok(())
     }
 
     #[inline]
     pub fn set_cursor_grab(&self, _grab: bool) -> Result<(), ExternalError> {
-        // Intentionally a no-op, as the web does not (properly) support grabbing the cursor
+        Err(ExternalError::NotSupported(NotSupportedError::new()))
-        Ok(())
     }
 
     #[inline]

src/platform_impl/windows/window.rs

@@ -609,7 +609,7 @@ impl Window {
 
     #[inline]
     pub fn set_ime_position(&self, _position: Position) {
-        unimplemented!();
+        warn!("`Window::set_ime_position` is ignored on Windows")
     }
 
     #[inline]

src/window.rs

@@ -401,6 +401,7 @@ impl Window {
     /// ## Platform-specific
     ///
     /// - **iOS:** Can only be called on the main thread.
+    /// - **Android:** Unsupported.
     #[inline]
     pub fn request_redraw(&self) {
         self.window.request_redraw()
@@ -420,6 +421,7 @@ impl Window {
     ///   window's [safe area] in the screen space coordinate system.
     /// - **Web:** Returns the top-left coordinates relative to the viewport. _Note: this returns the
     ///    same value as `outer_position`._
+    /// - **Android / Wayland:** Always returns [`NotSupportedError`].
     ///
     /// [safe area]: https://developer.apple.com/documentation/uikit/uiview/2891103-safeareainsets?language=objc
     #[inline]
@@ -442,6 +444,7 @@ impl Window {
     /// - **iOS:** Can only be called on the main thread. Returns the top left coordinates of the
     ///   window in the screen space coordinate system.
     /// - **Web:** Returns the top-left coordinates relative to the viewport.
+    /// - **Android / Wayland:** Always returns [`NotSupportedError`].
     #[inline]
     pub fn outer_position(&self) -> Result<PhysicalPosition<i32>, NotSupportedError> {
         self.window.outer_position()
@@ -457,6 +460,7 @@ impl Window {
     /// - **iOS:** Can only be called on the main thread. Sets the top left coordinates of the
     ///   window in the screen space coordinate system.
     /// - **Web:** Sets the top-left coordinates relative to the viewport.
+    /// - **Android / Wayland:** Unsupported.
     #[inline]
     pub fn set_outer_position<P: Into<Position>>(&self, position: P) {
         self.window.set_outer_position(position.into())
@@ -485,8 +489,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Unimplemented. Currently this panics, as it's not clear what `set_inner_size`
+    /// - **iOS / Android:** Unsupported.
-    ///   would mean for iOS.
     /// - **Web:** Sets the size of the canvas element.
     #[inline]
     pub fn set_inner_size<S: Into<Size>>(&self, size: S) {
@@ -513,8 +516,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android / Web:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_min_inner_size<S: Into<Size>>(&self, min_size: Option<S>) {
         self.window.set_min_inner_size(min_size.map(|s| s.into()))
@@ -524,8 +526,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Andraid / Web:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_max_inner_size<S: Into<Size>>(&self, max_size: Option<S>) {
         self.window.set_max_inner_size(max_size.map(|s| s.into()))
@@ -538,7 +539,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - Has no effect on iOS.
+    /// - **iOS / Android:** Unsupported.
     #[inline]
     pub fn set_title(&self, title: &str) {
         self.window.set_title(title)
@@ -549,9 +550,8 @@ impl Window {
     /// If `false`, this will hide the window. If `true`, this will show the window.
     /// ## Platform-specific
     ///
-    /// - **Android:** Has no effect.
+    /// - **Android / Wayland / Web:** Unsupported.
     /// - **iOS:** Can only be called on the main thread.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_visible(&self, visible: bool) {
         self.window.set_visible(visible)
@@ -570,8 +570,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android / Web:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_resizable(&self, resizable: bool) {
         self.window.set_resizable(resizable)
@@ -581,7 +580,8 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect
+    /// - **iOS / Android / Web:** Unsupported.
+    /// - **Wayland:** Un-minimize is unsupported.
     #[inline]
     pub fn set_minimized(&self, minimized: bool) {
         self.window.set_minimized(minimized);
@@ -591,8 +591,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android / Web:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_maximized(&self, maximized: bool) {
         self.window.set_maximized(maximized)
@@ -617,6 +616,7 @@ impl Window {
     /// - **iOS:** Can only be called on the main thread.
     /// - **Wayland:** Does not support exclusive fullscreen mode.
     /// - **Windows:** Screen saver is disabled in fullscreen mode.
+    /// - **Android:** Unsupported.
     #[inline]
     pub fn set_fullscreen(&self, fullscreen: Option<Fullscreen>) {
         self.window.set_fullscreen(fullscreen)
@@ -627,6 +627,7 @@ impl Window {
     /// ## Platform-specific
     ///
     /// - **iOS:** Can only be called on the main thread.
+    /// - **Android:** Will always return `None`.
     #[inline]
     pub fn fullscreen(&self) -> Option<Fullscreen> {
         self.window.fullscreen()
@@ -635,9 +636,8 @@ impl Window {
     /// Turn window decorations on or off.
     ///
     /// ## Platform-specific
-    /// - **iOS:** Can only be called on the main thread. Controls whether the status bar is hidden
+    ///
-    ///   via [`setPrefersStatusBarHidden`].
+    /// - **iOS / Android / Web:** Unsupported.
-    /// - **Web:** Has no effect.
     ///
     /// [`setPrefersStatusBarHidden`]: https://developer.apple.com/documentation/uikit/uiviewcontroller/1621440-prefersstatusbarhidden?language=objc
     #[inline]
@@ -649,8 +649,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android / Web / Wayland:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_always_on_top(&self, always_on_top: bool) {
         self.window.set_always_on_top(always_on_top)
@@ -661,7 +660,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// This only has an effect on Windows and X11.
+    /// - **iOS / Android / Web / Wayland / macOS:** Unsupported.
     ///
     /// On Windows, this sets `ICON_SMALL`. The base size for a window icon is 16x16, but it's
     /// recommended to account for screen scaling and pick a multiple of that, i.e. 32x32.
@@ -677,8 +676,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// **iOS:** Has no effect.
+    /// - **iOS / Android / Web / Wayland / Windows:** Unsupported.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_ime_position<P: Into<Position>>(&self, position: P) {
         self.window.set_ime_position(position.into())
@@ -691,8 +689,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android:** Unsupported.
-    /// - **Android:** Has no effect.
     #[inline]
     pub fn set_cursor_icon(&self, cursor: CursorIcon) {
         self.window.set_cursor_icon(cursor);
@@ -702,8 +699,7 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **iOS:** Always returns an `Err`.
+    /// - **iOS / Android / Web / Wayland:** Always returns an [`ExternalError::NotSupported`].
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_cursor_position<P: Into<Position>>(&self, position: P) -> Result<(), ExternalError> {
         self.window.set_cursor_position(position.into())
@@ -713,13 +709,8 @@ impl Window {
     ///
     /// ## Platform-specific
     ///
-    /// - **macOS:** This presently merely locks the cursor in a fixed location, which looks visually
+    /// - **macOS / Wayland:** This locks the cursor in a fixed location, which looks visually awkward.
-    ///   awkward.
+    /// - **iOS / Android / Web:** Always returns an [`ExternalError::NotSupported`].
-    /// - **Wayland:** This presently merely locks the cursor in a fixed location, which looks visually
-    ///   awkward.
-    /// - **Android:** Has no effect.
-    /// - **iOS:** Always returns an Err.
-    /// - **Web:** Has no effect.
     #[inline]
     pub fn set_cursor_grab(&self, grab: bool) -> Result<(), ExternalError> {
         self.window.set_cursor_grab(grab)
@@ -736,8 +727,7 @@ impl Window {
     /// - **Wayland:** The cursor is only hidden within the confines of the window.
     /// - **macOS:** The cursor is hidden as long as the window has input focus, even if the cursor is
     ///   outside of the window.
-    /// - **iOS:** Has no effect.
+    /// - **iOS / Android:** Unsupported.
-    /// - **Android:** Has no effect.
     #[inline]
     pub fn set_cursor_visible(&self, visible: bool) {
         self.window.set_cursor_visible(visible)