Struct EventLoop

pub struct EventLoop<T: 'static> { /* private fields */ }

Provides a way to retrieve events from the system and from the windows that were registered to the events loop.

An EventLoop can be seen more or less as a “context”. Calling EventLoop::new initializes everything that will be required to create windows. For example on Linux creating an event loop opens a connection to the X or Wayland server.

To wake up an EventLoop from a another thread, see the EventLoopProxy docs.

Note that this cannot be shared across threads (due to platform-dependant logic forbidding it), as such it is neither Send nor Sync. If you need cross-thread access, the Window created from this can be sent to an other thread, and the EventLoopProxy allows you to wake up an EventLoop from another thread.

Implementations

impl EventLoop<()>

pub fn new() -> Result<EventLoop<()>, EventLoopError>

Create the event loop.

This is an alias of EventLoop::builder().build().

Examples found in repository

examples/control_flow.rs (line 45)

fn main() -> Result<(), impl std::error::Error> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    info!("Press '1' to switch to Wait mode.");
    info!("Press '2' to switch to WaitUntil mode.");
    info!("Press '3' to switch to Poll mode.");
    info!("Press 'R' to toggle request_redraw() calls.");
    info!("Press 'Esc' to close the window.");

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

    let mut app = ControlFlowDemo::default();
    event_loop.run_app(&mut app)
}

examples/pump_events.rs (line 61)

fn main() -> std::process::ExitCode {
    use std::process::ExitCode;
    use std::thread::sleep;
    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::pump_events::{EventLoopExtPumpEvents, PumpStatus};
    use rio_window::window::{Window, WindowId};

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

    #[derive(Default)]
    struct PumpDemo {
        window: Option<Window>,
    }

    impl ApplicationHandler for PumpDemo {
        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
            let window_attributes =
                Window::default_attributes().with_title("A fantastic window!");
            self.window = Some(event_loop.create_window(window_attributes).unwrap());
        }

        fn window_event(
            &mut self,
            event_loop: &ActiveEventLoop,
            _window_id: WindowId,
            event: WindowEvent,
        ) {
            println!("{event:?}");

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

            match event {
                WindowEvent::CloseRequested => event_loop.exit(),
                WindowEvent::RedrawRequested => {
                    fill::fill_window(window);
                    window.request_redraw();
                }
                _ => (),
            }
        }
    }

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

    tracing_subscriber::fmt::init();

    let mut app = PumpDemo::default();

    loop {
        let timeout = Some(Duration::ZERO);
        let status = event_loop.pump_app_events(timeout, &mut app);

        if let PumpStatus::Exit(exit_code) = status {
            break ExitCode::from(exit_code as u8);
        }

        // Sleep for 1/60 second to simulate application work
        //
        // Since `pump_events` doesn't block it will be important to
        // throttle the loop in the app somehow.
        println!("Update()");
        sleep(Duration::from_millis(16));
    }
}

examples/run_on_demand.rs (line 81)

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(())
}

examples/child_window.rs (line 30)

fn main() -> Result<(), impl std::error::Error> {
    use std::collections::HashMap;

    use rio_window::dpi::{LogicalPosition, LogicalSize, Position};
    use rio_window::event::{ElementState, Event, KeyEvent, WindowEvent};
    use rio_window::event_loop::{ActiveEventLoop, EventLoop};
    use rio_window::raw_window_handle::HasRawWindowHandle;
    use rio_window::window::Window;

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

    fn spawn_child_window(parent: &Window, event_loop: &ActiveEventLoop) -> Window {
        let parent = parent.raw_window_handle().unwrap();
        let mut window_attributes = Window::default_attributes()
            .with_title("child window")
            .with_inner_size(LogicalSize::new(200.0f32, 200.0f32))
            .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
            .with_visible(true);
        // `with_parent_window` is unsafe. Parent window must be a valid window.
        window_attributes = unsafe { window_attributes.with_parent_window(Some(parent)) };

        event_loop.create_window(window_attributes).unwrap()
    }

    let mut windows = HashMap::new();

    let event_loop: EventLoop<()> = EventLoop::new().unwrap();
    let mut parent_window_id = None;

    event_loop.run(move |event: Event<()>, event_loop| {
        match event {
            Event::Resumed => {
                let attributes = Window::default_attributes()
                    .with_title("parent window")
                    .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
                    .with_inner_size(LogicalSize::new(640.0f32, 480.0f32));
                let window = event_loop.create_window(attributes).unwrap();

                parent_window_id = Some(window.id());

                println!("Parent window id: {parent_window_id:?})");
                windows.insert(window.id(), window);
            }
            Event::WindowEvent { window_id, event } => match event {
                WindowEvent::CloseRequested => {
                    windows.clear();
                    event_loop.exit();
                }
                WindowEvent::CursorEntered { device_id: _ } => {
                    // On x11, println when the cursor entered in a window even if the child window
                    // is created by some key inputs.
                    // the child windows are always placed at (0, 0) with size (200, 200) in the
                    // parent window, so we also can see this log when we move
                    // the cursor around (200, 200) in parent window.
                    println!("cursor entered in the window {window_id:?}");
                }
                WindowEvent::KeyboardInput {
                    event:
                        KeyEvent {
                            state: ElementState::Pressed,
                            ..
                        },
                    ..
                } => {
                    let parent_window = windows.get(&parent_window_id.unwrap()).unwrap();
                    let child_window = spawn_child_window(parent_window, event_loop);
                    let child_id = child_window.id();
                    println!("Child window created with id: {child_id:?}");
                    windows.insert(child_id, child_window);
                }
                WindowEvent::RedrawRequested => {
                    if let Some(window) = windows.get(&window_id) {
                        fill::fill_window(window);
                    }
                }
                _ => (),
            },
            _ => (),
        }
    })
}

pub fn builder() -> EventLoopBuilder<()>

Start building a new event loop.

This returns an EventLoopBuilder, to allow configuring the event loop before creation.

To get the actual event loop, call build on that.

impl<T> EventLoop<T>

pub fn with_user_event() -> EventLoopBuilder<T>

Start building a new event loop, with the given type as the user event type.

Examples found in repository

examples/window.rs (line 52)

fn main() -> Result<(), Box<dyn Error>> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    let event_loop = EventLoop::<UserEvent>::with_user_event().build()?;
    let _event_loop_proxy = event_loop.create_proxy();

    // Wire the user event from another thread.
    #[cfg(not(web_platform))]
    std::thread::spawn(move || {
        // Wake up the `event_loop` once every second and dispatch a custom event
        // from a different thread.
        info!("Starting to send user event every second");
        loop {
            let _ = _event_loop_proxy.send_event(UserEvent::WakeUp);
            std::thread::sleep(std::time::Duration::from_secs(1));
        }
    });

    let mut state = Application::new(&event_loop);

    event_loop.run_app(&mut state).map_err(Into::into)
}

pub fn run<F>(self, event_handler: F) -> Result<(), EventLoopError>

where F: FnMut(Event<T>, &ActiveEventLoop),

👎Deprecated: use EventLoop::run_app instead

See run_app.

Examples found in repository

examples/child_window.rs (lines 33-83)

fn main() -> Result<(), impl std::error::Error> {
    use std::collections::HashMap;

    use rio_window::dpi::{LogicalPosition, LogicalSize, Position};
    use rio_window::event::{ElementState, Event, KeyEvent, WindowEvent};
    use rio_window::event_loop::{ActiveEventLoop, EventLoop};
    use rio_window::raw_window_handle::HasRawWindowHandle;
    use rio_window::window::Window;

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

    fn spawn_child_window(parent: &Window, event_loop: &ActiveEventLoop) -> Window {
        let parent = parent.raw_window_handle().unwrap();
        let mut window_attributes = Window::default_attributes()
            .with_title("child window")
            .with_inner_size(LogicalSize::new(200.0f32, 200.0f32))
            .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
            .with_visible(true);
        // `with_parent_window` is unsafe. Parent window must be a valid window.
        window_attributes = unsafe { window_attributes.with_parent_window(Some(parent)) };

        event_loop.create_window(window_attributes).unwrap()
    }

    let mut windows = HashMap::new();

    let event_loop: EventLoop<()> = EventLoop::new().unwrap();
    let mut parent_window_id = None;

    event_loop.run(move |event: Event<()>, event_loop| {
        match event {
            Event::Resumed => {
                let attributes = Window::default_attributes()
                    .with_title("parent window")
                    .with_position(Position::Logical(LogicalPosition::new(0.0, 0.0)))
                    .with_inner_size(LogicalSize::new(640.0f32, 480.0f32));
                let window = event_loop.create_window(attributes).unwrap();

                parent_window_id = Some(window.id());

                println!("Parent window id: {parent_window_id:?})");
                windows.insert(window.id(), window);
            }
            Event::WindowEvent { window_id, event } => match event {
                WindowEvent::CloseRequested => {
                    windows.clear();
                    event_loop.exit();
                }
                WindowEvent::CursorEntered { device_id: _ } => {
                    // On x11, println when the cursor entered in a window even if the child window
                    // is created by some key inputs.
                    // the child windows are always placed at (0, 0) with size (200, 200) in the
                    // parent window, so we also can see this log when we move
                    // the cursor around (200, 200) in parent window.
                    println!("cursor entered in the window {window_id:?}");
                }
                WindowEvent::KeyboardInput {
                    event:
                        KeyEvent {
                            state: ElementState::Pressed,
                            ..
                        },
                    ..
                } => {
                    let parent_window = windows.get(&parent_window_id.unwrap()).unwrap();
                    let child_window = spawn_child_window(parent_window, event_loop);
                    let child_id = child_window.id();
                    println!("Child window created with id: {child_id:?}");
                    windows.insert(child_id, child_window);
                }
                WindowEvent::RedrawRequested => {
                    if let Some(window) = windows.get(&window_id) {
                        fill::fill_window(window);
                    }
                }
                _ => (),
            },
            _ => (),
        }
    })
}

pub fn run_app<A: ApplicationHandler<T>>( self, app: &mut A, ) -> Result<(), EventLoopError>

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

See the set_control_flow() docs on how to change the event loop’s behavior.

Platform-specific

• iOS: Will never return to the caller and so values not passed to this function will not be dropped before the process exits.

• Web: Will act as if it never returns to the caller by throwing a Javascript exception (that Rust doesn’t see) that will also mean that the rest of the function is never executed and any values not passed to this function will not be dropped.

  Web applications are recommended to use EventLoopExtWebSys::spawn() ¹ instead of run_app() to avoid the need for the Javascript exception trick, and to make it clearer that the event loop runs asynchronously (via the browser’s own, internal, event loop) and doesn’t block the current thread of execution like it does on other platforms.

  This function won’t be available with target_feature = "exception-handling".

---

1. EventLoopExtWebSys::spawn_app() is only available on Web. ↩

Examples found in repository

examples/control_flow.rs (line 48)

fn main() -> Result<(), impl std::error::Error> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    info!("Press '1' to switch to Wait mode.");
    info!("Press '2' to switch to WaitUntil mode.");
    info!("Press '3' to switch to Poll mode.");
    info!("Press 'R' to toggle request_redraw() calls.");
    info!("Press 'Esc' to close the window.");

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

    let mut app = ControlFlowDemo::default();
    event_loop.run_app(&mut app)
}

examples/window.rs (line 69)

fn main() -> Result<(), Box<dyn Error>> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    let event_loop = EventLoop::<UserEvent>::with_user_event().build()?;
    let _event_loop_proxy = event_loop.create_proxy();

    // Wire the user event from another thread.
    #[cfg(not(web_platform))]
    std::thread::spawn(move || {
        // Wake up the `event_loop` once every second and dispatch a custom event
        // from a different thread.
        info!("Starting to send user event every second");
        loop {
            let _ = _event_loop_proxy.send_event(UserEvent::WakeUp);
            std::thread::sleep(std::time::Duration::from_secs(1));
        }
    });

    let mut state = Application::new(&event_loop);

    event_loop.run_app(&mut state).map_err(Into::into)
}

pub fn create_proxy(&self) -> EventLoopProxy<T>

Creates an EventLoopProxy that can be used to dispatch user events to the main event loop, possibly from another thread.

Examples found in repository

examples/window.rs (line 53)

fn main() -> Result<(), Box<dyn Error>> {
    #[cfg(web_platform)]
    console_error_panic_hook::set_once();

    tracing::init();

    let event_loop = EventLoop::<UserEvent>::with_user_event().build()?;
    let _event_loop_proxy = event_loop.create_proxy();

    // Wire the user event from another thread.
    #[cfg(not(web_platform))]
    std::thread::spawn(move || {
        // Wake up the `event_loop` once every second and dispatch a custom event
        // from a different thread.
        info!("Starting to send user event every second");
        loop {
            let _ = _event_loop_proxy.send_event(UserEvent::WakeUp);
            std::thread::sleep(std::time::Duration::from_secs(1));
        }
    });

    let mut state = Application::new(&event_loop);

    event_loop.run_app(&mut state).map_err(Into::into)
}

pub fn owned_display_handle(&self) -> OwnedDisplayHandle

Gets a persistent reference to the underlying platform display.

See the OwnedDisplayHandle type for more information.

pub fn listen_device_events(&self, allowed: DeviceEvents)

Change if or when DeviceEvents are captured.

See ActiveEventLoop::listen_device_events for details.

pub fn set_confirm_before_quit(&self, confirmation: bool)

pub fn set_control_flow(&self, control_flow: ControlFlow)

Sets the ControlFlow.

pub fn create_window( &self, window_attributes: WindowAttributes, ) -> Result<Window, OsError>

👎Deprecated: use ActiveEventLoop::create_window instead

Create a window.

Creating window without event loop running often leads to improper window creation; use ActiveEventLoop::create_window instead.

pub fn create_custom_cursor( &self, custom_cursor: CustomCursorSource, ) -> CustomCursor

Create custom cursor.

Examples found in repository

examples/window.rs (line 115)

    fn new<T>(event_loop: &EventLoop<T>) -> Self {
        // SAFETY: we drop the context right before the event loop is stopped, thus making it safe.
        #[cfg(not(any(android_platform, ios_platform)))]
        let context = Some(
            Context::new(unsafe {
                std::mem::transmute::<DisplayHandle<'_>, DisplayHandle<'static>>(
                    event_loop.display_handle().unwrap(),
                )
            })
            .unwrap(),
        );

        // You'll have to choose an icon size at your own discretion. On X11, the desired size
        // varies by WM, and on Windows, you still have to account for screen scaling. Here
        // we use 32px, since it seems to work well enough in most cases. Be careful about
        // going too high, or you'll be bitten by the low-quality downscaling built into the
        // WM.
        let icon = load_icon(include_bytes!("data/icon.png"));

        info!("Loading cursor assets");
        let custom_cursors = vec![
            event_loop
                .create_custom_cursor(decode_cursor(include_bytes!("data/cross.png"))),
            event_loop
                .create_custom_cursor(decode_cursor(include_bytes!("data/cross2.png"))),
            event_loop
                .create_custom_cursor(decode_cursor(include_bytes!("data/gradient.png"))),
        ];

        Self {
            #[cfg(not(any(android_platform, ios_platform)))]
            context,
            custom_cursors,
            icon,
            windows: Default::default(),
        }
    }

Trait Implementations

impl<T> Debug for EventLoop<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> EventLoopExtPumpEvents for EventLoop<T>

type UserEvent = T

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

fn pump_events<F>( &mut self, timeout: Option<Duration>, event_handler: F, ) -> PumpStatus

where F: FnMut(Event<Self::UserEvent>, &ActiveEventLoop),

👎Deprecated: use EventLoopExtPumpEvents::pump_app_events

See pump_app_events.

fn pump_app_events<A: ApplicationHandler<Self::UserEvent>>( &mut self, timeout: Option<Duration>, app: &mut A, ) -> PumpStatus

Pump the EventLoop to check for and dispatch pending events.

impl<T> EventLoopExtRunOnDemand for EventLoop<T>

type UserEvent = T

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

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.

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.

impl<T> EventLoopExtWebSys for EventLoop<T>

type UserEvent = T

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

fn spawn_app<A: ApplicationHandler<Self::UserEvent> + 'static>(self, app: A)

Initializes the winit event loop.

fn spawn<F>(self, event_handler: F)

where F: 'static + FnMut(Event<Self::UserEvent>, &ActiveEventLoop),

👎Deprecated: use EventLoopExtWebSys::spawn_app

See spawn_app.

impl<T> HasDisplayHandle for EventLoop<T>

fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError>

Get a handle to the display controller of the windowing system.