Event Loop 2.0 API and Windows implementation

CHANGELOG.md

@@ -1,4 +1,41 @@
 # Unreleased
+- Changes below are considered **breaking**.
+- Change all occurrences of `EventsLoop` to `EventLoop`.
+- Previously flat API is now exposed through `event`, `event_loop`, `monitor`, and `window` modules.
+- `os` module changes:
+  - Renamed to `platform`.
+  - All traits now have platform-specific suffixes.
+  - Exposes new `desktop` module on Windows, Mac, and Linux.
+- Changes to event loop types:
+  - `EventLoopProxy::wakeup` has been removed in favor of `send_event`.
+  - **Major:** New `run` method drives winit event loop.
+    - Returns `!` to ensure API behaves identically across all supported platforms.
+      - This allows `emscripten` implementation to work without lying about the API.
+    - `ControlFlow`'s variants have been replaced with `Wait`, `WaitUntil(Instant)`, `Poll`, and `Exit`.
+      - Is read after `EventsCleared` is processed.
+      - `Wait` waits until new events are available.
+      - `WaitUntil` waits until either new events are available or the provided time has been reached.
+      - `Poll` instantly resumes the event loop.
+      - `Exit` aborts the event loop.
+    - Takes a closure that implements `'static + FnMut(Event<T>, &EventLoop<T>, &mut ControlFlow)`.
+      - `&EventLoop<T>` is provided to allow new `Window`s to be created.
+  - **Major:** `platform::desktop` module exposes `EventLoopExtDesktop` trait with `run_return` method.
+    - Behaves identically to `run`, but returns control flow to the calling context can take non-`'static` closures.
+  - `EventLoop`'s `poll_events` and `run_forever` methods have been removed in favor of `run` and `run_return`.
+- Changes to events:
+  - Remove `Event::Awakened` in favor of `Event::UserEvent(T)`.
+    - Can be sent with `EventLoopProxy::send_event`.
+  - Rename `WindowEvent::Refresh` to `WindowEvent::RedrawRequested`.
+    - `RedrawRequested` can be sent by the user with the `Window::request_redraw` method.
+  - `EventLoop`, `EventLoopProxy`, and `Event` are now generic over `T`, for use in `UserEvent`.
+  - **Major:** Add `NewEvents(StartCause)`, `EventsCleared`, and `LoopDestroyed` variants to `Event`.
+    - `NewEvents` is emitted when new events are ready to be processed by event loop.
+      - `StartCause` describes why new events are available, with `ResumeTimeReached`, `Poll`, `WaitCancelled`, and `Init` (sent once at start of loop).
+    - `EventsCleared` is emitted when all available events have been processed.
+      - Can be used to perform logic that depends on all events being processed (e.g. an iteration of a game loop).
+    - `LoopDestroyed` is emitted when the `run` or `run_return` method is about to exit.
+- Rename `MonitorId` to `MonitorHandle`.
+- Removed `serde` implementations from `ControlFlow`.
 
 # Version 0.18.0 (2018-11-07)
 

Cargo.toml

@@ -39,6 +39,7 @@ core-graphics = "0.17.3"
 version = "0.3.6"
 features = [
     "combaseapi",
+    "commctrl",
     "dwmapi",
     "errhandlingapi",
     "hidusage",
@@ -62,5 +63,7 @@ features = [
 wayland-client = { version = "0.21", features = [ "dlopen", "egl", "cursor"] }
 smithay-client-toolkit = "0.4"
 x11-dl = "2.18.3"
-parking_lot = "0.6"
 percent-encoding = "1.0"
+
+[target.'cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "openbsd", target_os = "windows"))'.dependencies.parking_lot]
+version = "0.6"

README.md

@@ -26,10 +26,10 @@ another library.
 extern crate winit;
 
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
-    let window = winit::Window::new(&events_loop).unwrap();
+    let mut event_loop = winit::EventLoop::new();
+    let window = winit::Window::new(&event_loop).unwrap();
 
-    events_loop.run_forever(|event| {
+    event_loop.run(|event| {
         match event {
             winit::Event::WindowEvent {
               event: winit::WindowEvent::CloseRequested,

examples/cursor.rs

@@ -1,32 +1,48 @@
 extern crate winit;
 
-use winit::{Event, ElementState, MouseCursor, WindowEvent, KeyboardInput, ControlFlow};
+use winit::window::{WindowBuilder, MouseCursor};
+use winit::event::{Event, WindowEvent, ElementState, KeyboardInput};
+use winit::event_loop::{EventLoop, ControlFlow};
 
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
+    let event_loop = EventLoop::new();
 
-    let window = winit::WindowBuilder::new().build(&events_loop).unwrap();
+    let window = WindowBuilder::new().build(&event_loop).unwrap();
     window.set_title("A fantastic window!");
 
-    let cursors = [MouseCursor::Default, MouseCursor::Crosshair, MouseCursor::Hand, MouseCursor::Arrow, MouseCursor::Move, MouseCursor::Text, MouseCursor::Wait, MouseCursor::Help, MouseCursor::Progress, MouseCursor::NotAllowed, MouseCursor::ContextMenu, MouseCursor::Cell, MouseCursor::VerticalText, MouseCursor::Alias, MouseCursor::Copy, MouseCursor::NoDrop, MouseCursor::Grab, MouseCursor::Grabbing, MouseCursor::AllScroll, MouseCursor::ZoomIn, MouseCursor::ZoomOut, MouseCursor::EResize, MouseCursor::NResize, MouseCursor::NeResize, MouseCursor::NwResize, MouseCursor::SResize, MouseCursor::SeResize, MouseCursor::SwResize, MouseCursor::WResize, MouseCursor::EwResize, MouseCursor::NsResize, MouseCursor::NeswResize, MouseCursor::NwseResize, MouseCursor::ColResize, MouseCursor::RowResize];
     let mut cursor_idx = 0;
 
-    events_loop.run_forever(|event| {
+    event_loop.run(move |event, _, control_flow| {
         match event {
             Event::WindowEvent { event: WindowEvent::KeyboardInput { input: KeyboardInput { state: ElementState::Pressed, .. }, .. }, .. } => {
-                println!("Setting cursor to \"{:?}\"", cursors[cursor_idx]);
-                window.set_cursor(cursors[cursor_idx]);
-                if cursor_idx < cursors.len() - 1 {
+                println!("Setting cursor to \"{:?}\"", CURSORS[cursor_idx]);
+                window.set_cursor(CURSORS[cursor_idx]);
+                if cursor_idx < CURSORS.len() - 1 {
                     cursor_idx += 1;
                 } else {
                     cursor_idx = 0;
                 }
             },
             Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
-                return ControlFlow::Break;
+                *control_flow = ControlFlow::Exit;
+                return;
             },
             _ => ()
         }
-        ControlFlow::Continue
     });
 }
+
+const CURSORS: &[MouseCursor] = &[
+    MouseCursor::Default, MouseCursor::Crosshair, MouseCursor::Hand,
+    MouseCursor::Arrow, MouseCursor::Move, MouseCursor::Text,
+    MouseCursor::Wait, MouseCursor::Help, MouseCursor::Progress,
+    MouseCursor::NotAllowed, MouseCursor::ContextMenu, MouseCursor::Cell,
+    MouseCursor::VerticalText, MouseCursor::Alias, MouseCursor::Copy,
+    MouseCursor::NoDrop, MouseCursor::Grab, MouseCursor::Grabbing,
+    MouseCursor::AllScroll, MouseCursor::ZoomIn, MouseCursor::ZoomOut,
+    MouseCursor::EResize, MouseCursor::NResize, MouseCursor::NeResize,
+    MouseCursor::NwResize, MouseCursor::SResize, MouseCursor::SeResize,
+    MouseCursor::SwResize, MouseCursor::WResize, MouseCursor::EwResize,
+    MouseCursor::NsResize, MouseCursor::NeswResize, MouseCursor::NwseResize,
+    MouseCursor::ColResize, MouseCursor::RowResize
+];

examples/cursor_grab.rs

@@ -1,30 +1,34 @@
 extern crate winit;
 
+use winit::window::WindowBuilder;
+use winit::event::{Event, WindowEvent, ElementState, KeyboardInput};
+use winit::event_loop::{EventLoop, ControlFlow};
+
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
+    let event_loop = EventLoop::new();
 
-    let window = winit::WindowBuilder::new()
+    let window = WindowBuilder::new()
         .with_title("Super Cursor Grab'n'Hide Simulator 9000")
-        .build(&events_loop)
+        .build(&event_loop)
         .unwrap();
 
-    events_loop.run_forever(|event| {
-        if let winit::Event::WindowEvent { event, .. } = event {
-            use winit::WindowEvent::*;
+    event_loop.run(move |event, _, control_flow| {
+        *control_flow = ControlFlow::Wait;
+        if let Event::WindowEvent { event, .. } = event {
             match event {
-                CloseRequested => return winit::ControlFlow::Break,
-                KeyboardInput {
-                    input: winit::KeyboardInput {
-                        state: winit::ElementState::Released,
+                WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
+                WindowEvent::KeyboardInput {
+                    input: KeyboardInput {
+                        state: ElementState::Released,
                         virtual_keycode: Some(key),
                         modifiers,
                         ..
                     },
                     ..
                 } => {
-                    use winit::VirtualKeyCode::*;
+                    use winit::event::VirtualKeyCode::*;
                     match key {
-                        Escape => return winit::ControlFlow::Break,
+                        Escape => *control_flow = ControlFlow::Exit,
                         G => window.grab_cursor(!modifiers.shift).unwrap(),
                         H => window.hide_cursor(!modifiers.shift),
                         _ => (),
@@ -33,6 +37,5 @@ fn main() {
                 _ => (),
             }
         }
-        winit::ControlFlow::Continue
     });
 }

examples/fullscreen.rs

@@ -1,14 +1,16 @@
 extern crate winit;
 
 use std::io::{self, Write};
-use winit::{ControlFlow, Event, WindowEvent};
+use winit::window::WindowBuilder;
+use winit::event::{Event, WindowEvent, VirtualKeyCode, ElementState, KeyboardInput};
+use winit::event_loop::{EventLoop, ControlFlow};
 
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
+    let event_loop = EventLoop::new();
 
     // enumerating monitors
     let monitor = {
-        for (num, monitor) in events_loop.get_available_monitors().enumerate() {
+        for (num, monitor) in event_loop.get_available_monitors().enumerate() {
             println!("Monitor #{}: {:?}", num, monitor.get_name());
         }
 
@@ -18,52 +20,53 @@ fn main() {
         let mut num = String::new();
         io::stdin().read_line(&mut num).unwrap();
         let num = num.trim().parse().ok().expect("Please enter a number");
-        let monitor = events_loop.get_available_monitors().nth(num).expect("Please enter a valid ID");
+        let monitor = event_loop.get_available_monitors().nth(num).expect("Please enter a valid ID");
 
         println!("Using {:?}", monitor.get_name());
 
         monitor
     };
 
-    let window = winit::WindowBuilder::new()
+    let window = WindowBuilder::new()
         .with_title("Hello world!")
         .with_fullscreen(Some(monitor))
-        .build(&events_loop)
+        .build(&event_loop)
         .unwrap();
 
     let mut is_fullscreen = true;
     let mut is_maximized = false;
     let mut decorations = true;
 
-    events_loop.run_forever(|event| {
+    event_loop.run(move |event, _, control_flow| {
         println!("{:?}", event);
+        *control_flow = ControlFlow::Wait;
 
         match event {
             Event::WindowEvent { event, .. } => match event {
-                WindowEvent::CloseRequested => return ControlFlow::Break,
+                WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
                 WindowEvent::KeyboardInput {
                     input:
-                        winit::KeyboardInput {
+                        KeyboardInput {
                             virtual_keycode: Some(virtual_code),
                             state,
                             ..
                         },
                     ..
                 } => match (virtual_code, state) {
-                    (winit::VirtualKeyCode::Escape, _) => return ControlFlow::Break,
-                    (winit::VirtualKeyCode::F, winit::ElementState::Pressed) => {
+                    (VirtualKeyCode::Escape, _) => *control_flow = ControlFlow::Exit,
+                    (VirtualKeyCode::F, ElementState::Pressed) => {
                         is_fullscreen = !is_fullscreen;
                         if !is_fullscreen {
                             window.set_fullscreen(None);
                         } else {
                             window.set_fullscreen(Some(window.get_current_monitor()));
                         }
                     }
-                    (winit::VirtualKeyCode::M, winit::ElementState::Pressed) => {
+                    (VirtualKeyCode::M, ElementState::Pressed) => {
                         is_maximized = !is_maximized;
                         window.set_maximized(is_maximized);
                     }
-                    (winit::VirtualKeyCode::D, winit::ElementState::Pressed) => {
+                    (VirtualKeyCode::D, ElementState::Pressed) => {
                         decorations = !decorations;
                         window.set_decorations(decorations);
                     }
@@ -73,7 +76,5 @@ fn main() {
             },
             _ => {}
         }
-
-        ControlFlow::Continue
     });
 }

examples/handling_close.rs

@@ -1,23 +1,27 @@
 extern crate winit;
 
+use winit::window::WindowBuilder;
+use winit::event::{Event, WindowEvent, KeyboardInput};
+use winit::event_loop::{EventLoop, ControlFlow};
+
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
+    let event_loop = EventLoop::new();
 
-    let _window = winit::WindowBuilder::new()
+    let _window = WindowBuilder::new()
         .with_title("Your faithful window")
-        .build(&events_loop)
+        .build(&event_loop)
         .unwrap();
 
     let mut close_requested = false;
 
-    events_loop.run_forever(|event| {
-        use winit::WindowEvent::*;
-        use winit::ElementState::Released;
-        use winit::VirtualKeyCode::{N, Y};
+    event_loop.run(move |event, _, control_flow| {
+        use winit::event::ElementState::Released;
+        use winit::event::VirtualKeyCode::{N, Y};
+        *control_flow = ControlFlow::Wait;
 
         match event {
-            winit::Event::WindowEvent { event, .. } => match event {
-                CloseRequested => {
+            Event::WindowEvent { event, .. } => match event {
+                WindowEvent::CloseRequested => {
                     // `CloseRequested` is sent when the close button on the window is pressed (or
                     // through whatever other mechanisms the window manager provides for closing a
                     // window). If you don't handle this event, the close button won't actually do
@@ -34,9 +38,9 @@ fn main() {
                     // closing the window. How to close the window is detailed in the handler for
                     // the Y key.
                 }
-                KeyboardInput {
+                WindowEvent::KeyboardInput {
                     input:
-                        winit::KeyboardInput {
+                        KeyboardInput {
                             virtual_keycode: Some(virtual_code),
                             state: Released,
                             ..
@@ -53,7 +57,7 @@ fn main() {
                             // event loop (i.e. if it's a multi-window application), you need to
                             // drop the window. That closes it, and results in `Destroyed` being
                             // sent.
-                            return winit::ControlFlow::Break;
+                            *control_flow = ControlFlow::Exit;
                         }
                     }
                     N => {
@@ -68,7 +72,5 @@ fn main() {
             },
             _ => (),
         }
-
-        winit::ControlFlow::Continue
     });
 }

examples/min_max_size.rs

@@ -1,23 +1,27 @@
 extern crate winit;
 
 use winit::dpi::LogicalSize;
+use winit::window::WindowBuilder;
+use winit::event::{Event, WindowEvent};
+use winit::event_loop::{EventLoop, ControlFlow};
 
 fn main() {
-    let mut events_loop = winit::EventsLoop::new();
+    let event_loop = EventLoop::new();
 
-    let window = winit::WindowBuilder::new()
-        .build(&events_loop)
+    let window = WindowBuilder::new()
+        .build(&event_loop)
         .unwrap();
 
     window.set_min_dimensions(Some(LogicalSize::new(400.0, 200.0)));
     window.set_max_dimensions(Some(LogicalSize::new(800.0, 400.0)));
 
-    events_loop.run_forever(|event| {
+    event_loop.run(move |event, _, control_flow| {
         println!("{:?}", event);
 
         match event {
-            winit::Event::WindowEvent { event: winit::WindowEvent::CloseRequested, .. } => winit::ControlFlow::Break,
-            _ => winit::ControlFlow::Continue,
+            Event::WindowEvent { event: WindowEvent::CloseRequested, .. } =>
+                *control_flow = ControlFlow::Exit,
+            _ => *control_flow = ControlFlow::Wait,
         }
     });
 }

examples/monitor_list.rs

@@ -1,7 +1,9 @@
 extern crate winit;
+use winit::event_loop::EventLoop;
+use winit::window::WindowBuilder;
 
 fn main() {
-    let event_loop = winit::EventsLoop::new();
-    let window = winit::WindowBuilder::new().build(&event_loop).unwrap();
+    let event_loop = EventLoop::new();
+    let window = WindowBuilder::new().build(&event_loop).unwrap();
     println!("{:#?}\nPrimary: {:#?}", window.get_available_monitors(), window.get_primary_monitor());
 }