Rename desktop eventloop extensions to run_return extension (#1738)

CHANGELOG.md

@@ -11,6 +11,7 @@
 - On macOS, fix compilation when targeting aarch64
 - On X11, fix `Window::request_redraw` not waking the event loop.
 - On Wayland, the keypad arrow keys are now recognized.
+- **Breaking** Rename `desktop::EventLoopExtDesktop` to `run_return::EventLoopExtRunReturn`.
 
 # 0.23.0 (2020-10-02)
 

examples/window_run_return.rs

@@ -15,7 +15,7 @@ fn main() {
     use winit::{
         event::{Event, WindowEvent},
         event_loop::{ControlFlow, EventLoop},
-        platform::desktop::EventLoopExtDesktop,
+        platform::run_return::EventLoopExtRunReturn,
         window::WindowBuilder,
     };
     let mut event_loop = EventLoop::new();

src/lib.rs

@@ -35,10 +35,10 @@
 //! entire program terminates.
 //!
 //! Winit no longer uses a `EventLoop::poll_events() -> impl Iterator<Event>`-based event loop
-//! model, since that can't be implemented properly on web and mobile platforms and works poorly on
-//! most desktop platforms. However, this model can be re-implemented to an extent on desktops with
-//! [`EventLoopExtDesktop::run_return`]. See that method's documentation for more reasons about why
-//! it's discouraged, beyond mobile/web compatibility reasons.
+//! model, since that can't be implemented properly on some platforms (e.g web, iOS) and works poorly on
+//! most other platforms. However, this model can be re-implemented to an extent with
+//! [`EventLoopExtRunReturn::run_return`]. See that method's documentation for more reasons about why
+//! it's discouraged, beyond compatibility reasons.
 //!
 //!
 //! ```no_run
@@ -109,7 +109,7 @@
 //! window visible only once you're ready to render into it.
 //!
 //! [`EventLoop`]: event_loop::EventLoop
-//! [`EventLoopExtDesktop::run_return`]: ./platform/desktop/trait.EventLoopExtDesktop.html#tymethod.run_return
+//! [`EventLoopExtRunReturn::run_return`]: ./platform/run_return/trait.EventLoopExtRunReturn.html#tymethod.run_return
 //! [`EventLoop::new()`]: event_loop::EventLoop::new
 //! [event_loop_run]: event_loop::EventLoop::run
 //! [`ControlFlow`]: event_loop::ControlFlow

src/platform/mod.rs

@@ -11,7 +11,7 @@
 //!
 //! And the following platform-specific module:
 //!
-//! - `desktop` (available on `windows`, `unix`, and `macos`)
+//! - `run_return` (available on `windows`, `unix`, `macos`, and `android`)
 //!
 //! However only the module corresponding to the platform you're compiling to will be available.
 
@@ -21,5 +21,5 @@ pub mod macos;
 pub mod unix;
 pub mod windows;
 
-pub mod desktop;
+pub mod run_return;
 pub mod web;

src/platform/desktop.rs → src/platform/run_return.rs

@@ -14,8 +14,8 @@ use crate::{
     event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
 };
 
-/// Additional methods on `EventLoop` that are specific to desktop platforms.
-pub trait EventLoopExtDesktop {
+/// Additional methods on `EventLoop` to return control flow to the caller.
+pub trait EventLoopExtRunReturn {
     /// A type provided by the user that can be passed through `Event::UserEvent`.
     type UserEvent;
 
@@ -25,12 +25,12 @@ pub trait EventLoopExtDesktop {
     /// control flow to the caller when `control_flow` is set to `ControlFlow::Exit`.
     ///
     /// # Caveats
-    /// Despite its apperance at first glance, this is *not* a perfect replacement for
+    /// Despite its appearance at first glance, this is *not* a perfect replacement for
     /// `poll_events`. For example, this function will not return on Windows or macOS while a
     /// window is getting resized, resulting in all application logic outside of the
     /// `event_handler` closure not running until the resize operation ends. Other OS operations
     /// may also result in such freezes. This behavior is caused by fundamental limitations in the
-    /// underyling OS APIs, which cannot be hidden by Winit without severe stability reprecussions.
+    /// underlying OS APIs, which cannot be hidden by `winit` without severe stability repercussions.
     ///
     /// You are strongly encouraged to use `run`, unless the use of this is absolutely necessary.
     fn run_return<F>(&mut self, event_handler: F)
@@ -42,7 +42,7 @@ pub trait EventLoopExtDesktop {
         );
 }
 
-impl<T> EventLoopExtDesktop for EventLoop<T> {
+impl<T> EventLoopExtRunReturn for EventLoop<T> {
     type UserEvent = T;
 
     fn run_return<F>(&mut self, event_handler: F)