f40b5f0dad
This adds two new extensions for running a Winit event loop which will replace `EventLoopExtRunReturn` The `run_return` API is trying to solve multiple problems and address multiple, unrelated, use cases but in doing so it is not succeeding at addressing any of them fully. The notable use cases we have are: 1. Applications want to be able to implement their own external event loop and call some Winit API to poll / pump events, once per iteration of their own loop, without blocking the outer, external loop. Addressing #2706 2. Applications want to be able to re-run separate instantiations of some Winit-based GUI and want to allow the event loop to exit with a status, and then later be able to run the loop again for a new instantiation of their GUI. Addressing #2431 It's very notable that these use cases can't be supported across all platforms and so they are extensions, similar to `EventLoopExtRunReturn` The intention is to support these extensions on: - Windows - Linux (X11 + Wayland) - macOS - Android These extensions aren't compatible with Web or iOS though. Each method of running the loop will behave consistently in terms of how `NewEvents(Init)`, `Resumed` and `LoopDestroyed` events are dispatched (so portable application code wouldn't necessarily need to have any awareness of which method of running the loop was being used) Once all backends have support for these extensions then we can remove `EventLoopExtRunReturn` For simplicity, the extensions are documented with the assumption that the above platforms will be supported. This patch makes no functional change, it only introduces these new extensions so we can then handle adding platform-specific backends in separate pull requests, so the work can be landed in stages.
82 lines
3.6 KiB
Rust
82 lines
3.6 KiB
Rust
use crate::{
|
|
error::RunLoopError,
|
|
event::Event,
|
|
event_loop::{ControlFlow, EventLoop, EventLoopWindowTarget},
|
|
};
|
|
|
|
#[cfg(doc)]
|
|
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;
|
|
|
|
/// Runs the event loop in the calling thread and calls the given `event_handler` closure
|
|
/// to dispatch any window system events.
|
|
///
|
|
/// Unlike [`EventLoop::run`], 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 setting the `control_flow` to [`ControlFlow::Exit`]) and
|
|
/// so the event loop can be re-run after it has exit.
|
|
///
|
|
/// It's expected that each run of the loop will be for orthogonal instantiations of your
|
|
/// Winit application, but internally each instantiation may re-use some common window
|
|
/// system resources, such as a display server connection.
|
|
///
|
|
/// 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)
|
|
///
|
|
/// Each time `run_ondemand` 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.
|
|
///
|
|
/// See the [`ControlFlow`] docs for information on how changes to `&mut ControlFlow` impact the
|
|
/// event loop's behavior.
|
|
///
|
|
/// # Caveats
|
|
/// - This extension isn't available on all platforms, since it's not always possible to
|
|
/// return to the caller (specifically this is impossible on iOS and Web - though with
|
|
/// the Web backend it is possible to use `spawn()` 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
|
|
///
|
|
/// # Supported Platforms
|
|
/// - Windows
|
|
/// - Linux
|
|
/// - macOS
|
|
/// - Android
|
|
///
|
|
/// # Unsupported Platforms
|
|
/// - **Web:** This API is fundamentally incompatible with the event-based way in which
|
|
/// Web browsers work because it's not possible to have a long-running external
|
|
/// loop that would block the browser and there is nothing that can be
|
|
/// polled to ask for new events. Events are delivered via callbacks based
|
|
/// on an event loop that is internal to the browser itself.
|
|
/// - **iOS:** It's not possible to stop and start an `NSApplication` repeatedly on iOS.
|
|
fn run_ondemand<F>(&mut self, event_handler: F) -> Result<(), RunLoopError>
|
|
where
|
|
F: FnMut(
|
|
Event<'_, Self::UserEvent>,
|
|
&EventLoopWindowTarget<Self::UserEvent>,
|
|
&mut ControlFlow,
|
|
);
|
|
}
|
|
|
|
impl<T> EventLoopExtRunOnDemand for EventLoop<T> {
|
|
type UserEvent = T;
|
|
|
|
fn run_ondemand<F>(&mut self, event_handler: F) -> Result<(), RunLoopError>
|
|
where
|
|
F: FnMut(
|
|
Event<'_, Self::UserEvent>,
|
|
&EventLoopWindowTarget<Self::UserEvent>,
|
|
&mut ControlFlow,
|
|
),
|
|
{
|
|
self.event_loop.run_ondemand(event_handler)
|
|
}
|
|
}
|