1use crate::application::ApplicationHandler;
2use crate::error::EventLoopError;
3use crate::event::Event;
4use crate::event_loop::{self, ActiveEventLoop, EventLoop};
5
6#[cfg(doc)]
7use crate::{platform::pump_events::EventLoopExtPumpEvents, window::Window};
8
9/// Additional methods on [`EventLoop`] to return control flow to the caller.
10pub trait EventLoopExtRunOnDemand {
11 /// A type provided by the user that can be passed through [`Event::UserEvent`].
12 type UserEvent: 'static;
13
14 /// See [`run_app_on_demand`].
15 ///
16 /// [`run_app_on_demand`]: Self::run_app_on_demand
17 #[deprecated = "use EventLoopExtRunOnDemand::run_app_on_demand"]
18 fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
19 where
20 F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop);
21
22 /// Run the application with the event loop on the calling thread.
23 ///
24 /// Unlike [`EventLoop::run_app`], this function accepts non-`'static` (i.e. non-`move`)
25 /// closures and it is possible to return control back to the caller without
26 /// consuming the `EventLoop` (by using [`exit()`]) and
27 /// so the event loop can be re-run after it has exit.
28 ///
29 /// It's expected that each run of the loop will be for orthogonal instantiations of your
30 /// Winit application, but internally each instantiation may re-use some common window
31 /// system resources, such as a display server connection.
32 ///
33 /// This API is not designed to run an event loop in bursts that you can exit from and return
34 /// to while maintaining the full state of your application. (If you need something like this
35 /// you can look at the [`EventLoopExtPumpEvents::pump_app_events()`] API)
36 ///
37 /// Each time `run_app_on_demand` is called the startup sequence of `init`, followed by
38 /// `resume` is being preserved.
39 ///
40 /// See the [`set_control_flow()`] docs on how to change the event loop's behavior.
41 ///
42 /// # Caveats
43 /// - This extension isn't available on all platforms, since it's not always possible to return
44 /// to the caller (specifically this is impossible on iOS and Web - though with the Web
45 /// backend it is possible to use `EventLoopExtWebSys::spawn()`
46 #[cfg_attr(not(web_platform), doc = "[^1]")]
47 /// more than once instead).
48 /// - No [`Window`] state can be carried between separate runs of the event loop.
49 ///
50 /// You are strongly encouraged to use [`EventLoop::run_app()`] for portability, unless you
51 /// specifically need the ability to re-run a single event loop more than once
52 ///
53 /// # Supported Platforms
54 /// - Windows
55 /// - Linux
56 /// - macOS
57 /// - Android
58 ///
59 /// # Unsupported Platforms
60 /// - **Web:** This API is fundamentally incompatible with the event-based way in which Web
61 /// browsers work because it's not possible to have a long-running external loop that would
62 /// block the browser and there is nothing that can be polled to ask for new events. Events
63 /// are delivered via callbacks based on an event loop that is internal to the browser itself.
64 /// - **iOS:** It's not possible to stop and start an `UIApplication` repeatedly on iOS.
65 #[cfg_attr(not(web_platform), doc = "[^1]: `spawn()` is only available on `wasm` platforms.")]
66 #[rustfmt::skip]
67 ///
68 /// [`exit()`]: ActiveEventLoop::exit()
69 /// [`set_control_flow()`]: ActiveEventLoop::set_control_flow()
70 fn run_app_on_demand<A: ApplicationHandler<Self::UserEvent>>(
71 &mut self,
72 app: &mut A,
73 ) -> Result<(), EventLoopError> {
74 #[allow(deprecated)]
75 self.run_on_demand(|event, event_loop| {
76 event_loop::dispatch_event_for_app(app, event_loop, event)
77 })
78 }
79}
80
81impl<T> EventLoopExtRunOnDemand for EventLoop<T> {
82 type UserEvent = T;
83
84 fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
85 where
86 F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop),
87 {
88 self.event_loop.window_target().clear_exit();
89 self.event_loop.run_on_demand(callback:event_handler)
90 }
91}
92
93impl ActiveEventLoop {
94 /// Clear exit status.
95 pub(crate) fn clear_exit(&self) {
96 self.p.clear_exit()
97 }
98}
99
100/// ```compile_fail
101/// use winit::event_loop::EventLoop;
102/// use winit::platform::run_on_demand::EventLoopExtRunOnDemand;
103///
104/// let mut event_loop = EventLoop::new().unwrap();
105/// event_loop.run_on_demand(|_, _| {
106/// // Attempt to run the event loop re-entrantly; this must fail.
107/// event_loop.run_on_demand(|_, _| {});
108/// });
109/// ```
110#[allow(dead_code)]
111fn test_run_on_demand_cannot_access_event_loop() {}
112