Struct EventLoopProxy

pub struct EventLoopProxy { /* private fields */ }

Control the EventLoop, possibly from a different thread, without referencing it directly.

Implementations

impl EventLoopProxy

pub fn wake_up(&self)

Wake up the EventLoop, resulting in ApplicationHandler::proxy_wake_up() being called.

Calls to this method are coalesced into a single call to proxy_wake_up, see the documentation on that for details.

If the event loop is no longer running, this is a no-op.

Platform-specific

• Windows: The wake-up may be ignored under high contention, see #3687.

Examples found in repository

examples/window.rs (line 67)

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

    tracing::init();

    let event_loop = EventLoop::new()?;
    let (sender, receiver) = mpsc::channel();

    // Wire the user event from another thread.
    #[cfg(not(web_platform))]
    {
        let event_loop_proxy = event_loop.create_proxy();
        let sender = sender.clone();
        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 _ = sender.send(Action::Message);
                event_loop_proxy.wake_up();
                std::thread::sleep(std::time::Duration::from_secs(1));
            }
        });
    }

    let app = Application::new(&event_loop, receiver, sender);
    Ok(event_loop.run_app(app)?)
}

/// Application state and event handling.
struct Application {
    /// Trigger actions through proxy wake up.
    receiver: Receiver<Action>,
    sender: Sender<Action>,
    /// Custom cursors assets.
    custom_cursors: Result<Vec<CustomCursor>, RequestError>,
    /// Application icon.
    icon: Icon,
    windows: HashMap<WindowId, WindowState>,
    /// Drawing context.
    ///
    /// With OpenGL it could be EGLDisplay.
    #[cfg(not(android_platform))]
    context: Option<Context<DisplayHandle<'static>>>,
}

impl Application {
    fn new(event_loop: &EventLoop, receiver: Receiver<Action>, sender: Sender<Action>) -> Self {
        // SAFETY: we drop the context right before the event loop is stopped, thus making it safe.
        #[cfg(not(android_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 = [
            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"))),
        ]
        .into_iter()
        .collect();

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

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

        #[allow(unused_mut)]
        let mut window_attributes = WindowAttributes::default()
            .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)]
        {
            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)
    }

    fn handle_action_from_proxy(&mut self, _event_loop: &dyn ActiveEventLoop, action: Action) {
        match action {
            #[cfg(web_platform)]
            Action::DumpMonitors => self.dump_monitors(_event_loop),
            Action::Message => {
                info!("User wake up");
            },
            _ => unreachable!("Tried to execute invalid action without `WindowId`"),
        }
    }

    fn handle_action_with_window(
        &mut self,
        event_loop: &dyn ActiveEventLoop,
        window_id: WindowId,
        action: Action,
    ) {
        // let cursor_position = self.cursor_position;
        let window = self.windows.get_mut(&window_id).unwrap();
        info!("Executing action: {action:?}");
        match action {
            Action::CloseWindow => {
                let _ = self.windows.remove(&window_id);
            },
            Action::CreateNewWindow => {
                #[cfg(any(x11_platform, wayland_platform))]
                if let Err(err) = window.window.request_activation_token() {
                    info!("Failed to get activation token: {err}");
                } else {
                    return;
                }

                if let Err(err) = self.create_window(event_loop, None) {
                    error!("Error creating new window: {err}");
                }
            },
            Action::ToggleResizeIncrements => window.toggle_resize_increments(),
            Action::ToggleCursorVisibility => window.toggle_cursor_visibility(),
            Action::ToggleResizable => window.toggle_resizable(),
            Action::ToggleDecorations => window.toggle_decorations(),
            Action::ToggleFullscreen => window.toggle_fullscreen(),
            #[cfg(macos_platform)]
            Action::ToggleSimpleFullscreen => {
                window.window.set_simple_fullscreen(!window.window.simple_fullscreen());
            },
            Action::ToggleMaximize => window.toggle_maximize(),
            Action::ToggleImeInput => window.toggle_ime(),
            Action::Minimize => window.minimize(),
            Action::NextCursor => window.next_cursor(),
            Action::NextCustomCursor => {
                if let Err(err) = self.custom_cursors.as_ref().map(|c| window.next_custom_cursor(c))
                {
                    error!("Error creating custom cursor: {err}");
                }
            },
            #[cfg(web_platform)]
            Action::UrlCustomCursor => {
                if let Err(err) = window.url_custom_cursor(event_loop) {
                    error!("Error creating custom cursor from URL: {err}");
                }
            },
            #[cfg(web_platform)]
            Action::AnimationCustomCursor => {
                if let Err(err) = self
                    .custom_cursors
                    .as_ref()
                    .map(|c| window.animation_custom_cursor(event_loop, c))
                {
                    error!("Error creating animated custom cursor: {err}");
                }
            },
            Action::CycleCursorGrab => window.cycle_cursor_grab(),
            Action::DragWindow => window.drag_window(),
            Action::DragResizeWindow => window.drag_resize_window(),
            Action::ShowWindowMenu => window.show_menu(),
            Action::PrintHelp => self.print_help(),
            #[cfg(macos_platform)]
            Action::CycleOptionAsAlt => window.cycle_option_as_alt(),
            Action::SetTheme(theme) => {
                window.window.set_theme(theme);
                // Get the resulting current theme to draw with
                let actual_theme = theme.or_else(|| window.window.theme()).unwrap_or(Theme::Dark);
                window.set_draw_theme(actual_theme);
            },
            #[cfg(macos_platform)]
            Action::CreateNewTab => {
                let tab_id = window.window.tabbing_identifier();
                if let Err(err) = self.create_window(event_loop, Some(tab_id)) {
                    error!("Error creating new window: {err}");
                }
            },
            Action::RequestResize => window.swap_dimensions(),
            #[cfg(web_platform)]
            Action::DumpMonitors => {
                let future = event_loop.request_detailed_monitor_permission();
                let proxy = event_loop.create_proxy();
                let sender = self.sender.clone();
                wasm_bindgen_futures::spawn_local(async move {
                    if let Err(error) = future.await {
                        error!("{error}")
                    }

                    let _ = sender.send(Action::DumpMonitors);
                    proxy.wake_up();
                });
            },
            #[cfg(not(web_platform))]
            Action::DumpMonitors => self.dump_monitors(event_loop),
            Action::Message => {
                self.sender.send(Action::Message).unwrap();
                event_loop.create_proxy().wake_up();
            },
        }
    }

Trait Implementations

impl Clone for EventLoopProxy

fn clone(&self) -> EventLoopProxy

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventLoopProxy

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

Formats the value using the given formatter.