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,4 +1,5 @@
 # Unreleased
+- Add web support via the 'stdweb' or 'web-sys' features
 
 # 0.20.0 Alpha 2 (2019-07-09)
 

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

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<String> {
         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<Item = VideoMode> {
         self.inner.video_modes()

src/platform/mod.rs

@@ -7,6 +7,7 @@
 //!  - `macos`
 //!  - `unix`
 //!  - `windows`
+//!  - `web`
 //!
 //! And the following platform-specific module:
 //!

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;
 

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<String> {
-        unimplemented!();
+        None
     }
 
     pub fn size(&self) -> PhysicalSize {
-        unimplemented!();
+        PhysicalSize {
+            width: 0.0,
+            height: 0.0,
+        }
     }
 
     pub fn video_modes(&self) -> impl Iterator<Item = VideoMode> {
-        // TODO: is this possible ?
         std::iter::empty()
     }
 }

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]

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<T: 'static>(
         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<T: 'static>(event_loop: &EventLoopWindowTarget<T>) -> Result<Window, OsError> {
         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<LogicalSize>) {
         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<LogicalSize>) {
         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)