Deprecate window creation with stale event loop

[kchibisov]

Creating window when event loop is not running generally doesn't work,
since a bunch of events and sync OS requests can't be processed. This
is also an issue on e.g. Android, since window can't be created outside
event loop easily.

Thus deprecate the window creation when event loop is not running,
as well as other resource creation to running event loop.

Given that all the examples use the bad pattern of creating the window
when event loop is not running and also most example existence is
questionable, since they show single thing and the majority of their
code is window/event loop initialization, they wore merged into
a single example 'window.rs' example that showcases very simple
application using winit.

Fixes #3399.

Replaces #3299 and #3400.

• Tested on all platforms changed // Kind of.
• Added an entry to CHANGELOG.md if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality
• Updated feature matrix, if new features were added or implemented

--

@daxpedda could you wire the web example into window.rs example somehow? We maybe also want android there as well, @MarijnS95 , just without drawing, I guess?

[kchibisov]

That's based on #3299

In general, I have the following questions:

1. Should we add ActiveEventLoop getter for pump_events trait? The API is kind of weird and requiring it to be normal doesn't sound right.
2. Maybe some types like CustomCursor should accept EventLoop instead?
3. Do we need threaded rendering example...? softbuffer is a bit tricky around threads.
4. Do we need something else in window example? I've added pretty much everything, though I don't print just all events, since it's a bit noisy.

[notgull]

1. Should we add `ActiveEventLoop` getter for `pump_events` trait? The API is kind of weird and requiring it to be normal doesn't sound right.

I don't think this works out.

2. Maybe some types like `CustomCursor` should accept `EventLoop` instead?

Maybe we should keep the EventLoopWindowTarget type around for this reason.

3. Do we need threaded rendering example...? softbuffer is a bit tricky around threads.

I'd agree.

4. Do we need something else in window example? I've added pretty much everything, though I don't print just all events, since it's a bit noisy.

Nah.

[madsmtm]

I think #3400 is the better way forwards for this, as it allows us to still support the "create event loop while it's not running" use-case, but allows us to mark it as deprecated for a release cycle.

[madsmtm]

Maybe?

Suggested change

	/// # fn scope(window: &Window) {
	/// # let window: &Window = unimplemented!();

Since the examples are no_run anyways.

[kchibisov]

I'm not sure about it since all the code in examples will be kind of dead with such pattern.

[madsmtm]

Yeah, on the other hand, if someone forgets no_run, then the example will still mistakenly run, it'll just do nothing.

[kchibisov]

I'd still probably go with fn for now.

[kchibisov]

"create event loop while it's not running"

Do you mean Window here? I'm not so sure about it, since I'd rather force users here to more correct design and allow us to deal with soundness stuff more nicely. The issue is though, that pump_events is a bit out of place and I'm not sure how to enforce lifetimes for it, etc. Like the users are more likely to drop the event loop when using it all together which could lead to issues all over the place. But I guess pump_events stuff should be discussed separately and probably marked as unsafe in the first place?

[kchibisov]

I think #3400 is the better way forwards for this

I've applied it for now the way you've suggested. Though, I haven't touched the CustomCursor for example.

[kchibisov]

Maybe we should keep the EventLoopWindowTarget type around for this reason.

I think the way forward would be to move CustomCursor into the EventLoop instead of getting the &EventLoopWindowTarget.

[madsmtm]

Proposal for custom cursors we discussed at the meeting today:

impl EventLoop {
    fn create_cursor(...);
}

impl ActiveEventLoop {
    fn create_cursor(...);
}

[madsmtm]

I like the combined example!

Should we add ActiveEventLoop getter for pump_events trait? The API is kind of weird and requiring it to be normal doesn't sound right.

I'm very unsure, but let's punt on it for now, as users still have the option of using EventLoop::create_window.

Do we need threaded rendering example...?

Would be kinda nice at some point, but it can definitely wait.

[madsmtm]

@daxpedda I've opened #3473 for making the big example work on the web.

[jackpot51]

Orbital changes are good

[madsmtm]

@daxpedda I believe this is waiting mostly on your review

[daxpedda]

Wow, that's actually a lot of changes in one PR.
LGTM!