VirtualKeyCode extensions + X11 bindings

[dhardy]

• [ ] Tested on all platforms changed
• [x] Compilation warnings were addressed
• [x] cargo fmt has been run on this branch
• [x] 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

This PR comes in two parts (not completely separated by commit):

1. Fix some missing X11 key bindings
2. Add some VirtualKeyCode enumerations and bindings for several common symbols (most of which don't usually appear on keys directly, but nevertheless are generated on my keyboard)

I expect this to be at least a little contentious: choices of which codes to add to VirtualKeyCode are arbitrary. I didn't touch any media/web keys yet (I can, and probably should, since many of these are already included in VirtualKeyCode); I also did not add locale-specific letters (ç, à, ä, etc.; there are many of these defined for X11). With some feedback I can fix this up.

Of course, these new enums deserve bindings on other platforms. Since I can't easily test on other platforms and since many X11 bindings were already missed, I feel no obligation to address this myself. Also, some of these enums may be specific to X11. I also feel no guilt about this, since I believe some of the other codes are likely platform specific (e.g. Ax, AbntC1).

There may be prior art in some other compilation of key symbols? Alternatively I'm half tempted to completely ignore this enumeration and use ReceivedCharacter instead, since this automatically includes all possible generated chars (although it misses media/web keys).

Useful link: x11-rs/src/keysym.rs

[dhardy]

Note that XKB can also directly pass unicode codes by adding 0x100_0000 to the code, e.g. 0x10000F7 = ÷, thus exhaustive bindings are completely infeasible.

There are other bindings missed on my keyboard, e.g. XK_ISO_Level3_Shift: c_uint = 0xfe03; — this I didn't bother mapping since it should not usually be interpreted by applications.

Aha, I see the web bindings are based roughly on this document. This does not appear sufficient for X11 which generates unique codes for shifted keys, e.g. Asterisk → *.

I have partial web key bindings incoming. What we care about here is quite arbitrary; e.g. I found an old keyboard with Webcam, Messenger and Shopping buttons, but I don't think there's much interest in supporting these.

[OvermindDL1]

I'd at least expect the Xfree86 extended keyboard mappings to be directly supported (which includes those odd keys like webcam, messenger, and shopping). My keyboard has over 140 keys and sends out quite a variety of these, and I really exceptionally hate that so many programs don't support them.

[murarth]

cc @Osspial, regarding the changes to platform-independent API.

[dhardy]

@OvermindDL1 I am also a member of the hack your own keyboard club. Most of what I've added here is pretty standard stuff however.

I have a couple of questions regarding how we should proceed here:

1. How applicable is this to other platforms? IIUC Wayland also uses XKB for keyboard configuration, thus should have exactly the same mapping here — but then why does it have its own implementation keysym_to_vkey? For other platforms I have no clue.
2. What should influence the design of the VirtualKeyCode enum? There are some things I dislike about the current implementation: lack of organisation of much of the contents (partially improved in my PR), lack of clarity what several things mean — is Stop to do with power management or web browsing — what precisely do Power and Sleep mean?
3. How comprehensive does it make sense to make the enumeration? Are there any guides for what applications should do with those, given that most devs only ever seem to care about standard QWERTY boards + a few media keys?
4. As mentioned above, even supporting the XFree86 extended mappings is not comprehensive. Should one even attempt to offer comprehensive support under WindowEvent::KeyboardInput, e.g. by falling back to a u32 or char?

[OvermindDL1]

1. Unsure about windows, but android supports xfree86's extended keys last I recall, and Windows has a similar form as well.

2. Yeah I think this enumeration needs a big go-over before accepted...

3. Should be fairly comprehensive, if not by names than at least categories. I do actually like to use those keys a lot, and winit isn't just for basic UI devs but for anything anywhere, it should be able to support anything that's handed to it.

[elinorbgr]

IIUC Wayland also uses XKB for keyboard configuration, thus should have exactly the same mapping here — but then why does it have its own implementation keysym_to_vkey?

I guess there is room for merging the huge match { } blocks of wayland and linux indeed, the keycodes are the same.

[dhardy]

This is still waiting on feedback (assuming @OvermindDL1 is speaking as a community member). In particular, this VirtualKeyCode enum — should I simply amend it as I see fit? Are any guidelines available on this?

[Ralith]

My keyboard has over 140 keys and sends out quite a variety of these, and I really exceptionally hate that so many programs don't support them.

It's worth noting that a well-written winit application with configurable key bindings can and probably should support binding keys outside of the VirtualKeyCode space via scancodes. VirtualKeyCode is only absolutely required when the key binding will be hard-coded (or configured by default).

[dhardy]

Apparently I accidentally overwrote this. Given it's age, I'll assume it's dead anyway.