Go to file
Rodrigo Batista de Moraes 3e991e13dc
Android: avoid deadlocks while handling UserEvent (#2343)
Replace `Arc<Mutex<VecDeque<T>>` by `mpsc`
2022-07-20 19:52:36 +02:00
.cargo Improve web example (#2115) 2022-02-25 12:57:46 +01:00
.github ci: Disallow warnings in rustdoc and test private items (#2341) 2022-06-17 14:19:09 +02:00
examples examples/multiwindow.rs: ignore synthetic key press events 2022-07-03 22:25:08 +03:00
run-wasm Improve web example (#2115) 2022-02-25 12:57:46 +01:00
src Android: avoid deadlocks while handling UserEvent (#2343) 2022-07-20 19:52:36 +02:00
tests Make size/position types generic over pixel type (#1277) 2020-01-05 14:15:11 -05:00
.gitattributes Update changelog guidelines to prevent conflicts from blocking PRs (#2145) 2022-01-23 13:55:33 +01:00
.gitignore Require setting the activation policy on the event loop (#1922) 2021-04-30 11:31:28 +02:00
.gitmodules Forward porting (#966) 2019-06-23 02:39:26 -04:00
Cargo.toml Bump sctk-adwaita to 0.4.1 2022-07-20 11:50:49 +03:00
CHANGELOG.md Make winit focus take activity into account on Windows (#2159) 2022-07-15 10:27:27 +02:00
CONTRIBUTING.md Update changelog guidelines to prevent conflicts from blocking PRs (#2145) 2022-01-23 13:55:33 +01:00
FEATURES.md Refine Window::set_cursor_grab API 2022-06-13 09:43:14 +03:00
HALL_OF_CHAMPIONS.md Update Hall of Champions (#1959) 2021-06-14 13:55:13 -07:00
LICENSE Initial commit 2014-07-27 11:41:26 +02:00
README.md Documentation cleanup (#2328) 2022-06-11 18:57:19 +02:00
rustfmt.toml Re-format on stable rustfmt (#974) 2019-06-24 12:14:55 -04:00

winit - Cross-platform window creation and management in Rust

Crates.io Docs.rs CI Status

[dependencies]
winit = "0.26.1"

Documentation

For features within the scope of winit, see FEATURES.md.

For features outside the scope of winit, see Missing features provided by other crates in the wiki.

Contact Us

Join us in any of these:

Matrix Libera.Chat

Usage

Winit is a window creation and management library. It can create windows and lets you handle events (for example: the window being resized, a key being pressed, a mouse movement, etc.) produced by window.

Winit is designed to be a low-level brick in a hierarchy of libraries. Consequently, in order to show something on the window you need to use the platform-specific getters provided by winit, or another library.

use winit::{
    event::{Event, WindowEvent},
    event_loop::{ControlFlow, EventLoop},
    window::WindowBuilder,
};

fn main() {
    let event_loop = EventLoop::new();
    let window = WindowBuilder::new().build(&event_loop).unwrap();

    event_loop.run(move |event, _, control_flow| {
        *control_flow = ControlFlow::Wait;

        match event {
            Event::WindowEvent {
                event: WindowEvent::CloseRequested,
                window_id,
            } if window_id == window.id() => *control_flow = ControlFlow::Exit,
            _ => (),
        }
    });
}

Winit is only officially supported on the latest stable version of the Rust compiler.

Cargo Features

Winit provides the following features, which can be enabled in your Cargo.toml file:

  • serde: Enables serialization/deserialization of certain types with Serde.
  • x11 (enabled by default): On Unix platform, compiles with the X11 backend
  • wayland (enabled by default): On Unix platform, compiles with the Wayland backend
  • mint: Enables mint (math interoperability standard types) conversions.

Platform-specific usage

Wayland

Note that windows don't appear on Wayland until you draw/present to them.

winit doesn't do drawing, try the examples in glutin instead.

WebAssembly

To run the web example: cargo run-wasm --example web

Winit supports compiling to the wasm32-unknown-unknown target with web-sys.

On the web platform, a Winit window is backed by a <canvas> element. You can either provide Winit with a <canvas> element, or let Winit create a <canvas> element which you can then retrieve and insert it into the DOM yourself.

For example code using Winit with WebAssembly, check out the web example. For information on using Rust on WebAssembly, check out the Rust and WebAssembly book.

Android

This library makes use of the ndk-rs crates, refer to that repo for more documentation.

The ndk_glue version needs to match the version used by winit. Otherwise, the application will not start correctly as ndk_glue's internal NativeActivity static is not the same due to version mismatch.

ndk_glue <-> winit version comparison compatibility:

winit ndk_glue
0.24 ndk_glue = "0.2.0"
0.25 ndk_glue = "0.3.0"
0.26 ndk_glue = "0.5.0"
0.27 ndk_glue = "0.6.0"

Running on an Android device needs a dynamic system library, add this to Cargo.toml:

[[example]]
name = "request_redraw_threaded"
crate-type = ["cdylib"]

And add this to the example file to add the native activity glue:

#[cfg_attr(target_os = "android", ndk_glue::main(backtrace = "on"))]
fn main() {
    ...
}

And run the application with cargo apk run --example request_redraw_threaded

MacOS

A lot of functionality expects the application to be ready before you start doing anything; this includes creating windows, fetching monitors, drawing, and so on, see issues #2238, #2051 and #2087.

If you encounter problems, you should try doing your initialization inside Event::NewEvents(StartCause::Init).