DPI version 0.1.0

The conversion of PhysicalUnit was wrongly computed and the tests were
not running on the CI for the dpi crate, thus it was missed, even though
the test was correctly failing.

Signed-off-by: John Nunley <dev@notgull.net>
Signed-off-by: Kirill Chibisov <contact@kchibisov.com>

.github/workflows/ci.yml

@@ -17,6 +17,24 @@ jobs:
     - name: Check Formatting
       run: cargo fmt -- --check
 
+  typos:
+    name: Check for typos
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: typos-cli
+      - name: run typos
+        run: typos
+      - name: Typos info
+        if: failure()
+        run: |
+          echo 'To fix typos, please run `typos -w`'
+          echo 'To check for a diff, run `typos`'
+          echo 'You can find typos here: https://crates.io/crates/typos'
+
   tests:
     name: Test ${{ matrix.toolchain }} ${{ matrix.platform.name }}
     runs-on: ${{ matrix.platform.os }}
@@ -127,6 +145,13 @@ jobs:
     - name: Build crate
       run: cargo $CMD build $OPTIONS
 
+    # Test only on Linux x86_64, so we avoid spending unnecessary CI hours.
+    - name: Test dpi crate
+      if: >
+        contains(matrix.platform.name, 'Linux 64bit') &&
+        matrix.toolchain != '1.70.0'
+      run: cargo test -p dpi
+
     - name: Build tests
       if: >
         !contains(matrix.platform.target, 'redox') &&

CHANGELOG.md

@@ -11,6 +11,10 @@ Unreleased` header.
 
 # Unreleased
 
+- Deprecate `EventLoop::run` in favor of `EventLoop::run_app`.
+- Deprecate `EventLoopExtRunOnDemand::run_on_demand` in favor of `EventLoop::run_app_on_demand`.
+- Deprecate `EventLoopExtPumpEvents::pump_events` in favor of `EventLoopExtPumpEvents::pump_app_events`.
+- Add `ApplicationHandler<T>` trait which mimics `Event<T>`.
 - Move `dpi` types to its own crate, and re-export it from the root crate.
 - Implement `Sync` for `EventLoopProxy<T: Send>`.
 - **Breaking:** Move `Window::new` to `ActiveEventLoop::create_window` and `EventLoop::create_window` (with the latter being deprecated).
@@ -47,6 +51,17 @@ Unreleased` header.
 - **Breaking:** Removed `EventLoopBuilder::with_user_event`, the functionality is now available in `EventLoop::with_user_event`.
 - Add `Window::default_attributes` to get default `WindowAttributes`.
 - `log` has been replaced with `tracing`. The old behavior can be emulated by setting the `log` feature on the `tracing` crate.
+- On X11, fix crash due to xsettings query on systems with incomplete xsettings.
+
+# 0.29.14
+
+- On X11/Wayland, fix `text` and `text_with_all_modifiers` not being `None` during compose.
+- On Wayland, don't reapply cursor grab when unchanged.
+- On X11, fix a bug where some mouse events would be unexpectedly filtered out.
+
+# 0.29.13
+
+- On Web, fix possible crash with `ControlFlow::Wait` and `ControlFlow::WaitUntil`.
 
 # 0.29.12
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Code of Conduct
+
+The `rust-windowing` project adheres to the [Rust Code of Conduct]. This
+describes the minimum behavior expected from all contributors.
+
+[Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "winit"
-version = "0.29.12"
+version = "0.29.14"
 authors = ["The winit contributors", "Pierre Krieger <pierre.krieger1708@gmail.com>"]
 description = "Cross-platform window creation library."
 keywords = ["windowing"]
@@ -188,7 +188,7 @@ wayland-backend = { version = "0.3.0", default_features = false, features = ["cl
 wayland-client = { version = "0.31.1", optional = true }
 wayland-protocols = { version = "0.31.0", features = [ "staging"], optional = true }
 wayland-protocols-plasma = { version = "0.2.0", features = [ "client" ], optional = true }
-x11-dl = { version = "2.18.5", optional = true }
+x11-dl = { version = "2.19.1", optional = true }
 x11rb = { version = "0.13.0", default-features = false, features = ["allow-unsafe-code", "dl-libxcb", "randr", "resource_manager", "xinput", "xkb"], optional = true }
 xkbcommon-dl = "0.4.2"
 

README.md

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

dpi/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Please keep one empty line before and after all headers. (This is required for
+`git` to produce a conflict when a release is made while a PR is open and the
+PR's changelog entry would go into the wrong section).
+
+And please only add new entries to the top of this list, right below the `#
+Unreleased` header.
+
+# Unreleased
+
+# 0.1.0
+
+- Add `LogicalUnit`, `PhysicalUnit` and `PixelUnit` types and related functions.

dpi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dpi"
-version = "0.0.0"
+version = "0.1.0"
 description = "Types for handling UI scaling"
 keywords = ["DPI", "HiDPI", "scale-factor"]
 categories = ["gui"]

dpi/src/lib.rs

@@ -35,8 +35,8 @@
 //!
 //! ### Position and Size types
 //!
-//! The [`PhysicalPosition`] / [`PhysicalSize`] types correspond with the actual pixels on the
-//! device, and the [`LogicalPosition`] / [`LogicalSize`] types correspond to the physical pixels
+//! The [`PhysicalPosition`] / [`PhysicalSize`] / [`PhysicalUnit`] types correspond with the actual pixels on the
+//! device, and the [`LogicalPosition`] / [`LogicalSize`] / [`LogicalUnit`] types correspond to the physical pixels
 //! divided by the scale factor.
 //!
 //! The position and size types are generic over their exact pixel type, `P`, to allow the
@@ -128,6 +128,238 @@ pub fn validate_scale_factor(scale_factor: f64) -> bool {
     scale_factor.is_sign_positive() && scale_factor.is_normal()
 }
 
+/// A logical pixel unit.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Default, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct LogicalUnit<P>(pub P);
+
+impl<P> LogicalUnit<P> {
+    /// Represents a minimum logical unit of [`f64::MAX`].
+    pub const MIN: LogicalUnit<f64> = LogicalUnit::new(f64::MIN);
+    /// Represents a logical unit of `0_f64`.
+    pub const ZERO: LogicalUnit<f64> = LogicalUnit::new(0.0);
+    /// Represents a maximum logical unit that is equal to [`f64::MAX`].
+    pub const MAX: LogicalUnit<f64> = LogicalUnit::new(f64::MAX);
+
+    #[inline]
+    pub const fn new(v: P) -> Self {
+        LogicalUnit(v)
+    }
+}
+
+impl<P: Pixel> LogicalUnit<P> {
+    #[inline]
+    pub fn from_physical<T: Into<PhysicalUnit<X>>, X: Pixel>(
+        physical: T,
+        scale_factor: f64,
+    ) -> Self {
+        physical.into().to_logical(scale_factor)
+    }
+
+    #[inline]
+    pub fn to_physical<X: Pixel>(&self, scale_factor: f64) -> PhysicalUnit<X> {
+        assert!(validate_scale_factor(scale_factor));
+        PhysicalUnit::new(self.0.into() * scale_factor).cast()
+    }
+
+    #[inline]
+    pub fn cast<X: Pixel>(&self) -> LogicalUnit<X> {
+        LogicalUnit(self.0.cast())
+    }
+}
+
+impl<P: Pixel, X: Pixel> From<X> for LogicalUnit<P> {
+    fn from(v: X) -> LogicalUnit<P> {
+        LogicalUnit::new(v.cast())
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for u8 {
+    fn from(v: LogicalUnit<P>) -> u8 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for u16 {
+    fn from(v: LogicalUnit<P>) -> u16 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for u32 {
+    fn from(v: LogicalUnit<P>) -> u32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for i8 {
+    fn from(v: LogicalUnit<P>) -> i8 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for i16 {
+    fn from(v: LogicalUnit<P>) -> i16 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for i32 {
+    fn from(v: LogicalUnit<P>) -> i32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for f32 {
+    fn from(v: LogicalUnit<P>) -> f32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for f64 {
+    fn from(v: LogicalUnit<P>) -> f64 {
+        v.0.cast()
+    }
+}
+
+/// A physical pixel unit.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Default, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct PhysicalUnit<P>(pub P);
+
+impl<P> PhysicalUnit<P> {
+    /// Represents a minimum physical unit of [`f64::MAX`].
+    pub const MIN: LogicalUnit<f64> = LogicalUnit::new(f64::MIN);
+    /// Represents a physical unit of `0_f64`.
+    pub const ZERO: LogicalUnit<f64> = LogicalUnit::new(0.0);
+    /// Represents a maximum physical unit that is equal to [`f64::MAX`].
+    pub const MAX: LogicalUnit<f64> = LogicalUnit::new(f64::MAX);
+
+    #[inline]
+    pub const fn new(v: P) -> Self {
+        PhysicalUnit(v)
+    }
+}
+
+impl<P: Pixel> PhysicalUnit<P> {
+    #[inline]
+    pub fn from_logical<T: Into<LogicalUnit<X>>, X: Pixel>(logical: T, scale_factor: f64) -> Self {
+        logical.into().to_physical(scale_factor)
+    }
+
+    #[inline]
+    pub fn to_logical<X: Pixel>(&self, scale_factor: f64) -> LogicalUnit<X> {
+        assert!(validate_scale_factor(scale_factor));
+        LogicalUnit::new(self.0.into() / scale_factor).cast()
+    }
+
+    #[inline]
+    pub fn cast<X: Pixel>(&self) -> PhysicalUnit<X> {
+        PhysicalUnit(self.0.cast())
+    }
+}
+
+impl<P: Pixel, X: Pixel> From<X> for PhysicalUnit<P> {
+    fn from(v: X) -> PhysicalUnit<P> {
+        PhysicalUnit::new(v.cast())
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for u8 {
+    fn from(v: PhysicalUnit<P>) -> u8 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for u16 {
+    fn from(v: PhysicalUnit<P>) -> u16 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for u32 {
+    fn from(v: PhysicalUnit<P>) -> u32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for i8 {
+    fn from(v: PhysicalUnit<P>) -> i8 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for i16 {
+    fn from(v: PhysicalUnit<P>) -> i16 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for i32 {
+    fn from(v: PhysicalUnit<P>) -> i32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for f32 {
+    fn from(v: PhysicalUnit<P>) -> f32 {
+        v.0.cast()
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for f64 {
+    fn from(v: PhysicalUnit<P>) -> f64 {
+        v.0.cast()
+    }
+}
+
+/// A pixel unit that's either physical or logical.
+pub enum PixelUnit {
+    Physical(PhysicalUnit<i32>),
+    Logical(LogicalUnit<f64>),
+}
+
+impl PixelUnit {
+    /// Represents a minimum logical unit of [`f64::MAX`].
+    pub const MIN: PixelUnit = PixelUnit::Logical(LogicalUnit::new(f64::MIN));
+    /// Represents a logical unit of `0_f64`.
+    pub const ZERO: PixelUnit = PixelUnit::Logical(LogicalUnit::new(0.0));
+    /// Represents a maximum logical unit that is equal to [`f64::MAX`].
+    pub const MAX: PixelUnit = PixelUnit::Logical(LogicalUnit::new(f64::MAX));
+
+    pub fn new<S: Into<PixelUnit>>(unit: S) -> PixelUnit {
+        unit.into()
+    }
+
+    pub fn to_logical<P: Pixel>(&self, scale_factor: f64) -> LogicalUnit<P> {
+        match *self {
+            PixelUnit::Physical(unit) => unit.to_logical(scale_factor),
+            PixelUnit::Logical(unit) => unit.cast(),
+        }
+    }
+
+    pub fn to_physical<P: Pixel>(&self, scale_factor: f64) -> PhysicalUnit<P> {
+        match *self {
+            PixelUnit::Physical(unit) => unit.cast(),
+            PixelUnit::Logical(unit) => unit.to_physical(scale_factor),
+        }
+    }
+}
+
+impl<P: Pixel> From<PhysicalUnit<P>> for PixelUnit {
+    #[inline]
+    fn from(unit: PhysicalUnit<P>) -> PixelUnit {
+        PixelUnit::Physical(unit.cast())
+    }
+}
+
+impl<P: Pixel> From<LogicalUnit<P>> for PixelUnit {
+    #[inline]
+    fn from(unit: LogicalUnit<P>) -> PixelUnit {
+        PixelUnit::Logical(unit.cast())
+    }
+}
+
 /// A position represented in logical pixels.
 ///
 /// The position is stored as floats, so please be careful. Casting floats to integers truncates the
@@ -730,6 +962,43 @@ mod tests {
         assert!(!validate_scale_factor(f64::NEG_INFINITY));
     }
 
+    #[test]
+    fn test_logical_unity() {
+        let log_unit = LogicalUnit::new(1.0);
+        assert_eq!(log_unit.to_physical::<u32>(1.0), PhysicalUnit::new(1));
+        assert_eq!(log_unit.to_physical::<u32>(2.0), PhysicalUnit::new(2));
+        assert_eq!(log_unit.cast::<u32>(), LogicalUnit::new(1));
+        assert_eq!(
+            log_unit,
+            LogicalUnit::from_physical(PhysicalUnit::new(1.0), 1.0)
+        );
+        assert_eq!(
+            log_unit,
+            LogicalUnit::from_physical(PhysicalUnit::new(2.0), 2.0)
+        );
+        assert_eq!(LogicalUnit::from(2.0), LogicalUnit::new(2.0));
+
+        let x: f64 = log_unit.into();
+        assert_eq!(x, 1.0);
+    }
+
+    #[test]
+    fn test_physical_unit() {
+        assert_eq!(
+            PhysicalUnit::from_logical(LogicalUnit::new(1.0), 1.0),
+            PhysicalUnit::new(1)
+        );
+        assert_eq!(
+            PhysicalUnit::from_logical(LogicalUnit::new(2.0), 0.5),
+            PhysicalUnit::new(1)
+        );
+        assert_eq!(PhysicalUnit::from(2.0), PhysicalUnit::new(2.0,));
+        assert_eq!(PhysicalUnit::from(2.0), PhysicalUnit::new(2.0));
+
+        let x: f64 = PhysicalUnit::new(1).into();
+        assert_eq!(x, 1.0);
+    }
+
     #[test]
     fn test_logical_position() {
         let log_pos = LogicalPosition::new(1.0, 2.0);

examples/control_flow.rs

@@ -3,29 +3,30 @@
 use std::thread;
 #[cfg(not(web_platform))]
 use std::time;
+
 #[cfg(web_platform)]
 use web_time as time;
 
-use winit::{
-    event::{ElementState, Event, KeyEvent, WindowEvent},
-    event_loop::{ControlFlow, EventLoop},
-    keyboard::{Key, NamedKey},
-    window::Window,
-};
+use winit::application::ApplicationHandler;
+use winit::event::{ElementState, KeyEvent, StartCause, WindowEvent};
+use winit::event_loop::{ActiveEventLoop, ControlFlow, EventLoop};
+use winit::keyboard::{Key, NamedKey};
+use winit::window::{Window, WindowId};
 
 #[path = "util/fill.rs"]
 mod fill;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+const WAIT_TIME: time::Duration = time::Duration::from_millis(100);
+const POLL_SLEEP_TIME: time::Duration = time::Duration::from_millis(100);
+
+#[derive(Default, Debug, Clone, Copy, PartialEq, Eq)]
 enum Mode {
+    #[default]
     Wait,
     WaitUntil,
     Poll,
 }
 
-const WAIT_TIME: time::Duration = time::Duration::from_millis(100);
-const POLL_SLEEP_TIME: time::Duration = time::Duration::from_millis(100);
-
 fn main() -> Result<(), impl std::error::Error> {
     tracing_subscriber::fmt::init();
 
@@ -37,96 +38,110 @@ fn main() -> Result<(), impl std::error::Error> {
 
     let event_loop = EventLoop::new().unwrap();
 
-    let mut mode = Mode::Wait;
-    let mut request_redraw = false;
-    let mut wait_cancelled = false;
-    let mut close_requested = false;
+    let mut app = ControlFlowDemo::default();
+    event_loop.run_app(&mut app)
+}
 
-    let mut window = None;
-    event_loop.run(move |event, event_loop| {
-        use winit::event::StartCause;
+#[derive(Default)]
+struct ControlFlowDemo {
+    mode: Mode,
+    request_redraw: bool,
+    wait_cancelled: bool,
+    close_requested: bool,
+    window: Option<Window>,
+}
+
+impl ApplicationHandler for ControlFlowDemo {
+    fn new_events(&mut self, _event_loop: &ActiveEventLoop, cause: StartCause) {
+        println!("new_events: {cause:?}");
+
+        self.wait_cancelled = match cause {
+            StartCause::WaitCancelled { .. } => self.mode == Mode::WaitUntil,
+            _ => false,
+        }
+    }
+
+    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        let window_attributes = Window::default_attributes().with_title(
+            "Press 1, 2, 3 to change control flow mode. Press R to toggle redraw requests.",
+        );
+        self.window = Some(event_loop.create_window(window_attributes).unwrap());
+    }
+
+    fn window_event(
+        &mut self,
+        _event_loop: &ActiveEventLoop,
+        _window_id: WindowId,
+        event: WindowEvent,
+    ) {
         println!("{event:?}");
+
         match event {
-            Event::NewEvents(start_cause) => {
-                wait_cancelled = match start_cause {
-                    StartCause::WaitCancelled { .. } => mode == Mode::WaitUntil,
-                    _ => false,
-                }
+            WindowEvent::CloseRequested => {
+                self.close_requested = true;
             }
-            Event::Resumed => {
-                let window_attributes = Window::default_attributes().with_title(
-                    "Press 1, 2, 3 to change control flow mode. Press R to toggle redraw requests.",
-                );
-                window = Some(event_loop.create_window(window_attributes).unwrap());
-            }
-            Event::WindowEvent { event, .. } => match event {
-                WindowEvent::CloseRequested => {
-                    close_requested = true;
+            WindowEvent::KeyboardInput {
+                event:
+                    KeyEvent {
+                        logical_key: key,
+                        state: ElementState::Pressed,
+                        ..
+                    },
+                ..
+            } => match key.as_ref() {
+                // WARNING: Consider using `key_without_modifiers()` if available on your platform.
+                // See the `key_binding` example
+                Key::Character("1") => {
+                    self.mode = Mode::Wait;
+                    println!("\nmode: {:?}\n", self.mode);
                 }
-                WindowEvent::KeyboardInput {
-                    event:
-                        KeyEvent {
-                            logical_key: key,
-                            state: ElementState::Pressed,
-                            ..
-                        },
-                    ..
-                } => match key.as_ref() {
-                    // WARNING: Consider using `key_without_modifiers()` if available on your platform.
-                    // See the `key_binding` example
-                    Key::Character("1") => {
-                        mode = Mode::Wait;
-                        println!("\nmode: {mode:?}\n");
-                    }
-                    Key::Character("2") => {
-                        mode = Mode::WaitUntil;
-                        println!("\nmode: {mode:?}\n");
-                    }
-                    Key::Character("3") => {
-                        mode = Mode::Poll;
-                        println!("\nmode: {mode:?}\n");
-                    }
-                    Key::Character("r") => {
-                        request_redraw = !request_redraw;
-                        println!("\nrequest_redraw: {request_redraw}\n");
-                    }
-                    Key::Named(NamedKey::Escape) => {
-                        close_requested = true;
-                    }
-                    _ => (),
-                },
-                WindowEvent::RedrawRequested => {
-                    let window = window.as_ref().unwrap();
-                    window.pre_present_notify();
-                    fill::fill_window(window);
+                Key::Character("2") => {
+                    self.mode = Mode::WaitUntil;
+                    println!("\nmode: {:?}\n", self.mode);
+                }
+                Key::Character("3") => {
+                    self.mode = Mode::Poll;
+                    println!("\nmode: {:?}\n", self.mode);
+                }
+                Key::Character("r") => {
+                    self.request_redraw = !self.request_redraw;
+                    println!("\nrequest_redraw: {}\n", self.request_redraw);
+                }
+                Key::Named(NamedKey::Escape) => {
+                    self.close_requested = true;
                 }
                 _ => (),
             },
-            Event::AboutToWait => {
-                if request_redraw && !wait_cancelled && !close_requested {
-                    window.as_ref().unwrap().request_redraw();
-                }
-
-                match mode {
-                    Mode::Wait => event_loop.set_control_flow(ControlFlow::Wait),
-                    Mode::WaitUntil => {
-                        if !wait_cancelled {
-                            event_loop.set_control_flow(ControlFlow::WaitUntil(
-                                time::Instant::now() + WAIT_TIME,
-                            ));
-                        }
-                    }
-                    Mode::Poll => {
-                        thread::sleep(POLL_SLEEP_TIME);
-                        event_loop.set_control_flow(ControlFlow::Poll);
-                    }
-                };
-
-                if close_requested {
-                    event_loop.exit();
-                }
+            WindowEvent::RedrawRequested => {
+                let window = self.window.as_ref().unwrap();
+                window.pre_present_notify();
+                fill::fill_window(window);
             }
             _ => (),
         }
-    })
+    }
+
+    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
+        if self.request_redraw && !self.wait_cancelled && !self.close_requested {
+            self.window.as_ref().unwrap().request_redraw();
+        }
+
+        match self.mode {
+            Mode::Wait => event_loop.set_control_flow(ControlFlow::Wait),
+            Mode::WaitUntil => {
+                if !self.wait_cancelled {
+                    event_loop
+                        .set_control_flow(ControlFlow::WaitUntil(time::Instant::now() + WAIT_TIME));
+                }
+            }
+            Mode::Poll => {
+                thread::sleep(POLL_SLEEP_TIME);
+                event_loop.set_control_flow(ControlFlow::Poll);
+            }
+        };
+
+        if self.close_requested {
+            event_loop.exit();
+        }
+    }
 }

examples/pump_events.rs

@@ -11,50 +11,59 @@
 fn main() -> std::process::ExitCode {
     use std::{process::ExitCode, thread::sleep, time::Duration};
 
-    use winit::{
-        event::{Event, WindowEvent},
-        event_loop::EventLoop,
-        platform::pump_events::{EventLoopExtPumpEvents, PumpStatus},
-        window::Window,
-    };
+    use winit::application::ApplicationHandler;
+    use winit::event::WindowEvent;
+    use winit::event_loop::{ActiveEventLoop, EventLoop};
+    use winit::platform::pump_events::{EventLoopExtPumpEvents, PumpStatus};
+    use winit::window::{Window, WindowId};
 
     #[path = "util/fill.rs"]
     mod fill;
 
+    #[derive(Default)]
+    struct PumpDemo {
+        window: Option<Window>,
+    }
+
+    impl ApplicationHandler for PumpDemo {
+        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+            let window_attributes = Window::default_attributes().with_title("A fantastic window!");
+            self.window = Some(event_loop.create_window(window_attributes).unwrap());
+        }
+
+        fn window_event(
+            &mut self,
+            event_loop: &ActiveEventLoop,
+            _window_id: WindowId,
+            event: WindowEvent,
+        ) {
+            println!("{event:?}");
+
+            let window = match self.window.as_ref() {
+                Some(window) => window,
+                None => return,
+            };
+
+            match event {
+                WindowEvent::CloseRequested => event_loop.exit(),
+                WindowEvent::RedrawRequested => {
+                    fill::fill_window(window);
+                    window.request_redraw();
+                }
+                _ => (),
+            }
+        }
+    }
+
     let mut event_loop = EventLoop::new().unwrap();
 
     tracing_subscriber::fmt::init();
 
-    let mut window = None;
+    let mut app = PumpDemo::default();
 
     loop {
         let timeout = Some(Duration::ZERO);
-        let status = event_loop.pump_events(timeout, |event, event_loop| {
-            if let Event::WindowEvent { event, .. } = &event {
-                // Print only Window events to reduce noise
-                println!("{event:?}");
-            }
-
-            match event {
-                Event::Resumed => {
-                    let window_attributes =
-                        Window::default_attributes().with_title("A fantastic window!");
-                    window = Some(event_loop.create_window(window_attributes).unwrap());
-                }
-                Event::WindowEvent { event, .. } => {
-                    let window = window.as_ref().unwrap();
-                    match event {
-                        WindowEvent::CloseRequested => event_loop.exit(),
-                        WindowEvent::RedrawRequested => fill::fill_window(window),
-                        _ => (),
-                    }
-                }
-                Event::AboutToWait => {
-                    window.as_ref().unwrap().request_redraw();
-                }
-                _ => (),
-            }
-        });
+        let status = event_loop.pump_app_events(timeout, &mut app);
 
         if let PumpStatus::Exit(exit_code) = status {
             break ExitCode::from(exit_code as u8);

examples/run_on_demand.rs

@@ -2,86 +2,94 @@
 
 // Limit this example to only compatible platforms.
 #[cfg(any(windows_platform, macos_platform, x11_platform, wayland_platform,))]
-fn main() -> Result<(), impl std::error::Error> {
+fn main() -> Result<(), Box<dyn std::error::Error>> {
     use std::time::Duration;
 
-    use winit::{
-        error::EventLoopError,
-        event::{Event, WindowEvent},
-        event_loop::EventLoop,
-        platform::run_on_demand::EventLoopExtRunOnDemand,
-        window::{Window, WindowId},
-    };
+    use winit::application::ApplicationHandler;
+    use winit::event::WindowEvent;
+    use winit::event_loop::{ActiveEventLoop, EventLoop};
+    use winit::platform::run_on_demand::EventLoopExtRunOnDemand;
+    use winit::window::{Window, WindowId};
 
     #[path = "util/fill.rs"]
     mod fill;
 
     #[derive(Default)]
     struct App {
+        idx: usize,
         window_id: Option<WindowId>,
         window: Option<Window>,
     }
 
-    tracing_subscriber::fmt::init();
-    let mut event_loop = EventLoop::new().unwrap();
-
-    fn run_app(event_loop: &mut EventLoop<()>, idx: usize) -> Result<(), EventLoopError> {
-        let mut app = App::default();
-
-        event_loop.run_on_demand(move |event, event_loop| {
-            println!("Run {idx}: {:?}", event);
-
-            if let Some(window) = &app.window {
-                match event {
-                    Event::WindowEvent {
-                        event: WindowEvent::CloseRequested,
-                        window_id,
-                    } if window.id() == window_id => {
-                        println!("--------------------------------------------------------- Window {idx} CloseRequested");
-                        fill::cleanup_window(window);
-                        app.window = None;
-                    }
-                    Event::AboutToWait => window.request_redraw(),
-                    Event::WindowEvent {
-                        event: WindowEvent::RedrawRequested,
-                        ..
-                    }  => {
-                        fill::fill_window(window);
-                    }
-                    _ => (),
-                }
-            } else if let Some(id) = app.window_id {
-                match event {
-                    Event::WindowEvent {
-                        event: WindowEvent::Destroyed,
-                        window_id,
-                    } if id == window_id => {
-                        println!("--------------------------------------------------------- Window {idx} Destroyed");
-                        app.window_id = None;
-                        event_loop.exit();
-                    }
-                    _ => (),
-                }
-            } else if let Event::Resumed = event {
-                let window_attributes = Window::default_attributes()
-                        .with_title("Fantastic window number one!")
-                        .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0));
-                let window = event_loop.create_window(window_attributes).unwrap();
-                app.window_id = Some(window.id());
-                app.window = Some(window);
+    impl ApplicationHandler for App {
+        fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {
+            if let Some(window) = self.window.as_ref() {
+                window.request_redraw();
             }
-        })
+        }
+
+        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+            let window_attributes = Window::default_attributes()
+                .with_title("Fantastic window number one!")
+                .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0));
+            let window = event_loop.create_window(window_attributes).unwrap();
+            self.window_id = Some(window.id());
+            self.window = Some(window);
+        }
+
+        fn window_event(
+            &mut self,
+            event_loop: &ActiveEventLoop,
+            window_id: WindowId,
+            event: WindowEvent,
+        ) {
+            if event == WindowEvent::Destroyed && self.window_id == Some(window_id) {
+                println!(
+                    "--------------------------------------------------------- Window {} Destroyed",
+                    self.idx
+                );
+                self.window_id = None;
+                event_loop.exit();
+                return;
+            }
+
+            let window = match self.window.as_mut() {
+                Some(window) => window,
+                None => return,
+            };
+
+            match event {
+                WindowEvent::CloseRequested => {
+                    println!("--------------------------------------------------------- Window {} CloseRequested", self.idx);
+                    fill::cleanup_window(window);
+                    self.window = None;
+                }
+                WindowEvent::RedrawRequested => {
+                    fill::fill_window(window);
+                }
+                _ => (),
+            }
+        }
     }
 
-    run_app(&mut event_loop, 1)?;
+    tracing_subscriber::fmt::init();
+
+    let mut event_loop = EventLoop::new().unwrap();
+
+    let mut app = App {
+        idx: 1,
+        ..Default::default()
+    };
+    event_loop.run_app_on_demand(&mut app)?;
 
     println!("--------------------------------------------------------- Finished first loop");
     println!("--------------------------------------------------------- Waiting 5 seconds");
     std::thread::sleep(Duration::from_secs(5));
 
-    let ret = run_app(&mut event_loop, 2);
+    app.idx += 1;
+    event_loop.run_app_on_demand(&mut app)?;
     println!("--------------------------------------------------------- Finished second loop");
-    ret
+    Ok(())
 }
 
 #[cfg(not(any(windows_platform, macos_platform, x11_platform, wayland_platform,)))]

examples/window.rs

@@ -14,8 +14,9 @@ use rwh_05::HasRawDisplayHandle;
 #[cfg(not(any(android_platform, ios_platform)))]
 use softbuffer::{Context, Surface};
 
+use winit::application::ApplicationHandler;
 use winit::dpi::{LogicalSize, PhysicalPosition, PhysicalSize};
-use winit::event::{DeviceEvent, DeviceId, Event, Ime, WindowEvent};
+use winit::event::{DeviceEvent, DeviceId, Ime, WindowEvent};
 use winit::event::{MouseButton, MouseScrollDelta};
 use winit::event_loop::{ActiveEventLoop, EventLoop};
 use winit::keyboard::{Key, ModifiersState};
@@ -53,38 +54,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let mut state = Application::new(&event_loop);
 
-    event_loop.run(move |event, event_loop| match event {
-        Event::NewEvents(_) => (),
-        Event::Resumed => {
-            println!("Resumed the event loop");
-            state.dump_monitors(event_loop);
-
-            // Create initial window.
-            state
-                .create_window(event_loop, None)
-                .expect("failed to create initial window");
-
-            state.print_help();
-        }
-        Event::AboutToWait => {
-            if state.windows.is_empty() {
-                println!("No windows left, exiting...");
-                event_loop.exit();
-            }
-        }
-        Event::WindowEvent { window_id, event } => {
-            state.handle_window_event(event_loop, window_id, event)
-        }
-        Event::DeviceEvent { device_id, event } => {
-            state.handle_device_event(event_loop, device_id, event)
-        }
-        Event::UserEvent(event) => {
-            println!("User event: {event:?}");
-        }
-        Event::Suspended | Event::LoopExiting | Event::MemoryWarning => (),
-    })?;
-
-    Ok(())
+    event_loop.run_app(&mut state).map_err(Into::into)
 }
 
 #[allow(dead_code)]
@@ -104,15 +74,14 @@ struct Application {
     ///
     /// With OpenGL it could be EGLDisplay.
     #[cfg(not(any(android_platform, ios_platform)))]
-    context: Context,
+    context: Option<Context>,
 }
 
 impl Application {
     fn new<T>(event_loop: &EventLoop<T>) -> Self {
-        // SAFETY: the context is dropped inside the loop, since the state we're using
-        // is moved inside the closure.
+        // SAFETY: we drop the context right before the event loop is stopped, thus making it safe.
         #[cfg(not(any(android_platform, ios_platform)))]
-        let context = unsafe { Context::from_raw(event_loop.raw_display_handle()).unwrap() };
+        let context = Some(unsafe { Context::from_raw(event_loop.raw_display_handle()).unwrap() });
 
         // You'll have to choose an icon size at your own discretion. On X11, the desired size varies
         // by WM, and on Windows, you still have to account for screen scaling. Here we use 32px,
@@ -227,7 +196,97 @@ impl Application {
         }
     }
 
-    fn handle_window_event(
+    fn dump_monitors(&self, event_loop: &ActiveEventLoop) {
+        println!("Monitors information");
+        let primary_monitor = event_loop.primary_monitor();
+        for monitor in event_loop.available_monitors() {
+            let intro = if primary_monitor.as_ref() == Some(&monitor) {
+                "Primary monitor"
+            } else {
+                "Monitor"
+            };
+
+            if let Some(name) = monitor.name() {
+                println!("{intro}: {name}");
+            } else {
+                println!("{intro}: [no name]");
+            }
+
+            let PhysicalSize { width, height } = monitor.size();
+            print!("  Current mode: {width}x{height}");
+            if let Some(m_hz) = monitor.refresh_rate_millihertz() {
+                println!(" @ {}.{} Hz", m_hz / 1000, m_hz % 1000);
+            } else {
+                println!();
+            }
+
+            let PhysicalPosition { x, y } = monitor.position();
+            println!("  Position: {x},{y}");
+
+            println!("  Scale factor: {}", monitor.scale_factor());
+
+            println!("  Available modes (width x height x bit-depth):");
+            for mode in monitor.video_modes() {
+                let PhysicalSize { width, height } = mode.size();
+                let bits = mode.bit_depth();
+                let m_hz = mode.refresh_rate_millihertz();
+                println!(
+                    "    {width}x{height}x{bits} @ {}.{} Hz",
+                    m_hz / 1000,
+                    m_hz % 1000
+                );
+            }
+        }
+    }
+
+    /// Process the key binding.
+    fn process_key_binding(key: &str, mods: &ModifiersState) -> Option<Action> {
+        KEY_BINDINGS.iter().find_map(|binding| {
+            binding
+                .is_triggered_by(&key, mods)
+                .then_some(binding.action)
+        })
+    }
+
+    /// Process mouse binding.
+    fn process_mouse_binding(button: MouseButton, mods: &ModifiersState) -> Option<Action> {
+        MOUSE_BINDINGS.iter().find_map(|binding| {
+            binding
+                .is_triggered_by(&button, mods)
+                .then_some(binding.action)
+        })
+    }
+
+    fn print_help(&self) {
+        println!("Keyboard bindings:");
+        for binding in KEY_BINDINGS {
+            println!(
+                "{}{:<10} - {} ({})",
+                modifiers_to_string(binding.mods),
+                binding.trigger,
+                binding.action,
+                binding.action.help(),
+            );
+        }
+        println!("Mouse bindings:");
+        for binding in MOUSE_BINDINGS {
+            println!(
+                "{}{:<10} - {} ({})",
+                modifiers_to_string(binding.mods),
+                mouse_button_to_string(binding.trigger),
+                binding.action,
+                binding.action.help(),
+            );
+        }
+    }
+}
+
+impl ApplicationHandler<UserEvent> for Application {
+    fn user_event(&mut self, _event_loop: &ActiveEventLoop, event: UserEvent) {
+        println!("User event: {event:?}");
+    }
+
+    fn window_event(
         &mut self,
         event_loop: &ActiveEventLoop,
         window_id: WindowId,
@@ -333,7 +392,7 @@ impl Application {
                     println!("Preedit: {}, with caret at {:?}", text, caret_pos);
                 }
                 Ime::Commit(text) => {
-                    println!("Commited: {}", text);
+                    println!("Committed: {}", text);
                 }
                 Ime::Disabled => println!("IME disabled for Window={window_id:?}"),
             },
@@ -371,92 +430,37 @@ impl Application {
         }
     }
 
-    fn handle_device_event(&mut self, _: &ActiveEventLoop, _: DeviceId, event: DeviceEvent) {
-        println!("Device event: {event:?}");
+    fn device_event(
+        &mut self,
+        _event_loop: &ActiveEventLoop,
+        device_id: DeviceId,
+        event: DeviceEvent,
+    ) {
+        println!("Device {device_id:?} event: {event:?}");
     }
 
-    fn dump_monitors(&self, event_loop: &ActiveEventLoop) {
-        println!("Monitors information");
-        let primary_monitor = event_loop.primary_monitor();
-        for monitor in event_loop.available_monitors() {
-            let intro = if primary_monitor.as_ref() == Some(&monitor) {
-                "Primary monitor"
-            } else {
-                "Monitor"
-            };
+    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        println!("Resumed the event loop");
+        self.dump_monitors(event_loop);
 
-            if let Some(name) = monitor.name() {
-                println!("{intro}: {name}");
-            } else {
-                println!("{intro}: [no name]");
-            }
+        // Create initial window.
+        self.create_window(event_loop, None)
+            .expect("failed to create initial window");
 
-            let PhysicalSize { width, height } = monitor.size();
-            print!("  Current mode: {width}x{height}");
-            if let Some(m_hz) = monitor.refresh_rate_millihertz() {
-                println!(" @ {}.{} Hz", m_hz / 1000, m_hz % 1000);
-            } else {
-                println!();
-            }
+        self.print_help();
+    }
 
-            let PhysicalPosition { x, y } = monitor.position();
-            println!("  Position: {x},{y}");
-
-            println!("  Scale factor: {}", monitor.scale_factor());
-
-            println!("  Available modes (width x height x bit-depth):");
-            for mode in monitor.video_modes() {
-                let PhysicalSize { width, height } = mode.size();
-                let bits = mode.bit_depth();
-                let m_hz = mode.refresh_rate_millihertz();
-                println!(
-                    "    {width}x{height}x{bits} @ {}.{} Hz",
-                    m_hz / 1000,
-                    m_hz % 1000
-                );
-            }
+    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
+        if self.windows.is_empty() {
+            println!("No windows left, exiting...");
+            event_loop.exit();
         }
     }
 
-    /// Process the key binding.
-    fn process_key_binding(key: &str, mods: &ModifiersState) -> Option<Action> {
-        KEY_BINDINGS.iter().find_map(|binding| {
-            binding
-                .is_triggered_by(&key, mods)
-                .then_some(binding.action)
-        })
-    }
-
-    /// Process mouse binding.
-    fn process_mouse_binding(button: MouseButton, mods: &ModifiersState) -> Option<Action> {
-        MOUSE_BINDINGS.iter().find_map(|binding| {
-            binding
-                .is_triggered_by(&button, mods)
-                .then_some(binding.action)
-        })
-    }
-
-    fn print_help(&self) {
-        println!("Keyboard bindings:");
-        for binding in KEY_BINDINGS {
-            println!(
-                "{}{:<10} - {} ({})",
-                modifiers_to_string(binding.mods),
-                binding.trigger,
-                binding.action,
-                binding.action.help(),
-            );
-        }
-        println!("Mouse bindings:");
-        for binding in MOUSE_BINDINGS {
-            println!(
-                "{}{:<10} - {} ({})",
-                modifiers_to_string(binding.mods),
-                mouse_button_to_string(binding.trigger),
-                binding.action,
-                binding.action.help(),
-            );
-        }
+    #[cfg(not(any(android_platform, ios_platform)))]
+    fn exiting(&mut self, _event_loop: &ActiveEventLoop) {
+        // We must drop the context here.
+        self.context = None;
     }
 }
 
@@ -496,11 +500,11 @@ struct WindowState {
 }
 
 impl WindowState {
-    fn new(application: &Application, window: Window) -> Result<Self, Box<dyn Error>> {
+    fn new(app: &Application, window: Window) -> Result<Self, Box<dyn Error>> {
         // SAFETY: the surface is dropped before the `window` which provided it with handle, thus
         // it doesn't outlive it.
         #[cfg(not(any(android_platform, ios_platform)))]
-        let surface = unsafe { Surface::new(&application.context, &window)? };
+        let surface = unsafe { Surface::new(app.context.as_ref().unwrap(), &window)? };
 
         let theme = window.theme().unwrap_or(Theme::Dark);
         println!("Theme: {theme:?}");
@@ -515,7 +519,7 @@ impl WindowState {
         let mut state = Self {
             #[cfg(macos_platform)]
             option_as_alt: window.option_as_alt(),
-            custom_idx: application.custom_cursors.len() - 1,
+            custom_idx: app.custom_cursors.len() - 1,
             cursor_grab: CursorGrabMode::None,
             named_idx,
             #[cfg(not(any(android_platform, ios_platform)))]

examples/x11_embed.rs

@@ -3,16 +3,52 @@ use std::error::Error;
 
 #[cfg(x11_platform)]
 fn main() -> Result<(), Box<dyn Error>> {
-    use winit::{
-        event::{Event, WindowEvent},
-        event_loop::EventLoop,
-        platform::x11::WindowAttributesExtX11,
-        window::Window,
-    };
+    use winit::application::ApplicationHandler;
+    use winit::event::WindowEvent;
+    use winit::event_loop::{ActiveEventLoop, EventLoop};
+    use winit::platform::x11::WindowAttributesExtX11;
+    use winit::window::{Window, WindowId};
 
     #[path = "util/fill.rs"]
     mod fill;
 
+    pub struct XEmbedDemo {
+        parent_window_id: u32,
+        window: Option<Window>,
+    }
+
+    impl ApplicationHandler for XEmbedDemo {
+        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+            let window_attributes = Window::default_attributes()
+                .with_title("An embedded window!")
+                .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0))
+                .with_embed_parent_window(self.parent_window_id);
+
+            self.window = Some(event_loop.create_window(window_attributes).unwrap());
+        }
+
+        fn window_event(
+            &mut self,
+            event_loop: &ActiveEventLoop,
+            _window_id: WindowId,
+            event: WindowEvent,
+        ) {
+            let window = self.window.as_ref().unwrap();
+            match event {
+                WindowEvent::CloseRequested => event_loop.exit(),
+                WindowEvent::RedrawRequested => {
+                    window.pre_present_notify();
+                    fill::fill_window(window);
+                }
+                _ => (),
+            }
+        }
+
+        fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {
+            self.window.as_ref().unwrap().request_redraw();
+        }
+    }
+
     // First argument should be a 32-bit X11 window ID.
     let parent_window_id = std::env::args()
         .nth(1)
@@ -22,35 +58,11 @@ fn main() -> Result<(), Box<dyn Error>> {
     tracing_subscriber::fmt::init();
     let event_loop = EventLoop::new()?;
 
-    let mut window = None;
-    event_loop.run(move |event, event_loop| match event {
-        Event::Resumed => {
-            let window_attributes = Window::default_attributes()
-                .with_title("An embedded window!")
-                .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0))
-                .with_embed_parent_window(parent_window_id);
-
-            window = Some(event_loop.create_window(window_attributes).unwrap());
-        }
-        Event::WindowEvent { event, .. } => {
-            let window = window.as_ref().unwrap();
-
-            match event {
-                WindowEvent::CloseRequested => event_loop.exit(),
-                WindowEvent::RedrawRequested => {
-                    window.pre_present_notify();
-                    fill::fill_window(window);
-                }
-                _ => (),
-            }
-        }
-        Event::AboutToWait => {
-            window.as_ref().unwrap().request_redraw();
-        }
-        _ => (),
-    })?;
-
-    Ok(())
+    let mut app = XEmbedDemo {
+        parent_window_id,
+        window: None,
+    };
+    event_loop.run_app(&mut app).map_err(Into::into)
 }
 
 #[cfg(not(x11_platform))]

src/application.rs

@@ -0,0 +1,221 @@
+//! End user application handling.
+
+use crate::event::{DeviceEvent, DeviceId, StartCause, WindowEvent};
+use crate::event_loop::ActiveEventLoop;
+use crate::window::WindowId;
+
+/// The handler of the application events.
+pub trait ApplicationHandler<T: 'static = ()> {
+    /// Emitted when new events arrive from the OS to be processed.
+    ///
+    /// This is a useful place to put code that should be done before you start processing
+    /// events, such as updating frame timing information for benchmarking or checking the
+    /// [`StartCause`] to see if a timer set by
+    /// [`ControlFlow::WaitUntil`](crate::event_loop::ControlFlow::WaitUntil) has elapsed.
+    fn new_events(&mut self, event_loop: &ActiveEventLoop, cause: StartCause) {
+        let _ = (event_loop, cause);
+    }
+
+    /// Emitted when the application has been resumed.
+    ///
+    /// For consistency, all platforms emit a `Resumed` event even if they don't themselves have a
+    /// formal suspend/resume lifecycle. For systems without a formal suspend/resume lifecycle
+    /// the `Resumed` event is always emitted after the [`NewEvents(StartCause::Init)`][StartCause::Init]
+    /// event.
+    ///
+    /// # Portability
+    ///
+    /// It's recommended that applications should only initialize their graphics context and create
+    /// a window after they have received their first `Resumed` event. Some systems
+    /// (specifically Android) won't allow applications to create a render surface until they are
+    /// resumed.
+    ///
+    /// Considering that the implementation of [`Suspended`] and `Resumed` events may be internally
+    /// driven by multiple platform-specific events, and that there may be subtle differences across
+    /// platforms with how these internal events are delivered, it's recommended that applications
+    /// be able to gracefully handle redundant (i.e. back-to-back) [`Suspended`] or `Resumed` events.
+    ///
+    /// Also see [`Suspended`] notes.
+    ///
+    /// ## Android
+    ///
+    /// On Android, the `Resumed` event is sent when a new [`SurfaceView`] has been created. This is
+    /// expected to closely correlate with the [`onResume`] lifecycle event but there may technically
+    /// be a discrepancy.
+    ///
+    /// [`onResume`]: https://developer.android.com/reference/android/app/Activity#onResume()
+    ///
+    /// Applications that need to run on Android must wait until they have been `Resumed`
+    /// before they will be able to create a render surface (such as an `EGLSurface`,
+    /// [`VkSurfaceKHR`] or [`wgpu::Surface`]) which depend on having a
+    /// [`SurfaceView`]. Applications must also assume that if they are [`Suspended`], then their
+    /// render surfaces are invalid and should be dropped.
+    ///
+    /// Also see [`Suspended`] notes.
+    ///
+    /// [`SurfaceView`]: https://developer.android.com/reference/android/view/SurfaceView
+    /// [Activity lifecycle]: https://developer.android.com/guide/components/activities/activity-lifecycle
+    /// [`VkSurfaceKHR`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkSurfaceKHR.html
+    /// [`wgpu::Surface`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html
+    ///
+    /// ## iOS
+    ///
+    /// On iOS, the `Resumed` event is emitted in response to an [`applicationDidBecomeActive`]
+    /// callback which means the application is "active" (according to the
+    /// [iOS application lifecycle]).
+    ///
+    /// [`applicationDidBecomeActive`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622956-applicationdidbecomeactive
+    /// [iOS application lifecycle]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle
+    ///
+    /// ## Web
+    ///
+    /// On Web, the `Resumed` event is emitted in response to a [`pageshow`] event
+    /// with the property [`persisted`] being true, which means that the page is being
+    /// restored from the [`bfcache`] (back/forward cache) - an in-memory cache that
+    /// stores a complete snapshot of a page (including the JavaScript heap) as the
+    /// user is navigating away.
+    ///
+    /// [`pageshow`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/pageshow_event
+    /// [`persisted`]: https://developer.mozilla.org/en-US/docs/Web/API/PageTransitionEvent/persisted
+    /// [`bfcache`]: https://web.dev/bfcache/
+    /// [`Suspended`]: Self::suspended
+    fn resumed(&mut self, event_loop: &ActiveEventLoop);
+
+    /// Emitted when an event is sent from [`EventLoopProxy::send_event`].
+    ///
+    /// [`EventLoopProxy::send_event`]: crate::event_loop::EventLoopProxy::send_event
+    fn user_event(&mut self, event_loop: &ActiveEventLoop, event: T) {
+        let _ = (event_loop, event);
+    }
+
+    /// Emitted when the OS sends an event to a winit window.
+    fn window_event(
+        &mut self,
+        event_loop: &ActiveEventLoop,
+        window_id: WindowId,
+        event: WindowEvent,
+    );
+
+    /// Emitted when the OS sends an event to a device.
+    fn device_event(
+        &mut self,
+        event_loop: &ActiveEventLoop,
+        device_id: DeviceId,
+        event: DeviceEvent,
+    ) {
+        let _ = (event_loop, device_id, event);
+    }
+
+    /// Emitted when the event loop is about to block and wait for new events.
+    ///
+    /// Most applications shouldn't need to hook into this event since there is no real relationship
+    /// between how often the event loop needs to wake up and the dispatching of any specific events.
+    ///
+    /// High frequency event sources, such as input devices could potentially lead to lots of wake
+    /// ups and also lots of corresponding `AboutToWait` events.
+    ///
+    /// This is not an ideal event to drive application rendering from and instead applications
+    /// should render in response to [`WindowEvent::RedrawRequested`] events.
+    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
+        let _ = event_loop;
+    }
+
+    /// Emitted when the application has been suspended.
+    ///
+    /// # Portability
+    ///
+    /// Not all platforms support the notion of suspending applications, and there may be no
+    /// technical way to guarantee being able to emit a `Suspended` event if the OS has
+    /// no formal application lifecycle (currently only Android, iOS, and Web do). For this reason,
+    /// Winit does not currently try to emit pseudo `Suspended` events before the application
+    /// quits on platforms without an application lifecycle.
+    ///
+    /// Considering that the implementation of `Suspended` and [`Resumed`] events may be internally
+    /// driven by multiple platform-specific events, and that there may be subtle differences across
+    /// platforms with how these internal events are delivered, it's recommended that applications
+    /// be able to gracefully handle redundant (i.e. back-to-back) `Suspended` or [`Resumed`] events.
+    ///
+    /// Also see [`Resumed`] notes.
+    ///
+    /// ## Android
+    ///
+    /// On Android, the `Suspended` event is only sent when the application's associated
+    /// [`SurfaceView`] is destroyed. This is expected to closely correlate with the [`onPause`]
+    /// lifecycle event but there may technically be a discrepancy.
+    ///
+    /// [`onPause`]: https://developer.android.com/reference/android/app/Activity#onPause()
+    ///
+    /// Applications that need to run on Android should assume their [`SurfaceView`] has been
+    /// destroyed, which indirectly invalidates any existing render surfaces that may have been
+    /// created outside of Winit (such as an `EGLSurface`, [`VkSurfaceKHR`] or [`wgpu::Surface`]).
+    ///
+    /// After being `Suspended` on Android applications must drop all render surfaces before
+    /// the event callback completes, which may be re-created when the application is next [`Resumed`].
+    ///
+    /// [`SurfaceView`]: https://developer.android.com/reference/android/view/SurfaceView
+    /// [Activity lifecycle]: https://developer.android.com/guide/components/activities/activity-lifecycle
+    /// [`VkSurfaceKHR`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkSurfaceKHR.html
+    /// [`wgpu::Surface`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html
+    ///
+    /// ## iOS
+    ///
+    /// On iOS, the `Suspended` event is currently emitted in response to an
+    /// [`applicationWillResignActive`] callback which means that the application is
+    /// about to transition from the active to inactive state (according to the
+    /// [iOS application lifecycle]).
+    ///
+    /// [`applicationWillResignActive`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622950-applicationwillresignactive
+    /// [iOS application lifecycle]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle
+    ///
+    /// ## Web
+    ///
+    /// On Web, the `Suspended` event is emitted in response to a [`pagehide`] event
+    /// with the property [`persisted`] being true, which means that the page is being
+    /// put in the [`bfcache`] (back/forward cache) - an in-memory cache that stores a
+    /// complete snapshot of a page (including the JavaScript heap) as the user is
+    /// navigating away.
+    ///
+    /// [`pagehide`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
+    /// [`persisted`]: https://developer.mozilla.org/en-US/docs/Web/API/PageTransitionEvent/persisted
+    /// [`bfcache`]: https://web.dev/bfcache/
+    /// [`Resumed`]: Self::resumed
+    fn suspended(&mut self, event_loop: &ActiveEventLoop) {
+        let _ = event_loop;
+    }
+
+    /// Emitted when the event loop is being shut down.
+    ///
+    /// This is irreversible - if this method is called, it is guaranteed that the event loop
+    /// will exist right after.
+    fn exiting(&mut self, event_loop: &ActiveEventLoop) {
+        let _ = event_loop;
+    }
+
+    /// Emitted when the application has received a memory warning.
+    ///
+    /// ## Platform-specific
+    ///
+    /// ### Android
+    ///
+    /// On Android, the `MemoryWarning` event is sent when [`onLowMemory`] was called. The application
+    /// must [release memory] or risk being killed.
+    ///
+    /// [`onLowMemory`]: https://developer.android.com/reference/android/app/Application.html#onLowMemory()
+    /// [release memory]: https://developer.android.com/topic/performance/memory#release
+    ///
+    /// ### iOS
+    ///
+    /// On iOS, the `MemoryWarning` event is emitted in response to an [`applicationDidReceiveMemoryWarning`]
+    /// callback. The application must free as much memory as possible or risk being terminated, see
+    /// [how to respond to memory warnings].
+    ///
+    /// [`applicationDidReceiveMemoryWarning`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623063-applicationdidreceivememorywarni
+    /// [how to respond to memory warnings]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle/responding_to_memory_warnings
+    ///
+    /// ### Others
+    ///
+    /// - **macOS / Orbital / Wayland / Web / Windows:** Unsupported.
+    fn memory_warning(&mut self, event_loop: &ActiveEventLoop) {
+        let _ = event_loop;
+    }
+}

src/cursor.rs

@@ -195,6 +195,7 @@ impl OnlyCursorImageSource {
 }
 
 /// Platforms export this directly as `PlatformCustomCursor` if they don't implement caching.
+#[allow(dead_code)]
 #[derive(Debug, Clone)]
 pub(crate) struct OnlyCursorImage(pub(crate) Arc<CursorImage>);
 

src/event.rs

@@ -1,36 +1,37 @@
 //! The [`Event`] enum and assorted supporting types.
 //!
-//! These are sent to the closure given to [`EventLoop::run(...)`], where they get
+//! These are sent to the closure given to [`EventLoop::run_app(...)`], where they get
 //! processed and used to modify the program state. For more details, see the root-level documentation.
 //!
 //! Some of these events represent different "parts" of a traditional event-handling loop. You could
-//! approximate the basic ordering loop of [`EventLoop::run(...)`] like this:
+//! approximate the basic ordering loop of [`EventLoop::run_app(...)`] like this:
 //!
 //! ```rust,ignore
 //! let mut start_cause = StartCause::Init;
 //!
 //! while !elwt.exiting() {
-//!     event_handler(NewEvents(start_cause), elwt);
+//!     app.new_events(event_loop, start_cause);
 //!
-//!     for e in (window events, user events, device events) {
-//!         event_handler(e, elwt);
+//!     for event in (window events, user events, device events) {
+//!         // This will pick the right method on the application based on the event.
+//!         app.handle_event(event_loop, event);
 //!     }
 //!
-//!     for w in (redraw windows) {
-//!         event_handler(RedrawRequested(w), elwt);
+//!     for window_id in (redraw windows) {
+//!         app.window_event(event_loop, window_id, RedrawRequested);
 //!     }
 //!
-//!     event_handler(AboutToWait, elwt);
+//!     app.about_to_wait(event_loop);
 //!     start_cause = wait_if_necessary();
 //! }
 //!
-//! event_handler(LoopExiting, elwt);
+//! app.exiting(event_loop);
 //! ```
 //!
 //! This leaves out timing details like [`ControlFlow::WaitUntil`] but hopefully
 //! describes what happens in what order.
 //!
-//! [`EventLoop::run(...)`]: crate::event_loop::EventLoop::run
+//! [`EventLoop::run_app(...)`]: crate::event_loop::EventLoop::run_app
 //! [`ControlFlow::WaitUntil`]: crate::event_loop::ControlFlow::WaitUntil
 use std::path::PathBuf;
 use std::sync::{Mutex, Weak};
@@ -59,199 +60,55 @@ use crate::{
 /// See the module-level docs for more information on the event loop manages each event.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Event<T: 'static> {
-    /// Emitted when new events arrive from the OS to be processed.
+    /// See [`ApplicationHandler::new_events`] for details.
     ///
-    /// This event type is useful as a place to put code that should be done before you start
-    /// processing events, such as updating frame timing information for benchmarking or checking
-    /// the [`StartCause`] to see if a timer set by
-    /// [`ControlFlow::WaitUntil`](crate::event_loop::ControlFlow::WaitUntil) has elapsed.
+    /// [`ApplicationHandler::new_events`]: crate::application::ApplicationHandler::new_events
     NewEvents(StartCause),
 
-    /// Emitted when the OS sends an event to a winit window.
+    /// See [`ApplicationHandler::window_event`] for details.
+    ///
+    /// [`ApplicationHandler::window_event`]: crate::application::ApplicationHandler::window_event
     WindowEvent {
         window_id: WindowId,
         event: WindowEvent,
     },
 
-    /// Emitted when the OS sends an event to a device.
+    /// See [`ApplicationHandler::device_event`] for details.
+    ///
+    /// [`ApplicationHandler::device_event`]: crate::application::ApplicationHandler::device_event
     DeviceEvent {
         device_id: DeviceId,
         event: DeviceEvent,
     },
 
-    /// Emitted when an event is sent from [`EventLoopProxy::send_event`](crate::event_loop::EventLoopProxy::send_event)
+    /// See [`ApplicationHandler::user_event`] for details.
+    ///
+    /// [`ApplicationHandler::user_event`]: crate::application::ApplicationHandler::user_event
     UserEvent(T),
 
-    /// Emitted when the application has been suspended.
+    /// See [`ApplicationHandler::suspended`] for details.
     ///
-    /// # Portability
-    ///
-    /// Not all platforms support the notion of suspending applications, and there may be no
-    /// technical way to guarantee being able to emit a `Suspended` event if the OS has
-    /// no formal application lifecycle (currently only Android, iOS, and Web do). For this reason,
-    /// Winit does not currently try to emit pseudo `Suspended` events before the application
-    /// quits on platforms without an application lifecycle.
-    ///
-    /// Considering that the implementation of `Suspended` and [`Resumed`] events may be internally
-    /// driven by multiple platform-specific events, and that there may be subtle differences across
-    /// platforms with how these internal events are delivered, it's recommended that applications
-    /// be able to gracefully handle redundant (i.e. back-to-back) `Suspended` or [`Resumed`] events.
-    ///
-    /// Also see [`Resumed`] notes.
-    ///
-    /// ## Android
-    ///
-    /// On Android, the `Suspended` event is only sent when the application's associated
-    /// [`SurfaceView`] is destroyed. This is expected to closely correlate with the [`onPause`]
-    /// lifecycle event but there may technically be a discrepancy.
-    ///
-    /// [`onPause`]: https://developer.android.com/reference/android/app/Activity#onPause()
-    ///
-    /// Applications that need to run on Android should assume their [`SurfaceView`] has been
-    /// destroyed, which indirectly invalidates any existing render surfaces that may have been
-    /// created outside of Winit (such as an `EGLSurface`, [`VkSurfaceKHR`] or [`wgpu::Surface`]).
-    ///
-    /// After being `Suspended` on Android applications must drop all render surfaces before
-    /// the event callback completes, which may be re-created when the application is next [`Resumed`].
-    ///
-    /// [`SurfaceView`]: https://developer.android.com/reference/android/view/SurfaceView
-    /// [Activity lifecycle]: https://developer.android.com/guide/components/activities/activity-lifecycle
-    /// [`VkSurfaceKHR`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkSurfaceKHR.html
-    /// [`wgpu::Surface`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html
-    ///
-    /// ## iOS
-    ///
-    /// On iOS, the `Suspended` event is currently emitted in response to an
-    /// [`applicationWillResignActive`] callback which means that the application is
-    /// about to transition from the active to inactive state (according to the
-    /// [iOS application lifecycle]).
-    ///
-    /// [`applicationWillResignActive`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622950-applicationwillresignactive
-    /// [iOS application lifecycle]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle
-    ///
-    /// ## Web
-    ///
-    /// On Web, the `Suspended` event is emitted in response to a [`pagehide`] event
-    /// with the property [`persisted`] being true, which means that the page is being
-    /// put in the [`bfcache`] (back/forward cache) - an in-memory cache that stores a
-    /// complete snapshot of a page (including the JavaScript heap) as the user is
-    /// navigating away.
-    ///
-    /// [`pagehide`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
-    /// [`persisted`]: https://developer.mozilla.org/en-US/docs/Web/API/PageTransitionEvent/persisted
-    /// [`bfcache`]: https://web.dev/bfcache/
-    ///
-    /// [`Resumed`]: Self::Resumed
+    /// [`ApplicationHandler::suspended`]: crate::application::ApplicationHandler::suspended
     Suspended,
 
-    /// Emitted when the application has been resumed.
+    /// See [`ApplicationHandler::resumed`] for details.
     ///
-    /// For consistency, all platforms emit a `Resumed` event even if they don't themselves have a
-    /// formal suspend/resume lifecycle. For systems without a standard suspend/resume lifecycle
-    /// the `Resumed` event is always emitted after the [`NewEvents(StartCause::Init)`][StartCause::Init]
-    /// event.
-    ///
-    /// # Portability
-    ///
-    /// It's recommended that applications should only initialize their graphics context and create
-    /// a window after they have received their first `Resumed` event. Some systems
-    /// (specifically Android) won't allow applications to create a render surface until they are
-    /// resumed.
-    ///
-    /// Considering that the implementation of [`Suspended`] and `Resumed` events may be internally
-    /// driven by multiple platform-specific events, and that there may be subtle differences across
-    /// platforms with how these internal events are delivered, it's recommended that applications
-    /// be able to gracefully handle redundant (i.e. back-to-back) [`Suspended`] or `Resumed` events.
-    ///
-    /// Also see [`Suspended`] notes.
-    ///
-    /// ## Android
-    ///
-    /// On Android, the `Resumed` event is sent when a new [`SurfaceView`] has been created. This is
-    /// expected to closely correlate with the [`onResume`] lifecycle event but there may technically
-    /// be a discrepancy.
-    ///
-    /// [`onResume`]: https://developer.android.com/reference/android/app/Activity#onResume()
-    ///
-    /// Applications that need to run on Android must wait until they have been `Resumed`
-    /// before they will be able to create a render surface (such as an `EGLSurface`,
-    /// [`VkSurfaceKHR`] or [`wgpu::Surface`]) which depend on having a
-    /// [`SurfaceView`]. Applications must also assume that if they are [`Suspended`], then their
-    /// render surfaces are invalid and should be dropped.
-    ///
-    /// Also see [`Suspended`] notes.
-    ///
-    /// [`SurfaceView`]: https://developer.android.com/reference/android/view/SurfaceView
-    /// [Activity lifecycle]: https://developer.android.com/guide/components/activities/activity-lifecycle
-    /// [`VkSurfaceKHR`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkSurfaceKHR.html
-    /// [`wgpu::Surface`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html
-    ///
-    /// ## iOS
-    ///
-    /// On iOS, the `Resumed` event is emitted in response to an [`applicationDidBecomeActive`]
-    /// callback which means the application is "active" (according to the
-    /// [iOS application lifecycle]).
-    ///
-    /// [`applicationDidBecomeActive`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622956-applicationdidbecomeactive
-    /// [iOS application lifecycle]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle
-    ///
-    /// ## Web
-    ///
-    /// On Web, the `Resumed` event is emitted in response to a [`pageshow`] event
-    /// with the property [`persisted`] being true, which means that the page is being
-    /// restored from the [`bfcache`] (back/forward cache) - an in-memory cache that
-    /// stores a complete snapshot of a page (including the JavaScript heap) as the
-    /// user is navigating away.
-    ///
-    /// [`pageshow`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/pageshow_event
-    /// [`persisted`]: https://developer.mozilla.org/en-US/docs/Web/API/PageTransitionEvent/persisted
-    /// [`bfcache`]: https://web.dev/bfcache/
-    ///
-    /// [`Suspended`]: Self::Suspended
+    /// [`ApplicationHandler::resumed`]: crate::application::ApplicationHandler::resumed
     Resumed,
 
-    /// Emitted when the event loop is about to block and wait for new events.
+    /// See [`ApplicationHandler::about_to_wait`] for details.
     ///
-    /// Most applications shouldn't need to hook into this event since there is no real relationship
-    /// between how often the event loop needs to wake up and the dispatching of any specific events.
-    ///
-    /// High frequency event sources, such as input devices could potentially lead to lots of wake
-    /// ups and also lots of corresponding `AboutToWait` events.
-    ///
-    /// This is not an ideal event to drive application rendering from and instead applications
-    /// should render in response to [`WindowEvent::RedrawRequested`] events.
+    /// [`ApplicationHandler::about_to_wait`]: crate::application::ApplicationHandler::about_to_wait
     AboutToWait,
 
-    /// Emitted when the event loop is being shut down.
+    /// See [`ApplicationHandler::exiting`] for details.
     ///
-    /// This is irreversible - if this event is emitted, it is guaranteed to be the last event that
-    /// gets emitted. You generally want to treat this as a "do on quit" event.
+    /// [`ApplicationHandler::exiting`]: crate::application::ApplicationHandler::exiting
     LoopExiting,
 
-    /// Emitted when the application has received a memory warning.
+    /// See [`ApplicationHandler::memory_warning`] for details.
     ///
-    /// ## Platform-specific
-    ///
-    /// ### Android
-    ///
-    /// On Android, the `MemoryWarning` event is sent when [`onLowMemory`] was called. The application
-    /// must [release memory] or risk being killed.
-    ///
-    /// [`onLowMemory`]: https://developer.android.com/reference/android/app/Application.html#onLowMemory()
-    /// [release memory]: https://developer.android.com/topic/performance/memory#release
-    ///
-    /// ### iOS
-    ///
-    /// On iOS, the `MemoryWarning` event is emitted in response to an [`applicationDidReceiveMemoryWarning`]
-    /// callback. The application must free as much memory as possible or risk being terminated, see
-    /// [how to respond to memory warnings].
-    ///
-    /// [`applicationDidReceiveMemoryWarning`]: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623063-applicationdidreceivememorywarni
-    /// [how to respond to memory warnings]: https://developer.apple.com/documentation/uikit/app_and_environment/managing_your_app_s_life_cycle/responding_to_memory_warnings
-    ///
-    /// ### Others
-    ///
-    /// - **macOS / Wayland / Windows / Orbital:** Unsupported.
+    /// [`ApplicationHandler::memory_warning`]: crate::application::ApplicationHandler::memory_warning
     MemoryWarning,
 }
 

src/event_loop.rs

@@ -18,6 +18,7 @@ use std::time::{Duration, Instant};
 #[cfg(web_platform)]
 use web_time::{Duration, Instant};
 
+use crate::application::ApplicationHandler;
 use crate::error::{EventLoopError, OsError};
 use crate::window::{CustomCursor, CustomCursorSource, Window, WindowAttributes};
 use crate::{event::Event, monitor::MonitorHandle, platform_impl};
@@ -215,8 +216,22 @@ impl<T> EventLoop<T> {
         }
     }
 
-    /// Runs the event loop in the calling thread and calls the given `event_handler` closure
-    /// to dispatch any pending events.
+    /// See [`run_app`].
+    ///
+    /// [`run_app`]: Self::run_app
+    #[inline]
+    #[deprecated = "use `EventLoop::run_app` instead"]
+    #[cfg(not(all(web_platform, target_feature = "exception-handling")))]
+    pub fn run<F>(self, event_handler: F) -> Result<(), EventLoopError>
+    where
+        F: FnMut(Event<T>, &ActiveEventLoop),
+    {
+        let _span = tracing::debug_span!("winit::EventLoop::run").entered();
+
+        self.event_loop.run(event_handler)
+    }
+
+    /// Run the application with the event loop on the calling thread.
     ///
     /// See the [`set_control_flow()`] docs on how to change the event loop's behavior.
     ///
@@ -231,10 +246,10 @@ impl<T> EventLoop<T> {
     ///   Web applications are recommended to use
     #[cfg_attr(
         web_platform,
-        doc = "[`EventLoopExtWebSys::spawn()`][crate::platform::web::EventLoopExtWebSys::spawn()]"
+        doc = "[`EventLoopExtWebSys::spawn_app()`][crate::platform::web::EventLoopExtWebSys::spawn_app()]"
     )]
     #[cfg_attr(not(web_platform), doc = "`EventLoopExtWebSys::spawn()`")]
-    ///   [^1] instead of [`run()`] to avoid the need
+    ///   [^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.
@@ -242,17 +257,13 @@ impl<T> EventLoop<T> {
     ///   This function won't be available with `target_feature = "exception-handling"`.
     ///
     /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
-    /// [`run()`]: Self::run()
-    /// [^1]: `EventLoopExtWebSys::spawn()` is only available on Web.
+    /// [`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<F>(self, event_handler: F) -> Result<(), EventLoopError>
-    where
-        F: FnMut(Event<T>, &ActiveEventLoop),
-    {
-        let _span = tracing::debug_span!("winit::EventLoop::run").entered();
-
-        self.event_loop.run(event_handler)
+    pub fn run_app<A: ApplicationHandler<T>>(self, app: &mut A) -> Result<(), EventLoopError> {
+        self.event_loop
+            .run(|event, event_loop| dispatch_event_for_app(app, event_loop, event))
     }
 
     /// Creates an [`EventLoopProxy`] that can be used to dispatch user events
@@ -344,11 +355,11 @@ unsafe impl<T> rwh_05::HasRawDisplayHandle for EventLoop<T> {
 impl<T> AsFd for EventLoop<T> {
     /// Get the underlying [EventLoop]'s `fd` which you can register
     /// into other event loop, like [`calloop`] or [`mio`]. When doing so, the
-    /// loop must be polled with the [`pump_events`] API.
+    /// loop must be polled with the [`pump_app_events`] API.
     ///
     /// [`calloop`]: https://crates.io/crates/calloop
     /// [`mio`]: https://crates.io/crates/mio
-    /// [`pump_events`]: crate::platform::pump_events::EventLoopExtPumpEvents::pump_events
+    /// [`pump_app_events`]: crate::platform::pump_events::EventLoopExtPumpEvents::pump_app_events
     fn as_fd(&self) -> BorrowedFd<'_> {
         self.event_loop.as_fd()
     }
@@ -358,11 +369,11 @@ impl<T> AsFd for EventLoop<T> {
 impl<T> AsRawFd for EventLoop<T> {
     /// Get the underlying [EventLoop]'s raw `fd` which you can register
     /// into other event loop, like [`calloop`] or [`mio`]. When doing so, the
-    /// loop must be polled with the [`pump_events`] API.
+    /// loop must be polled with the [`pump_app_events`] API.
     ///
     /// [`calloop`]: https://crates.io/crates/calloop
     /// [`mio`]: https://crates.io/crates/mio
-    /// [`pump_events`]: crate::platform::pump_events::EventLoopExtPumpEvents::pump_events
+    /// [`pump_app_events`]: crate::platform::pump_events::EventLoopExtPumpEvents::pump_app_events
     fn as_raw_fd(&self) -> RawFd {
         self.event_loop.as_raw_fd()
     }
@@ -630,3 +641,23 @@ impl AsyncRequestSerial {
         Self { serial }
     }
 }
+
+/// Shim for various run APIs.
+#[inline(always)]
+pub(crate) fn dispatch_event_for_app<T: 'static, A: ApplicationHandler<T>>(
+    app: &mut A,
+    event_loop: &ActiveEventLoop,
+    event: Event<T>,
+) {
+    match event {
+        Event::NewEvents(cause) => app.new_events(event_loop, cause),
+        Event::WindowEvent { window_id, event } => app.window_event(event_loop, window_id, event),
+        Event::DeviceEvent { device_id, event } => app.device_event(event_loop, device_id, event),
+        Event::UserEvent(event) => app.user_event(event_loop, event),
+        Event::Suspended => app.suspended(event_loop),
+        Event::Resumed => app.resumed(event_loop),
+        Event::AboutToWait => app.about_to_wait(event_loop),
+        Event::LoopExiting => app.exiting(event_loop),
+        Event::MemoryWarning => app.memory_warning(event_loop),
+    }
+}

src/lib.rs

@@ -21,7 +21,7 @@
 //! Some user activity, like mouse movement, can generate both a [`WindowEvent`] *and* a
 //! [`DeviceEvent`]. You can also create and handle your own custom [`Event::UserEvent`]s, if desired.
 //!
-//! You can retrieve events by calling [`EventLoop::run()`]. This function will
+//! You can retrieve events by calling [`EventLoop::run_app()`]. This function will
 //! dispatch events for every [`Window`] that was created with that particular [`EventLoop`], and
 //! will run until [`exit()`] is used, at which point [`Event::LoopExiting`].
 //!
@@ -36,7 +36,7 @@
         x11_platform,
         wayland_platform
     ),
-    doc = "[`EventLoopExtPumpEvents::pump_events()`][platform::pump_events::EventLoopExtPumpEvents::pump_events()]"
+    doc = "[`EventLoopExtPumpEvents::pump_app_events()`][platform::pump_events::EventLoopExtPumpEvents::pump_app_events()]"
 )]
 #![cfg_attr(
     not(any(
@@ -46,18 +46,54 @@
         x11_platform,
         wayland_platform
     )),
-    doc = "`EventLoopExtPumpEvents::pump_events()`"
+    doc = "`EventLoopExtPumpEvents::pump_app_events()`"
 )]
 //! [^1]. See that method's documentation for more reasons about why
 //! it's discouraged beyond compatibility reasons.
 //!
 //!
 //! ```no_run
-//! use winit::{
-//!     event::{Event, WindowEvent},
-//!     event_loop::{ControlFlow, EventLoop},
-//!     window::Window,
-//! };
+//! use winit::application::ApplicationHandler;
+//! use winit::event::WindowEvent;
+//! use winit::event_loop::{ActiveEventLoop, ControlFlow, EventLoop};
+//! use winit::window::{Window, WindowId};
+//!
+//! #[derive(Default)]
+//! struct App {
+//!     window: Option<Window>,
+//! }
+//!
+//! impl ApplicationHandler for App {
+//!     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+//!         self.window = Some(event_loop.create_window(Window::default_attributes()).unwrap());
+//!     }
+//!
+//!     fn window_event(&mut self, event_loop: &ActiveEventLoop, id: WindowId, event: WindowEvent) {
+//!         match event {
+//!             WindowEvent::CloseRequested => {
+//!                 println!("The close button was pressed; stopping");
+//!                 event_loop.exit();
+//!             },
+//!             WindowEvent::RedrawRequested => {
+//!                 // Redraw the application.
+//!                 //
+//!                 // It's preferable for applications that do not render continuously to render in
+//!                 // this event rather than in AboutToWait, since rendering in here allows
+//!                 // the program to gracefully handle redraws requested by the OS.
+//!
+//!                 // Draw.
+//!
+//!                 // Queue a RedrawRequested event.
+//!                 //
+//!                 // You only need to call this if you've determined that you need to redraw in
+//!                 // applications which do not always need to. Applications that redraw continuously
+//!                 // can render here instead.
+//!                 self.window.as_ref().unwrap().request_redraw();
+//!             }
+//!             _ => (),
+//!         }
+//!     }
+//! }
 //!
 //! let event_loop = EventLoop::new().unwrap();
 //!
@@ -70,43 +106,8 @@
 //! // input, and uses significantly less power/CPU time than ControlFlow::Poll.
 //! event_loop.set_control_flow(ControlFlow::Wait);
 //!
-//! let mut window = None;
-//!
-//! event_loop.run(move |event, event_loop| {
-//!     match event {
-//!         Event::Resumed => {
-//!             window = Some(event_loop.create_window(Window::default_attributes()).unwrap());
-//!         }
-//!         Event::WindowEvent {
-//!             event: WindowEvent::CloseRequested,
-//!             ..
-//!         } => {
-//!             println!("The close button was pressed; stopping");
-//!             event_loop.exit();
-//!         },
-//!         Event::AboutToWait => {
-//!             // Application update code.
-//!
-//!             // Queue a RedrawRequested event.
-//!             //
-//!             // You only need to call this if you've determined that you need to redraw in
-//!             // applications which do not always need to. Applications that redraw continuously
-//!             // can render here instead.
-//!             window.as_ref().unwrap().request_redraw();
-//!         },
-//!         Event::WindowEvent {
-//!             event: WindowEvent::RedrawRequested,
-//!             ..
-//!         } => {
-//!             // Redraw the application.
-//!             //
-//!             // It's preferable for applications that do not render continuously to render in
-//!             // this event rather than in AboutToWait, since rendering in here allows
-//!             // the program to gracefully handle redraws requested by the OS.
-//!         },
-//!         _ => ()
-//!     }
-//! });
+//! let mut app = App::default();
+//! event_loop.run_app(&mut app);
 //! ```
 //!
 //! [`WindowEvent`] has a [`WindowId`] member. In multi-window environments, it should be
@@ -164,7 +165,7 @@
 //!
 //! [`EventLoop`]: event_loop::EventLoop
 //! [`EventLoop::new()`]: event_loop::EventLoop::new
-//! [`EventLoop::run()`]: event_loop::EventLoop::run
+//! [`EventLoop::run_app()`]: event_loop::EventLoop::run_app
 //! [`exit()`]: event_loop::ActiveEventLoop::exit
 //! [`Window`]: window::Window
 //! [`WindowId`]: window::WindowId
@@ -178,7 +179,7 @@
 //! [`Event::LoopExiting`]: event::Event::LoopExiting
 //! [`raw_window_handle`]: ./window/struct.Window.html#method.raw_window_handle
 //! [`raw_display_handle`]: ./window/struct.Window.html#method.raw_display_handle
-//! [^1]: `EventLoopExtPumpEvents::pump_events()` is only available on Windows, macOS, Android, X11 and Wayland.
+//! [^1]: `EventLoopExtPumpEvents::pump_app_events()` is only available on Windows, macOS, Android, X11 and Wayland.
 
 #![deny(rust_2018_idioms)]
 #![deny(rustdoc::broken_intra_doc_links)]
@@ -200,6 +201,7 @@ pub use rwh_06 as raw_window_handle;
 #[doc(inline)]
 pub use dpi;
 
+pub mod application;
 #[macro_use]
 pub mod error;
 mod cursor;

src/platform/android.rs

@@ -60,7 +60,7 @@
 //!
 //! 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.29.12", features = [ "android-native-activity" ] }`
+//! 2. Enable the `"android-native-activity"` feature for Winit: `winit = { version = "0.29.14", 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).
 //! 4. Pass a clone of the `AndroidApp` that your application receives to Winit when building your event loop (as shown above).
 

src/platform/pump_events.rs

@@ -1,22 +1,13 @@
 use std::time::Duration;
 
-use crate::{
-    event::Event,
-    event_loop::{ActiveEventLoop, EventLoop},
-};
-
-/// The return status for `pump_events`
-pub enum PumpStatus {
-    /// Continue running external loop.
-    Continue,
-    /// Exit external loop.
-    Exit(i32),
-}
+use crate::application::ApplicationHandler;
+use crate::event::Event;
+use crate::event_loop::{self, ActiveEventLoop, EventLoop};
 
 /// Additional methods on [`EventLoop`] for pumping events within an external event loop
 pub trait EventLoopExtPumpEvents {
     /// A type provided by the user that can be passed through [`Event::UserEvent`].
-    type UserEvent;
+    type UserEvent: 'static;
 
     /// Pump the `EventLoop` to check for and dispatch pending events.
     ///
@@ -113,6 +104,21 @@ pub trait EventLoopExtPumpEvents {
     ///   If you render outside of Winit you are likely to see window resizing artifacts
     ///   since MacOS expects applications to render synchronously during any `drawRect`
     ///   callback.
+    fn pump_app_events<A: ApplicationHandler<Self::UserEvent>>(
+        &mut self,
+        timeout: Option<Duration>,
+        app: &mut A,
+    ) -> PumpStatus {
+        #[allow(deprecated)]
+        self.pump_events(timeout, |event, event_loop| {
+            event_loop::dispatch_event_for_app(app, event_loop, event)
+        })
+    }
+
+    /// See [`pump_app_events`].
+    ///
+    /// [`pump_app_events`]: Self::pump_app_events
+    #[deprecated = "use EventLoopExtPumpEvents::pump_app_events"]
     fn pump_events<F>(&mut self, timeout: Option<Duration>, event_handler: F) -> PumpStatus
     where
         F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop);
@@ -128,3 +134,11 @@ impl<T> EventLoopExtPumpEvents for EventLoop<T> {
         self.event_loop.pump_events(timeout, event_handler)
     }
 }
+
+/// The return status for `pump_events`
+pub enum PumpStatus {
+    /// Continue running external loop.
+    Continue,
+    /// Exit external loop.
+    Exit(i32),
+}

src/platform/run_on_demand.rs

@@ -1,8 +1,7 @@
-use crate::{
-    error::EventLoopError,
-    event::Event,
-    event_loop::{ActiveEventLoop, EventLoop},
-};
+use crate::application::ApplicationHandler;
+use crate::error::EventLoopError;
+use crate::event::Event;
+use crate::event_loop::{self, ActiveEventLoop, EventLoop};
 
 #[cfg(doc)]
 use crate::{platform::pump_events::EventLoopExtPumpEvents, window::Window};
@@ -10,12 +9,19 @@ use crate::{platform::pump_events::EventLoopExtPumpEvents, window::Window};
 /// Additional methods on [`EventLoop`] to return control flow to the caller.
 pub trait EventLoopExtRunOnDemand {
     /// A type provided by the user that can be passed through [`Event::UserEvent`].
-    type UserEvent;
+    type UserEvent: 'static;
 
-    /// Runs the event loop in the calling thread and calls the given `event_handler` closure
-    /// to dispatch any window system events.
+    /// See [`run_app_on_demand`].
     ///
-    /// Unlike [`EventLoop::run`], this function accepts non-`'static` (i.e. non-`move`) closures
+    /// [`run_app_on_demand`]: Self::run_app_on_demand
+    #[deprecated = "use EventLoopExtRunOnDemand::run_app_on_demand"]
+    fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
+    where
+        F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop);
+
+    /// 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.
@@ -26,11 +32,10 @@ pub trait EventLoopExtRunOnDemand {
     ///
     /// This API is not designed to run an event loop in bursts that you can exit from and return
     /// to while maintaining the full state of your application. (If you need something like this
-    /// you can look at the [`EventLoopExtPumpEvents::pump_events()`] API)
+    /// you can look at the [`EventLoopExtPumpEvents::pump_app_events()`] API)
     ///
-    /// Each time `run_on_demand` is called the `event_handler` can expect to receive a
-    /// `NewEvents(Init)` and `Resumed` event (even on platforms that have no suspend/resume
-    /// lifecycle) - which can be used to consistently initialize application state.
+    /// Each time `run_app_on_demand` is called the startup sequence of `init`, followed by
+    /// `resume` is being preserved.
     ///
     /// See the [`set_control_flow()`] docs on how to change the event loop's behavior.
     ///
@@ -40,8 +45,8 @@ pub trait EventLoopExtRunOnDemand {
     ///   backend it is possible to use `EventLoopExtWebSys::spawn()`[^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()`] for portability, unless you specifically need
-    /// the ability to re-run a single event loop more than once
+    /// You are strongly encouraged to use [`EventLoop::run_app()`] for portability, unless you
+    /// specifically need the ability to re-run a single event loop more than once
     ///
     /// # Supported Platforms
     /// - Windows
@@ -64,9 +69,15 @@ pub trait EventLoopExtRunOnDemand {
     ///
     /// [`exit()`]: ActiveEventLoop::exit()
     /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
-    fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
-    where
-        F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop);
+    fn run_app_on_demand<A: ApplicationHandler<Self::UserEvent>>(
+        &mut self,
+        app: &mut A,
+    ) -> Result<(), EventLoopError> {
+        #[allow(deprecated)]
+        self.run_on_demand(|event, event_loop| {
+            event_loop::dispatch_event_for_app(app, event_loop, event)
+        })
+    }
 }
 
 impl<T> EventLoopExtRunOnDemand for EventLoop<T> {

src/platform/web.rs

@@ -53,9 +53,10 @@ use std::time::Duration;
 #[cfg(web_platform)]
 use web_sys::HtmlCanvasElement;
 
+use crate::application::ApplicationHandler;
 use crate::cursor::CustomCursorSource;
 use crate::event::Event;
-use crate::event_loop::{ActiveEventLoop, EventLoop};
+use crate::event_loop::{self, ActiveEventLoop, EventLoop};
 #[cfg(web_platform)]
 use crate::platform_impl::CustomCursorFuture as PlatformCustomCursorFuture;
 use crate::platform_impl::PlatformCustomCursorSource;
@@ -160,18 +161,18 @@ impl WindowAttributesExtWebSys for WindowAttributes {
 /// Additional methods on `EventLoop` that are specific to the web.
 pub trait EventLoopExtWebSys {
     /// A type provided by the user that can be passed through `Event::UserEvent`.
-    type UserEvent;
+    type UserEvent: 'static;
 
     /// Initializes the winit event loop.
     ///
     /// Unlike
     #[cfg_attr(
         all(web_platform, target_feature = "exception-handling"),
-        doc = "`run()`"
+        doc = "`run_app()`"
     )]
     #[cfg_attr(
         not(all(web_platform, target_feature = "exception-handling")),
-        doc = "[`run()`]"
+        doc = "[`run_app()`]"
     )]
     /// [^1], this returns immediately, and doesn't throw an exception in order to
     /// satisfy its [`!`] return type.
@@ -183,9 +184,15 @@ pub trait EventLoopExtWebSys {
     ///
     #[cfg_attr(
         not(all(web_platform, target_feature = "exception-handling")),
-        doc = "[`run()`]: EventLoop::run()"
+        doc = "[`run_app()`]: EventLoop::run_app()"
     )]
-    /// [^1]: `run()` is _not_ available on WASM when the target supports `exception-handling`.
+    /// [^1]: `run_app()` is _not_ available on WASM when the target supports `exception-handling`.
+    fn spawn_app<A: ApplicationHandler<Self::UserEvent> + 'static>(self, app: A);
+
+    /// See [`spawn_app`].
+    ///
+    /// [`spawn_app`]: Self::spawn_app
+    #[deprecated = "use EventLoopExtWebSys::spawn_app"]
     fn spawn<F>(self, event_handler: F)
     where
         F: 'static + FnMut(Event<Self::UserEvent>, &ActiveEventLoop);
@@ -194,6 +201,12 @@ pub trait EventLoopExtWebSys {
 impl<T> EventLoopExtWebSys for EventLoop<T> {
     type UserEvent = T;
 
+    fn spawn_app<A: ApplicationHandler<Self::UserEvent> + 'static>(self, mut app: A) {
+        self.event_loop.spawn(move |event, event_loop| {
+            event_loop::dispatch_event_for_app(&mut app, event_loop, event)
+        });
+    }
+
     fn spawn<F>(self, event_handler: F)
     where
         F: 'static + FnMut(Event<Self::UserEvent>, &ActiveEventLoop),

src/platform_impl/ios/event_loop.rs

@@ -182,7 +182,7 @@ impl<T: 'static> EventLoop<T> {
             application.is_none(),
             "\
                 `EventLoop` cannot be `run` after a call to `UIApplicationMain` on iOS\n\
-                 Note: `EventLoop::run` calls `UIApplicationMain` on iOS",
+                 Note: `EventLoop::run_app` calls `UIApplicationMain` on iOS",
         );
 
         let handler = map_user_event(handler, self.receiver);

src/platform_impl/ios/window.rs

@@ -689,7 +689,7 @@ impl Inner {
             let screen_frame = self.rect_to_screen_space(bounds);
             let status_bar_frame = {
                 let app = UIApplication::shared(MainThreadMarker::new().unwrap()).expect(
-                    "`Window::get_inner_position` cannot be called before `EventLoop::run` on iOS",
+                    "`Window::get_inner_position` cannot be called before `EventLoop::run_app` on iOS",
                 );
                 app.statusBarFrame()
             };

src/platform_impl/linux/common/xkb/mod.rs

@@ -373,10 +373,15 @@ impl<'a, 'b> KeyEventResults<'a, 'b> {
 
     fn composed_text(&mut self) -> Result<Option<SmolStr>, ()> {
         match self.compose {
-            ComposeStatus::Accepted(xkb_compose_status::XKB_COMPOSE_COMPOSED) => {
-                let state = self.context.compose_state1.as_mut().unwrap();
-                Ok(state.get_string(self.context.scratch_buffer))
-            }
+            ComposeStatus::Accepted(status) => match status {
+                xkb_compose_status::XKB_COMPOSE_COMPOSED => {
+                    let state = self.context.compose_state1.as_mut().unwrap();
+                    Ok(state.get_string(self.context.scratch_buffer))
+                }
+                xkb_compose_status::XKB_COMPOSE_COMPOSING
+                | xkb_compose_status::XKB_COMPOSE_CANCELLED => Ok(None),
+                xkb_compose_status::XKB_COMPOSE_NOTHING => Err(()),
+            },
             _ => Err(()),
         }
     }

src/platform_impl/linux/wayland/window/state.rs

@@ -826,9 +826,14 @@ impl WindowState {
 
     /// Set the cursor grabbing state on the top-level.
     pub fn set_cursor_grab(&mut self, mode: CursorGrabMode) -> Result<(), ExternalError> {
-        // Replace the user grabbing mode.
+        if self.cursor_grab_mode.user_grab_mode == mode {
+            return Ok(());
+        }
+
+        self.set_cursor_grab_inner(mode)?;
+        // Update user grab on success.
         self.cursor_grab_mode.user_grab_mode = mode;
-        self.set_cursor_grab_inner(mode)
+        Ok(())
     }
 
     /// Reload the hints for minimum and maximum sizes.

src/platform_impl/linux/x11/event_processor.rs

@@ -981,7 +981,7 @@ impl EventProcessor {
 
         // Always update the modifiers when we're not replaying.
         if !replay {
-            self.udpate_mods_from_core_event(window_id, xev.state as u16, &mut callback);
+            self.update_mods_from_core_event(window_id, xev.state as u16, &mut callback);
         }
 
         if keycode != 0 && !self.is_composing {
@@ -1778,7 +1778,7 @@ impl EventProcessor {
         self.send_modifiers(window_id, mods.into(), true, &mut callback)
     }
 
-    pub fn udpate_mods_from_core_event<T: 'static, F>(
+    pub fn update_mods_from_core_event<T: 'static, F>(
         &mut self,
         window_id: crate::window::WindowId,
         state: u16,

src/platform_impl/linux/x11/mod.rs

@@ -887,6 +887,9 @@ pub enum X11Error {
 
     /// Unable to parse xsettings.
     XsettingsParse(xsettings::ParserError),
+
+    /// Failed to get property.
+    GetProperty(util::GetPropertyError),
 }
 
 impl fmt::Display for X11Error {
@@ -896,6 +899,7 @@ impl fmt::Display for X11Error {
             X11Error::Connect(e) => write!(f, "X11 connection error: {}", e),
             X11Error::Connection(e) => write!(f, "X11 connection error: {}", e),
             X11Error::XidsExhausted(e) => write!(f, "XID range exhausted: {}", e),
+            X11Error::GetProperty(e) => write!(f, "Failed to get X property {}", e),
             X11Error::X11(e) => write!(f, "X11 error: {:?}", e),
             X11Error::UnexpectedNull(s) => write!(f, "Xlib function returned null: {}", s),
             X11Error::InvalidActivationToken(s) => write!(
@@ -988,6 +992,12 @@ impl From<xsettings::ParserError> for X11Error {
     }
 }
 
+impl From<util::GetPropertyError> for X11Error {
+    fn from(value: util::GetPropertyError) -> Self {
+        Self::GetProperty(value)
+    }
+}
+
 /// Type alias for a void cookie.
 type VoidCookie<'a> = x11rb::cookie::VoidCookie<'a, X11rbConnection>;
 

src/platform_impl/linux/x11/util/mouse.rs

@@ -30,8 +30,8 @@ macro_rules! consume {
         let this = $this;
         let (x, y) = match (this.x.abs() < <$ty>::EPSILON, this.y.abs() < <$ty>::EPSILON) {
             (true, true) => return None,
-            (true, false) => (this.x, 0.0),
-            (false, true) => (0.0, this.y),
+            (false, true) => (this.x, 0.0),
+            (true, false) => (0.0, this.y),
             (false, false) => (this.x, this.y),
         };
 

src/platform_impl/linux/x11/util/randr.rs

@@ -53,6 +53,7 @@ impl XConnection {
             .get_string("Xft.dpi", "")
             .and_then(|s| f64::from_str(s).ok())
     }
+
     pub fn get_output_info(
         &self,
         resources: &monitor::ScreenResources,

src/platform_impl/linux/x11/util/window_property.rs

@@ -1,13 +1,18 @@
-use super::*;
-use bytemuck::{NoUninit, Pod};
+use std::error::Error;
+use std::fmt;
 use std::sync::Arc;
 
+use bytemuck::{NoUninit, Pod};
+
 use x11rb::connection::Connection;
 use x11rb::errors::ReplyError;
 
-pub type Cardinal = u32;
+use super::*;
+
 pub const CARDINAL_SIZE: usize = mem::size_of::<u32>();
 
+pub type Cardinal = u32;
+
 #[derive(Debug, Clone)]
 pub enum GetPropertyError {
     X11rbError(Arc<ReplyError>),
@@ -15,12 +20,6 @@ pub enum GetPropertyError {
     FormatMismatch(c_int),
 }
 
-impl<T: Into<ReplyError>> From<T> for GetPropertyError {
-    fn from(e: T) -> Self {
-        Self::X11rbError(Arc::new(e.into()))
-    }
-}
-
 impl GetPropertyError {
     pub fn is_actual_property_type(&self, t: xproto::Atom) -> bool {
         if let GetPropertyError::TypeMismatch(actual_type) = *self {
@@ -31,6 +30,24 @@ impl GetPropertyError {
     }
 }
 
+impl<T: Into<ReplyError>> From<T> for GetPropertyError {
+    fn from(e: T) -> Self {
+        Self::X11rbError(Arc::new(e.into()))
+    }
+}
+
+impl fmt::Display for GetPropertyError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            GetPropertyError::X11rbError(err) => err.fmt(f),
+            GetPropertyError::TypeMismatch(err) => write!(f, "type mismatch: {err}"),
+            GetPropertyError::FormatMismatch(err) => write!(f, "format mismatch: {err}"),
+        }
+    }
+}
+
+impl Error for GetPropertyError {}
+
 // Number of 32-bit chunks to retrieve per iteration of get_property's inner loop.
 // To test if `get_property` works correctly, set this to 1.
 const PROPERTY_BUFFER_SIZE: u32 = 1024; // 4k of RAM ought to be enough for anyone!

src/platform_impl/linux/x11/util/xmodmap.rs

@@ -16,7 +16,7 @@ const NUM_MODS: usize = 8;
 #[derive(Debug, Default)]
 pub struct ModifierKeymap {
     // Maps keycodes to modifiers
-    modifers: HashSet<XKeyCode>,
+    modifiers: HashSet<XKeyCode>,
 }
 
 impl ModifierKeymap {
@@ -25,7 +25,7 @@ impl ModifierKeymap {
     }
 
     pub fn is_modifier(&self, keycode: XKeyCode) -> bool {
-        self.modifers.contains(&keycode)
+        self.modifiers.contains(&keycode)
     }
 
     pub fn reload_from_x_connection(&mut self, xconn: &super::XConnection) {
@@ -48,9 +48,9 @@ impl ModifierKeymap {
         let keys = unsafe {
             slice::from_raw_parts(keymap.modifiermap as *const _, keys_per_mod * NUM_MODS)
         };
-        self.modifers.clear();
+        self.modifiers.clear();
         for key in keys {
-            self.modifers.insert(*key);
+            self.modifiers.insert(*key);
         }
     }
 }

src/platform_impl/linux/x11/xdisplay.rs

@@ -159,7 +159,7 @@ impl XConnection {
 
         // Get PropertyNotify events from the XSETTINGS window.
         // TODO: The XSETTINGS window here can change. In the future, listen for DestroyNotify on this window
-        // in order to accomodate for a changed window here.
+        // in order to accommodate for a changed window here.
         let selector_window = xcb
             .get_selection_owner(xsettings_screen)
             .ok()?

src/platform_impl/linux/x11/xsettings.rs

@@ -33,13 +33,11 @@ impl XConnection {
             .reply()?;
 
         // Read the _XSETTINGS_SETTINGS property.
-        let data: Vec<u8> = self
-            .get_property(
-                owner.owner,
-                atoms[_XSETTINGS_SETTINGS],
-                atoms[_XSETTINGS_SETTINGS],
-            )
-            .unwrap();
+        let data: Vec<u8> = self.get_property(
+            owner.owner,
+            atoms[_XSETTINGS_SETTINGS],
+            atoms[_XSETTINGS_SETTINGS],
+        )?;
 
         // Parse the property.
         let dpi_setting = read_settings(&data)?

src/platform_impl/macos/app_delegate.rs

@@ -91,7 +91,7 @@ declare_class!(
             self.set_is_running(true);
             self.dispatch_init_events();
 
-            // If the application is being launched via `EventLoop::pump_events()` then we'll
+            // If the application is being launched via `EventLoop::pump_app_events()` then we'll
             // want to stop the app once it is launched (and return to the external loop)
             //
             // In this case we still want to consider Winit's `EventLoop` to be "running",

src/platform_impl/web/event_loop/runner.rs

@@ -75,8 +75,8 @@ enum RunnerEnum {
     Pending,
     /// The `EventLoop` is being run.
     Running(Runner),
-    /// The `EventLoop` is exited after being started with `EventLoop::run`. Since
-    /// `EventLoop::run` takes ownership of the `EventLoop`, we can be certain
+    /// The `EventLoop` is exited after being started with `EventLoop::run_app`. Since
+    /// `EventLoop::run_app` takes ownership of the `EventLoop`, we can be certain
     /// that this event loop will never be run again.
     Destroyed,
 }
@@ -735,7 +735,7 @@ impl Shared {
         // * `self`, i.e. the item which triggered this event loop wakeup, which
         //   is usually a `wasm-bindgen` `Closure`, which will be dropped after
         //   returning to the JS glue code.
-        // * The `ActiveEventLoop` leaked inside `EventLoop::run` due to the
+        // * The `ActiveEventLoop` leaked inside `EventLoop::run_app` due to the
         //   JS exception thrown at the end.
         // * For each undropped `Window`:
         //     * The `register_redraw_request` closure.

src/platform_impl/web/web_sys/schedule.rs

@@ -117,9 +117,7 @@ impl Schedule {
         let channel = MessageChannel::new().unwrap();
         let closure = Closure::new(f);
         let port_1 = channel.port1();
-        port_1
-            .add_event_listener_with_callback("message", closure.as_ref().unchecked_ref())
-            .expect("Failed to set message handler");
+        port_1.set_onmessage(Some(closure.as_ref().unchecked_ref()));
         port_1.start();
 
         let port_2 = channel.port2();
@@ -178,6 +176,7 @@ impl Drop for Schedule {
             } => {
                 window.clear_timeout_with_handle(*handle);
                 port.close();
+                port.set_onmessage(None);
             }
         }
     }

src/platform_impl/windows/ime.rs

@@ -45,12 +45,12 @@ impl ImeContext {
         let mut boundary_before_char = 0;
 
         for (attr, chr) in attrs.into_iter().zip(text.chars()) {
-            let char_is_targetted =
+            let char_is_targeted =
                 attr as u32 == ATTR_TARGET_CONVERTED || attr as u32 == ATTR_TARGET_NOTCONVERTED;
 
-            if first.is_none() && char_is_targetted {
+            if first.is_none() && char_is_targeted {
                 first = Some(boundary_before_char);
-            } else if first.is_some() && last.is_none() && !char_is_targetted {
+            } else if first.is_some() && last.is_none() && !char_is_targeted {
                 last = Some(boundary_before_char);
             }
 

src/window.rs

@@ -20,7 +20,7 @@ use serde::{Deserialize, Serialize};
 ///
 /// The window is closed when dropped.
 ///
-/// # Threading
+/// ## Threading
 ///
 /// This is `Send + Sync`, meaning that it can be freely used from other
 /// threads.
@@ -30,37 +30,6 @@ use serde::{Deserialize, Serialize};
 /// window from a thread other than the main, the code is scheduled to run on
 /// the main thread, and your thread may be blocked until that completes.
 ///
-/// # Example
-///
-/// ```no_run
-/// use winit::{
-///     event::{Event, WindowEvent},
-///     event_loop::{ControlFlow, EventLoop},
-///     window::Window,
-/// };
-///
-/// let mut event_loop = EventLoop::new().unwrap();
-/// event_loop.set_control_flow(ControlFlow::Wait);
-/// let mut windows = Vec::new();
-///
-/// event_loop.run(move |event, event_loop| {
-///     match event {
-///         Event::Resumed => {
-///             let window = event_loop.create_window(Window::default_attributes()).unwrap();
-///             windows.push(window);
-///         }
-///         Event::WindowEvent {
-///             event: WindowEvent::CloseRequested,
-///             ..
-///         } => {
-///             windows.clear();
-///             event_loop.exit();
-///         }
-///         _ => (),
-///     }
-/// });
-/// ```
-///
 /// ## Platform-specific
 ///
 /// **Web:** The [`Window`], which is represented by a `HTMLElementCanvas`, can

typos.toml

@@ -0,0 +1,6 @@
+# documentation: https://github.com/crate-ci/typos/blob/master/docs/reference.md
+
+[default.extend-identifiers]
+ptd = "ptd"                         # From winwows_sys::Win32::System::Com::FORMATETC { ptd, ..}
+requestor = "requestor"             # From x11_dl::xlib::XSelectionEvent { requestor ..}
+XF86_Calculater = "XF86_Calculater" # From xkbcommon_dl::keysyms::XF86_Calculater