Documentation doesn't explain how to create an ActiveEventLoop

[Calandiel]

To quote from https://docs.rs/winit/latest/winit/index.html

Before you can create a Window, you first need to build an EventLoop. This is done with the EventLoop::new() function.

use winit::event_loop::EventLoop;
let event_loop = EventLoop::new().unwrap();

Then you create a Window with create_window

This doesn't work because the suggested next step requires a different type. While there are examples in repo, they're all large and bespoke which encourages using the library as a blackbox. Some other users had similar issues: https://github.com/rust-windowing/winit/discussions/3662

Personally, reading the docs, I'm still not sure if it's even possible to use the library without having it hijack the execution flow from the hosting applications thread.

My impression is that it isn't (as per comments on run_app regarding handling of iOS) and you're expected to provide an Application type. If that is the case, it may be worth clarifying in the docs too as the next step isn't to create a Window with create_window but to implement.

[daxpedda]

Personally, reading the docs, I'm still not sure if it's even possible to use the library without having it hijack the execution flow from the hosting applications thread.

My impression is that it isn't (as per comments on run_app regarding handling of iOS) and you're expected to provide an Application type.

Indeed.

However there is run_on_demand and pump_events, but not for iOS.

The documentation is outdated in this regard! So thank you for filing the issue, I'm planning to do a documentation overhaul before the next release.

[kchibisov]

I'd note that ios itself works by transferring all the control flow and you can not even return, because you must transfer the control flow and you have the same looking callbacks from ios as what you have with winit, so it's not possible on a platform level, and not just winit limitation in ios case.

[madsmtm]

I'd note that ios itself works by transferring all the control flow

Indeed. I recently looked at SDL, seems like even they instead run the user's pump_events-like code on a separate thread. SDL3 has recently also fixed this by providing (effectively) closures that gets run on each event.

[LyndonArmitage]

Any up to date documentation on how to get started with this library?

use winit::event_loop::EventLoop;

fn main() {
    let event_loop = EventLoop::new().unwrap();
    // ...
}

Then you create a Window with create_window.

I can't create a window with ActiveEventLoop when I don't have one. As mentioned before, the documentation moves on without actually explaining how to go from an EventLoop to an ActiveEventLoop.

Just a minimal example would be great. As a prospective user an immediate hurdle like this means I likely won't use this library.

The event handling documentation below this defers creating a window to container with an implementation of ApplicationHandler. Is this the only way to go from the EventLoop to ActiveEventLoop? Is it the standard way of working with this library? If it is, then the documentation should be moved about to reflect this.

[kchibisov]

Looking into window example might help to get an idea how it works. But as name implies, active event loop is the event loop, once it becomes active, thus you have to run it.

[LyndonArmitage]

Despite the "Building windows" documentation I did manage to get something working based on the event handling section below it, so the information is there, just not in the right order or succinctly explained.

I'd recommend rejigging the "Building windows" section to clearly describe a minimally working example, by moving the information up from the "Event handling" section and/or explaining how to go from an event loop to an active event loop rather than the current:

1. Create an EventLoop
2. ????
3. Use ActiveEventLoop.create_window()

Something as simple as:

In order to create a window you must first be using an ActiveEventLoop. The idiomatic way to do this is to create the window from within the ActiveEventLoop. You can see an example of doing this upon a resume as part of an ApplicationHandler implementation in the below Event handling section.