From d5fd8682eb79b71d69b8f4df225dfbd97c137c95 Mon Sep 17 00:00:00 2001 From: daxpedda Date: Wed, 10 Jul 2024 16:17:39 +0200 Subject: [PATCH] Web: use the word "Web" correctly and consistently (#3785) --- .github/ISSUE_TEMPLATE/bug_web.yml | 2 +- .github/workflows/ci.yml | 6 +-- examples/window.rs | 6 +-- src/changelog/unreleased.md | 1 + src/cursor.rs | 2 +- src/event_loop.rs | 21 ++++---- src/icon.rs | 2 +- src/keyboard.rs | 2 +- src/lib.rs | 2 +- src/platform/run_on_demand.rs | 14 ++++-- src/platform/web.rs | 57 +++++++++++----------- src/platform_impl/web/event_loop/mod.rs | 2 +- src/platform_impl/web/event_loop/runner.rs | 4 +- src/platform_impl/web/mod.rs | 10 ++-- src/platform_impl/web/window.rs | 2 +- src/window.rs | 4 +- 16 files changed, 71 insertions(+), 66 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_web.yml b/.github/ISSUE_TEMPLATE/bug_web.yml index fb35eb9799..d9a97fea77 100644 --- a/.github/ISSUE_TEMPLATE/bug_web.yml +++ b/.github/ISSUE_TEMPLATE/bug_web.yml @@ -1,5 +1,5 @@ name: Web bug -description: Create a web-specific bug report +description: Create a Web-specific bug report labels: - B - bug - DS - web diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5f1353a92b..02390b9863 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -58,7 +58,7 @@ jobs: - { name: 'macOS', target: x86_64-apple-darwin, os: macos-latest, } - { name: 'iOS x86_64', target: x86_64-apple-ios, os: macos-latest, } - { name: 'iOS Aarch64', target: aarch64-apple-ios, os: macos-latest, } - - { name: 'web', target: wasm32-unknown-unknown, os: ubuntu-latest, } + - { name: 'Web', target: wasm32-unknown-unknown, os: ubuntu-latest, } exclude: # Android is tested on stable-3 - toolchain: '1.73' @@ -68,7 +68,7 @@ jobs: platform: { name: 'Android', target: aarch64-linux-android, os: ubuntu-latest, options: '--package=winit --features=android-native-activity', cmd: 'apk --' } - toolchain: 'nightly' platform: { - name: 'web Atomic', + name: 'Web Atomic', target: wasm32-unknown-unknown, os: ubuntu-latest, options: '-Zbuild-std=panic_abort,std', @@ -216,7 +216,7 @@ jobs: - { name: 'Linux', target: x86_64-unknown-linux-gnu } - { name: 'macOS', target: x86_64-apple-darwin } - { name: 'Redox OS', target: x86_64-unknown-redox } - - { name: 'web', target: wasm32-unknown-unknown } + - { name: 'Web', target: wasm32-unknown-unknown } - { name: 'Windows', target: x86_64-pc-windows-gnu } steps: diff --git a/examples/window.rs b/examples/window.rs index 5ad1eed312..679100c864 100644 --- a/examples/window.rs +++ b/examples/window.rs @@ -139,7 +139,7 @@ impl Application { #[cfg(web_platform)] { - use winit::platform::web::WindowAttributesExtWebSys; + use winit::platform::web::WindowAttributesExtWeb; window_attributes = window_attributes.with_append(true); } @@ -704,7 +704,7 @@ impl WindowState { ) { use std::time::Duration; - use winit::platform::web::CustomCursorExtWebSys; + use winit::platform::web::CustomCursorExtWeb; let cursors = vec![ custom_cursors[0].clone(), @@ -943,7 +943,7 @@ fn decode_cursor(bytes: &[u8]) -> CustomCursorSource { fn url_custom_cursor() -> CustomCursorSource { use std::sync::atomic::{AtomicU64, Ordering}; - use winit::platform::web::CustomCursorExtWebSys; + use winit::platform::web::CustomCursorExtWeb; static URL_COUNTER: AtomicU64 = AtomicU64::new(0); diff --git a/src/changelog/unreleased.md b/src/changelog/unreleased.md index 385c1d0340..d74090d132 100644 --- a/src/changelog/unreleased.md +++ b/src/changelog/unreleased.md @@ -64,6 +64,7 @@ changelog entry. `ApplicationHandler::resumed/suspended()` are now only emitted by iOS and Web and now signify actually resuming/suspending the application. +- Rename `platform::web::*ExtWebSys` to `*ExtWeb`. ### Removed diff --git a/src/cursor.rs b/src/cursor.rs index 7bcac54d76..f89639ae8f 100644 --- a/src/cursor.rs +++ b/src/cursor.rs @@ -62,7 +62,7 @@ impl From for Cursor { /// /// #[cfg(target_family = "wasm")] /// let source = { -/// use winit::platform::web::CustomCursorExtWebSys; +/// use winit::platform::web::CustomCursorExtWeb; /// CustomCursor::from_url(String::from("http://localhost:3000/cursor.png"), 0, 0) /// }; /// diff --git a/src/event_loop.rs b/src/event_loop.rs index f83ef7828c..b8e0e90e25 100644 --- a/src/event_loop.rs +++ b/src/event_loop.rs @@ -224,20 +224,21 @@ impl EventLoop { /// /// Web applications are recommended to use #[cfg_attr( - web_platform, - doc = "[`EventLoopExtWebSys::spawn_app()`][crate::platform::web::EventLoopExtWebSys::spawn_app()]" + any(web_platform, docsrs), + doc = " [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]" )] - #[cfg_attr(not(web_platform), doc = "`EventLoopExtWebSys::spawn()`")] - /// [^1] instead of [`run_app()`] to avoid the need - /// for the Javascript exception trick, and to make it clearer that the event loop runs - /// asynchronously (via the browser's own, internal, event loop) and doesn't block the - /// current thread of execution like it does on other platforms. + #[cfg_attr(not(any(web_platform, docsrs)), doc = " `EventLoopExtWeb::spawn_app()`")] + /// [^1] instead of [`run_app()`] to avoid the need for the Javascript exception trick, and to + /// make it clearer that the event loop runs asynchronously (via the browser's own, + /// internal, event loop) and doesn't block the current thread of execution like it does + /// on other platforms. /// /// This function won't be available with `target_feature = "exception-handling"`. /// + /// [^1]: `spawn_app()` is only available on the Web platform. + /// /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow() /// [`run_app()`]: Self::run_app() - /// [^1]: `EventLoopExtWebSys::spawn_app()` is only available on Web. #[inline] #[cfg(not(all(web_platform, target_feature = "exception-handling")))] pub fn run_app(self, app: &mut A) -> Result<(), EventLoopError> { @@ -357,8 +358,8 @@ impl ActiveEventLoop { /// /// ## Platform-specific /// - /// - **Web:** The window is created but not inserted into the web page automatically. Please - /// see the web platform module for more information. + /// - **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 create_window(&self, window_attributes: WindowAttributes) -> Result { let _span = tracing::debug_span!( diff --git a/src/icon.rs b/src/icon.rs index ba497cf8ea..bb8f4fea14 100644 --- a/src/icon.rs +++ b/src/icon.rs @@ -57,7 +57,7 @@ pub(crate) struct RgbaIcon { pub(crate) height: u32, } -/// For platforms which don't have window icons (e.g. web) +/// For platforms which don't have window icons (e.g. Web) #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct NoIcon; diff --git a/src/keyboard.rs b/src/keyboard.rs index 8c7005fe17..6039e92c10 100644 --- a/src/keyboard.rs +++ b/src/keyboard.rs @@ -84,7 +84,7 @@ pub use smol_str::SmolStr; /// haven't mapped for you yet, this lets you use use [`KeyCode`] to: /// /// - Correctly match key press and release events. -/// - On non-web platforms, support assigning keybinds to virtually any key through a UI. +/// - On non-Web platforms, support assigning keybinds to virtually any key through a UI. #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum NativeKeyCode { diff --git a/src/lib.rs b/src/lib.rs index 8f850560a3..b4949ed9ec 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -26,7 +26,7 @@ //! will run until [`exit()`] is used, at which point [`exiting()`] is called. //! //! Winit no longer uses a `EventLoop::poll_events() -> impl Iterator`-based event loop -//! model, since that can't be implemented properly on some platforms (e.g web, iOS) and works +//! model, since that can't be implemented properly on some platforms (e.g Web, iOS) and works //! poorly on most other platforms. However, this model can be re-implemented to an extent with #![cfg_attr( any(windows_platform, macos_platform, android_platform, x11_platform, wayland_platform), diff --git a/src/platform/run_on_demand.rs b/src/platform/run_on_demand.rs index 3f8737de98..b7b847e64f 100644 --- a/src/platform/run_on_demand.rs +++ b/src/platform/run_on_demand.rs @@ -29,9 +29,13 @@ pub trait EventLoopExtRunOnDemand { /// # Caveats /// - This extension isn't available on all platforms, since it's not always possible to return /// to the caller (specifically this is impossible on iOS and Web - though with the Web - /// backend it is possible to use `EventLoopExtWebSys::spawn()` - #[cfg_attr(not(web_platform), doc = "[^1]")] - /// more than once instead). + /// backend it is possible to use + #[cfg_attr( + any(web_platform, docsrs), + doc = " [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]" + )] + #[cfg_attr(not(any(web_platform, docsrs)), doc = " `EventLoopExtWeb::spawn_app()`")] + /// [^1] more than once instead). /// - No [`Window`] state can be carried between separate runs of the event loop. /// /// You are strongly encouraged to use [`EventLoop::run_app()`] for portability, unless you @@ -49,8 +53,8 @@ pub trait EventLoopExtRunOnDemand { /// block the browser and there is nothing that can be polled to ask for new events. Events /// are delivered via callbacks based on an event loop that is internal to the browser itself. /// - **iOS:** It's not possible to stop and start an `UIApplication` repeatedly on iOS. - #[cfg_attr(not(web_platform), doc = "[^1]: `spawn()` is only available on `wasm` platforms.")] - #[rustfmt::skip] + /// + /// [^1]: `spawn_app()` is only available on the Web platforms. /// /// [`exit()`]: ActiveEventLoop::exit() /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow() diff --git a/src/platform/web.rs b/src/platform/web.rs index 1e804f495b..1dd612ce24 100644 --- a/src/platform/web.rs +++ b/src/platform/web.rs @@ -1,24 +1,23 @@ //! # Web //! -//! The officially supported browsers are Chrome, Firefox and Safari 13.1+, -//! though forks of these should work fine. +//! Winit supports running in Browsers by compiling to WebAssembly with +//! [`wasm-bindgen`][wasm_bindgen]. For information on using Rust on WebAssembly, check out the +//! [Rust and WebAssembly book]. //! -//! Winit supports compiling to the `wasm32-unknown-unknown` target with -//! `web-sys`. +//! The officially supported browsers are Chrome, Firefox and Safari 13.1+, though forks of these +//! should work fine. //! -//! On the web platform, a Winit window is backed by a `` element. You -//! can either [provide Winit with a `` element][with_canvas], or -//! [let Winit create a `` element which you can then retrieve][get] -//! and insert it into the DOM yourself. +//! On the Web platform, a Winit [`Window`] is backed by a [`HTMLCanvasElement`][canvas]. Winit will +//! create that canvas for you or you can [provide your own][with_canvas]. Then you can either let +//! Winit [insert it into the DOM for you][insert], or [retrieve the canvas][get] and insert it +//! yourself. //! -//! Currently, there is no example code using Winit on Web, see [#3473]. For -//! information on using Rust on WebAssembly, check out the [Rust and -//! WebAssembly book]. -//! -//! [with_canvas]: WindowAttributesExtWebSys::with_canvas -//! [get]: WindowExtWebSys::canvas -//! [#3473]: https://github.com/rust-windowing/winit/issues/3473 -//! [Rust and WebAssembly book]: https://rustwasm.github.io/book/ +//! [canvas]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement +//! [with_canvas]: WindowAttributesExtWeb::with_canvas +//! [get]: WindowExtWeb::canvas +//! [insert]: WindowAttributesExtWeb::with_append +#![cfg_attr(not(web_platform), doc = "[wasm_bindgen]: https://docs.rs/wasm-bindgen")] +//! [Rust and WebAssembly book]: https://rustwasm.github.io/book //! //! ## CSS properties //! @@ -65,7 +64,7 @@ use crate::window::{CustomCursor, Window, WindowAttributes}; #[doc(hidden)] pub struct HtmlCanvasElement; -pub trait WindowExtWebSys { +pub trait WindowExtWeb { /// Only returns the canvas if called from inside the window context (the /// main thread). fn canvas(&self) -> Option; @@ -86,7 +85,7 @@ pub trait WindowExtWebSys { fn set_prevent_default(&self, prevent_default: bool); } -impl WindowExtWebSys for Window { +impl WindowExtWeb for Window { #[inline] fn canvas(&self) -> Option { self.window.canvas() @@ -101,11 +100,11 @@ impl WindowExtWebSys for Window { } } -pub trait WindowAttributesExtWebSys { +pub trait WindowAttributesExtWeb { /// Pass an [`HtmlCanvasElement`] to be used for this [`Window`]. If [`None`], /// [`WindowAttributes::default()`] will create one. /// - /// In any case, the canvas won't be automatically inserted into the web page. + /// In any case, the canvas won't be automatically inserted into the Web page. /// /// [`None`] by default. #[cfg_attr(not(web_platform), doc = "", doc = "[`HtmlCanvasElement`]: #only-available-on-wasm")] @@ -125,13 +124,13 @@ pub trait WindowAttributesExtWebSys { /// Enabled by default. fn with_focusable(self, focusable: bool) -> Self; - /// On window creation, append the canvas element to the web page if it isn't already. + /// On window creation, append the canvas element to the Web page if it isn't already. /// /// Disabled by default. fn with_append(self, append: bool) -> Self; } -impl WindowAttributesExtWebSys for WindowAttributes { +impl WindowAttributesExtWeb for WindowAttributes { fn with_canvas(mut self, canvas: Option) -> Self { self.platform_specific.set_canvas(canvas); self @@ -153,8 +152,8 @@ impl WindowAttributesExtWebSys for WindowAttributes { } } -/// Additional methods on `EventLoop` that are specific to the web. -pub trait EventLoopExtWebSys { +/// Additional methods on `EventLoop` that are specific to the Web. +pub trait EventLoopExtWeb { /// Initializes the winit event loop. /// /// Unlike @@ -208,7 +207,7 @@ pub trait EventLoopExtWebSys { fn wait_until_strategy(&self) -> WaitUntilStrategy; } -impl EventLoopExtWebSys for EventLoop { +impl EventLoopExtWeb for EventLoop { fn spawn_app(self, app: A) { self.event_loop.spawn_app(app); } @@ -230,7 +229,7 @@ impl EventLoopExtWebSys for EventLoop { } } -pub trait ActiveEventLoopExtWebSys { +pub trait ActiveEventLoopExtWeb { /// Sets the strategy for [`ControlFlow::Poll`]. /// /// See [`PollStrategy`]. @@ -264,7 +263,7 @@ pub trait ActiveEventLoopExtWebSys { fn create_custom_cursor_async(&self, source: CustomCursorSource) -> CustomCursorFuture; } -impl ActiveEventLoopExtWebSys for ActiveEventLoop { +impl ActiveEventLoopExtWeb for ActiveEventLoop { #[inline] fn create_custom_cursor_async(&self, source: CustomCursorSource) -> CustomCursorFuture { self.p.create_custom_cursor_async(source) @@ -340,7 +339,7 @@ pub enum WaitUntilStrategy { Worker, } -pub trait CustomCursorExtWebSys { +pub trait CustomCursorExtWeb { /// Returns if this cursor is an animation. fn is_animation(&self) -> bool; @@ -359,7 +358,7 @@ pub trait CustomCursorExtWebSys { ) -> Result; } -impl CustomCursorExtWebSys for CustomCursor { +impl CustomCursorExtWeb for CustomCursor { fn is_animation(&self) -> bool { self.inner.animation } diff --git a/src/platform_impl/web/event_loop/mod.rs b/src/platform_impl/web/event_loop/mod.rs index cc5ce82d93..56742b87eb 100644 --- a/src/platform_impl/web/event_loop/mod.rs +++ b/src/platform_impl/web/event_loop/mod.rs @@ -5,7 +5,7 @@ use crate::application::ApplicationHandler; use crate::error::EventLoopError; use crate::event::Event; use crate::event_loop::ActiveEventLoop as RootActiveEventLoop; -use crate::platform::web::{ActiveEventLoopExtWebSys, PollStrategy, WaitUntilStrategy}; +use crate::platform::web::{ActiveEventLoopExtWeb, PollStrategy, WaitUntilStrategy}; mod proxy; pub(crate) mod runner; diff --git a/src/platform_impl/web/event_loop/runner.rs b/src/platform_impl/web/event_loop/runner.rs index 0663fcba96..c7275dcc3e 100644 --- a/src/platform_impl/web/event_loop/runner.rs +++ b/src/platform_impl/web/event_loop/runner.rs @@ -439,7 +439,7 @@ impl Shared { } pub fn init(&self) { - // NB: For consistency all platforms must call `can_create_surfaces` even though web + // NB: For consistency all platforms must call `can_create_surfaces` even though Web // applications don't themselves have a formal surface destroy/create lifecycle. self.run_until_cleared( [Event::NewEvents(StartCause::Init), Event::CreateSurfaces].into_iter(), @@ -604,7 +604,7 @@ impl Shared { self.exit(); self.apply_control_flow(); // We don't call `handle_loop_destroyed` here because we don't need to - // perform cleanup when the web browser is going to destroy the page. + // perform cleanup when the Web browser is going to destroy the page. self.handle_event(Event::LoopExiting); } diff --git a/src/platform_impl/web/mod.rs b/src/platform_impl/web/mod.rs index 9c2403425a..9a8e3c6f95 100644 --- a/src/platform_impl/web/mod.rs +++ b/src/platform_impl/web/mod.rs @@ -1,14 +1,14 @@ -// Brief introduction to the internals of the web backend: -// The web backend used to support both wasm-bindgen and stdweb as methods of binding to the -// environment. Because they are both supporting the same underlying APIs, the actual web bindings +// Brief introduction to the internals of the Web backend: +// The Web backend used to support both wasm-bindgen and stdweb as methods of binding to the +// environment. Because they are both supporting the same underlying APIs, the actual Web bindings // are cordoned off into backend abstractions, which present the thinnest unifying layer possible. // // When adding support for new events or interactions with the browser, first consult trusted // documentation (such as MDN) to ensure it is well-standardised and supported across many browsers. -// Once you have decided on the relevant web APIs, add support to both backends. +// Once you have decided on the relevant Web APIs, add support to both backends. // // The backend is used by the rest of the module to implement Winit's business logic, which forms -// the rest of the code. 'device', 'error', 'monitor', and 'window' define web-specific structures +// the rest of the code. 'device', 'error', 'monitor', and 'window' define Web-specific structures // for winit's cross-platform structures. They are all relatively simple translations. // // The event_loop module handles listening for and processing events. 'Proxy' implements diff --git a/src/platform_impl/web/window.rs b/src/platform_impl/web/window.rs index a18b9172ff..b071bc5ba4 100644 --- a/src/platform_impl/web/window.rs +++ b/src/platform_impl/web/window.rs @@ -325,7 +325,7 @@ impl Inner { #[inline] pub fn set_ime_cursor_area(&self, _position: Position, _size: Size) { - // Currently a no-op as it does not seem there is good support for this on web + // Currently not implemented } #[inline] diff --git a/src/window.rs b/src/window.rs index 991ec4e157..b0d4b98d07 100644 --- a/src/window.rs +++ b/src/window.rs @@ -1154,7 +1154,7 @@ impl Window { /// /// Enable/disable window decorations provided by the server or Winit. /// By default this is enabled. Note that fullscreen windows and windows on - /// mobile and web platforms naturally do not have decorations. + /// mobile and Web platforms naturally do not have decorations. /// /// ## Platform-specific /// @@ -1168,7 +1168,7 @@ impl Window { /// Gets the window's current decorations state. /// /// Returns `true` when windows are decorated (server-side or by Winit). - /// Also returns `true` when no decorations are required (mobile, web). + /// Also returns `true` when no decorations are required (mobile, Web). /// /// ## Platform-specific ///