mirror of
https://github.com/rust-windowing/winit.git
synced 2026-06-28 07:33:14 -04:00
3fb93b4f83
Creating window when event loop is not running generally doesn't work, since a bunch of events and sync OS requests can't be processed. This is also an issue on e.g. Android, since window can't be created outside event loop easily. Thus deprecate the window creation when event loop is not running, as well as other resource creation to running event loop. Given that all the examples use the bad pattern of creating the window when event loop is not running and also most example existence is questionable, since they show single thing and the majority of their code is window/event loop initialization, they wore merged into a single example 'window.rs' example that showcases very simple application using winit. Fixes #3399.
103 lines
4.2 KiB
Rust
103 lines
4.2 KiB
Rust
use crate::{
|
|
error::EventLoopError,
|
|
event::Event,
|
|
event_loop::{ActiveEventLoop, EventLoop},
|
|
};
|
|
|
|
#[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 using [`exit()`]) and
|
|
/// so the event loop can be re-run after it has exit.
|
|
///
|
|
/// It's expected that each run of the loop will be for orthogonal instantiations of your
|
|
/// Winit application, but internally each instantiation may re-use some common window
|
|
/// 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_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.
|
|
///
|
|
/// See the [`set_control_flow()`] docs on how to change 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 `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
|
|
///
|
|
/// # 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 `UIApplication` repeatedly on iOS.
|
|
///
|
|
#[cfg_attr(
|
|
not(web_platform),
|
|
doc = "[^1]: `spawn()` is only available on `wasm` platforms."
|
|
)]
|
|
///
|
|
/// [`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);
|
|
}
|
|
|
|
impl<T> EventLoopExtRunOnDemand for EventLoop<T> {
|
|
type UserEvent = T;
|
|
|
|
fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
|
|
where
|
|
F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop),
|
|
{
|
|
self.event_loop.window_target().clear_exit();
|
|
self.event_loop.run_on_demand(event_handler)
|
|
}
|
|
}
|
|
|
|
impl ActiveEventLoop {
|
|
/// Clear exit status.
|
|
pub(crate) fn clear_exit(&self) {
|
|
self.p.clear_exit()
|
|
}
|
|
}
|
|
|
|
/// ```compile_fail
|
|
/// use winit::event_loop::EventLoop;
|
|
/// use winit::platform::run_on_demand::EventLoopExtRunOnDemand;
|
|
///
|
|
/// let mut event_loop = EventLoop::new().unwrap();
|
|
/// event_loop.run_on_demand(|_, _| {
|
|
/// // Attempt to run the event loop re-entrantly; this must fail.
|
|
/// event_loop.run_on_demand(|_, _| {});
|
|
/// });
|
|
/// ```
|
|
#[allow(dead_code)]
|
|
fn test_run_on_demand_cannot_access_event_loop() {}
|