README.md
1# winit - Cross-platform window creation and management in Rust
2
3[![Crates.io](https://img.shields.io/crates/v/winit.svg)](https://crates.io/crates/winit)
4[![Docs.rs](https://docs.rs/winit/badge.svg)](https://docs.rs/winit)
5[![CI Status](https://github.com/rust-windowing/winit/workflows/CI/badge.svg)](https://github.com/rust-windowing/winit/actions)
6
7```toml
8[dependencies]
9winit = "0.22.2"
10```
11
12## [Documentation](https://docs.rs/winit)
13
14For features _within_ the scope of winit, see [FEATURES.md](FEATURES.md).
15
16For features _outside_ the scope of winit, see [Missing features provided by other crates](https://github.com/rust-windowing/winit/wiki/Missing-features-provided-by-other-crates) in the wiki.
17
18## Contact Us
19
20Join us in any of these:
21
22[![Freenode](https://img.shields.io/badge/freenode.net-%23glutin-red.svg)](http://webchat.freenode.net?channels=%23glutin&uio=MTY9dHJ1ZSYyPXRydWUmND10cnVlJjExPTE4NSYxMj10cnVlJjE1PXRydWU7a)
23[![Matrix](https://img.shields.io/badge/Matrix-%23Glutin%3Amatrix.org-blueviolet.svg)](https://matrix.to/#/#Glutin:matrix.org)
24[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tomaka/glutin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
25
26## Usage
27
28Winit is a window creation and management library. It can create windows and lets you handle
29events (for example: the window being resized, a key being pressed, a mouse movement, etc.)
30produced by window.
31
32Winit is designed to be a low-level brick in a hierarchy of libraries. Consequently, in order to
33show something on the window you need to use the platform-specific getters provided by winit, or
34another library.
35
36```rust
37use winit::{
38 event::{Event, WindowEvent},
39 event_loop::{ControlFlow, EventLoop},
40 window::WindowBuilder,
41};
42
43fn main() {
44 let event_loop = EventLoop::new();
45 let window = WindowBuilder::new().build(&event_loop).unwrap();
46
47 event_loop.run(move |event, _, control_flow| {
48 *control_flow = ControlFlow::Wait;
49
50 match event {
51 Event::WindowEvent {
52 event: WindowEvent::CloseRequested,
53 window_id,
54 } if window_id == window.id() => *control_flow = ControlFlow::Exit,
55 _ => (),
56 }
57 });
58}
59```
60
61Winit is only officially supported on the latest stable version of the Rust compiler.
62
63### Cargo Features
64
65Winit provides the following features, which can be enabled in your `Cargo.toml` file:
66* `serde`: Enables serialization/deserialization of certain types with [Serde](https://crates.io/crates/serde).
67* `x11` (enabled by default): On Unix platform, compiles with the X11 backend
68* `wayland` (enabled by default): On Unix platform, compiles with the Wayland backend
69
70### Platform-specific usage
71
72#### WebAssembly
73
74Building a binary will yield a `.js` file. In order to use it in an HTML file, you need to:
75
76- Put a `<canvas id="my_id"></canvas>` element somewhere. A canvas corresponds to a winit "window".
77- Write a Javascript code that creates a global variable named `Module`. Set `Module.canvas` to
78 the element of the `<canvas>` element (in the example you would retrieve it via `document.getElementById("my_id")`).
79 More information [here](https://kripken.github.io/emscripten-site/docs/api_reference/module.html).
80- Make sure that you insert the `.js` file generated by Rust after the `Module` variable is created.
81
82#### Android
83
84This library makes use of the [ndk-rs](https://github.com/rust-windowing/android-ndk-rs) crates, refer to that repo for more documentation.
85
86Running on an Android device needs a dynamic system library, add this to Cargo.toml:
87```toml
88[[example]]
89name = "request_redraw_threaded"
90crate-type = ["cdylib"]
91```
92
93And add this to the example file to add the native activity glue:
94```rust
95#[cfg(target_os = "android")]
96ndk_glue::ndk_glue!(main);
97```
98
99And run the application with `cargo apk run --example request_redraw_threaded`
100