winit-sonoma-fix/README.md

122 lines
4.5 KiB
Markdown
Raw Normal View History

2016-11-01 03:19:37 +11:00
# winit - Cross-platform window creation and management in Rust
2014-07-27 18:55:37 +10:00
[![Crates.io](https://img.shields.io/crates/v/winit.svg)](https://crates.io/crates/winit)
2016-11-01 03:19:37 +11:00
[![Docs.rs](https://docs.rs/winit/badge.svg)](https://docs.rs/winit)
[![CI Status](https://github.com/rust-windowing/winit/workflows/CI/badge.svg)](https://github.com/rust-windowing/winit/actions)
2014-09-20 03:51:54 +10:00
2015-02-16 04:28:12 +11:00
```toml
[dependencies]
2022-01-06 01:38:59 +11:00
winit = "0.26.1"
2015-02-16 04:28:12 +11:00
```
2016-11-01 03:19:37 +11:00
## [Documentation](https://docs.rs/winit)
2014-07-28 19:45:59 +10:00
For features _within_ the scope of winit, see [FEATURES.md](FEATURES.md).
For 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.
## Contact Us
Join us in any of these:
2021-12-08 06:27:30 +11:00
[![Matrix](https://img.shields.io/badge/Matrix-%23rust--windowing%3Amatrix.org-blueviolet.svg)](https://matrix.to/#/#rust-windowing:matrix.org)
[![Libera.Chat](https://img.shields.io/badge/libera.chat-%23winit-red.svg)](https://web.libera.chat/#winit)
2014-07-27 23:59:58 +10:00
## Usage
2016-11-01 03:33:36 +11:00
Winit is a window creation and management library. It can create windows and lets you handle
2017-12-18 06:13:16 +11:00
events (for example: the window being resized, a key being pressed, a mouse movement, etc.)
2016-11-01 03:19:37 +11:00
produced by window.
2015-02-22 21:31:27 +11:00
2016-11-01 03:19:37 +11:00
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.
2015-02-22 21:31:27 +11:00
2014-07-27 23:59:58 +10:00
```rust
use winit::{
event::{Event, WindowEvent},
event_loop::{ControlFlow, EventLoop},
window::WindowBuilder,
};
2014-07-27 23:59:58 +10:00
fn main() {
let event_loop = EventLoop::new();
let window = WindowBuilder::new().build(&event_loop).unwrap();
2014-07-27 23:59:58 +10:00
event_loop.run(move |event, _, control_flow| {
*control_flow = ControlFlow::Wait;
2015-06-16 21:48:08 +10:00
match event {
Event::WindowEvent {
event: WindowEvent::CloseRequested,
window_id,
} if window_id == window.id() => *control_flow = ControlFlow::Exit,
_ => (),
2015-06-16 21:48:08 +10:00
}
});
2014-07-27 23:59:58 +10:00
}
```
Winit is only officially supported on the latest stable version of the Rust compiler.
2018-11-20 08:56:11 +11:00
### 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](https://crates.io/crates/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
#### WebAssembly
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][web with_canvas], or [let Winit
create a `<canvas>` element which you can then retrieve][web canvas getter] 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].
[web with_canvas]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowBuilderExtWebSys.html#tymethod.with_canvas
[web canvas getter]: https://docs.rs/winit/latest/wasm32-unknown-unknown/winit/platform/web/trait.WindowExtWebSys.html#tymethod.canvas
[web example]: ./examples/web.rs
[Rust and WebAssembly book]: https://rustwasm.github.io/book/
#### Android
This library makes use of the [ndk-rs](https://github.com/rust-windowing/android-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"` |
2021-11-25 02:56:57 +11:00
| 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:
```toml
[[example]]
name = "request_redraw_threaded"
crate-type = ["cdylib"]
```
And add this to the example file to add the native activity glue:
```rust
#[cfg_attr(target_os = "android", ndk_glue::main(backtrace = "on"))]
fn main() {
...
}
```
And run the application with `cargo apk run --example request_redraw_threaded`