Key

Each instance represents a physical key on a keyboard. i.e. a piece of plastic with one or more symbols printed on it, and a switch underneath ;-) Not be confused with a Character or a KeyCombination.

When a key has two (or more) symbols printed on it, the name here is for the lower symbol (i.e. when shift is not pressed). e.g. There is no PLUS, because plus is Shift + EQUALS.

Alt keys

The two Alt keys are normally labelled Alt and AltGr. Unlike the two Shift keys or the two Control keys, the two Alt keys sometimes behave differently (which is why they have two different labels). But here, I've ignored this, and called them LEFT_ALT and RIGHT_ALT for consistency with Shift and Control.

Elsewhere, LEFT_ALT is often referred to as just ALT, and RIGHT_ALT as ALT_GRAPH.

World Keys

WORLD_1 on a UK keyboard this the # key (on US Keyboards, # is Shift+3).

As an owner of UK keyboards, please consider using WORLD_1 as an alternative to Shift+3 for keyboard shortcuts relating to grids ;-))

Alas, I'm, not sure what WORLD_1 or WORLD_2 refer to in other parts of the world.

Comparison with JavaFX

Glok's Key is somewhat similar to JavaFX's KeyCode. Here's JavaFX's javadocs for KeyCode :

Set of key codes for KeyEvent objects

Hmm, that's not very helpful is it!

IMHO, KeyCode is badly named, and is based on the name of an Int parameter sent from the operating system to represent a physical key.

Also, I think JavaFX is trying to be clever (and failing), by abstracting away the concept of a physical key. Glok takes the KISS principle (Keep it simple stupid).

Glok's Key names are different names from JavaFX's KeyCode names. e.g. JavaFX uses DIGIT0 instead of DIGIT_0, and NUMPAD0 instead of NUMPAD_0. IMHO adding the underscore makes code much more readable.

Number pad key names are different. e.g. NUMPAD_PERIOD, NUMPAD_MINUS instead of JavaFX's DECIMAL and SUBTRACT. (Another JavaFX fail : Using SUBTRACT and MINUS is just asking for unintended bugs!)

JavaFX, has many more KeyCodes, e.g. AMPERSAND. I have no clue what these extras are for. Are there keyboards with an actual ampersand key (not the 7 key)? Maybe they are only relevant for virtual keyboards found on mobile devices. The API docs doesn't explain.

If my guess is correct, IMHO, this is just wrong. Virtual keyboards should not generate KEY_PRESSED nor KEY_RELEASED for non-standard keys. They should only generate KEY_TYPED events. In which case, there is no Key instance involved.

To prove this point, should there be a KeyCode for every character that could appear on a virtual keyboard, including, all non-ascii letters, all character symbols, all emoji? No! That's what KeyTypedEvent.char and KeyTypedEvent.codePoint are for!

If you want to implement a virtual keyboard which generates KEY_PRESSED and KEY_RELEASED events too, that's fine, but only when it is mimicking physical keys (i.e. don't introduce new KeyCode instances).