From 8cea3e262be4073b80f920f79d80cc8dc4942ed4 Mon Sep 17 00:00:00 2001 From: Ryan G Date: Tue, 24 Sep 2019 19:33:32 -0400 Subject: [PATCH] Update the documentation to reflect web support (#1183) * Update the documentation to reflect web support Indicate which methods have platform-specific web behavior * cargo fmt --- CHANGELOG.md | 1 + src/dpi.rs | 1 + src/monitor.rs | 17 +++++++++++++++++ src/platform/mod.rs | 1 + src/platform/web.rs | 5 +++++ src/platform_impl/web/monitor.rs | 10 ++++++---- src/platform_impl/web/window.rs | 8 ++++---- src/window.rs | 18 ++++++++++++++++++ 8 files changed, 53 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65555cf0..aece17e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,5 @@ # Unreleased +- Add web support via the 'stdweb' or 'web-sys' features # 0.20.0 Alpha 2 (2019-07-09) diff --git a/src/dpi.rs b/src/dpi.rs index 9c89c12c..99848ae9 100644 --- a/src/dpi.rs +++ b/src/dpi.rs @@ -55,6 +55,7 @@ //! - **Wayland:** On Wayland, DPI factors are set per-screen by the server, and are always integers (most often 1 or 2). //! - **iOS:** DPI factors are both constant and device-specific on iOS. //! - **Android:** This feature isn't yet implemented on Android, so the DPI factor will always be returned as 1.0. +//! - **Web:** DPI factors are handled by the browser and will always be 1.0 for your application. //! //! The window's logical size is conserved across DPI changes, resulting in the physical size changing instead. This //! may be surprising on X11, but is quite standard elsewhere. Physical size changes always produce a diff --git a/src/monitor.rs b/src/monitor.rs index f27ef9d7..56358f8f 100644 --- a/src/monitor.rs +++ b/src/monitor.rs @@ -99,12 +99,20 @@ impl MonitorHandle { /// Returns a human-readable name of the monitor. /// /// Returns `None` if the monitor doesn't exist anymore. + /// + /// ## Platform-specific + /// + /// - **Web:** Always returns None #[inline] pub fn name(&self) -> Option { self.inner.name() } /// Returns the monitor's resolution. + /// + /// ## Platform-specific + /// + /// - **Web:** Always returns (0,0) #[inline] pub fn size(&self) -> PhysicalSize { self.inner.size() @@ -112,6 +120,10 @@ impl MonitorHandle { /// Returns the top-left corner position of the monitor relative to the larger full /// screen area. + /// + /// ## Platform-specific + /// + /// - **Web:** Always returns (0,0) #[inline] pub fn position(&self) -> PhysicalPosition { self.inner.position() @@ -125,12 +137,17 @@ impl MonitorHandle { /// /// - **X11:** Can be overridden using the `WINIT_HIDPI_FACTOR` environment variable. /// - **Android:** Always returns 1.0. + /// - **Web:** Always returns 1.0 #[inline] pub fn hidpi_factor(&self) -> f64 { self.inner.hidpi_factor() } /// Returns all fullscreen video modes supported by this monitor. + /// + /// ## Platform-specific + /// + /// - **Web:** Always returns an empty iterator #[inline] pub fn video_modes(&self) -> impl Iterator { self.inner.video_modes() diff --git a/src/platform/mod.rs b/src/platform/mod.rs index 01125fbb..27ecde18 100644 --- a/src/platform/mod.rs +++ b/src/platform/mod.rs @@ -7,6 +7,7 @@ //! - `macos` //! - `unix` //! - `windows` +//! - `web` //! //! And the following platform-specific module: //! diff --git a/src/platform/web.rs b/src/platform/web.rs index 6a1a98cd..5fca0c42 100644 --- a/src/platform/web.rs +++ b/src/platform/web.rs @@ -1,5 +1,10 @@ #![cfg(target_arch = "wasm32")] +//! The web target does not automatically insert the canvas element object into the web page, to +//! allow end users to determine how the page should be laid out. Use the `WindowExtStdweb` or +//! `WindowExtWebSys` traits (depending on your web backend) to retrieve the canvas from the +//! Window. + #[cfg(feature = "stdweb")] use stdweb::web::html_element::CanvasElement; diff --git a/src/platform_impl/web/monitor.rs b/src/platform_impl/web/monitor.rs index 1aeaa320..5cde23e5 100644 --- a/src/platform_impl/web/monitor.rs +++ b/src/platform_impl/web/monitor.rs @@ -10,19 +10,21 @@ impl Handle { } pub fn position(&self) -> PhysicalPosition { - unimplemented!(); + PhysicalPosition { x: 0.0, y: 0.0 } } pub fn name(&self) -> Option { - unimplemented!(); + None } pub fn size(&self) -> PhysicalSize { - unimplemented!(); + PhysicalSize { + width: 0.0, + height: 0.0, + } } pub fn video_modes(&self) -> impl Iterator { - // TODO: is this possible ? std::iter::empty() } } diff --git a/src/platform_impl/web/window.rs b/src/platform_impl/web/window.rs index 5a14c6db..73602dd4 100644 --- a/src/platform_impl/web/window.rs +++ b/src/platform_impl/web/window.rs @@ -177,13 +177,13 @@ impl Window { #[inline] pub fn set_cursor_position(&self, _position: LogicalPosition) -> Result<(), ExternalError> { - // TODO: pointer capture + // Intentionally a no-op, as the web does not support setting cursor positions Ok(()) } #[inline] pub fn set_cursor_grab(&self, _grab: bool) -> Result<(), ExternalError> { - // TODO: pointer capture + // Intentionally a no-op, as the web does not (properly) support grabbing the cursor Ok(()) } @@ -199,7 +199,7 @@ impl Window { #[inline] pub fn set_maximized(&self, _maximized: bool) { - // TODO: should there be a maximization / fullscreen API? + // Intentionally a no-op, as canvases cannot be 'maximized' } #[inline] @@ -230,7 +230,7 @@ impl Window { #[inline] pub fn set_ime_position(&self, _position: LogicalPosition) { - // TODO: what is this? + // Currently a no-op as it does not seem there is good support for this on web } #[inline] diff --git a/src/window.rs b/src/window.rs index dfde6713..657fa0f1 100644 --- a/src/window.rs +++ b/src/window.rs @@ -286,6 +286,10 @@ impl WindowBuilder { /// Builds the window. /// /// Possible causes of error include denied permission, incompatible system, and lack of memory. + /// + /// Platform-specific behavior: + /// - **Web**: The window is created but not inserted into the web page automatically. Please + /// see the web platform module for more information. #[inline] pub fn build( self, @@ -305,6 +309,10 @@ impl Window { /// /// Error should be very rare and only occur in case of permission denied, incompatible system, /// out of memory, etc. + /// + /// Platform-specific behavior: + /// - **Web**: The window is created but not inserted into the web page automatically. Please + /// see the web platform module for more information. #[inline] pub fn new(event_loop: &EventLoopWindowTarget) -> Result { let builder = WindowBuilder::new(); @@ -460,6 +468,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Has no effect. + /// - **Web:** Has no effect. #[inline] pub fn set_min_inner_size(&self, dimensions: Option) { self.window.set_min_inner_size(dimensions) @@ -470,6 +479,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Has no effect. + /// - **Web:** Has no effect. #[inline] pub fn set_max_inner_size(&self, dimensions: Option) { self.window.set_max_inner_size(dimensions) @@ -495,6 +505,7 @@ impl Window { /// /// - **Android:** Has no effect. /// - **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) @@ -514,6 +525,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Has no effect. + /// - **Web:** Has no effect. #[inline] pub fn set_resizable(&self, resizable: bool) { self.window.set_resizable(resizable) @@ -524,6 +536,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Has no effect. + /// - **Web:** Has no effect. #[inline] pub fn set_maximized(&self, maximized: bool) { self.window.set_maximized(maximized) @@ -555,6 +568,7 @@ impl Window { /// /// - **iOS:** Can only be called on the main thread. Controls whether the status bar is hidden /// via [`setPrefersStatusBarHidden`]. + /// - **Web:** Has no effect. /// /// [`setPrefersStatusBarHidden`]: https://developer.apple.com/documentation/uikit/uiviewcontroller/1621440-prefersstatusbarhidden?language=objc #[inline] @@ -567,6 +581,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Has no effect. + /// - **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) @@ -590,6 +605,7 @@ impl Window { /// ## Platform-specific /// /// **iOS:** Has no effect. + /// - **Web:** Has no effect. #[inline] pub fn set_ime_position(&self, position: LogicalPosition) { self.window.set_ime_position(position) @@ -614,6 +630,7 @@ impl Window { /// ## Platform-specific /// /// - **iOS:** Always returns an `Err`. + /// - **Web:** Has no effect. #[inline] pub fn set_cursor_position(&self, position: LogicalPosition) -> Result<(), ExternalError> { self.window.set_cursor_position(position) @@ -627,6 +644,7 @@ impl Window { /// 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)