rio_window::platform::run_on_demand

Trait EventLoopExtRunOnDemand

Source 
pub trait EventLoopExtRunOnDemand {
    type UserEvent: 'static;

    // Required method
    fn run_on_demand<F>(
        &mut self,
        event_handler: F,
    ) -> Result<(), EventLoopError>
       where F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop);

    // Provided method
    fn run_app_on_demand<A: ApplicationHandler<Self::UserEvent>>(
        &mut self,
        app: &mut A,
    ) -> Result<(), EventLoopError> { ... }
}
Expand description

Additional methods on EventLoop to return control flow to the caller.

Required Associated Types§

Source

type UserEvent: 'static

A type provided by the user that can be passed through Event::UserEvent.

Required Methods§

Source

fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
where F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop),

👎Deprecated: use EventLoopExtRunOnDemand::run_app_on_demand

See run_app_on_demand.

Provided Methods§

Source

fn run_app_on_demand<A: ApplicationHandler<Self::UserEvent>>( &mut self, app: &mut A, ) -> Result<(), EventLoopError>

Run the application with the event loop on the calling thread.

Unlike EventLoop::run_app, 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_app_events() API)

Each time run_app_on_demand is called the startup sequence of init, followed by resume is being preserved.

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_app() 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.

  1. spawn() is only available on wasm platforms. ↩

Examples found in repository?
examples/run_on_demand.rs (line 87)
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
fn main() -> Result<(), Box<dyn std::error::Error>> {
    use std::time::Duration;

    use rio_window::application::ApplicationHandler;
    use rio_window::event::WindowEvent;
    use rio_window::event_loop::{ActiveEventLoop, EventLoop};
    use rio_window::platform::run_on_demand::EventLoopExtRunOnDemand;
    use rio_window::window::{Window, WindowId};

    #[path = "util/fill.rs"]
    mod fill;

    #[derive(Default)]
    struct App {
        idx: usize,
        window_id: Option<WindowId>,
        window: Option<Window>,
    }

    impl ApplicationHandler for App {
        fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {
            if let Some(window) = self.window.as_ref() {
                window.request_redraw();
            }
        }

        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
            let window_attributes = Window::default_attributes()
                .with_title("Fantastic window number one!")
                .with_inner_size(rio_window::dpi::LogicalSize::new(128.0, 128.0));
            let window = event_loop.create_window(window_attributes).unwrap();
            self.window_id = Some(window.id());
            self.window = Some(window);
        }

        fn window_event(
            &mut self,
            event_loop: &ActiveEventLoop,
            window_id: WindowId,
            event: WindowEvent,
        ) {
            if event == WindowEvent::Destroyed && self.window_id == Some(window_id) {
                println!(
                    "--------------------------------------------------------- Window {} Destroyed",
                    self.idx
                );
                self.window_id = None;
                event_loop.exit();
                return;
            }

            let window = match self.window.as_mut() {
                Some(window) => window,
                None => return,
            };

            match event {
                WindowEvent::CloseRequested => {
                    println!(
                        "--------------------------------------------------------- Window {} \
                         CloseRequested",
                        self.idx
                    );
                    fill::cleanup_window(window);
                    self.window = None;
                }
                WindowEvent::RedrawRequested => {
                    fill::fill_window(window);
                }
                _ => (),
            }
        }
    }

    tracing_subscriber::fmt::init();

    let mut event_loop = EventLoop::new().unwrap();

    let mut app = App {
        idx: 1,
        ..Default::default()
    };
    event_loop.run_app_on_demand(&mut app)?;

    println!(
        "--------------------------------------------------------- Finished first loop"
    );
    println!(
        "--------------------------------------------------------- Waiting 5 seconds"
    );
    std::thread::sleep(Duration::from_secs(5));

    app.idx += 1;
    event_loop.run_app_on_demand(&mut app)?;
    println!(
        "--------------------------------------------------------- Finished second loop"
    );
    Ok(())
}

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§