Scancode

[mantognini]

Purpose

Scancodes are a very important feature that's been asked to be implemented in SFML for a long time. It gives developers a layout independent way of reading keyboard input. Suppose you're using standard "WASD" walking input scheme in your game. If you just say "if pressed sf::Keyboard::Key::A then go left", it'll work as expected only on a QWERTY and a bunch of layouts where "WASD" is in the place gamers usually expect it to be. But, it'll work wrong on AZERTY layout, which has "A" where "Q" on QWERTY is.

Scancodes prevent this problem. If we say "if pressed sf::Keyboard::ScanA then go left", we're telling something like "if pressed the key which is in the place where A on QWERTY keyboards is then go left".

Testing

Either of the follow applications can be used to test:

• SFML-Input: https://github.com/eXpl0it3r/SFML-Input
• SFML-Test-Events (feature branch: scancode): https://github.com/mantognini/SFML-Test-Events/tree/scancode

Snapshot Builds: https://artifacts.sfml-dev.org/by-branch/feature/scancode/

SFML Tasks

• Create a complete list of key mappings
  • Scancodes
  • Description (Names) -> OS & Language dependant
  • Windows
  • Linux
  • macOS
• Windows: Implement scancode retrieval for events
• Windows: Look into issue with TDM build -> TDM builds were decommissioned
• Discussion Points
  • Rename sf::Keyboard::Key names for Numpad to align with scancode naming?
  • Find a name for Key 45
  • Check on Linux & macOS whether Key 42 also maps to scancode 0x56
• Find a better way to handle descriptions on macOS or use fixed names
• Check all methods are implemented for all OS
  • Windows
    • Key events
    • Keyboard static function
    • Localize
    • Unlocalize
    • Description
  • Linux
    • Key events
    • Keyboard static function
    • Localize
    • Unlocalize
    • Description
  • macOS
    • Key events
    • Keyboard static function
    • Localize
    • Unlocalize
    • Description
• Check that the documentation is aligned
• (optional) Consider providing additional images to explain the scancode positions better
• Squash commits for a better overview of the change
• Fix isKeyPressed issue
• Look into required PrintScreen workarounds
• Scoping for Scancode enum
• Linux caps lock + naming fix
• Review
• Test ❗️

---

Layout agnostic keyboard reference image from the Microsoft Scancode Specification

Following on #7, and some (old) discussion on the forum, here is an API to deal with Scancodes and an implementation for Mac. You can test this implementation, or new ones, using the scancode branch of SFML-Test-Events.

Note that there are a few TODOs that deserve a quick discussion, especially w.r.t. the upcoming 3.0 and its breaking changes.

So, send your feedback this way and if you want to implement it for Linux or Windows, let me know!

[eXpl0it3r]

As mentioned, it's still missing Windows and Linux (& iOS and Android) implementations.

[eXpl0it3r]

We're still looking for someone to be willing to provide an implementation for Windows and Linux!

If you want to contribute, fork SFML and provide a pull request based this branch feature/scancode.

[Hapaxia]

I think the scancodes should be named more similar to the SFML key codes already.

For example, since Return is used in the key code enum, it should be used for the scan code on the main key set. However, the number pad's enter key should probably never be called return. The current setup seems inverted. If the pad's enter isto be called Return, it could be NumpadReturn or similar, which would mean that PadEquals should be NumpadEquals. Whether it is Numpad or just Pad, they should be the same. It's also possible that the pad's Enter key on PC is equivalent to the pad's Equals key on the Mac.

There is absolutely no need for the unnecessary pre-fix 'forwards' to be added to a standard slash. 'Reverse solidus' just means "backwards slash"; how is it different from BackSlash?

All of the above presumes the Scan prefix is included, of course.

[mantognini]

For example, since Return is used in the key code enum, it should be used for the scan code on the main key set. However, the number pad's enter key should probably never be called return. The current setup seems inverted.

Yes, there are some inconsistencies. The names I've selected are from the USB HID specs. We might indeed want to deviate from them a bit here and there.

'Reverse solidus' just means "backwards slash"; how is it different from BackSlash?

That's a good question, to which the HID specs doesn't seem to give an answer, so I don't know.

[mantognini]

@SFML/sfml I'd like to update this but I need your feedback on the above open questions.

[mantognini]

I'd like your input on the above open questions in order to update the code & integrate @JonnyPtn's work from #1294 for Windows.

[eliasdaler]

By the way, I've been working on Linux implementation for some time, and I'll make a pull request once all the functions are implemented. I think there'll be a lot of things to discuss since the current keyboard code for X11 was a bit scattered around and I had to move it around a bit to get the needed functionality. I based my implementation on GLFW's, because scancodes on X11 are not easy to deal with.
And I just want to know: what is the proper way to refer to other code bases as a source? I've seen some code that was based on SDL and it just said so in comments. Should I do the same for GLFW? :)

P.S. getDescription is giving me the most trouble as for now, it's very hard to implement properly.

[eliasdaler]

https://github.com/eliasdaler/SFML/tree/scancode-linux
My branch can be found here. Not ready to make pull request yet (it has no comments!), but it works.
Once I find the time to implement getDescription and add comments, I'll make a PR.

[mantognini]

This PR is now stalled until #1395 is merged in order to address naming.

@eliasdaler I only see your question now... I guess it's always safer to post an additional comment instead of editing your messages. ;-)

what is the proper way to refer to other code bases as a source? I've seen some code that was based on SDL and it just said so in comments. Should I do the same for GLFW? :)

That would be perfect IMO.

Did you make some progress on getDescription? Don't worry about the upcoming changes of enum values, I'll rebase/adapt your work for Linux (and @JonnyPtn's for Windows) afterwards in one go.

[ChrisThrasher]

A feature of this size can't get proper testing until it's actually merged and in the hands of those using the 2.6.x branch. I move to merge this PR now and fix the remaining issues in subsequent PRs leading up to the release of 2.6.0. That will result in us more quickly developing a shippable implementation of scancodes than keeping it quarantined in this branch forever.

[dogunbound]

I agree with @ChrisThrasher

You can release a version 2.6.0, and do fixes in 2.6.1. If necessary, quickly release 2.6.1 after 2.6.0. 2.6 update is huge, and many of the errors will only show up by releasing it.

[eXpl0it3r]

Minor clean ups

[eXpl0it3r]

What can I say? It's been in the making for a long time and there's still work to be done (e.g. DRM support), but it's time to get it into the hands of all the 2.6.x branch users and I guess after quite some clean up work into the master branch users. 🎉

[eXpl0it3r]

Thank you to everyone who have contributed to this feature!

Special thanks to @mantognini for the macOS part, @JonnyPtn for the Windows part, @eliasdaler for the Linux part, and @kimci86 for all the testing and fixing. <3

[mantognini]

This is awesome, kudos to all of you! 🎉

[Hapaxia]

I've had some opportunity to do some testing of this and I've found that it's working 'almost' perfectly.

Some tiny issues that I've found (on my keyboard, at least):

1. I have a key named "Fn" (for function, obviously) and it doesn't get noticed by SFML.
2. The print screen key (scancode 77) doesn't get noticed by SFML when it is pressed.
3. The right alt key (scancode 133) also triggers the left control key (scancode 127).

I've found no other issues in usage so great job!

It's worth noting that it's very common for right alt (when named Alt Gr) to trigger a left control event and a simple search shows that this happens a lot.
With that said, this is the operating system triggering the control key event. The point of using scancodes is to separate the keys from what they are expected to be used for.
If someone does not press a key, the scancode should not be showing that it has been pressed.

I presume the function key won't get noticed as it's designed to be used in conjunction with other keys.

[eXpl0it3r]

Thank you for testing this! 🙂
And your cool testing project

I have a key named "Fn" (for function, obviously) and it doesn't get noticed by SFML.

This is usually a "hardware" switch and doesn't get reported, and there isn't really a scancode for it as far as I know.

The print screen key (scancode 77) doesn't get noticed by SFML when it is pressed.

Yeah, it's a rather special key and all implementations I've seen, have some workarounds for it. I didn't really feel like investing more time just to figure a perfect solution. If someone wants to spend a bit of time investigating, I'd be more than happy to merge such a PR.

The right alt key (scancode 133) also triggers the left control key (scancode 127).

Alt Gr is not the same as RAlt, but I understand your point about physical keys being pressed. Not sure if SFML should filter the event here 🤔

[Hapaxia]

Thanks for replying.

Thank you for testing this! 🙂 And your cool testing project

Glad you like it :)

As expected with the function key. Mainly just wanted to state it so that we're aware if anyone brings it up saying that "it doesn't work".

Print screen is always a weird key. That said, SFML is providing a code (value) for it; does it work in some cases?

Alt Gr is not the same as RAlt, but I understand your point about physical keys being pressed. Not sure if SFML should filter the event here 🤔

I agree that Alt Gr is not the same as R Alt. However, the physical key is there instead of it, in the same way a \ key might be there instead of < key, for instance.
It would make sense for the normal key events to be more abstract and understand it as Alt Gr and give a Control event but, with scancodes, the physical key should be represented if possible. That's part of the reason behind scancodes, surely.
I think scancodes should be expected to represent 1:1 a physical key.