winit Documentation

Winit provides a cross-platform abstraction for window creation and input handling. It supports Desktop (Windows, macOS, X11, Wayland, Redox OS/Orbital), Mobile (iOS, Android), and Web.

Features are categorized into three tiers:

• Core: Essential features providing a well-formed abstraction across all platforms.
• Platform: Platform-specific features that cannot be meaningfully abstracted. These are not maintained by the core Winit team.
• Usability: Optional features that improve usability and are typically exposed via Cargo features.

Note: Winit does not provide APIs for drawing inside windows or creating native menus directly, but it provides the necessary APIs for higher-level crates to implement these functionalities.

The Window::set_cursor_state method and the CursorState enum have been removed in version 0.16. They are replaced by more composable methods:

• Use Window::grab_cursor to grab the cursor.
• Use Window::hide_cursor to hide the cursor.

Note: On Windows and macOS, grabbing the cursor no longer automatically hides it. To maintain previous behavior, you must call both grab_cursor and hide_cursor.

To use winit in your Rust project, add it to your Cargo.toml dependencies. Note that the README specifies a beta version for the example.

[dependencies]
winit = "0.31.0-beta.2"

Version 0.20.0-alpha6 introduced breaking changes to how redraw events are processed:

• Event Location: RedrawRequested has moved from WindowEvent to the top-level Event enum.
• Event Renaming: EventsCleared has been renamed to MainEventsCleared.
• Execution Order: RedrawRequested is now issued only after MainEventsCleared. RedrawEventsCleared is issued after each set of RedrawRequested events.

In v0.29, several platform-specific extensions were removed in favor of the raw-window-handle trait. Instead of using WindowExtWindows, WindowExtIOS, WindowExtMacOS, WindowExtWayland, or WindowExtX11, you should use the raw-window-handle implementation provided in the window module (which re-exports raw-window-handle).

Removed extensions include:

• Windows: hinstance, hwnd
• iOS: ui_window, ui_view_controller, ui_view
• macOS: ns_window, ns_view
• Wayland: wayland_display, wayland_surface
• X11: xlib_window, xlib_display, xlib_screen_id, xcb_connection

Starting with version 0.16, the API for sizes and positions has changed significantly. Most methods now produce and consume LogicalSize and LogicalPosition instead of physical units.

Key distinction:

• Windows/EventsLoop/General API: Uses LogicalSize and LogicalPosition.
• MonitorId methods: Continue to use PhysicalSize and PhysicalPosition.

Additionally, winit now automatically conserves logical size when the DPI factor changes.

In winit v0.30.0, Window::new has been removed. You must now create windows using ActiveEventLoop::create_window or EventLoop::create_window.

To ensure compatibility with platforms like iOS and macOS, windows should be created inside the resumed() method of your ApplicationHandler implementation. This ensures the window is created only after the application has properly launched and the event loop is active.

Recommended Pattern: Store the window in an Option<Window> within your state struct and initialize it during the resumed event.

impl ApplicationHandler for State {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        // This is the correct place to create windows
        self.window = Some(event_loop.create_window(Window::default_attributes()).unwrap());
    }
}