So, attached is the thing I've been talking about for a while: a prototype implementation (for Mac OS X (Quartz) and X11) of a keyboard handling feature that in my opinion could replace both the "sym" field of the SDL_keysym structure (SDL_Event.key.keysym) with the associated SDLK_* constants and its "scancode" field. However, since I've gotten the impression that some people are of different opinion, I'm proposing it as an addition rather than a replacement.

It is implemented as a patch against SDL 1.2 (rev. 2741 from today, but none of the affected files has changed after rev. 2549) because at the time I started it, SDL 1.3 wasn't functional enough for it, but the intention is to get it into SDL 1.3 if people agree.

It adds three things to the SDL API:

- A new field in the SDL_keysym (SDL_Event.key.keysym) structure: SDLPKey pkey.

- An enumerated type SDLPKey in SDL_keysym.h with a set of constants for this field: e.g. SDL_PK_A, SDL_PK_RETURN, SDL_PK_LSHIFT.

- A new function: const char * SDL_PKeyName(SDLPKey pkey), explained below.

Unlike the SDL_Event.key.keysym.sym field with its SDLK_* constants, which refers to a key with a particular label, the SDL_Event.key.keysym.pkey field with its SDL_PK_* constants refers to a key at a specific physical position on the keyboard (hence the name "physical key code"). E.g. SDL_PK_A means "the leftmost letter key in the middle alphabetic row" (which is labeled "A" on a US keyboard).

The SDL_PKeyName function takes a physical key code and returns a human-readable description for that key that ideally matches what's printed on the key cap on the user's keyboard, i.e. it takes into account the OS' current key mapping settings.

One case where the usefulness of such a system should be obvious is emulators (of devices with PC-like keyboards, e.g. Basilisk or Qemu or PearPC) - what they usually did up to now was to work with the platform-dependent "scancode" field and translate it to the emulated scancodes they need using platform-specific lookup tables. Now SDL takes the work of compiling these tables off them.

However, even in the case of games I think this system has its advantages. First, when the keyboard is used as some sort of gamepad, it seems much more natural to map the keys by their position than by their label. E.g. SDL_PK_Z will always be below SDL_PK_A, while SDLK_z is only below SDLK_a on a US keyboard, not on a French or German one. Second, I find that SDL_PKeyName() works much better for presenting key names to the user than SDL_KeyName() - e.g. when I press the "