Struct ActiveEventLoop

pub struct ActiveEventLoop { /* private fields */ }

Target that associates windows with an EventLoop.

This type exists to allow you to create new windows while Winit executes your callback.

Implementations

impl ActiveEventLoop

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

Create the window.

Possible causes of error include denied permission, incompatible system, and lack of memory.

Platform-specific

• Web: The window is created but not inserted into the web page automatically. Please see the web platform module for more information.

Examples found in repository

examples/pump_events.rs (line 27)

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

examples/control_flow.rs (line 74)

    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        let window_attributes = Window::default_attributes().with_title(
            "Press 1, 2, 3 to change control flow mode. Press R to toggle redraw requests.",
        );
        self.window = Some(event_loop.create_window(window_attributes).unwrap());
    }

examples/x11_embed.rs (line 27)

        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
            let window_attributes = Window::default_attributes()
                .with_title("An embedded window!")
                .with_inner_size(winit::dpi::LogicalSize::new(128.0, 128.0))
                .with_embed_parent_window(self.parent_window_id);

            self.window = Some(event_loop.create_window(window_attributes).unwrap());
        }

examples/run_on_demand.rs (line 35)

        fn resumed(&mut self, event_loop: &ActiveEventLoop) {
            let window_attributes = Window::default_attributes()
                .with_title("Fantastic window number one!")
                .with_inner_size(winit::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);
        }

examples/child_window.rs (line 25)

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

    use winit::dpi::{LogicalPosition, LogicalSize, Position};
    use winit::event::{ElementState, Event, KeyEvent, WindowEvent};
    use winit::event_loop::{ActiveEventLoop, EventLoop};
    use winit::raw_window_handle::HasRawWindowHandle;
    use winit::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);
                    }
                },
                _ => (),
            },
            _ => (),
        }
    })
}

examples/window.rs (line 178)

    fn create_window(
        &mut self,
        event_loop: &ActiveEventLoop,
        _tab_id: Option<String>,
    ) -> Result<WindowId, Box<dyn Error>> {
        // TODO read-out activation token.

        #[allow(unused_mut)]
        let mut window_attributes = Window::default_attributes()
            .with_title("Winit window")
            .with_transparent(true)
            .with_window_icon(Some(self.icon.clone()));

        #[cfg(any(x11_platform, wayland_platform))]
        if let Some(token) = event_loop.read_token_from_env() {
            startup_notify::reset_activation_token_env();
            info!("Using token {:?} to activate a window", token);
            window_attributes = window_attributes.with_activation_token(token);
        }

        #[cfg(x11_platform)]
        match std::env::var("X11_VISUAL_ID") {
            Ok(visual_id_str) => {
                info!("Using X11 visual id {visual_id_str}");
                let visual_id = visual_id_str.parse()?;
                window_attributes = window_attributes.with_x11_visual(visual_id);
            },
            Err(_) => info!("Set the X11_VISUAL_ID env variable to request specific X11 visual"),
        }

        #[cfg(x11_platform)]
        match std::env::var("X11_SCREEN_ID") {
            Ok(screen_id_str) => {
                info!("Placing the window on X11 screen {screen_id_str}");
                let screen_id = screen_id_str.parse()?;
                window_attributes = window_attributes.with_x11_screen(screen_id);
            },
            Err(_) => info!(
                "Set the X11_SCREEN_ID env variable to place the window on non-default screen"
            ),
        }

        #[cfg(macos_platform)]
        if let Some(tab_id) = _tab_id {
            window_attributes = window_attributes.with_tabbing_identifier(&tab_id);
        }

        #[cfg(web_platform)]
        {
            use winit::platform::web::WindowAttributesExtWebSys;
            window_attributes = window_attributes.with_append(true);
        }

        let window = event_loop.create_window(window_attributes)?;

        #[cfg(ios_platform)]
        {
            use winit::platform::ios::WindowExtIOS;
            window.recognize_doubletap_gesture(true);
            window.recognize_pinch_gesture(true);
            window.recognize_rotation_gesture(true);
            window.recognize_pan_gesture(true, 2, 2);
        }

        let window_state = WindowState::new(self, window)?;
        let window_id = window_state.window.id();
        info!("Created new window with id={window_id:?}");
        self.windows.insert(window_id, window_state);
        Ok(window_id)
    }

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

Create custom cursor.

pub fn available_monitors(&self) -> impl Iterator<Item = MonitorHandle>

Returns the list of all the monitors available on the system.

Examples found in repository

examples/window.rs (line 259)

    fn dump_monitors(&self, event_loop: &ActiveEventLoop) {
        info!("Monitors information");
        let primary_monitor = event_loop.primary_monitor();
        for monitor in event_loop.available_monitors() {
            let intro = if primary_monitor.as_ref() == Some(&monitor) {
                "Primary monitor"
            } else {
                "Monitor"
            };

            if let Some(name) = monitor.name() {
                info!("{intro}: {name}");
            } else {
                info!("{intro}: [no name]");
            }

            let PhysicalSize { width, height } = monitor.size();
            info!(
                "  Current mode: {width}x{height}{}",
                if let Some(m_hz) = monitor.refresh_rate_millihertz() {
                    format!(" @ {}.{} Hz", m_hz / 1000, m_hz % 1000)
                } else {
                    String::new()
                }
            );

            let PhysicalPosition { x, y } = monitor.position();
            info!("  Position: {x},{y}");

            info!("  Scale factor: {}", monitor.scale_factor());

            info!("  Available modes (width x height x bit-depth):");
            for mode in monitor.video_modes() {
                let PhysicalSize { width, height } = mode.size();
                let bits = mode.bit_depth();
                let m_hz = mode.refresh_rate_millihertz();
                info!("    {width}x{height}x{bits} @ {}.{} Hz", m_hz / 1000, m_hz % 1000);
            }
        }
    }

pub fn primary_monitor(&self) -> Option<MonitorHandle>

Returns the primary monitor of the system.

Returns None if it can’t identify any monitor as a primary one.

Platform-specific

Wayland / Web: Always returns None.

Examples found in repository

examples/window.rs (line 258)

    fn dump_monitors(&self, event_loop: &ActiveEventLoop) {
        info!("Monitors information");
        let primary_monitor = event_loop.primary_monitor();
        for monitor in event_loop.available_monitors() {
            let intro = if primary_monitor.as_ref() == Some(&monitor) {
                "Primary monitor"
            } else {
                "Monitor"
            };

            if let Some(name) = monitor.name() {
                info!("{intro}: {name}");
            } else {
                info!("{intro}: [no name]");
            }

            let PhysicalSize { width, height } = monitor.size();
            info!(
                "  Current mode: {width}x{height}{}",
                if let Some(m_hz) = monitor.refresh_rate_millihertz() {
                    format!(" @ {}.{} Hz", m_hz / 1000, m_hz % 1000)
                } else {
                    String::new()
                }
            );

            let PhysicalPosition { x, y } = monitor.position();
            info!("  Position: {x},{y}");

            info!("  Scale factor: {}", monitor.scale_factor());

            info!("  Available modes (width x height x bit-depth):");
            for mode in monitor.video_modes() {
                let PhysicalSize { width, height } = mode.size();
                let bits = mode.bit_depth();
                let m_hz = mode.refresh_rate_millihertz();
                info!("    {width}x{height}x{bits} @ {}.{} Hz", m_hz / 1000, m_hz % 1000);
            }
        }
    }

pub fn listen_device_events(&self, allowed: DeviceEvents)

Change if or when DeviceEvents are captured.

Since the DeviceEvent capture can lead to high CPU usage for unfocused windows, winit will ignore them by default for unfocused windows on Linux/BSD. This method allows changing this at runtime to explicitly capture them again.

Platform-specific

• Wayland / macOS / iOS / Android / Orbital: Unsupported.

pub fn system_theme(&self) -> Option<Theme>

Returns the current system theme.

Returns None if it cannot be determined on the current platform.

Platform-specific

• iOS / Android / Wayland / x11 / Orbital: Unsupported.

pub fn set_control_flow(&self, control_flow: ControlFlow)

Sets the ControlFlow.

Examples found in repository

examples/control_flow.rs (line 131)

    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
        if self.request_redraw && !self.wait_cancelled && !self.close_requested {
            self.window.as_ref().unwrap().request_redraw();
        }

        match self.mode {
            Mode::Wait => event_loop.set_control_flow(ControlFlow::Wait),
            Mode::WaitUntil => {
                if !self.wait_cancelled {
                    event_loop
                        .set_control_flow(ControlFlow::WaitUntil(time::Instant::now() + WAIT_TIME));
                }
            },
            Mode::Poll => {
                thread::sleep(POLL_SLEEP_TIME);
                event_loop.set_control_flow(ControlFlow::Poll);
            },
        };

        if self.close_requested {
            event_loop.exit();
        }
    }

pub fn control_flow(&self) -> ControlFlow

Gets the current ControlFlow.

pub fn exit(&self)

This exits the event loop.

See LoopExiting.

Examples found in repository

examples/window.rs (line 505)

    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
        if self.windows.is_empty() {
            info!("No windows left, exiting...");
            event_loop.exit();
        }
    }

examples/x11_embed.rs (line 38)

        fn window_event(
            &mut self,
            event_loop: &ActiveEventLoop,
            _window_id: WindowId,
            event: WindowEvent,
        ) {
            let window = self.window.as_ref().unwrap();
            match event {
                WindowEvent::CloseRequested => event_loop.exit(),
                WindowEvent::RedrawRequested => {
                    window.pre_present_notify();
                    fill::fill_window(window);
                },
                _ => (),
            }
        }

examples/pump_events.rs (line 44)

        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();
                },
                _ => (),
            }
        }

examples/control_flow.rs (line 145)

    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
        if self.request_redraw && !self.wait_cancelled && !self.close_requested {
            self.window.as_ref().unwrap().request_redraw();
        }

        match self.mode {
            Mode::Wait => event_loop.set_control_flow(ControlFlow::Wait),
            Mode::WaitUntil => {
                if !self.wait_cancelled {
                    event_loop
                        .set_control_flow(ControlFlow::WaitUntil(time::Instant::now() + WAIT_TIME));
                }
            },
            Mode::Poll => {
                thread::sleep(POLL_SLEEP_TIME);
                event_loop.set_control_flow(ControlFlow::Poll);
            },
        };

        if self.close_requested {
            event_loop.exit();
        }
    }

examples/run_on_demand.rs (line 52)

        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);
                },
                _ => (),
            }
        }

examples/child_window.rs (line 50)

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

    use winit::dpi::{LogicalPosition, LogicalSize, Position};
    use winit::event::{ElementState, Event, KeyEvent, WindowEvent};
    use winit::event_loop::{ActiveEventLoop, EventLoop};
    use winit::raw_window_handle::HasRawWindowHandle;
    use winit::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 exiting(&self) -> bool

Returns if the EventLoop is about to stop.

See exit().

pub fn owned_display_handle(&self) -> OwnedDisplayHandle

Gets a persistent reference to the underlying platform display.

See the OwnedDisplayHandle type for more information.

Trait Implementations

impl ActiveEventLoopExtAndroid for ActiveEventLoop

Available on android_platform only.

fn android_app(&self) -> &AndroidApp

Get the [AndroidApp] which was used to create this event loop.

impl ActiveEventLoopExtMacOS for ActiveEventLoop

Available on macos_platform only.

fn hide_application(&self)

Hide the entire application. In most applications this is typically triggered with Command-H.

fn hide_other_applications(&self)

Hide the other applications. In most applications this is typically triggered with Command+Option-H.

fn set_allows_automatic_window_tabbing(&self, enabled: bool)

Set whether the system can automatically organize windows into tabs.

fn allows_automatic_window_tabbing(&self) -> bool

Returns whether the system can automatically organize windows into tabs.

impl ActiveEventLoopExtWayland for ActiveEventLoop

Available on wayland_platform only.

fn is_wayland(&self) -> bool

True if the ActiveEventLoop uses Wayland.

impl ActiveEventLoopExtWebSys for ActiveEventLoop

Available on web_platform only.

fn create_custom_cursor_async( &self, source: CustomCursorSource, ) -> CustomCursorFuture

Async version of ActiveEventLoop::create_custom_cursor() which waits until the cursor has completely finished loading.

fn set_poll_strategy(&self, strategy: PollStrategy)

Sets the strategy for ControlFlow::Poll.

fn poll_strategy(&self) -> PollStrategy

Gets the strategy for ControlFlow::Poll.

fn set_wait_until_strategy(&self, strategy: WaitUntilStrategy)

Sets the strategy for ControlFlow::WaitUntil.

fn wait_until_strategy(&self) -> WaitUntilStrategy

Gets the strategy for ControlFlow::WaitUntil.

impl ActiveEventLoopExtX11 for ActiveEventLoop

Available on x11_platform only.

fn is_x11(&self) -> bool

True if the ActiveEventLoop uses X11.

impl Debug for ActiveEventLoop

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

Formats the value using the given formatter.

impl EventLoopExtStartupNotify for ActiveEventLoop

Available on x11_platform or wayland_platform only.

fn read_token_from_env(&self) -> Option<ActivationToken>

Read the token from the environment.

impl HasDisplayHandle for ActiveEventLoop

Available on crate feature rwh_06 only.

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

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

impl HasRawDisplayHandle for ActiveEventLoop

Available on crate feature rwh_05 only.

fn raw_display_handle(&self) -> RawDisplayHandle

Returns a rwh_05::RawDisplayHandle for the event loop.