Winit version 0.31.0-beta.2

To allow users to explicitly choose the run semantics that they want.

Cargo.toml

@@ -8,22 +8,22 @@ edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/rust-windowing/winit"
 rust-version = "1.85"
-version = "0.30.12"
+version = "0.31.0-beta.2"
 
 [workspace.dependencies]
 # Workspace dependencies.
 # `winit` has no version here to allow using it in dev deps for docs.
 winit = { path = "winit" }
-winit-android = { version = "0.30.12", path = "winit-android" }
-winit-appkit = { version = "0.30.12", path = "winit-appkit" }
-winit-common = { version = "0.30.12", path = "winit-common" }
-winit-core = { version = "0.30.12", path = "winit-core" }
-winit-orbital = { version = "0.30.12", path = "winit-orbital" }
-winit-uikit = { version = "0.30.12", path = "winit-uikit" }
-winit-wayland = { version = "0.30.12", path = "winit-wayland", default-features = false }
-winit-web = { version = "0.30.12", path = "winit-web" }
-winit-win32 = { version = "0.30.12", path = "winit-win32" }
-winit-x11 = { version = "0.30.12", path = "winit-x11" }
+winit-android = { version = "=0.31.0-beta.2", path = "winit-android" }
+winit-appkit = { version = "=0.31.0-beta.2", path = "winit-appkit" }
+winit-common = { version = "=0.31.0-beta.2", path = "winit-common" }
+winit-core = { version = "=0.31.0-beta.2", path = "winit-core" }
+winit-orbital = { version = "=0.31.0-beta.2", path = "winit-orbital" }
+winit-uikit = { version = "=0.31.0-beta.2", path = "winit-uikit" }
+winit-wayland = { version = "=0.31.0-beta.2", path = "winit-wayland", default-features = false }
+winit-web = { version = "=0.31.0-beta.2", path = "winit-web" }
+winit-win32 = { version = "=0.31.0-beta.2", path = "winit-win32" }
+winit-x11 = { version = "=0.31.0-beta.2", path = "winit-x11" }
 
 # Core dependencies.
 bitflags = "2"

README.md

@@ -8,7 +8,7 @@
 
 ```toml
 [dependencies]
-winit = "0.30.12"
+winit = "0.31.0-beta.2"
 ```
 
 ## [Documentation](https://docs.rs/winit)

winit-android/src/event_loop.rs

@@ -500,10 +500,6 @@ impl EventLoop {
         input_status
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, app: A) -> Result<(), EventLoopError> {
-        self.run_app_on_demand(app)
-    }
-
     pub fn run_app_on_demand<A: ApplicationHandler>(
         &mut self,
         mut app: A,

winit-android/src/lib.rs

@@ -62,8 +62,8 @@
 //! If your application is currently based on `NativeActivity` via the `ndk-glue` crate and building
 //! with `cargo apk`, then the minimal changes would be:
 //! 1. Remove `ndk-glue` from your `Cargo.toml`
-//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.30.12",
-//!    features = [ "android-native-activity" ] }`
+//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version =
+//!    "0.31.0-beta.2", features = [ "android-native-activity" ] }`
 //! 3. Add an `android_main` entrypoint (as above), instead of using the '`[ndk_glue::main]` proc
 //!    macro from `ndk-macros` (optionally add a dependency on `android_logger` and initialize
 //!    logging as above).

winit-appkit/src/event_loop.rs

@@ -232,10 +232,6 @@ impl EventLoop {
         &self.window_target
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, app: A) -> Result<(), EventLoopError> {
-        self.run_app_on_demand(app)
-    }
-
     // NB: we don't base this on `pump_events` because for `MacOs` we can't support
     // `pump_events` elegantly (we just ask to run the loop for a "short" amount of
     // time and so a layered implementation would end up using a lot of CPU due to

winit-core/src/event_loop/mod.rs

@@ -1,4 +1,6 @@
+pub mod never_return;
 pub mod pump_events;
+pub mod register;
 pub mod run_on_demand;
 
 use std::fmt::{self, Debug};

winit-core/src/event_loop/never_return.rs

@@ -0,0 +1,14 @@
+use crate::application::ApplicationHandler;
+
+/// Additional methods on `EventLoop` for platforms whose run method never return.
+pub trait EventLoopExtNeverReturn {
+    /// Run the event loop and call `process::exit` once finished.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **iOS**: This registers the callbacks with the system and calls `UIApplicationMain`.
+    /// - **macOS**: Unimplemented (TODO: Should call `NSApplicationMain`).
+    /// - **Android/Orbital/Wayland/Windows/X11**: Unsupported.
+    /// - **Web**: Impossible to support properly.
+    fn run_app_never_return<A: ApplicationHandler + 'static>(self, app: A) -> !;
+}

winit-core/src/event_loop/register.rs

@@ -0,0 +1,17 @@
+use crate::application::ApplicationHandler;
+
+/// Additional methods on `EventLoop` that registers it with the system event loop.
+pub trait EventLoopExtRegister {
+    /// Initialize and register the application with the system's event loop, such that the
+    /// callbacks will be run later.
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **Web**: Once the event loop has been destroyed, it's possible to reinitialize another
+    ///   event loop by calling this function again. This can be useful if you want to recreate the
+    ///   event loop while the WebAssembly module is still loaded. For example, this can be used to
+    ///   recreate the event loop when switching between tabs on a single page application.
+    /// - **iOS/macOS**: Unimplemented.
+    /// - **Android/Orbital/Wayland/Windows/X11**: Unsupported.
+    fn register_app<A: ApplicationHandler + 'static>(self, app: A);
+}

winit-core/src/event_loop/run_on_demand.rs

@@ -6,15 +6,13 @@ use crate::{
     window::Window,
 };
 
-#[allow(rustdoc::broken_intra_doc_links)] // FIXME(madsmtm): Fix these.
 /// Additional methods on [`EventLoop`] to return control flow to the caller.
 pub trait EventLoopExtRunOnDemand {
     /// Run the application with the event loop on the calling thread.
     ///
     /// Unlike [`EventLoop::run_app`], this function accepts non-`'static` (i.e. non-`move`)
-    /// closures and it is possible to return control back to the caller without
-    /// consuming the `EventLoop` (by using [`exit()`]) and
-    /// so the event loop can be re-run after it has exit.
+    /// state and it is possible to return control back to the caller without consuming the
+    /// `EventLoop` (by using [`exit()`]) and so the event loop can be re-run after it has exit.
     ///
     /// It's expected that each run of the loop will be for orthogonal instantiations of your
     /// Winit application, but internally each instantiation may re-use some common window
@@ -31,8 +29,7 @@ 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 `EventLoopExtWeb::spawn_app()`[^1] more than once instead).
+    ///   to the caller (specifically this is impossible on iOS and Web).
     /// - 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
@@ -51,8 +48,6 @@ pub trait EventLoopExtRunOnDemand {
     ///   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.
     ///
-    /// [^1]: `spawn_app()` is only available on the Web platforms.
-    ///
     /// [`exit()`]: ActiveEventLoop::exit()
     /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
     fn run_app_on_demand<A: ApplicationHandler>(&mut self, app: A) -> Result<(), EventLoopError>;

winit-core/src/window.rs

@@ -1136,7 +1136,7 @@ pub trait Window: AsAny + Send + Sync + fmt::Debug {
         let action = if allowed {
             let position = LogicalPosition::new(0, 0);
             let size = LogicalSize::new(0, 0);
-            let ime_caps = ImeCapabilities::new().without_hint_and_purpose().with_cursor_area();
+            let ime_caps = ImeCapabilities::new().with_hint_and_purpose().with_cursor_area();
             let request_data = ImeRequestData {
                 hint_and_purpose: Some((ImeHint::NONE, ImePurpose::Normal)),
                 // WARNING: there's nothing sensible to use here by default.

winit-orbital/src/event_loop.rs

@@ -481,7 +481,10 @@ impl EventLoop {
         }
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, mut app: A) -> Result<(), EventLoopError> {
+    pub fn run_app_on_demand<A: ApplicationHandler>(
+        &mut self,
+        mut app: A,
+    ) -> Result<(), EventLoopError> {
         let mut start_cause = StartCause::Init;
         loop {
             app.new_events(&self.window_target, start_cause);

winit-uikit/src/event_loop.rs

@@ -238,7 +238,8 @@ impl EventLoop {
         })
     }
 
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> ! {
+    // Require `'static` for correctness, we won't be able to `Drop` the user's state otherwise.
+    pub fn run_app_never_return<A: ApplicationHandler + 'static>(self, app: A) -> ! {
         let application: Option<Retained<UIApplication>> =
             unsafe { msg_send![UIApplication::class(), sharedApplication] };
         assert!(
@@ -250,6 +251,10 @@ impl EventLoop {
 
         // We intentionally override neither the application nor the delegate,
         // to allow the user to do so themselves!
+        //
+        // NOTE: `UIApplicationMain` is _the only way_ to start the event loop on iOS/UIKit, there
+        // are no other feasible options. See also:
+        // <https://github.com/rust-windowing/winit/pull/4165#issuecomment-2760514167>
         app_state::launch(self.mtm, app, || UIApplication::main(None, None, self.mtm))
     }
 

winit-wayland/src/event_loop/mod.rs

@@ -169,10 +169,6 @@ impl EventLoop {
         Ok(event_loop)
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, app: A) -> Result<(), EventLoopError> {
-        self.run_app_on_demand(app)
-    }
-
     pub fn run_app_on_demand<A: ApplicationHandler>(
         &mut self,
         mut app: A,

winit-web/src/event_loop/mod.rs

@@ -39,32 +39,8 @@ impl EventLoop {
         EVENT_LOOP_CREATED.store(false, Ordering::Relaxed);
     }
 
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> ! {
-        let app = Box::new(app);
-
-        // SAFETY: The `transmute` is necessary because `run()` requires `'static`. This is safe
-        // because this function will never return and all resources not cleaned up by the point we
-        // `throw` will leak, making this actually `'static`.
-        let app = unsafe {
-            std::mem::transmute::<
-                Box<dyn ApplicationHandler + '_>,
-                Box<dyn ApplicationHandler + 'static>,
-            >(app)
-        };
-
-        self.elw.run(app, false);
-
-        // Throw an exception to break out of Rust execution and use unreachable to tell the
-        // compiler this function won't return, giving it a return type of '!'
-        backend::throw(
-            "Using exceptions for control flow, don't mind me. This isn't actually an error!",
-        );
-
-        unreachable!();
-    }
-
-    pub fn spawn_app<A: ApplicationHandler + 'static>(self, app: A) {
-        self.elw.run(Box::new(app), true);
+    pub fn register_app<A: ApplicationHandler + 'static>(self, app: A) {
+        self.elw.run(Box::new(app));
     }
 
     pub fn window_target(&self) -> &dyn RootActiveEventLoop {

winit-web/src/event_loop/runner.rs

@@ -48,7 +48,6 @@ struct Execution {
     exit: Cell<bool>,
     runner: RefCell<RunnerEnum>,
     suspended: Cell<bool>,
-    event_loop_recreation: Cell<bool>,
     events: RefCell<VecDeque<Event>>,
     id: Cell<usize>,
     window: web_sys::Window,
@@ -195,7 +194,6 @@ impl Shared {
                 exit: Cell::new(false),
                 runner: RefCell::new(RunnerEnum::Pending),
                 suspended: Cell::new(false),
-                event_loop_recreation: Cell::new(false),
                 events: RefCell::new(VecDeque::new()),
                 window,
                 navigator,
@@ -772,9 +770,7 @@ impl Shared {
         // * For each undropped `Window`:
         //     * The `register_redraw_request` closure.
         //     * The `destroy_fn` closure.
-        if self.0.event_loop_recreation.get() {
-            EventLoop::allow_event_loop_recreation();
-        }
+        EventLoop::allow_event_loop_recreation();
     }
 
     // Check if the event loop is currently closed
@@ -809,10 +805,6 @@ impl Shared {
         }
     }
 
-    pub fn event_loop_recreation(&self, allow: bool) {
-        self.0.event_loop_recreation.set(allow)
-    }
-
     pub(crate) fn control_flow(&self) -> ControlFlow {
         self.0.control_flow.get()
     }

winit-web/src/event_loop/window_target.rs

@@ -56,8 +56,7 @@ impl ActiveEventLoop {
         Self { runner: runner::Shared::new(), modifiers: ModifiersShared::default() }
     }
 
-    pub(crate) fn run(&self, app: Box<dyn ApplicationHandler>, event_loop_recreation: bool) {
-        self.runner.event_loop_recreation(event_loop_recreation);
+    pub(crate) fn run(&self, app: Box<dyn ApplicationHandler>) {
         self.runner.start(app, self.clone());
     }
 

winit-web/src/lib.rs

@@ -85,7 +85,6 @@ use std::task::{Context, Poll};
 use ::web_sys::HtmlCanvasElement;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
-use winit_core::application::ApplicationHandler;
 use winit_core::cursor::{CustomCursor, CustomCursorSource};
 use winit_core::error::NotSupportedError;
 use winit_core::event_loop::ActiveEventLoop;
@@ -237,30 +236,6 @@ impl Default for WindowAttributesWeb {
 
 /// Additional methods on `EventLoop` that are specific to the Web.
 pub trait EventLoopExtWeb {
-    /// Initializes the winit event loop.
-    ///
-    /// Unlike
-    #[cfg_attr(target_feature = "exception-handling", doc = "`run_app()`")]
-    #[cfg_attr(
-        not(target_feature = "exception-handling"),
-        doc = "[`run_app()`]"
-    )]
-    /// [^1], this returns immediately, and doesn't throw an exception in order to
-    /// satisfy its [`!`] return type.
-    ///
-    /// Once the event loop has been destroyed, it's possible to reinitialize another event loop
-    /// by calling this function again. This can be useful if you want to recreate the event loop
-    /// while the WebAssembly module is still loaded. For example, this can be used to recreate the
-    /// event loop when switching between tabs on a single page application.
-    #[rustfmt::skip]
-    ///
-    #[cfg_attr(
-        not(target_feature = "exception-handling"),
-        doc = "[`run_app()`]: EventLoop::run_app()"
-    )]
-    /// [^1]: `run_app()` is _not_ available on Wasm when the target supports `exception-handling`.
-    fn spawn_app<A: ApplicationHandler + 'static>(self, app: A);
-
     /// Sets the strategy for [`ControlFlow::Poll`].
     ///
     /// See [`PollStrategy`].

winit-web/src/web_sys/mod.rs

@@ -25,10 +25,6 @@ pub use self::resize_scaling::ResizeScaleHandle;
 pub use self::safe_area::SafeAreaHandle;
 pub use self::schedule::Schedule;
 
-pub fn throw(msg: &str) {
-    wasm_bindgen::throw_str(msg);
-}
-
 pub struct PageTransitionEventHandle {
     _show_listener: event_handle::EventListenerHandle<dyn FnMut(PageTransitionEvent)>,
     _hide_listener: event_handle::EventListenerHandle<dyn FnMut(PageTransitionEvent)>,

winit-win32/src/event_loop.rs

@@ -247,10 +247,6 @@ impl EventLoop {
         ActiveEventLoop::from_ref(&self.runner)
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, app: A) -> Result<(), EventLoopError> {
-        self.run_app_on_demand(app)
-    }
-
     pub fn run_app_on_demand<A: ApplicationHandler>(
         &mut self,
         mut app: A,

winit-x11/src/event_loop.rs

@@ -427,10 +427,6 @@ impl EventLoop {
         &self.event_processor.target
     }
 
-    pub fn run_app<A: ApplicationHandler>(mut self, app: A) -> Result<(), EventLoopError> {
-        self.run_app_on_demand(app)
-    }
-
     pub fn run_app_on_demand<A: ApplicationHandler>(
         &mut self,
         mut app: A,

winit/examples/run_on_demand.rs

@@ -1,7 +1,7 @@
 #![allow(clippy::single_match)]
 
 // Limit this example to only compatible platforms.
-#[cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform,))]
+#[cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform, orbital_platform))]
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     use std::time::Duration;
 
@@ -93,7 +93,13 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-#[cfg(not(any(windows_platform, macos_platform, x11_platform, wayland_platform,)))]
+#[cfg(not(any(
+    windows_platform,
+    macos_platform,
+    x11_platform,
+    wayland_platform,
+    orbital_platform
+)))]
 fn main() {
     println!("This example is not supported on this platform");
 }

winit/src/changelog/unreleased.md

@@ -39,237 +39,3 @@ The migration guide could reference other migration examples in the current
 changelog entry.
 
 ## Unreleased
-
-### Added
-
-- Add `ActiveEventLoop::create_proxy()`.
-- On Web, add `ActiveEventLoopExtWeb::is_cursor_lock_raw()` to determine if
-  `DeviceEvent::MouseMotion` is returning raw data, not OS accelerated, when using
-  `CursorGrabMode::Locked`.
-- On Web, implement `MonitorHandle` and `VideoModeHandle`.
-
-  Without prompting the user for permission, only the current monitor is returned. But when
-  prompting and being granted permission through
-  `ActiveEventLoop::request_detailed_monitor_permission()`, access to all monitors and their
-  details is available. Handles created with "detailed monitor permissions" can be used in
-  `Window::set_fullscreen()` as well.
-
-  Keep in mind that handles do not auto-upgrade after permissions are granted and have to be
-  re-created to make full use of this feature.
-- Implement `Clone`, `Copy`, `Debug`, `Deserialize`, `Eq`, `Hash`, `Ord`, `PartialEq`, `PartialOrd`
-  and `Serialize` on many types.
-- Add `MonitorHandle::current_video_mode()`.
-- Add `ApplicationHandlerExtMacOS` trait, and a `macos_handler` method to `ApplicationHandler` which returns a `dyn ApplicationHandlerExtMacOS` which allows for macOS specific extensions to winit.
-- Add a `standard_key_binding` method to the `ApplicationHandlerExtMacOS` trait. This allows handling of standard keybindings such as "go to end of line" on macOS.
-- On macOS, add `WindowExtMacOS::set_unified_titlebar` and `WindowAttributesMacOS::with_unified_titlebar`
-  to use a larger style of titlebar.
-- Add `WindowId::into_raw()` and `from_raw()`.
-- Add `PointerKind`, `PointerSource`, `ButtonSource`, `FingerId`, `primary` and `position` to all
-  pointer events as part of the pointer event overhaul.
-- Add `DeviceId::into_raw()` and `from_raw()`.
-- Added `Window::surface_position`, which is the position of the surface inside the window.
-- Added `Window::safe_area`, which describes the area of the surface that is unobstructed.
-- On X11, Wayland, Windows and macOS, improved scancode conversions for more obscure key codes.
-- Add ability to make non-activating window on macOS using `NSPanel` with `NSWindowStyleMask::NonactivatingPanel`.
-- Implement `MonitorHandleProvider` for `MonitorHandle` to access common monitor API.
-- On X11, set an "area" attribute on XIM input connection to convey the cursor area.
-- Implement `CustomCursorProvider` for `CustomCursor` to access cursor API.
-- Add `CustomCursorSource::Url`, `CustomCursorSource::from_animation`.
-- Implement `CustomIconProvider` for `RgbaIcon`.
-- Add `icon` module that exposes winit's icon API.
-- `VideoMode::new` to create a `VideoMode`.
-- `keyboard::ModifiersKey` to track which modifier is exactly pressed.
-- `ActivationToken::as_raw` to get a ref to raw token.
-- Each platform now has corresponding `WindowAttributes` struct instead of trait extension.
-- On Wayland, added implementation for `Window::set_window_icon`
-- On Wayland, added `PanGesture`, `PinchGesture`, and `RotationGesture`
-- Add `Window::request_ime_update` to atomically apply set of IME changes.
-- Add `Ime::DeleteSurrounding` to let the input method delete text.
-- Add more `ImePurpose` values.
-- Add `ImeHints` to request particular IME behaviour.
-- Add Pen input support on Wayland, Windows, and Web via new Pointer event.
-
-### Changed
-
-- Change `ActiveEventLoop` and `Window` to be traits, and added `cast_ref`/`cast_mut`/`cast`
-  methods to extract the backend type from those.
-- `ActiveEventLoop::create_window` now returns `Box<dyn Window>`.
-- `ApplicationHandler` now uses `dyn ActiveEventLoop`.
-- On Web, let events wake up event loop immediately when using `ControlFlow::Poll`.
-- Bump MSRV from `1.70` to `1.85`.
-- Changed `ApplicationHandler::user_event` to `user_wake_up`, removing the
-  generic user event.
-
-  Winit will now only indicate that wake up happened, you will have to pair
-  this with an external mechanism like `std::sync::mpsc::channel` if you want
-  to send specific data to be processed on the main thread.
-- Changed `EventLoopProxy::send_event` to `EventLoopProxy::wake_up`, it now
-  only wakes up the loop.
-- On X11, implement smooth resizing through the sync extension API.
-- `ApplicationHandler::can_create|destroy_surfaces()` was split off from
-  `ApplicationHandler::resumed/suspended()`.
-
-  `ApplicationHandler::can_create_surfaces()` should, for portability reasons
-  to Android, be the only place to create render surfaces.
-
-  `ApplicationHandler::resumed/suspended()` are now only emitted by iOS, Web
-  and Android, and now signify actually resuming/suspending the application.
-- Rename `platform::web::*ExtWebSys` to `*ExtWeb`.
-- Change signature of `EventLoop::run_app`, `EventLoopExtPumpEvents::pump_app_events` and
-  `EventLoopExtRunOnDemand::run_app_on_demand` to accept a `impl ApplicationHandler` directly,
-  instead of requiring a `&mut` reference to it.
-- On Web, `Window::canvas()` now returns a reference.
-- On Web, `CursorGrabMode::Locked` now lets `DeviceEvent::MouseMotion` return raw data, not OS
-  accelerated, if the browser supports it.
-- `(Active)EventLoop::create_custom_cursor()` now returns a `Result<CustomCursor, ExternalError>`.
-- Changed how `ModifiersState` is serialized by Serde.
-- `VideoModeHandle::refresh_rate_millihertz()` and `bit_depth()` now return a `Option<NonZero*>`.
-- `MonitorHandle::position()` now returns an `Option`.
-- On macOS, remove custom application delegates. You are now allowed to override the
-  application delegate yourself.
-- On X11, remove our dependency on libXcursor. (#3749)
-- Renamed the following APIs to make it clearer that the sizes apply to the underlying surface:
-  - `WindowEvent::Resized` to `SurfaceResized`.
-  - `InnerSizeWriter` to `SurfaceSizeWriter`.
-  - `WindowAttributes.inner_size` to `surface_size`.
-  - `WindowAttributes.min_inner_size` to `min_surface_size`.
-  - `WindowAttributes.max_inner_size` to `max_surface_size`.
-  - `WindowAttributes.resize_increments` to `surface_resize_increments`.
-  - `WindowAttributes::with_inner_size` to `with_surface_size`.
-  - `WindowAttributes::with_min_inner_size` to `with_min_surface_size`.
-  - `WindowAttributes::with_max_inner_size` to `with_max_surface_size`.
-  - `WindowAttributes::with_resize_increments` to `with_surface_resize_increments`.
-  - `Window::inner_size` to `surface_size`.
-  - `Window::request_inner_size` to `request_surface_size`.
-  - `Window::set_min_inner_size` to `set_min_surface_size`.
-  - `Window::set_max_inner_size` to `set_max_surface_size`.
-
-  To migrate, you can probably just replace all instances of `inner_size` with `surface_size` in your codebase.
-- Every event carrying a `DeviceId` now uses `Option<DeviceId>` instead. A `None` value signifies that the
-  device can't be uniquely identified.
-- Pointer `WindowEvent`s were overhauled. The new events can handle any type of pointer, serving as
-  a single pointer input source. Now your application can handle any pointer type without having to
-  explicitly handle e.g. `Touch`:
-  - Rename `CursorMoved` to `PointerMoved`.
-  - Rename `CursorEntered` to `PointerEntered`.
-  - Rename `CursorLeft` to `PointerLeft`.
-  - Rename `MouseInput` to `PointerButton`.
-  - Add `primary` to every `PointerEvent` as a way to identify discard non-primary pointers in a
-    multi-touch interaction.
-  - Add `position` to every `PointerEvent`.
-  - `PointerMoved` is **not sent** after `PointerEntered` anymore.
-  - Remove `Touch`, which is folded into the `Pointer*` events.
-  - New `PointerKind` added to `PointerEntered` and `PointerLeft`, signifying which pointer type is
-    the source of this event.
-  - New `PointerSource` added to `PointerMoved`, similar to `PointerKind` but holding additional
-    data.
-  - New `ButtonSource` added to `PointerButton`, similar to `PointerKind` but holding pointer type
-    specific buttons. Use `ButtonSource::mouse_button()` to easily normalize any pointer button
-    type to a generic mouse button.
-  - New `FingerId` added to `PointerKind::Touch` and `PointerSource::Touch` able to uniquely
-    identify a finger in a multi-touch interaction. Replaces the old `Touch::id`.
-  - In the same spirit rename `DeviceEvent::MouseMotion` to `PointerMotion`.
-  - Remove `Force::Calibrated::altitude_angle`.
-- On X11, use bottom-right corner for IME hotspot in `Window::set_ime_cursor_area`.
-- On macOS and iOS, no longer emit `ScaleFactorChanged` upon window creation.
-- On macOS, no longer emit `Focused` upon window creation.
-- On iOS, emit more events immediately, instead of queuing them.
-- Update `smol_str` to version `0.3`
-- Rename `VideoModeHandle` to `VideoMode`, now it only stores plain data.
-- Make `Fullscreen::Exclusive` contain `(MonitorHandle, VideoMode)`.
-- Reworked the file drag-and-drop API.
-- On macOS, the default menu uses the bundle name or falls back to the process name as before.
-
-  The `WindowEvent::DroppedFile`, `WindowEvent::HoveredFile` and `WindowEvent::HoveredFileCancelled`
-  events have been removed, and replaced with `WindowEvent::DragEntered`, `WindowEvent::DragMoved`,
-  `WindowEvent::DragDropped` and `WindowEvent::DragLeft`.
-
-  The old drag-and-drop events were emitted once per file. This occurred when files were *first*
-  hovered over the window, dropped, or left the window. The new drag-and-drop events are emitted
-  once per set of files dragged, and include a list of all dragged files. They also include the
-  pointer position.
-
-  The rough correspondence is:
-  - `WindowEvent::HoveredFile` -> `WindowEvent::DragEntered`
-  - `WindowEvent::DroppedFile` -> `WindowEvent::DragDropped`
-  - `WindowEvent::HoveredFileCancelled` -> `WindowEvent::DragLeft`
-
-  The `WindowEvent::DragMoved` event is entirely new, and is emitted whenever the pointer moves
-  whilst files are being dragged over the window. It doesn't contain any file paths, just the
-  pointer position.
-- Updated `objc2` to `v0.6`.
-- Updated `windows-sys` to `v0.59`.
-  - To match the corresponding changes in `windows-sys`, the `HWND`, `HMONITOR`, and `HMENU` types
-    now alias to `*mut c_void` instead of `isize`.
-- Removed `KeyEventExtModifierSupplement`, and made the fields `text_with_all_modifiers` and
-  `key_without_modifiers` public on `KeyEvent` instead.
-- Move `window::Fullscreen` to `monitor::Fullscreen`.
-- Renamed "super" key to "meta", to match the naming in the W3C specification.
-  `NamedKey::Super` still exists, but it's non-functional and deprecated, `NamedKey::Meta` should be used instead.
-- Move `IconExtWindows` into `WinIcon`.
-- Move `EventLoopExtPumpEvents` and `PumpStatus` from platform module to `winit::event_loop::pump_events`.
-- Move `EventLoopExtRunOnDemand` from platform module to `winit::event_loop::run_on_demand`.
-- Use `NamedKey`, `Code` and `Location` from the `keyboard-types` v0.8 crate.
-- Deprecate `Window::set_ime_allowed`, `Window::set_ime_cursor_area`, and `Window::set_ime_purpose`.
-- `Force::normalized()` now takes a `Option<ToolAngle>` to calculate the perpendicular force.
-- On Windows, don't confine cursor to center of window when grabbed and hidden.
-
-### Removed
-
-- Remove `Event`.
-- Remove already deprecated APIs:
-  - `EventLoop::create_window()`
-  - `EventLoop::run`.
-  - `EventLoopBuilder::new()`
-  - `EventLoopExtPumpEvents::pump_events`.
-  - `EventLoopExtRunOnDemand::run_on_demand`.
-  - `VideoMode`
-  - `WindowAttributes::new()`
-  - `Window::set_cursor_icon()`
-- On iOS, remove `platform::ios::EventLoopExtIOS` and related `platform::ios::Idiom` type.
-
-  This feature was incomplete, and the equivalent functionality can be trivially achieved outside
-  of `winit` using `objc2-ui-kit` and calling `UIDevice::currentDevice().userInterfaceIdiom()`.
-- On Web, remove unused `platform::web::CustomCursorError::Animation`.
-- Remove the `rwh_04` and `rwh_05` cargo feature and the corresponding `raw-window-handle` v0.4 and
-  v0.5 support. v0.6 remains in place and is enabled by default.
-- Remove `DeviceEvent::Added` and `DeviceEvent::Removed`.
-- Remove `DeviceEvent::Motion` and `WindowEvent::AxisMotion`.
-- Remove `MonitorHandle::size()` and `refresh_rate_millihertz()` in favor of
-  `MonitorHandle::current_video_mode()`.
-- On Android, remove all `MonitorHandle` support instead of emitting false data.
-- Remove `impl From<u64> for WindowId` and `impl From<WindowId> for u64`. Replaced with
-  `WindowId::into_raw()` and `from_raw()`.
-- Remove `dummy()` from `WindowId` and `DeviceId`.
-- Remove `WindowEvent::Touch` and `Touch` in favor of the new `PointerKind`, `PointerSource` and
- `ButtonSource` as part of the new pointer event overhaul.
-- Remove `Force::altitude_angle`.
-- Remove `Window::inner_position`, use the new `Window::surface_position` instead.
-- Remove `CustomCursorExtWeb`, use the `CustomCursorSource`.
-- Remove `CustomCursor::from_rgba`, use `CustomCursorSource` instead.
-- Remove `ApplicationHandler::exited`, the event loop being shut down can now be listened to in
-  the `Drop` impl on the application handler.
-- Remove `NamedKey::Space`, match on `Key::Character(" ")` instead.
-- Remove `PartialEq` impl for `WindowAttributes`.
-- `WindowAttributesExt*` platform extensions; use `WindowAttributes*` instead.
-- Remove `Force::Calibrated::altitude_angle` in favor of `ToolAngle::altitude`.
-
-### Fixed
-
-- On Orbital, `MonitorHandle::name()` now returns `None` instead of a dummy name.
-- On Orbital, implement `fullscreen`.
-- On iOS, fixed `SurfaceResized` and `Window::surface_size` not reporting the size of the actual surface.
-- On macOS, fixed the scancode conversion for audio volume keys.
-- On macOS, fixed the scancode conversion for `IntlBackslash`.
-- On macOS, fixed redundant `SurfaceResized` event at window creation.
-- On macOS, don't panic on monitors with unknown bit-depths.
-- On macOS, fixed crash when closing the window on macOS 26+.
-- On Windows, account for mouse wheel lines per scroll setting for `WindowEvent::MouseWheel`.
-- On Windows, `Window::theme` will return the correct theme after setting it through `Window::set_theme`.
-- On Windows, `Window::set_theme` will change the title bar color immediately now.
-- On Windows 11, prevent incorrect shifting when dragging window onto a monitor with different DPI.
-- On Windows, avoid returning `SurfaceResized` with size zero when an application is minimized. Let `Window::surface_size` return the pre-minimization window size even while minimized.
-- On Web, device events are emitted regardless of cursor type.
-- On Wayland, `axis_value120` scroll events now generate `MouseScrollDelta::LineDelta`
-- On X11, mouse scroll button events no longer cause duplicated `WindowEvent::MouseWheel` events.
-- On macOS, fixed crash when dragging non-file content onto window.

winit/src/changelog/v0.31.md

@@ -0,0 +1,252 @@
+## 0.31.0-beta.2
+
+### Added
+
+- Add `EventLoopExtRegister::register_app` for being explicit about how the event loop runs on Web.
+- Add `EventLoopExtNeverReturn::run_app_never_return` for being explicit about how the event loop runs on iOS.
+
+### Changed
+
+- On Web, avoid throwing an exception in `EventLoop::run_app`, instead preferring to return to the caller.
+  This requires passing a `'static` application to ensure that the application state will live as long as necessary.
+- On Web, the event loop can now always be re-created once it has finished running.
+
+### Fixed
+
+- Fixed panic when calling `Window::set_ime_allowed`.
+
+## 0.31.0-beta.1
+
+### Added
+
+- Add `ActiveEventLoop::create_proxy()`.
+- On Web, add `ActiveEventLoopExtWeb::is_cursor_lock_raw()` to determine if
+  `DeviceEvent::MouseMotion` is returning raw data, not OS accelerated, when using
+  `CursorGrabMode::Locked`.
+- On Web, implement `MonitorHandle` and `VideoModeHandle`.
+
+  Without prompting the user for permission, only the current monitor is returned. But when
+  prompting and being granted permission through
+  `ActiveEventLoop::request_detailed_monitor_permission()`, access to all monitors and their
+  details is available. Handles created with "detailed monitor permissions" can be used in
+  `Window::set_fullscreen()` as well.
+
+  Keep in mind that handles do not auto-upgrade after permissions are granted and have to be
+  re-created to make full use of this feature.
+- Implement `Clone`, `Copy`, `Debug`, `Deserialize`, `Eq`, `Hash`, `Ord`, `PartialEq`, `PartialOrd`
+  and `Serialize` on many types.
+- Add `MonitorHandle::current_video_mode()`.
+- Add `ApplicationHandlerExtMacOS` trait, and a `macos_handler` method to `ApplicationHandler` which returns a `dyn ApplicationHandlerExtMacOS` which allows for macOS specific extensions to winit.
+- Add a `standard_key_binding` method to the `ApplicationHandlerExtMacOS` trait. This allows handling of standard keybindings such as "go to end of line" on macOS.
+- On macOS, add `WindowExtMacOS::set_unified_titlebar` and `WindowAttributesMacOS::with_unified_titlebar`
+  to use a larger style of titlebar.
+- Add `WindowId::into_raw()` and `from_raw()`.
+- Add `PointerKind`, `PointerSource`, `ButtonSource`, `FingerId`, `primary` and `position` to all
+  pointer events as part of the pointer event overhaul.
+- Add `DeviceId::into_raw()` and `from_raw()`.
+- Added `Window::surface_position`, which is the position of the surface inside the window.
+- Added `Window::safe_area`, which describes the area of the surface that is unobstructed.
+- On X11, Wayland, Windows and macOS, improved scancode conversions for more obscure key codes.
+- Add ability to make non-activating window on macOS using `NSPanel` with `NSWindowStyleMask::NonactivatingPanel`.
+- Implement `MonitorHandleProvider` for `MonitorHandle` to access common monitor API.
+- On X11, set an "area" attribute on XIM input connection to convey the cursor area.
+- Implement `CustomCursorProvider` for `CustomCursor` to access cursor API.
+- Add `CustomCursorSource::Url`, `CustomCursorSource::from_animation`.
+- Implement `CustomIconProvider` for `RgbaIcon`.
+- Add `icon` module that exposes winit's icon API.
+- `VideoMode::new` to create a `VideoMode`.
+- `keyboard::ModifiersKey` to track which modifier is exactly pressed.
+- `ActivationToken::as_raw` to get a ref to raw token.
+- Each platform now has corresponding `WindowAttributes` struct instead of trait extension.
+- On Wayland, added implementation for `Window::set_window_icon`
+- On Wayland, added `PanGesture`, `PinchGesture`, and `RotationGesture`
+- Add `Window::request_ime_update` to atomically apply set of IME changes.
+- Add `Ime::DeleteSurrounding` to let the input method delete text.
+- Add more `ImePurpose` values.
+- Add `ImeHints` to request particular IME behaviour.
+- Add Pen input support on Wayland, Windows, and Web via new Pointer event.
+
+### Changed
+
+- Change `ActiveEventLoop` and `Window` to be traits, and added `cast_ref`/`cast_mut`/`cast`
+  methods to extract the backend type from those.
+- `ActiveEventLoop::create_window` now returns `Box<dyn Window>`.
+- `ApplicationHandler` now uses `dyn ActiveEventLoop`.
+- On Web, let events wake up event loop immediately when using `ControlFlow::Poll`.
+- Bump MSRV from `1.70` to `1.85`.
+- Changed `ApplicationHandler::user_event` to `user_wake_up`, removing the
+  generic user event.
+
+  Winit will now only indicate that wake up happened, you will have to pair
+  this with an external mechanism like `std::sync::mpsc::channel` if you want
+  to send specific data to be processed on the main thread.
+- Changed `EventLoopProxy::send_event` to `EventLoopProxy::wake_up`, it now
+  only wakes up the loop.
+- On X11, implement smooth resizing through the sync extension API.
+- `ApplicationHandler::can_create|destroy_surfaces()` was split off from
+  `ApplicationHandler::resumed/suspended()`.
+
+  `ApplicationHandler::can_create_surfaces()` should, for portability reasons
+  to Android, be the only place to create render surfaces.
+
+  `ApplicationHandler::resumed/suspended()` are now only emitted by iOS, Web
+  and Android, and now signify actually resuming/suspending the application.
+- Rename `platform::web::*ExtWebSys` to `*ExtWeb`.
+- Change signature of `EventLoop::run_app`, `EventLoopExtPumpEvents::pump_app_events` and
+  `EventLoopExtRunOnDemand::run_app_on_demand` to accept a `impl ApplicationHandler` directly,
+  instead of requiring a `&mut` reference to it.
+- On Web, `Window::canvas()` now returns a reference.
+- On Web, `CursorGrabMode::Locked` now lets `DeviceEvent::MouseMotion` return raw data, not OS
+  accelerated, if the browser supports it.
+- `(Active)EventLoop::create_custom_cursor()` now returns a `Result<CustomCursor, ExternalError>`.
+- Changed how `ModifiersState` is serialized by Serde.
+- `VideoModeHandle::refresh_rate_millihertz()` and `bit_depth()` now return a `Option<NonZero*>`.
+- `MonitorHandle::position()` now returns an `Option`.
+- On macOS, remove custom application delegates. You are now allowed to override the
+  application delegate yourself.
+- On X11, remove our dependency on libXcursor. (#3749)
+- Renamed the following APIs to make it clearer that the sizes apply to the underlying surface:
+  - `WindowEvent::Resized` to `SurfaceResized`.
+  - `InnerSizeWriter` to `SurfaceSizeWriter`.
+  - `WindowAttributes.inner_size` to `surface_size`.
+  - `WindowAttributes.min_inner_size` to `min_surface_size`.
+  - `WindowAttributes.max_inner_size` to `max_surface_size`.
+  - `WindowAttributes.resize_increments` to `surface_resize_increments`.
+  - `WindowAttributes::with_inner_size` to `with_surface_size`.
+  - `WindowAttributes::with_min_inner_size` to `with_min_surface_size`.
+  - `WindowAttributes::with_max_inner_size` to `with_max_surface_size`.
+  - `WindowAttributes::with_resize_increments` to `with_surface_resize_increments`.
+  - `Window::inner_size` to `surface_size`.
+  - `Window::request_inner_size` to `request_surface_size`.
+  - `Window::set_min_inner_size` to `set_min_surface_size`.
+  - `Window::set_max_inner_size` to `set_max_surface_size`.
+
+  To migrate, you can probably just replace all instances of `inner_size` with `surface_size` in your codebase.
+- Every event carrying a `DeviceId` now uses `Option<DeviceId>` instead. A `None` value signifies that the
+  device can't be uniquely identified.
+- Pointer `WindowEvent`s were overhauled. The new events can handle any type of pointer, serving as
+  a single pointer input source. Now your application can handle any pointer type without having to
+  explicitly handle e.g. `Touch`:
+  - Rename `CursorMoved` to `PointerMoved`.
+  - Rename `CursorEntered` to `PointerEntered`.
+  - Rename `CursorLeft` to `PointerLeft`.
+  - Rename `MouseInput` to `PointerButton`.
+  - Add `primary` to every `PointerEvent` as a way to identify discard non-primary pointers in a
+    multi-touch interaction.
+  - Add `position` to every `PointerEvent`.
+  - `PointerMoved` is **not sent** after `PointerEntered` anymore.
+  - Remove `Touch`, which is folded into the `Pointer*` events.
+  - New `PointerKind` added to `PointerEntered` and `PointerLeft`, signifying which pointer type is
+    the source of this event.
+  - New `PointerSource` added to `PointerMoved`, similar to `PointerKind` but holding additional
+    data.
+  - New `ButtonSource` added to `PointerButton`, similar to `PointerKind` but holding pointer type
+    specific buttons. Use `ButtonSource::mouse_button()` to easily normalize any pointer button
+    type to a generic mouse button.
+  - New `FingerId` added to `PointerKind::Touch` and `PointerSource::Touch` able to uniquely
+    identify a finger in a multi-touch interaction. Replaces the old `Touch::id`.
+  - In the same spirit rename `DeviceEvent::MouseMotion` to `PointerMotion`.
+  - Remove `Force::Calibrated::altitude_angle`.
+- On X11, use bottom-right corner for IME hotspot in `Window::set_ime_cursor_area`.
+- On macOS and iOS, no longer emit `ScaleFactorChanged` upon window creation.
+- On macOS, no longer emit `Focused` upon window creation.
+- On iOS, emit more events immediately, instead of queuing them.
+- Update `smol_str` to version `0.3`
+- Rename `VideoModeHandle` to `VideoMode`, now it only stores plain data.
+- Make `Fullscreen::Exclusive` contain `(MonitorHandle, VideoMode)`.
+- Reworked the file drag-and-drop API.
+- On macOS, the default menu uses the bundle name or falls back to the process name as before.
+
+  The `WindowEvent::DroppedFile`, `WindowEvent::HoveredFile` and `WindowEvent::HoveredFileCancelled`
+  events have been removed, and replaced with `WindowEvent::DragEntered`, `WindowEvent::DragMoved`,
+  `WindowEvent::DragDropped` and `WindowEvent::DragLeft`.
+
+  The old drag-and-drop events were emitted once per file. This occurred when files were *first*
+  hovered over the window, dropped, or left the window. The new drag-and-drop events are emitted
+  once per set of files dragged, and include a list of all dragged files. They also include the
+  pointer position.
+
+  The rough correspondence is:
+  - `WindowEvent::HoveredFile` -> `WindowEvent::DragEntered`
+  - `WindowEvent::DroppedFile` -> `WindowEvent::DragDropped`
+  - `WindowEvent::HoveredFileCancelled` -> `WindowEvent::DragLeft`
+
+  The `WindowEvent::DragMoved` event is entirely new, and is emitted whenever the pointer moves
+  whilst files are being dragged over the window. It doesn't contain any file paths, just the
+  pointer position.
+- Updated `objc2` to `v0.6`.
+- Updated `windows-sys` to `v0.59`.
+  - To match the corresponding changes in `windows-sys`, the `HWND`, `HMONITOR`, and `HMENU` types
+    now alias to `*mut c_void` instead of `isize`.
+- Removed `KeyEventExtModifierSupplement`, and made the fields `text_with_all_modifiers` and
+  `key_without_modifiers` public on `KeyEvent` instead.
+- Move `window::Fullscreen` to `monitor::Fullscreen`.
+- Renamed "super" key to "meta", to match the naming in the W3C specification.
+  `NamedKey::Super` still exists, but it's non-functional and deprecated, `NamedKey::Meta` should be used instead.
+- Move `IconExtWindows` into `WinIcon`.
+- Move `EventLoopExtPumpEvents` and `PumpStatus` from platform module to `winit::event_loop::pump_events`.
+- Move `EventLoopExtRunOnDemand` from platform module to `winit::event_loop::run_on_demand`.
+- Use `NamedKey`, `Code` and `Location` from the `keyboard-types` v0.8 crate.
+- Deprecate `Window::set_ime_allowed`, `Window::set_ime_cursor_area`, and `Window::set_ime_purpose`.
+- `Force::normalized()` now takes a `Option<ToolAngle>` to calculate the perpendicular force.
+- On Windows, don't confine cursor to center of window when grabbed and hidden.
+
+### Removed
+
+- Remove `Event`.
+- Remove already deprecated APIs:
+  - `EventLoop::create_window()`
+  - `EventLoop::run`.
+  - `EventLoopBuilder::new()`
+  - `EventLoopExtPumpEvents::pump_events`.
+  - `EventLoopExtRunOnDemand::run_on_demand`.
+  - `VideoMode`
+  - `WindowAttributes::new()`
+  - `Window::set_cursor_icon()`
+- On iOS, remove `platform::ios::EventLoopExtIOS` and related `platform::ios::Idiom` type.
+
+  This feature was incomplete, and the equivalent functionality can be trivially achieved outside
+  of `winit` using `objc2-ui-kit` and calling `UIDevice::currentDevice().userInterfaceIdiom()`.
+- On Web, remove unused `platform::web::CustomCursorError::Animation`.
+- Remove the `rwh_04` and `rwh_05` cargo feature and the corresponding `raw-window-handle` v0.4 and
+  v0.5 support. v0.6 remains in place and is enabled by default.
+- Remove `DeviceEvent::Added` and `DeviceEvent::Removed`.
+- Remove `DeviceEvent::Motion` and `WindowEvent::AxisMotion`.
+- Remove `MonitorHandle::size()` and `refresh_rate_millihertz()` in favor of
+  `MonitorHandle::current_video_mode()`.
+- On Android, remove all `MonitorHandle` support instead of emitting false data.
+- Remove `impl From<u64> for WindowId` and `impl From<WindowId> for u64`. Replaced with
+  `WindowId::into_raw()` and `from_raw()`.
+- Remove `dummy()` from `WindowId` and `DeviceId`.
+- Remove `WindowEvent::Touch` and `Touch` in favor of the new `PointerKind`, `PointerSource` and
+ `ButtonSource` as part of the new pointer event overhaul.
+- Remove `Force::altitude_angle`.
+- Remove `Window::inner_position`, use the new `Window::surface_position` instead.
+- Remove `CustomCursorExtWeb`, use the `CustomCursorSource`.
+- Remove `CustomCursor::from_rgba`, use `CustomCursorSource` instead.
+- Remove `ApplicationHandler::exited`, the event loop being shut down can now be listened to in
+  the `Drop` impl on the application handler.
+- Remove `NamedKey::Space`, match on `Key::Character(" ")` instead.
+- Remove `PartialEq` impl for `WindowAttributes`.
+- `WindowAttributesExt*` platform extensions; use `WindowAttributes*` instead.
+- Remove `Force::Calibrated::altitude_angle` in favor of `ToolAngle::altitude`.
+
+### Fixed
+
+- On Orbital, `MonitorHandle::name()` now returns `None` instead of a dummy name.
+- On Orbital, implement `fullscreen`.
+- On iOS, fixed `SurfaceResized` and `Window::surface_size` not reporting the size of the actual surface.
+- On macOS, fixed the scancode conversion for audio volume keys.
+- On macOS, fixed the scancode conversion for `IntlBackslash`.
+- On macOS, fixed redundant `SurfaceResized` event at window creation.
+- On macOS, don't panic on monitors with unknown bit-depths.
+- On macOS, fixed crash when closing the window on macOS 26+.
+- On Windows, account for mouse wheel lines per scroll setting for `WindowEvent::MouseWheel`.
+- On Windows, `Window::theme` will return the correct theme after setting it through `Window::set_theme`.
+- On Windows, `Window::set_theme` will change the title bar color immediately now.
+- On Windows 11, prevent incorrect shifting when dragging window onto a monitor with different DPI.
+- On Windows, avoid returning `SurfaceResized` with size zero when an application is minimized. Let `Window::surface_size` return the pre-minimization window size even while minimized.
+- On Web, device events are emitted regardless of cursor type.
+- On Wayland, `axis_value120` scroll events now generate `MouseScrollDelta::LineDelta`
+- On X11, mouse scroll button events no longer cause duplicated `WindowEvent::MouseWheel` events.
+- On macOS, fixed crash when dragging non-file content onto window.

winit/src/event_loop.rs

@@ -118,7 +118,7 @@ impl EventLoop {
         EventLoopBuilder { platform_specific: Default::default() }
     }
 
-    /// Run the application with the event loop on the calling thread.
+    /// Run the event loop with the given application on the calling thread.
     ///
     /// The `app` is dropped when the event loop is shut down.
     ///
@@ -173,35 +173,74 @@ impl EventLoop {
     /// [`ControlFlow::WaitUntil`] and life-cycle methods like [`ApplicationHandler::resumed`], but
     /// it should give you an idea of how things fit together.
     ///
-    /// ## Platform-specific
+    /// ## Returns
     ///
-    /// - **iOS:** Will never return to the caller and so values not passed to this function will
-    ///   *not* be dropped before the process exits.
-    /// - **Web:** Will _act_ as if it never returns to the caller by throwing a Javascript
-    ///   exception (that Rust doesn't see) that will also mean that the rest of the function is
-    ///   never executed and any values not passed to this function will *not* be dropped.
+    /// The semantics of this function can be a bit confusing, because the way different platforms
+    /// control their event loop varies significantly.
     ///
-    ///   Web applications are recommended to use
-    #[cfg_attr(
-        web_platform,
-        doc = "  [`EventLoopExtWeb::spawn_app()`][crate::platform::web::EventLoopExtWeb::spawn_app()]"
-    )]
-    #[cfg_attr(not(web_platform), 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.
+    /// On most platforms (Android, macOS, Orbital, X11, Wayland, Windows), this blocks the caller,
+    /// runs the event loop internally, and then returns once [`ActiveEventLoop::exit`] is called.
+    /// See [`run_app_on_demand`] for more detailed semantics.
     ///
-    ///   This function won't be available with `target_feature = "exception-handling"`.
+    /// On iOS, this will register the application handler, and then call [`UIApplicationMain`]
+    /// (which is the only way to run the system event loop), which never returns to the caller
+    /// (the process instead exits after the handler has been dropped). See also
+    /// [`run_app_never_return`].
     ///
-    /// [^1]: `spawn_app()` is only available on the Web platform.
+    /// On the web, this works by registering the application handler, and then immediately
+    /// returning to the caller. This is necessary because WebAssembly (and JavaScript) is always
+    /// executed in the context of the browser's own (internal) event loop, and thus we need to
+    /// return to avoid blocking that and allow events to later be delivered asynchronously. See
+    /// also [`register_app`].
     ///
-    /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
-    /// [`run_app()`]: Self::run_app()
+    /// If you call this function inside `fn main`, you usually do not need to think about these
+    /// details.
+    ///
+    /// [`UIApplicationMain`]: https://developer.apple.com/documentation/uikit/uiapplicationmain(_:_:_:_:)-1yub7?language=objc
+    /// [`run_app_on_demand`]: crate::event_loop::run_on_demand::EventLoopExtRunOnDemand::run_app_on_demand
+    /// [`run_app_never_return`]: crate::event_loop::never_return::EventLoopExtNeverReturn::run_app_never_return
+    /// [`register_app`]: crate::event_loop::register::EventLoopExtRegister::register_app
+    ///
+    /// ## Static
+    ///
+    /// To alleviate the issues noted above, this function requires that you pass in a `'static`
+    /// handler, to ensure that any state your application uses will be alive as long as the
+    /// application is running.
+    ///
+    /// To be clear, you should avoid doing e.g. `event_loop.run_app(&mut app)?`, and prefer
+    /// `event_loop.run_app(app)?` instead.
+    ///
+    /// If this requirement is prohibitive for you, consider using [`run_app_on_demand`] instead
+    /// (though note that this is not available on iOS and web).
     #[inline]
-    #[cfg(not(all(web_platform, target_feature = "exception-handling")))]
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> Result<(), EventLoopError> {
-        self.event_loop.run_app(app)
+    #[allow(unused_mut)]
+    pub fn run_app<A: ApplicationHandler + 'static>(
+        mut self,
+        mut app: A,
+    ) -> Result<(), EventLoopError> {
+        #[cfg(any(
+            windows_platform,
+            macos_platform,
+            android_platform,
+            orbital_platform,
+            x11_platform,
+            wayland_platform,
+        ))]
+        {
+            let result = self.event_loop.run_app_on_demand(&mut app);
+            // SAFETY: unsure that the state is dropped before the exit from the event loop.
+            drop(app);
+            result
+        }
+        #[cfg(web_platform)]
+        {
+            self.event_loop.register_app(app);
+            Ok(())
+        }
+        #[cfg(ios_platform)]
+        {
+            self.event_loop.run_app_never_return(app)
+        }
     }
 
     /// Creates an [`EventLoopProxy`] that can be used to dispatch user events
@@ -306,6 +345,7 @@ impl winit_core::event_loop::pump_events::EventLoopExtPumpEvents for EventLoop {
     windows_platform,
     macos_platform,
     android_platform,
+    orbital_platform,
     x11_platform,
     wayland_platform,
     docsrs,
@@ -316,6 +356,13 @@ impl winit_core::event_loop::run_on_demand::EventLoopExtRunOnDemand for EventLoo
     }
 }
 
+#[cfg(any(web_platform, docsrs))]
+impl winit_core::event_loop::register::EventLoopExtRegister for EventLoop {
+    fn register_app<A: ApplicationHandler + 'static>(self, app: A) {
+        self.event_loop.register_app(app)
+    }
+}
+
 #[cfg(android_platform)]
 impl winit_android::EventLoopExtAndroid for EventLoop {
     fn android_app(&self) -> &winit_android::activity::AndroidApp {
@@ -385,10 +432,6 @@ impl winit_wayland::EventLoopBuilderExtWayland for EventLoopBuilder {
 
 #[cfg(web_platform)]
 impl winit_web::EventLoopExtWeb for EventLoop {
-    fn spawn_app<A: ApplicationHandler + 'static>(self, app: A) {
-        self.event_loop.spawn_app(app);
-    }
-
     fn set_poll_strategy(&self, strategy: winit_web::PollStrategy) {
         self.event_loop.set_poll_strategy(strategy);
     }

winit/src/platform_impl/linux/mod.rs

@@ -147,10 +147,6 @@ impl EventLoop {
         }
     }
 
-    pub fn run_app<A: ApplicationHandler>(self, app: A) -> Result<(), EventLoopError> {
-        x11_or_wayland!(match self; EventLoop(evlp) => evlp.run_app(app))
-    }
-
     pub fn run_app_on_demand<A: ApplicationHandler>(
         &mut self,
         app: A,