This is definitely an important feature to illustrate, but I don't consider the winit api a part of the "bevy api" and therefore its not something I want in our examples. In general, I don't want to encourage users to use the winit api directly because it then ties their app to winit backends (which we might not always use on every platform).

As you are probably aware, bevy doesn't have an "abstract" mouse capture api (which means users must use winit for it currently). Additionally our Window abstraction as it stands today isn't very dynamic. It doesn't let you set window properties on demand like you can with winit. I chose to expose WinitWindows because I acknowledge that the gaps as they stand prevent people from building useful things. But I also dont want "official learning material" to include this because it actively encourages non-future proof code.

In the short term, I'm cool with tacking these properties onto the existing WindowDescriptor to unblock scenarios like this. But medium term I think we need to revisit our Window abstraction and either:

1. Expose a way to easily / dynamically set window properties at runtime
2. Fully embrace winit as our windowing abstraction (which implicitly means that we must extend winit whenever we want to support new platforms, such as consoles). This is a pretty big commitment, so I'm pretty hesitant to do this. But it would certainly simplify the code / immediately expose a bunch of nice features.

There is a very similar example in the cookbook: https://github.com/jamadazi/bevy-cookbook/blob/master/bevy-cookbook.md#grabbing-the-mouse

Thanks for taking the time to write about the design considerations. I'll close this pull request, and then we can refer to it (or the cookbook) if someone wants to know how to do mouse capturing currently. Shall we create an issue for a mouse capture API and another for the window abstraction?

That would be much appreciated!