Due to casts and use of platform specific crates in those modules
it's not really feasible to build docs for them.
After separating crates, thus should become way easier to navigate,
since backends information would be publicly available.
Wayland:
I found the calloop abstraction a little awkward to work with while I was
trying to understand why there was surprising workaround code in the wayland
backend for manually dispatching pending events.
Investigating this further it looks like there may currently be several issues
with the calloop WaylandSource (with how prepare_read is used and with (not)
flushing writes before polling)
Considering the current minimal needs for polling in all winit backends I do
personally tend to think it would be simpler to just own the responsibility for
polling more directly, so the logic for wayland-client `prepare_read` wouldn't
be in a separate crate (and in this current situation would also be easier to fix)
I've tried to maintain the status quo with calloop + workarounds.
X11:
I found that the recent changes (4ac2006cbc) to port the X11 backend
from mio to calloop lost the ability to check for pending events before
needing to poll/dispatch. (The `has_pending` state being queried
before dispatching() was based on state that was filled in during
dispatching)
As part of the rebase this re-introduces the PeekableReceiver and
WakeSender which are small utilities on top of
`std::sync::mpsc::channel()`. This adds a calloop `PingSource`
so we can use a `Ping` as a generic event loop waker.
For taking into account false positive wake ups the X11 source now
tracks when the file descriptor is readable so after we poll via
calloop we can then specifically check if there are new X11 events
or pending redraw/user events when deciding whether to skip the
event loop iteration.
The implementation of `pump_events` essentially works by hooking into the
`RunLoopObserver` and requesting that the app should be stopped the next time
that the `RunLoop` prepares to wait for new events.
Originally I had thought I would poke the `CFRunLoop` for the app directly and
I was originally going to implement `pump_events` based on a timeout which I'd
seen SDL doing.
I found that `[NSApp run]` wasn't actually being stopped by asking the RunLoop
to stop directly and inferred that `NSApp run` will actually catch this and
re-start the loop.
Hooking into the observer and calling `[NSApp stop]` actually seems like a
better solution that doesn't need a hacky constant timeout.
The end result is quite similar to what happens with existing apps that
call `run_return` inside an external loop and cause the loop to exit for
each iteration (that also results in the `NSApp` stopping each
iteration).
A surprising amount of work was required to enable these extensions
on Windows.
I had originally assumed that pump_events was going to be very similar
to run except would use PeekMessageW instead of GetMessageW to avoid
blocking the external loop but I found the Windows backend broke
several assumptions I had.
Overall I think these changes can hopefully be considered a quite a
significant simplification (I think it's a net deletion of a fair amount
of code) and I think it also helps bring it into slightly closer alignment
with other backends too
Key changes:
- I have removed the `wait_thread` that was a fairly fiddly way of handling
`ControlFlow::WaitUntil` timeouts in favor of using `SetTimer` which works
with the same messages picked up by `GetMessage` and `PeekMessage`.
- I have removed the ordering guarantees between `MainEventsCleared`,
`RedrawRequested` and `RedrawEventsCleared` events due to the complexity in
maintaining this artificial ordering, which is already not supported
consistently across backends anyway (in particular this ordering already
isn't compatible with how MacOS / iOS work).
- `RedrawRequested` events are now directly dispatched via `WM_PAINT` messages
- comparable to how `RedrawRequested` is dispatched via `drawRect` in the
MacOS backend.
- I have re-worked how `NewEvents`, `MainEventsCleared`, and `RedrawEventsCleared`
get dispatched to be more in line with the MacOS backend and also more in line
with how we have recently discussed defining them for all platforms.
`NewEvents` is conceptually delivered when the event loop "wakes up" and
`MainEventsCleared` gets dispatched when the event loop is about to ask the
OS to wait for new events.
This is a more portable model, and is already how these events work in the
MacOS backend.
`RedrawEventsCleared` are just delivered after `MainEventsCleared` but this
event no longer has a useful meaning.
Probably the most controversial thing here is that this "breaks" the ordering
rules for redraw event handling, but since my changes interacted with how the
order is maintained I was very reluctant to figure out how to continue
maintaining something that we have recently been discussing changing:
https://github.com/rust-windowing/winit/issues/2640.
Additionally, since the MacOS backend already doesn't strictly maintain this
order it's somewhat academic to see this as a breakage if Winit applications
can't really rely on it already.
This updates the documentation for `request_redraw()` to reflect that we
no longer guarantee that `RedrawRequested` events must be dispatched
after `MainEventsCleared`.
The utils in this module should help the users to activate the windows
they create, as well as manage activation tokens environment variables.
The API is essential for Wayland in the first place, since some
compositors may decide initial focus of the window based on whether
the activation token was during the window creation.
Fixes#2279.
Co-authored-by: John Nunley <jtnunley01@gmail.com>
Overhaul the keyboard API in winit to mimic the W3C specification
to achieve better crossplatform parity. The `KeyboardInput` event
is now uses `KeyEvent` which consists of:
- `physical_key` - a cross platform way to refer to scancodes;
- `logical_key` - keysym value, which shows your key respecting the
layout;
- `text` - the text produced by this keypress;
- `location` - the location of the key on the keyboard;
- `repeat` - whether the key was produced by the repeat.
And also a `platform_specific` field which encapsulates extra
information on desktop platforms, like key without modifiers
and text with all modifiers.
The `Modifiers` were also slightly reworked as in, the information
whether the left or right modifier is pressed is now also exposed
on platforms where it could be queried reliably. The support was
also added for the web and orbital platforms finishing the API
change.
This change made the `OptionAsAlt` API on macOS redundant thus it
was removed all together.
Co-authored-by: Artúr Kovács <kovacs.artur.barnabas@gmail.com>
Co-authored-by: Kirill Chibisov <contact@kchibisov.com>
Co-authored-by: daxpedda <daxpedda@gmail.com>
Fixes: #2631.
Fixes: #2055.
Fixes: #2032.
Fixes: #1904.
Fixes: #1810.
Fixes: #1700.
Fixes: #1443.
Fixes: #1343.
Fixes: #1208.
Fixes: #1151.
Fixes: #812.
Fixes: #600.
Fixes: #361.
Fixes: #343.
* Add Redox OS support
* Simplify control flow usage
* Apply more recommendations
* Update naming to indicate that Orbital is a platform
* Adjust import order
* Remove redundant documentation links
* Add note to README about windows not showing up on Wayland
* Fix documentation links
* Small documentation fixes
* Add note about doing stuff after StartCause::Init on macOS
* Rename EventsLoop and associated types to EventLoop
* Rename WindowEvent::Refresh to WindowEvent::Redraw
* Remove second thread from win32 backend
* Update run_forever to hijack thread
* Replace windows Mutex with parking_lot Mutex
* Implement new ControlFlow and associated events
* Add StartCause::Init support, timer example
* Add ability to send custom user events
* Fully invert windows control flow so win32 calls into winit's callback
* Add request_redraw
* Rename platform to platform_impl
* Rename os to platform, add Ext trait postfixes
* Add platform::desktop module with EventLoopExt::run_return
* Re-organize into module structure
* Improve documentation
* Small changes to examples
* Improve docs for run and run_return
* Change instances of "events_loop" to "event_loop"
* Rename MonitorId to MonitorHandle
* Add CHANGELOG entry
* Improve WaitUntil timer precision
* When SendEvent is called during event closure, buffer events
* Fix resize lag when waiting in some situations
* Update send test and errors that broke some examples/APIs
* Improve clarity/fix typos in docs
* Fix unreachable panic after setting ControlFlow to Poll during some RedrawRequested events.
* Fix crash when running in release mode
* Remove crossbeam dependency and make drop events work again
* Remove serde implementations from ControlFlow
* Fix 1.24.1 build
* Fix freeze when setting decorations
* Replace &EventLoop in callback with &EventLoopWindowTarget
* Document and implement Debug for EventLoopWindowTarget
* Fix some deadlocks that could occur when changing window state
* Fix thread executor not executing closure when called from non-loop thread
* Fix buffered events not getting dispatched
* Fix crash with runner refcell not getting dropped
* Address review feedback
* Fix CHANGELOG typo
* Catch panics in user callback
* partial implementation for emscripten
this pull request contain a partial but working implementation of emscripten backend
some implementations may be controversial.
here some implementation detail:
* cursor state:
* on grab: emscripten request pointer lock deferred and also set a callback when pointer lock change
the callback request pointer lock deferred.
* on hide: `emscripten_hide_mouse` exist but not `emscripten_show_mouse`
a pull request has been open on october 2016 but never been merged
so I copied the javascript function and put it in emscripten_asm_const function
* fullscreen: if fullscreen is requested then it request fullscreen deferred and set a callback on fullscreen change
the callback request fullscreen deferred
* run forever: this method use emscripten main loop to run an infinite loop
* keyboard callback doesn't consume the event. I think it is more apopriate as in desktop environment it is the same, is it ?
* emscripten dir is added in example and contains html pages
Some things that are not implemented:
* lots of events
* min and max dimension can be implemented with a callback that listen to size change and resize if dimension out of bound
* title may be implemented using javascript to change document.title
* Use std::os::raw in the emscripten bindings
* Fix emscripten code
* Update code
* Add CI
* Remove the emscripten-specific examples
* Add some information to the README
