rust-windowing / winit Goto Github PK

View Code? Open in Web Editor NEW

4.4K 60.0 860.0 9.84 MB

Window handling library in pure Rust

Home Page: https://docs.rs/winit/

License: Apache License 2.0

Rust 100.00%

rust windowing android ios macos wasm wayland windows x11 gui

winit's Introduction

winit - Cross-platform window creation and management in Rust

[dependencies]
winit = "0.29.15"

Documentation

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

For features outside the scope of winit, see Are we GUI Yet? and Are we game yet?, depending on what kind of project you're looking to do.

Contact Us

Join us in our room. If you don't get an answer there, try .

The maintainers have a meeting every friday at UTC 15. The meeting notes can be found here.

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 the 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.

MSRV Policy

This crate's Minimum Supported Rust Version (MSRV) is 1.70. Changes to the MSRV will be accompanied by a minor version bump.

As a tentative policy, the upper bound of the MSRV is given by the following formula:

min(sid, stable - 3)

Where sid is the current version of rustc provided by Debian Sid, and stable is the latest stable version of Rust. This bound may be broken in case of a major ecosystem shift or a security vulnerability.

The exception is for the Android platform, where a higher Rust version must be used for certain Android features. In this case, the MSRV will be capped at the latest stable version of Rust minus three. This inconsistency is not reflected in Cargo metadata, as it is not powerful enough to expose this restriction.

All crates in the rust-windowing organizations have the same MSRV policy.

Platform-specific usage

Check out the winit::platform module for platform-specific usage.

winit's People

Contributors

Stargazers

Watchers

Forkers

fkaa elinorbgr osspial nicokoch ozkriff emilgardis sklopi mitchmindtree wvdschel frewsxcv zerosign tanderegg rerion bpostlethwaite jrmuizel samdphillips nowl chances bvssvni azriel91 pedrocr paulrouget denialadams cactorium thiolliere jwilm uk992 syntheorem sotaroikeda y-fujii mystal mortimergoro skligys torkleyy ralith gregkatz boscop gridbugs determinant codeforks brendanzab burtonageo glowcoil rukai conorlpboyle willglynn alexheretic shockham tmiller monomadic umurgdk mcginty zakorgy ekicyou bogdad mrmekon nequissimus trishume alteous technici4n gilbertw1 tiby312 chyvonomys golddranks stuartnelson3 diggsey lain-dono francesca64 heh9 yonran bgourlie kvark mcoffin robertgzr jtitor spearman lolzballs b-r-u forbjok x0ddf larago sodiumjoe jturner314 jice-nospam iquiw thermalspan hcpl icefoxen yvt ebarnard fschutt edwin0cheng virome green-s simonsapin branan goertzenator chrisduerr tinaun anderspitman

winit's Issues

No keyboard input in fullscreen mode on X11

Original: rust-windowing/glutin#509

`wait_events()` on X11 burns CPU after failing to process MappingNotify event

Original: rust-windowing/glutin#471

Key presses report "virtual" key presses (including repetition), not physical key down events

Original: rust-windowing/glutin#558

Add support for XCB

Change the way you get a window

Original: rust-windowing/glutin#175

Update README

The README file is still the one from glutin.

RFC: Switch to a futures-compatible API

Winit's and glutin's current API look like this:

impl Window {
    pub fn wait_events(&self) -> impl Iterator<Item = Event> { ... }
    pub fn poll_events(&self) -> impl Iterator<Item = Event> { ... }
}

I suggest that instead you'd have to register your window to what's called an events loop. Then, you'd call a method on the events loop to run it. Running the events loop would process events received by the operating system, and call a callback previously registered on the window.

This is essentially the same approach as the future-rs library, except that we're not using future-rs directly because it's not totally stable. I'd like to eventually publish winit 1.0 (in, like, the next nine months or so), and it's unlikely that future-rs publishes its 1.0 before winit.

Example usage with the new API (just to give an overview, the details are not important at the moment):

let events_loop = EventsLoop::new();
let window = WindowBuilder::new().with_title("hello").build(&events_loop).unwrap();
window.set_callback(|event| match event { ... });

loop {
    events_loop.run_once();     // calls the closure passed to set_callback earlier
}

I've always been a bit wary about callbacks because they are often too "magical", like you don't know which thread calls them and at what moment. But the fact that it's the run() method of the events loop that calls the callbacks means that it's a good design in my opinion.

This approach would have some benefits over the current system:

In the implementation we can decouple the Window object in Rust from the actual window. The actual window could be stored in the EventsLoop for example.
Right now on Windows winit spawns a background thread for events handling ; this could be removed.
We can force the EventsLoop to run on the main thread for OSX while still allowing the Window objects to be shared between threads. This has been a huge safety hole in glutin since the beginning.
The set_resize_callback function of MacOS would be gone.
The WindowProxy would be gone in favor of an "EventsLoopProxy".
We can later register other kinds of callbacks to the events loop, for example a callback when a monitoring is plugged in or removed that is not tied to particular window.
This design is also more appropriate for emscripten in glutin, as emscripten/javascript are based on callbacks and not on preemptive multitasking.

Event::Moved isn't working

Original: rust-windowing/glutin#724

Fullscreen mode is not reverted in X11

Original: rust-windowing/glutin#661

Resize events not working on OSX

Original: rust-windowing/glutin#445

Example "multiwindow" does not close on OSX

Original: rust-windowing/glutin#544

Events are broken when opening multiple windows

Original: rust-windowing/glutin#727

Enable `Less` and `Greater` Keys on X11

Original: rust-windowing/glutin#775

Clarification in the docs on key codes

Original: rust-windowing/glutin#259

Setting the window icon

Original: rust-windowing/glutin#771

X11 doesn't like creating and destroying a lot of windows

Original: rust-windowing/glutin#89

Add a better diagnostic when X11 is not available

Original: rust-windowing/glutin#555

set_cursor_position blocks infinitely on x11

Original: rust-windowing/glutin#478

Error when switching to fullscreen on Windows

Original: rust-windowing/glutin#379

Consider using DwmFlush with a transparent window

Original: rust-windowing/glutin#461

How to handle MouseWheel when both pixel and line deltas are available ?

In some cases (if the compositor supports it), the wayland backend can have access to both LineDelta and PixelDelta values for a given scroll event.

In this case, what should be done ?

generate only the PixelDelta event ?
generate only the LineDelta event ?
generate both ?
modify the MouseWheel event so that it may provide both values ?

Consider adding a drag & drop event

Original: rust-windowing/glutin#496

resizability & min/max dimensions

Original: rust-windowing/glutin#681

Support keypress events with non-ascii chars

Original: rust-windowing/glutin#625

Relative mouse motion

Original: rust-windowing/glutin#774

Meaning of Event::Closed not clear

Original: rust-windowing/glutin#520

Add keyboard support for F16-F25

Original: rust-windowing/glutin#266

Multiwindow example is broken on OS X

Original: rust-windowing/glutin#618

PRs that need to be merged into winit

PRs that were merged in glutin but not in winit:

Command Q to quit on Mac OS X

Original: rust-windowing/glutin#468

Not sure if still relevant.

Window example on wayland creates 0x0 pixels window

It looks like winit doesn't resize wayland window after start (resize_callback function have not been called).
I've checked glutin example on wayland and it works well. Then I checked the difference beetween api/wayland/window.rs in winit and glutin and found out that there is no resize calls in winit. For example: glutin and winit. It seems to me that there should be some code to resize surface, but I haven't find any API in wayland-client to do so.