Date: Thu, 05 Jul 2007 14:02:33 -0700

From: Sam Lantinga
Subject: SDL 1.3 keyboard plan

After lots of discussion with Christian, this is what we came up with:

> So, to sum up...
> SDLK_* become the physical keys, starting at > (1<<21)
> We create a macro SDLK_INDEX(X)
> We have two functions SDL_GetLayoutKey(SDLKey) and SDL_GetKeyName()
> SDL_GetLayoutKey maps to UCS4 for printable characters, and SDLK* for
  non-printable characters
> and does so based on the OS's current keyboard layout
> SDL_GetKeyName() handles both SDLK_* and UCS4, converting UCS4 to UTF-8 and
  converting SDLK_* into our names, which are UTF-8 for printable characters.
> WASD folks use SDLK_*, and 'I' folks use SDL_GetLayoutKey(SDLK_*)

Here is the patch he came up with, and his e-mail about it:

Date: Fri, 17 Aug 2007 19:50:28 +0200
From: Christian Walther
Subject: Re: SDL 1.3 keyboard plan

> Sounds great, go ahead and send me a patch.

Here goes! Thanks for having a look. Don't hesitate to comment if
anything does not conform to your ideas.

One caveat: Committing this now may break compilability of some video
drivers - specifically, if they use any of the SDLK_* codes that were
obsoleted and moved into SDL_compat.h. I only tried Cocoa (which did
break, but is already fixed) and X11 (which didn't, but then its key
handling is #iffed out). If that's a problem, it may need to go into
a branch.

  -Christian

--HG--
extra : convert_revision : svn%3Ac70aab31-4412-0410-b14c-859654838e24/trunk%402630

include/SDL_compat.h

@@ -130,6 +130,87 @@ typedef enum
 
 struct SDL_SysWMinfo;
 
+/* Key codes
+   Note that the correspondences defined here are approximate at best because
+   the meaning of the event structure field that carries these values has
+   changed: in SDL 1.2, it referred to the key's label in the current keyboard
+   layout, whereas now it refers to a specific physical key on the keyboard,
+   regardless of the keyboard layout setting.
+   To get comparable behavior to SDL 1.2, code that uses any of the codes below
+   in ways like "if (somekey == SDLK_EXCLAIM)" should be changed to the
+   equivalent of "if (SDL_GetLayoutKey(somekey) == '!')".
+ */
+
+/* These key constants were renamed for clarity or consistence. */
+#define SDLK_QUOTE SDLK_APOSTROPHE
+#define SDLK_MINUS SDLK_HYPHENMINUS
+#define SDLK_BACKQUOTE SDLK_GRAVE
+#define SDLK_a SDLK_A
+#define SDLK_b SDLK_B
+#define SDLK_c SDLK_C
+#define SDLK_d SDLK_D
+#define SDLK_e SDLK_E
+#define SDLK_f SDLK_F
+#define SDLK_g SDLK_G
+#define SDLK_h SDLK_H
+#define SDLK_i SDLK_I
+#define SDLK_j SDLK_J
+#define SDLK_k SDLK_K
+#define SDLK_l SDLK_L
+#define SDLK_m SDLK_M
+#define SDLK_n SDLK_N
+#define SDLK_o SDLK_O
+#define SDLK_p SDLK_P
+#define SDLK_q SDLK_Q
+#define SDLK_r SDLK_R
+#define SDLK_s SDLK_S
+#define SDLK_t SDLK_T
+#define SDLK_u SDLK_U
+#define SDLK_v SDLK_V
+#define SDLK_w SDLK_W
+#define SDLK_x SDLK_X
+#define SDLK_y SDLK_Y
+#define SDLK_z SDLK_Z
+#define SDLK_KP0 SDLK_KP_0
+#define SDLK_KP1 SDLK_KP_1
+#define SDLK_KP2 SDLK_KP_2
+#define SDLK_KP3 SDLK_KP_3
+#define SDLK_KP4 SDLK_KP_4
+#define SDLK_KP5 SDLK_KP_5
+#define SDLK_KP6 SDLK_KP_6
+#define SDLK_KP7 SDLK_KP_7
+#define SDLK_KP8 SDLK_KP_8
+#define SDLK_KP9 SDLK_KP_9
+#define SDLK_NUMLOCK SDLK_KP_NUMLOCKCLEAR
+#define SDLK_SCROLLOCK SDLK_SCROLLLOCK
+#define SDLK_PRINT SDLK_PRINTSCREEN
+
+/* These key constants are obsoleted the new keyboard handling, their definitions here correspond to how they appear on a US keyboard. */
+#define SDLK_EXCLAIM SDLK_1
+#define SDLK_QUOTEDBL SDLK_APOSTROPHE
+#define SDLK_HASH SDLK_3
+#define SDLK_DOLLAR SDLK_4
+#define SDLK_AMPERSAND SDLK_7
+#define SDLK_LEFTPAREN SDLK_9
+#define SDLK_RIGHTPAREN SDLK_0
+#define SDLK_ASTERISK SDLK_8
+#define SDLK_PLUS SDLK_EQUALS
+#define SDLK_COLON SDLK_SEMICOLON
+#define SDLK_LESS SDLK_COMMA
+#define SDLK_GREATER SDLK_PERIOD
+#define SDLK_QUESTION SDLK_SLASH
+#define SDLK_AT SDLK_2
+#define SDLK_CARET SDLK_6
+#define SDLK_UNDERSCORE SDLK_HYPHENMINUS
+
+/* These keys don't appear in the USB specification (or at least not under those names). I'm unsure if the following assignments make sense or if these codes should be defined as actual additional SDLK_ constants. */
+#define SDLK_LSUPER SDLK_LMETA
+#define SDLK_RSUPER SDLK_RMETA
+#define SDLK_COMPOSE SDLK_APPLICATION
+#define SDLK_BREAK SDLK_STOP
+#define SDLK_EURO SDLK_2
+
+
 #define SDL_SetModuleHandle(x)
 #define SDL_AllocSurface    SDL_CreateRGBSurface
 

include/SDL_keyboard.h

@@ -50,7 +50,7 @@ typedef struct SDL_keysym
 {
     Uint8 scancode;             /**< keyboard specific scancode */
     Uint8 padding[3];           /**< alignment padding */
-    Uint16 sym;                 /**< SDL virtual keysym */
+    SDLKey sym;                 /**< SDL virtual key code - see ::SDLKey for details */
     Uint16 mod;                 /**< current key modifiers */
     Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
 } SDL_keysym;
@@ -97,11 +97,13 @@ extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
  *
  * \brief Get a snapshot of the current state of the selected keyboard.
  *
- * \return An array of keystates, indexed by the SDLK_* syms.
+ * \param numkeys if non-NULL, receives the length of the returned array.
+ *
+ * \return An array of key states. Indexes into this array are obtained by using the SDLK_INDEX() macro on the \link ::SDLPhysicalKey SDLK_* \endlink syms.
  *
  * Example:
  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
- *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
+ *	if ( keystate[SDLK_INDEX(SDLK_RETURN)] ) ... <RETURN> is pressed.
  */
 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys);
 
@@ -122,11 +124,32 @@ extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 
 /**
- * \fn const char *SDL_GetKeyName(SDLKey key)
+ * \fn SDLKey SDL_GetLayoutKey(SDLKey physicalKey)
+ * 
+ * \brief Get the layout key code corresponding to the given physical key code according to the current keyboard layout.
+ *
+ * See ::SDLKey for details.
+ *
+ * If \a physicalKey is not a physical key code, it is returned unchanged.
+ *
+ * \sa SDL_GetKeyName()
+ */
+extern DECLSPEC SDLKey SDLCALL SDL_GetLayoutKey(SDLKey physicalKey);
+
+/**
+ * \fn const char *SDL_GetKeyName(SDLKey layoutKey)
+ * 
+ * \brief Get a human-readable name for a key.
+ *
+ * \param layoutKey An SDL layout key code.
+ *
+ * If what you have is a physical key code, e.g. from the \link SDL_keysym::sym key.keysym.sym \endlink field of the SDL_Event structure, convert it to a layout key code using SDL_GetLayoutKey() first. Doing this ensures that the returned name matches what users see on their keyboards. Calling this function directly on a physical key code (that is not also a layout key code) is possible, but is not recommended except for debugging purposes. The name returned in that case is the name of the \link ::SDLPhysicalKey SDLK_* \endlink constant and is not suitable for display to users.
+ *
+ * \return A pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it. Always non-NULL.
  *
- * \brief Get the name of an SDL virtual keysym
+ * \sa SDLKey
  */
-extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
+extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey layoutKey);
 
 
 /* Ends C function definitions when using C++ */

include/SDL_keysym.h

@@ -27,175 +27,412 @@
 #ifndef _SDL_keysym_h
 #define _SDL_keysym_h
 
+#include "SDL_stdinc.h"
+
 /**
- * \enum SDLKey
+ * \typedef SDLKey
+ *
+ * \brief The SDL virtual key representation.
+ *
+ * Values of this type are used to represent keyboard keys, among other places
+ * in the \link SDL_keysym::sym key.keysym.sym \endlink field of the SDL_Event
+ * structure.
+ *
+ * There are two fundamental ways of referring to a key: First, a certain code
+ * can stand for a key at a specific physical location on the keyboard,
+ * independent of its label or what character it generates. These are the \e
+ * physical key codes, comparable to the raw hardware scancodes that a keyboard
+ * generates. Second, a code can refer to a key with a specific label,
+ * generating a specific character or performing a specific function, which may
+ * be located at different places on the keyboard, or not exist at all,
+ * depending on what keyboard layout is used. These are \e layout key codes.
+ *
+ * There is a certain overlap between the sets of physical key codes and layout
+ * key codes: \e return, \e tab, \e ctrl etc. are typically independent of the
+ * keyboard layout and can be thought of as either a physical or a layout key.
+ * Therefore, rather than having separate types with separate sets of constants
+ * for physical keys and layout keys, a single type ::SDLKey is used for both
+ * sets. The physical key codes (forming a well-known set of a few hundred
+ * elements) are enumerated in enum ::SDLPhysicalKey. The set of layout key
+ * codes is more diverse: For keys that don't generate characters, the layout
+ * key code is equal to the physical key code, i.e. the same SDLK_* constants
+ * from enum ::SDLPhysicalKey are used. For character keys, the layout key code
+ * is equal to the Unicode code point of the character that is generated when
+ * the key is pressed without shift or any other modifiers (for ASCII
+ * characters, this can be directly written as a character literal like
+ * <tt>'x'</tt>).
  *
- * \brief The SDL virtual key representation
+ * The \link SDL_keysym::sym key.keysym.sym \endlink field of the SDL_Event
+ * structure is always a physical key code. To get the layout key code for the
+ * event, run that physical key code through SDL_GetLayoutKey(), which converts
+ * it to a layout key code according to the current keyboard layout settings of
+ * the OS. In particular, this is what should be done when displaying the name
+ * of a key to the user: use
+ * <tt>SDL_GetKeyName(SDL_GetLayoutKey(myPhysicalKeyCode))</tt>. Do not use
+ * SDL_GetKeyName() directly on a physical key code (except for debugging
+ * purposes), as the name returned by that will not correspond to how the key
+ * is labeled on the user's keyboard.
  *
- * The SDLKey represents the unmodified character printed on the key
- * for the current keyboard layout.  The first 255 characters are used
- * unchanged from Latin-1, e.g. a key with 'a' on it will have the value "a".
- * The rest of the keys are named below, and fall into the range above 255.
+ * \par Example:
+ * To implement WASD directional keys, it makes sense to use physical key
+ * codes, so that the "forward" key will be above the "backward" key even
+ * though, for example, it's labeled "Z", not "W", on a French keyboard:
+ * \code
+ * print("To go forward, press the %s key.", SDL_GetKeyName(SDL_GetLayoutKey(SDLK_W)));
+ * ...
+ * switch (event.key.keysym.sym) {
+ *     case SDLK_W:
+ *         forward();
+ *         break;
+ *     case SDLK_A:
+ *         left();
+ *         break;
+ *     ...
+ * }
+ * \endcode
+ * For keys based on mnemonics like "I for inventory" or "Z for zoom", use
+ * layout key codes, so that the key labeled "Z" will zoom, whether it's at the
+ * bottom left of the keyboard like on a US layout, or in the upper center like
+ * on a German layout (but keep in mind that this forces your users to use a
+ * keyboard layout where there \e is an I or Z key):
+ * \code
+ * print("To open the inventory, press the %s key.", SDL_GetKeyName('i'));
+ * ...
+ * switch (SDL_GetLayoutKey(event.key.keysym.sym)) {
+ *     case 'i':
+ *         inventory();
+ *         break;
+ *     case 'z':
+ *         zoom();
+ *         break;
+ *     ...
+ * }
+ * \endcode
+ * Of course, in a real application, you should not hardcode your key
+ * assignments like this, but make them user-configurable.
  */
-typedef enum
-{
-    /* The keyboard syms have been cleverly chosen to map to ASCII */
-    SDLK_UNKNOWN = 0,
-    SDLK_FIRST = 0,
-    SDLK_BACKSPACE = 8,
-    SDLK_TAB = 9,
-    SDLK_CLEAR = 12,
-    SDLK_RETURN = 13,
-    SDLK_PAUSE = 19,
-    SDLK_ESCAPE = 27,
-    SDLK_SPACE = 32,
-    SDLK_EXCLAIM = 33,
-    SDLK_QUOTEDBL = 34,
-    SDLK_HASH = 35,
-    SDLK_DOLLAR = 36,
-    SDLK_AMPERSAND = 38,
-    SDLK_QUOTE = 39,
-    SDLK_LEFTPAREN = 40,
-    SDLK_RIGHTPAREN = 41,
-    SDLK_ASTERISK = 42,
-    SDLK_PLUS = 43,
-    SDLK_COMMA = 44,
-    SDLK_MINUS = 45,
-    SDLK_PERIOD = 46,
-    SDLK_SLASH = 47,
-    SDLK_0 = 48,
-    SDLK_1 = 49,
-    SDLK_2 = 50,
-    SDLK_3 = 51,
-    SDLK_4 = 52,
-    SDLK_5 = 53,
-    SDLK_6 = 54,
-    SDLK_7 = 55,
-    SDLK_8 = 56,
-    SDLK_9 = 57,
-    SDLK_COLON = 58,
-    SDLK_SEMICOLON = 59,
-    SDLK_LESS = 60,
-    SDLK_EQUALS = 61,
-    SDLK_GREATER = 62,
-    SDLK_QUESTION = 63,
-    SDLK_AT = 64,
-    /* 
-       Skip uppercase letters
+typedef Uint32 SDLKey;
+
+#define SDL_KEY_CAN_BE_PHYSICAL_BIT (1<<24)     /* marks SDLKeys from the "physical" set (some of these are also in the "layout" set) */
+#define SDL_KEY_KEYPAD_BIT (1<<25)      /* marks keypad keys that need [] around their name to distinguish them from the corresponding keyboard keys */
+#define SDL_KEY_LAYOUT_SPECIAL_BIT (1<<26)      /* marks non-physical layout keys that cannot be described by a single character */
+
+/** Converts an \link ::SDLPhysicalKey SDLK_* \endlink constant to an index into the array obtained from SDL_GetKeyState(). */
+#define SDLK_INDEX(k) ((k) & 0x00FFFFFF)
+
+#define SDL_PHYSICAL_KEY(n) ((n) | SDL_KEY_CAN_BE_PHYSICAL_BIT)
+
+/**
+ * \brief SDL physical key codes.
+ *
+ * This is the set of physical key codes, i.e. the values of SDL_keysym::sym.
+ * Some of them (those for non-character keys) also appear as layout key codes.
+ * The constants are typically named after how the key would be labeled on a US
+ * keyboard, e.g. SDLK_A or SDLK_LEFTBRACKET refer to the keys used as A and [
+ * on a US layout, but used as Q and ^ on a French layout.
+ *
+ * <em>enum SDLPhysicalKey</em> is not a useful type in its own right - the
+ * constants defined here are intended as values of the ::SDLKey type. The only
+ * reason for the enum to have a name at all is that otherwise it would be
+ * impossible to refer to it in the documentation.
+ *
+ * \sa SDLKey
+ *
+ * \par Notes for driver implementors:
+ * These constants and their numerical values are based on the USB HID usage
+ * tables, version 1.12
+ * <http://www.usb.org/developers/devclass_docs/Hut1_12.pdf>, section "10
+ * Keyboard/Keypad Page (0x07)". When deciding what code to generate for what
+ * key, the following rules can be used as guidelines:
+ * - A given key on a given keyboard should produce the same SDLK_* code, no
+ * matter what computer it is connected to, what OS runs on that computer, and
+ * what the keyboard layout settings in the OS are. For USB keyboards, that
+ * should be the code numerically corresponding to the key's USB usage code
+ * (with exceptions, see comments for specific constants).
+ * - Two keys on two different keyboards are considered "the same key" and
+ * should generate the same SDLK_* code if, when connected to the same
+ * computer, they are treated equally by the OS. For USB keyboards, that's
+ * generally the case when they generate the same USB usage code. Non-USB
+ * keyboards can probably be treated like USB keyboards of the same layout, if
+ * such exist. If not, and there's no possibility to determine the equivalence
+ * relation by transitivity from the above - in particular, on devices like
+ * phones or game consoles that don't have PC-style alphabetic keyboards -
+ * apply common sense. If none of the predefined codes fit, insert new ones at
+ * the end.
  */
-    SDLK_LEFTBRACKET = 91,
-    SDLK_BACKSLASH = 92,
-    SDLK_RIGHTBRACKET = 93,
-    SDLK_CARET = 94,
-    SDLK_UNDERSCORE = 95,
-    SDLK_BACKQUOTE = 96,
-    SDLK_a = 97,
-    SDLK_b = 98,
-    SDLK_c = 99,
-    SDLK_d = 100,
-    SDLK_e = 101,
-    SDLK_f = 102,
-    SDLK_g = 103,
-    SDLK_h = 104,
-    SDLK_i = 105,
-    SDLK_j = 106,
-    SDLK_k = 107,
-    SDLK_l = 108,
-    SDLK_m = 109,
-    SDLK_n = 110,
-    SDLK_o = 111,
-    SDLK_p = 112,
-    SDLK_q = 113,
-    SDLK_r = 114,
-    SDLK_s = 115,
-    SDLK_t = 116,
-    SDLK_u = 117,
-    SDLK_v = 118,
-    SDLK_w = 119,
-    SDLK_x = 120,
-    SDLK_y = 121,
-    SDLK_z = 122,
-    SDLK_DELETE = 127,
-    /* End of ASCII mapped keysyms */
-
-    /* Numeric keypad */
-    SDLK_KP0 = 256,
-    SDLK_KP1 = 257,
-    SDLK_KP2 = 258,
-    SDLK_KP3 = 259,
-    SDLK_KP4 = 260,
-    SDLK_KP5 = 261,
-    SDLK_KP6 = 262,
-    SDLK_KP7 = 263,
-    SDLK_KP8 = 264,
-    SDLK_KP9 = 265,
-    SDLK_KP_PERIOD = 266,
-    SDLK_KP_DIVIDE = 267,
-    SDLK_KP_MULTIPLY = 268,
-    SDLK_KP_MINUS = 269,
-    SDLK_KP_PLUS = 270,
-    SDLK_KP_ENTER = 271,
-    SDLK_KP_EQUALS = 272,
-
-    /* Arrows + Home/End pad */
-    SDLK_UP = 273,
-    SDLK_DOWN = 274,
-    SDLK_RIGHT = 275,
-    SDLK_LEFT = 276,
-    SDLK_INSERT = 277,
-    SDLK_HOME = 278,
-    SDLK_END = 279,
-    SDLK_PAGEUP = 280,
-    SDLK_PAGEDOWN = 281,
-
-    /* Function keys */
-    SDLK_F1 = 282,
-    SDLK_F2 = 283,
-    SDLK_F3 = 284,
-    SDLK_F4 = 285,
-    SDLK_F5 = 286,
-    SDLK_F6 = 287,
-    SDLK_F7 = 288,
-    SDLK_F8 = 289,
-    SDLK_F9 = 290,
-    SDLK_F10 = 291,
-    SDLK_F11 = 292,
-    SDLK_F12 = 293,
-    SDLK_F13 = 294,
-    SDLK_F14 = 295,
-    SDLK_F15 = 296,
-
-    /* Key state modifier keys */
-    SDLK_NUMLOCK = 300,
-    SDLK_CAPSLOCK = 301,
-    SDLK_SCROLLOCK = 302,
-    SDLK_RSHIFT = 303,
-    SDLK_LSHIFT = 304,
-    SDLK_RCTRL = 305,
-    SDLK_LCTRL = 306,
-    SDLK_RALT = 307,
-    SDLK_LALT = 308,
-    SDLK_RMETA = 309,
-    SDLK_LMETA = 310,
-    SDLK_LSUPER = 311,          /**< Left "Windows" key */
-    SDLK_RSUPER = 312,          /**< Right "Windows" key */
-    SDLK_MODE = 313,            /**< "Alt Gr" key */
-    SDLK_COMPOSE = 314,         /**< Multi-key compose key */
-
-    /* Miscellaneous function keys */
-    SDLK_HELP = 315,
-    SDLK_PRINT = 316,
-    SDLK_SYSREQ = 317,
-    SDLK_BREAK = 318,
-    SDLK_MENU = 319,
-    SDLK_POWER = 320,           /**< Power Macintosh power key */
-    SDLK_EURO = 321,            /**< Some european keyboards */
-    SDLK_UNDO = 322,            /**< Atari keyboard has Undo */
+enum SDLPhysicalKey
+{
+    SDLK_FIRST_PHYSICAL = 0, /**< (not a key, just marks the lowest used value in this enum) */
+    SDLK_NONE = SDL_PHYSICAL_KEY(0),
+    SDLK_UNKNOWN = SDL_PHYSICAL_KEY(1), /* Not from the USB spec, but this is a convenient place for it */
+
+    SDLK_A = SDL_PHYSICAL_KEY(4),
+    SDLK_B = SDL_PHYSICAL_KEY(5),
+    SDLK_C = SDL_PHYSICAL_KEY(6),
+    SDLK_D = SDL_PHYSICAL_KEY(7),
+    SDLK_E = SDL_PHYSICAL_KEY(8),
+    SDLK_F = SDL_PHYSICAL_KEY(9),
+    SDLK_G = SDL_PHYSICAL_KEY(10),
+    SDLK_H = SDL_PHYSICAL_KEY(11),
+    SDLK_I = SDL_PHYSICAL_KEY(12),
+    SDLK_J = SDL_PHYSICAL_KEY(13),
+    SDLK_K = SDL_PHYSICAL_KEY(14),
+    SDLK_L = SDL_PHYSICAL_KEY(15),
+    SDLK_M = SDL_PHYSICAL_KEY(16),
+    SDLK_N = SDL_PHYSICAL_KEY(17),
+    SDLK_O = SDL_PHYSICAL_KEY(18),
+    SDLK_P = SDL_PHYSICAL_KEY(19),
+    SDLK_Q = SDL_PHYSICAL_KEY(20),
+    SDLK_R = SDL_PHYSICAL_KEY(21),
+    SDLK_S = SDL_PHYSICAL_KEY(22),
+    SDLK_T = SDL_PHYSICAL_KEY(23),
+    SDLK_U = SDL_PHYSICAL_KEY(24),
+    SDLK_V = SDL_PHYSICAL_KEY(25),
+    SDLK_W = SDL_PHYSICAL_KEY(26),
+    SDLK_X = SDL_PHYSICAL_KEY(27),
+    SDLK_Y = SDL_PHYSICAL_KEY(28),
+    SDLK_Z = SDL_PHYSICAL_KEY(29),
+
+    SDLK_1 = SDL_PHYSICAL_KEY(30),
+    SDLK_2 = SDL_PHYSICAL_KEY(31),
+    SDLK_3 = SDL_PHYSICAL_KEY(32),
+    SDLK_4 = SDL_PHYSICAL_KEY(33),
+    SDLK_5 = SDL_PHYSICAL_KEY(34),
+    SDLK_6 = SDL_PHYSICAL_KEY(35),
+    SDLK_7 = SDL_PHYSICAL_KEY(36),
+    SDLK_8 = SDL_PHYSICAL_KEY(37),
+    SDLK_9 = SDL_PHYSICAL_KEY(38),
+    SDLK_0 = SDL_PHYSICAL_KEY(39),
+
+    SDLK_RETURN = SDL_PHYSICAL_KEY(40),
+    SDLK_ESCAPE = SDL_PHYSICAL_KEY(41),
+    SDLK_BACKSPACE = SDL_PHYSICAL_KEY(42),
+    SDLK_TAB = SDL_PHYSICAL_KEY(43),
+    SDLK_SPACE = SDL_PHYSICAL_KEY(44),
+
+    SDLK_HYPHENMINUS = SDL_PHYSICAL_KEY(45),
+    SDLK_EQUALS = SDL_PHYSICAL_KEY(46),
+    SDLK_LEFTBRACKET = SDL_PHYSICAL_KEY(47),
+    SDLK_RIGHTBRACKET = SDL_PHYSICAL_KEY(48),
+    SDLK_BACKSLASH = SDL_PHYSICAL_KEY(49), /**< Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout. */
+    SDLK_NONUSHASH = SDL_PHYSICAL_KEY(50), /**< ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDLK_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards. */
+    SDLK_SEMICOLON = SDL_PHYSICAL_KEY(51),
+    SDLK_APOSTROPHE = SDL_PHYSICAL_KEY(52),
+    SDLK_GRAVE = SDL_PHYSICAL_KEY(53), /**< Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards. */
+    SDLK_COMMA = SDL_PHYSICAL_KEY(54),
+    SDLK_PERIOD = SDL_PHYSICAL_KEY(55),
+    SDLK_SLASH = SDL_PHYSICAL_KEY(56),
+
+    SDLK_CAPSLOCK = SDL_PHYSICAL_KEY(57),
+
+    SDLK_F1 = SDL_PHYSICAL_KEY(58),
+    SDLK_F2 = SDL_PHYSICAL_KEY(59),
+    SDLK_F3 = SDL_PHYSICAL_KEY(60),
+    SDLK_F4 = SDL_PHYSICAL_KEY(61),
+    SDLK_F5 = SDL_PHYSICAL_KEY(62),
+    SDLK_F6 = SDL_PHYSICAL_KEY(63),
+    SDLK_F7 = SDL_PHYSICAL_KEY(64),
+    SDLK_F8 = SDL_PHYSICAL_KEY(65),
+    SDLK_F9 = SDL_PHYSICAL_KEY(66),
+    SDLK_F10 = SDL_PHYSICAL_KEY(67),
+    SDLK_F11 = SDL_PHYSICAL_KEY(68),
+    SDLK_F12 = SDL_PHYSICAL_KEY(69),
+
+    SDLK_PRINTSCREEN = SDL_PHYSICAL_KEY(70),
+    SDLK_SCROLLLOCK = SDL_PHYSICAL_KEY(71),
+    SDLK_PAUSE = SDL_PHYSICAL_KEY(72),
+    SDLK_INSERT = SDL_PHYSICAL_KEY(73), /**< insert on PC, help on some Mac keyboards (but does send code 73, not 117) */
+    SDLK_HOME = SDL_PHYSICAL_KEY(74),
+    SDLK_PAGEUP = SDL_PHYSICAL_KEY(75),
+    SDLK_DELETE = SDL_PHYSICAL_KEY(76),
+    SDLK_END = SDL_PHYSICAL_KEY(77),
+    SDLK_PAGEDOWN = SDL_PHYSICAL_KEY(78),
+    SDLK_RIGHT = SDL_PHYSICAL_KEY(79),
+    SDLK_LEFT = SDL_PHYSICAL_KEY(80),
+    SDLK_DOWN = SDL_PHYSICAL_KEY(81),
+    SDLK_UP = SDL_PHYSICAL_KEY(82),
+
+    SDLK_KP_NUMLOCKCLEAR = SDL_PHYSICAL_KEY(83), /**< num lock on PC, clear on Mac keyboards */
+    SDLK_KP_DIVIDE = SDL_PHYSICAL_KEY(84) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MULTIPLY = SDL_PHYSICAL_KEY(85) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MINUS = SDL_PHYSICAL_KEY(86) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_PLUS = SDL_PHYSICAL_KEY(87) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_ENTER = SDL_PHYSICAL_KEY(88),
+    SDLK_KP_1 = SDL_PHYSICAL_KEY(89) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_2 = SDL_PHYSICAL_KEY(90) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_3 = SDL_PHYSICAL_KEY(91) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_4 = SDL_PHYSICAL_KEY(92) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_5 = SDL_PHYSICAL_KEY(93) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_6 = SDL_PHYSICAL_KEY(94) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_7 = SDL_PHYSICAL_KEY(95) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_8 = SDL_PHYSICAL_KEY(96) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_9 = SDL_PHYSICAL_KEY(97) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_0 = SDL_PHYSICAL_KEY(98) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_PERIOD = SDL_PHYSICAL_KEY(99) | SDL_KEY_KEYPAD_BIT,
+
+    SDLK_NONUSBACKSLASH = SDL_PHYSICAL_KEY(100), /**< This is the additional key that ISO keyboards have over ANSI ones, located between left shift and Y. Produces GRAVE ACCENT and TILDE in a US or UK Mac layout, REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US or UK Windows layout, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French layout. */
+    SDLK_APPLICATION = SDL_PHYSICAL_KEY(101), /**< windows contextual menu, compose */
+    SDLK_POWER = SDL_PHYSICAL_KEY(102), /**< The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key. */
+    SDLK_KP_EQUALS = SDL_PHYSICAL_KEY(103) | SDL_KEY_KEYPAD_BIT,
+    SDLK_F13 = SDL_PHYSICAL_KEY(104),
+    SDLK_F14 = SDL_PHYSICAL_KEY(105),
+    SDLK_F15 = SDL_PHYSICAL_KEY(106),
+    SDLK_F16 = SDL_PHYSICAL_KEY(107),
+    SDLK_F17 = SDL_PHYSICAL_KEY(108),
+    SDLK_F18 = SDL_PHYSICAL_KEY(109),
+    SDLK_F19 = SDL_PHYSICAL_KEY(110),
+    SDLK_F20 = SDL_PHYSICAL_KEY(111),
+    SDLK_F21 = SDL_PHYSICAL_KEY(112),
+    SDLK_F22 = SDL_PHYSICAL_KEY(113),
+    SDLK_F23 = SDL_PHYSICAL_KEY(114),
+    SDLK_F24 = SDL_PHYSICAL_KEY(115),
+    SDLK_EXECUTE = SDL_PHYSICAL_KEY(116),
+    SDLK_HELP = SDL_PHYSICAL_KEY(117),
+    SDLK_MENU = SDL_PHYSICAL_KEY(118),
+    SDLK_SELECT = SDL_PHYSICAL_KEY(119),
+    SDLK_STOP = SDL_PHYSICAL_KEY(120),
+    SDLK_AGAIN = SDL_PHYSICAL_KEY(121), /*!< redo */
+    SDLK_UNDO = SDL_PHYSICAL_KEY(122),
+    SDLK_CUT = SDL_PHYSICAL_KEY(123),
+    SDLK_COPY = SDL_PHYSICAL_KEY(124),
+    SDLK_PASTE = SDL_PHYSICAL_KEY(125),
+    SDLK_FIND = SDL_PHYSICAL_KEY(126),
+    SDLK_MUTE = SDL_PHYSICAL_KEY(127),
+    SDLK_VOLUMEUP = SDL_PHYSICAL_KEY(128),
+    SDLK_VOLUMEDOWN = SDL_PHYSICAL_KEY(129),
+    /*SDLK_LOCKINGCAPSLOCK = SDL_PHYSICAL_KEY(130), not sure whether there's a reason to enable these
+       SDLK_LOCKINGNUMLOCK = SDL_PHYSICAL_KEY(131),
+       SDLK_LOCKINGSCROLLLOCK = SDL_PHYSICAL_KEY(132), */
+    SDLK_KP_COMMA = SDL_PHYSICAL_KEY(133) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_EQUALSAS400 = SDL_PHYSICAL_KEY(134) | SDL_KEY_KEYPAD_BIT,
+
+    SDLK_INTERNATIONAL1 = SDL_PHYSICAL_KEY(135), /**< used on Asian keyboards, see footnotes in USB doc */
+    SDLK_INTERNATIONAL2 = SDL_PHYSICAL_KEY(136),
+    SDLK_INTERNATIONAL3 = SDL_PHYSICAL_KEY(137), /**< Yen */
+    SDLK_INTERNATIONAL4 = SDL_PHYSICAL_KEY(138),
+    SDLK_INTERNATIONAL5 = SDL_PHYSICAL_KEY(139),
+    SDLK_INTERNATIONAL6 = SDL_PHYSICAL_KEY(140),
+    SDLK_INTERNATIONAL7 = SDL_PHYSICAL_KEY(141),
+    SDLK_INTERNATIONAL8 = SDL_PHYSICAL_KEY(142),
+    SDLK_INTERNATIONAL9 = SDL_PHYSICAL_KEY(143),
+    SDLK_LANG1 = SDL_PHYSICAL_KEY(144), /**< Hangul/English toggle */
+    SDLK_LANG2 = SDL_PHYSICAL_KEY(145), /**< Hanja conversion */
+    SDLK_LANG3 = SDL_PHYSICAL_KEY(146), /**< Katakana */
+    SDLK_LANG4 = SDL_PHYSICAL_KEY(147), /**< Hiragana */
+    SDLK_LANG5 = SDL_PHYSICAL_KEY(148), /**< Zenkaku/Hankaku */
+    SDLK_LANG6 = SDL_PHYSICAL_KEY(149), /**< reserved */
+    SDLK_LANG7 = SDL_PHYSICAL_KEY(150), /**< reserved */
+    SDLK_LANG8 = SDL_PHYSICAL_KEY(151), /**< reserved */
+    SDLK_LANG9 = SDL_PHYSICAL_KEY(152), /**< reserved */
+
+    SDLK_ALTERASE = SDL_PHYSICAL_KEY(153), /**< Erase-Eaze */
+    SDLK_SYSREQ = SDL_PHYSICAL_KEY(154),
+    SDLK_CANCEL = SDL_PHYSICAL_KEY(155),
+    SDLK_CLEAR = SDL_PHYSICAL_KEY(156),
+    SDLK_PRIOR = SDL_PHYSICAL_KEY(157),
+    SDLK_RETURN2 = SDL_PHYSICAL_KEY(158),
+    SDLK_SEPARATOR = SDL_PHYSICAL_KEY(159),
+    SDLK_OUT = SDL_PHYSICAL_KEY(160),
+    SDLK_OPER = SDL_PHYSICAL_KEY(161),
+    SDLK_CLEARAGAIN = SDL_PHYSICAL_KEY(162),
+    SDLK_CRSELPROPS = SDL_PHYSICAL_KEY(163),
+    SDLK_EXSEL = SDL_PHYSICAL_KEY(164),
+
+    SDLK_KP_00 = SDL_PHYSICAL_KEY(176) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_000 = SDL_PHYSICAL_KEY(177) | SDL_KEY_KEYPAD_BIT,
+    SDLK_THOUSANDSSEPARATOR = SDL_PHYSICAL_KEY(178),
+    SDLK_DECIMALSEPARATOR = SDL_PHYSICAL_KEY(179),
+    SDLK_CURRENCYUNIT = SDL_PHYSICAL_KEY(180),
+    SDLK_CURRENCYSUBUNIT = SDL_PHYSICAL_KEY(181),
+    SDLK_KP_LEFTPAREN = SDL_PHYSICAL_KEY(182) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_RIGHTPAREN = SDL_PHYSICAL_KEY(183) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_LEFTBRACE = SDL_PHYSICAL_KEY(184) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_RIGHTBRACE = SDL_PHYSICAL_KEY(185) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_TAB = SDL_PHYSICAL_KEY(186) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_BACKSPACE = SDL_PHYSICAL_KEY(187) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_A = SDL_PHYSICAL_KEY(188) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_B = SDL_PHYSICAL_KEY(189) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_C = SDL_PHYSICAL_KEY(190) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_D = SDL_PHYSICAL_KEY(191) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_E = SDL_PHYSICAL_KEY(192) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_F = SDL_PHYSICAL_KEY(193) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_XOR = SDL_PHYSICAL_KEY(194) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_POWER = SDL_PHYSICAL_KEY(195) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_PERCENT = SDL_PHYSICAL_KEY(196) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_LESS = SDL_PHYSICAL_KEY(197) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_GREATER = SDL_PHYSICAL_KEY(198) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_AMPERSAND = SDL_PHYSICAL_KEY(199) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_DBLAMPERSAND = SDL_PHYSICAL_KEY(200) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_VERTICALBAR = SDL_PHYSICAL_KEY(201) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_DBLVERTICALBAR = SDL_PHYSICAL_KEY(202) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_COLON = SDL_PHYSICAL_KEY(203) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_HASH = SDL_PHYSICAL_KEY(204) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_SPACE = SDL_PHYSICAL_KEY(205) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_AT = SDL_PHYSICAL_KEY(206) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_EXCLAM = SDL_PHYSICAL_KEY(207) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMSTORE = SDL_PHYSICAL_KEY(208) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMRECALL = SDL_PHYSICAL_KEY(209) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMCLEAR = SDL_PHYSICAL_KEY(210) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMADD = SDL_PHYSICAL_KEY(211) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMSUBTRACT = SDL_PHYSICAL_KEY(212) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMMULTIPLY = SDL_PHYSICAL_KEY(213) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_MEMDIVIDE = SDL_PHYSICAL_KEY(214) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_PLUSMINUS = SDL_PHYSICAL_KEY(215) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_CLEAR = SDL_PHYSICAL_KEY(216) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_CLEARENTRY = SDL_PHYSICAL_KEY(217) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_BINARY = SDL_PHYSICAL_KEY(218) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_OCTAL = SDL_PHYSICAL_KEY(219) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_DECIMAL = SDL_PHYSICAL_KEY(220) | SDL_KEY_KEYPAD_BIT,
+    SDLK_KP_HEXADECIMAL = SDL_PHYSICAL_KEY(221) | SDL_KEY_KEYPAD_BIT,
+
+    SDLK_LCTRL = SDL_PHYSICAL_KEY(224),
+    SDLK_LSHIFT = SDL_PHYSICAL_KEY(225),
+    SDLK_LALT = SDL_PHYSICAL_KEY(226), /**< alt, option */
+    SDLK_LMETA = SDL_PHYSICAL_KEY(227), /**< windows, command (apple), meta */
+    SDLK_RCTRL = SDL_PHYSICAL_KEY(228),
+    SDLK_RSHIFT = SDL_PHYSICAL_KEY(229),
+    SDLK_RALT = SDL_PHYSICAL_KEY(230), /**< alt gr, option */
+    SDLK_RMETA = SDL_PHYSICAL_KEY(231), /**< windows, command (apple), meta */
+
+    /* Everything below here is not from the USB spec */
+
+    SDLK_MODE = SDL_PHYSICAL_KEY(232),  /* I'm not sure if this is really not covered by any of the above, but since there's a special KMOD_MODE for it I'm adding it here */
+
+    SDLK_BRIGHTNESSDOWN = SDL_PHYSICAL_KEY(236),
+    SDLK_BRIGHTNESSUP = SDL_PHYSICAL_KEY(237),
+    SDLK_DISPLAYSWITCH = SDL_PHYSICAL_KEY(238), /**< display mirroring/dual display switch, video mode switch */
+    SDLK_KBDILLUMTOGGLE = SDL_PHYSICAL_KEY(239),
+    SDLK_KBDILLUMDOWN = SDL_PHYSICAL_KEY(240),
+    SDLK_KBDILLUMUP = SDL_PHYSICAL_KEY(241),
+    SDLK_EJECT = SDL_PHYSICAL_KEY(242),
+    SDLK_SLEEP = SDL_PHYSICAL_KEY(243),
+
+    /* Some of the more common and more standardized "multimedia"/"internet" keyboard keys */
+    SDLK_AUDIOPLAY = SDL_PHYSICAL_KEY(244),
+    SDLK_AUDIOSTOP = SDL_PHYSICAL_KEY(245),
+    SDLK_AUDIOPREV = SDL_PHYSICAL_KEY(246),
+    SDLK_AUDIONEXT = SDL_PHYSICAL_KEY(247),
+    SDLK_CALC = SDL_PHYSICAL_KEY(248),
+    SDLK_WWW = SDL_PHYSICAL_KEY(249),
+    SDLK_EMAIL = SDL_PHYSICAL_KEY(250),
+    SDLK_MEDIA = SDL_PHYSICAL_KEY(251),
+    SDLK_COMPUTER = SDL_PHYSICAL_KEY(252),
+    SDLK_SEARCH = SDL_PHYSICAL_KEY(253),
+    SDLK_BOOKMARKS = SDL_PHYSICAL_KEY(254),
+    SDLK_BROWSERBACK = SDL_PHYSICAL_KEY(255),
+    SDLK_BROWSERFORWARD = SDL_PHYSICAL_KEY(256),
+    SDLK_BROWSERRELOAD = SDL_PHYSICAL_KEY(257),
+    SDLK_BROWSERSTOP = SDL_PHYSICAL_KEY(258),
 
     /* Add any other keys here */
 
-    SDLK_LAST
-} SDLKey;
+    SDLK_LAST_PHYSICAL /**< (not a key, just marks the highest used value in this enum) */
+};
+
+#define SDLK_FIRST SDLK_INDEX(SDLK_FIRST_PHYSICAL)
+#define SDLK_LAST SDLK_INDEX(SDLK_LAST_PHYSICAL)
+
+
 
 /**
  * \enum SDLMod

src/events/SDL_keyboard.c

@@ -27,6 +27,7 @@
 #include "SDL_events.h"
 #include "SDL_events_c.h"
 #include "SDL_sysevents.h"
+#include "SDL_keynames.h"
 
 
 /* Global keyboard information */
@@ -35,246 +36,13 @@ static int SDL_num_keyboards;
 static int SDL_current_keyboard;
 static SDL_Keyboard **SDL_keyboards;
 
-static const char *SDL_keynames[SDLK_LAST];     /* Array of keycode names */
-
 /* Public functions */
 int
 SDL_KeyboardInit(void)
 {
-    int i;
-
     /* Set default mode of UNICODE translation */
     SDL_EnableUNICODE(DEFAULT_UNICODE_TRANSLATION);
 
-    /* Initialize the tables */
-    for (i = 0; i < SDL_arraysize(SDL_keynames); ++i) {
-        switch (i) {
-        case SDLK_BACKSPACE:
-            SDL_keynames[i] = "backspace";
-            break;
-        case SDLK_TAB:
-            SDL_keynames[i] = "tab";
-            break;
-        case SDLK_CLEAR:
-            SDL_keynames[i] = "clear";
-            break;
-        case SDLK_RETURN:
-            SDL_keynames[i] = "return";
-            break;
-        case SDLK_PAUSE:
-            SDL_keynames[i] = "pause";
-            break;
-        case SDLK_ESCAPE:
-            SDL_keynames[i] = "escape";
-            break;
-        case SDLK_SPACE:
-            SDL_keynames[i] = "space";
-            break;
-
-        case SDLK_KP0:
-            SDL_keynames[i] = "[0]";
-            break;
-        case SDLK_KP1:
-            SDL_keynames[i] = "[1]";
-            break;
-        case SDLK_KP2:
-            SDL_keynames[i] = "[2]";
-            break;
-        case SDLK_KP3:
-            SDL_keynames[i] = "[3]";
-            break;
-        case SDLK_KP4:
-            SDL_keynames[i] = "[4]";
-            break;
-        case SDLK_KP5:
-            SDL_keynames[i] = "[5]";
-            break;
-        case SDLK_KP6:
-            SDL_keynames[i] = "[6]";
-            break;
-        case SDLK_KP7:
-            SDL_keynames[i] = "[7]";
-            break;
-        case SDLK_KP8:
-            SDL_keynames[i] = "[8]";
-            break;
-        case SDLK_KP9:
-            SDL_keynames[i] = "[9]";
-            break;
-        case SDLK_KP_PERIOD:
-            SDL_keynames[i] = "[.]";
-            break;
-        case SDLK_KP_DIVIDE:
-            SDL_keynames[i] = "[/]";
-            break;
-        case SDLK_KP_MULTIPLY:
-            SDL_keynames[i] = "[*]";
-            break;
-        case SDLK_KP_MINUS:
-            SDL_keynames[i] = "[-]";
-            break;
-        case SDLK_KP_PLUS:
-            SDL_keynames[i] = "[+]";
-            break;
-        case SDLK_KP_ENTER:
-            SDL_keynames[i] = "enter";
-            break;
-        case SDLK_KP_EQUALS:
-            SDL_keynames[i] = "equals";
-            break;
-
-        case SDLK_UP:
-            SDL_keynames[i] = "up";
-            break;
-        case SDLK_DOWN:
-            SDL_keynames[i] = "down";
-            break;
-        case SDLK_RIGHT:
-            SDL_keynames[i] = "right";
-            break;
-        case SDLK_LEFT:
-            SDL_keynames[i] = "left";
-            break;
-        case SDLK_INSERT:
-            SDL_keynames[i] = "insert";
-            break;
-        case SDLK_HOME:
-            SDL_keynames[i] = "home";
-            break;
-        case SDLK_END:
-            SDL_keynames[i] = "end";
-            break;
-        case SDLK_PAGEUP:
-            SDL_keynames[i] = "page up";
-            break;
-        case SDLK_PAGEDOWN:
-            SDL_keynames[i] = "page down";
-            break;
-
-        case SDLK_F1:
-            SDL_keynames[i] = "f1";
-            break;
-        case SDLK_F2:
-            SDL_keynames[i] = "f2";
-            break;
-        case SDLK_F3:
-            SDL_keynames[i] = "f3";
-            break;
-        case SDLK_F4:
-            SDL_keynames[i] = "f4";
-            break;
-        case SDLK_F5:
-            SDL_keynames[i] = "f5";
-            break;
-        case SDLK_F6:
-            SDL_keynames[i] = "f6";
-            break;
-        case SDLK_F7:
-            SDL_keynames[i] = "f7";
-            break;
-        case SDLK_F8:
-            SDL_keynames[i] = "f8";
-            break;
-        case SDLK_F9:
-            SDL_keynames[i] = "f9";
-            break;
-        case SDLK_F10:
-            SDL_keynames[i] = "f10";
-            break;
-        case SDLK_F11:
-            SDL_keynames[i] = "f11";
-            break;
-        case SDLK_F12:
-            SDL_keynames[i] = "f12";
-            break;
-        case SDLK_F13:
-            SDL_keynames[i] = "f13";
-            break;
-        case SDLK_F14:
-            SDL_keynames[i] = "f14";
-            break;
-        case SDLK_F15:
-            SDL_keynames[i] = "f15";
-            break;
-
-        case SDLK_NUMLOCK:
-            SDL_keynames[i] = "numlock";
-            break;
-        case SDLK_CAPSLOCK:
-            SDL_keynames[i] = "caps lock";
-            break;
-        case SDLK_SCROLLOCK:
-            SDL_keynames[i] = "scroll lock";
-            break;
-        case SDLK_RSHIFT:
-            SDL_keynames[i] = "right shift";
-            break;
-        case SDLK_LSHIFT:
-            SDL_keynames[i] = "left shift";
-            break;
-        case SDLK_RCTRL:
-            SDL_keynames[i] = "right ctrl";
-            break;
-        case SDLK_LCTRL:
-            SDL_keynames[i] = "left ctrl";
-            break;
-        case SDLK_RALT:
-            SDL_keynames[i] = "right alt";
-            break;
-        case SDLK_LALT:
-            SDL_keynames[i] = "left alt";
-            break;
-        case SDLK_RMETA:
-            SDL_keynames[i] = "right meta";
-            break;
-        case SDLK_LMETA:
-            SDL_keynames[i] = "left meta";
-            break;
-        case SDLK_LSUPER:
-            SDL_keynames[i] = "left super";     /* "Windows" keys */
-            break;
-        case SDLK_RSUPER:
-            SDL_keynames[i] = "right super";
-            break;
-        case SDLK_MODE:
-            SDL_keynames[i] = "alt gr";
-            break;
-        case SDLK_COMPOSE:
-            SDL_keynames[i] = "compose";
-            break;
-
-        case SDLK_HELP:
-            SDL_keynames[i] = "help";
-            break;
-        case SDLK_PRINT:
-            SDL_keynames[i] = "print screen";
-            break;
-        case SDLK_SYSREQ:
-            SDL_keynames[i] = "sys req";
-            break;
-        case SDLK_BREAK:
-            SDL_keynames[i] = "break";
-            break;
-        case SDLK_MENU:
-            SDL_keynames[i] = "menu";
-            break;
-        case SDLK_POWER:
-            SDL_keynames[i] = "power";
-            break;
-        case SDLK_EURO:
-            SDL_keynames[i] = "euro";
-            break;
-        case SDLK_UNDO:
-            SDL_keynames[i] = "undo";
-            break;
-
-        default:
-            SDL_keynames[i] = NULL;
-            break;
-        }
-    }
-
-    /* Done.  Whew. */
     return (0);
 }
 
@@ -338,7 +106,7 @@ void
 SDL_ResetKeyboard(int index)
 {
     SDL_Keyboard *keyboard = SDL_GetKeyboard(index);
-    SDLKey key;
+    int key;
 
     if (!keyboard) {
         return;
@@ -346,7 +114,8 @@ SDL_ResetKeyboard(int index)
 
     for (key = SDLK_FIRST; key < SDLK_LAST; ++key) {
         if (keyboard->keystate[key] == SDL_PRESSED) {
-            SDL_SendKeyboardKey(index, SDL_RELEASED, 0, key);
+            SDL_SendKeyboardKey(index, SDL_RELEASED, 0,
+                                key | SDL_KEY_CAN_BE_PHYSICAL_BIT);
         }
     }
 }
@@ -432,35 +201,80 @@ SDL_SetModState(SDLMod modstate)
     keyboard->modstate = modstate;
 }
 
-const char *
-SDL_GetKeyName(SDLKey key)
+SDLKey
+SDL_GetLayoutKey(SDLKey physicalKey)
 {
-    const char *keyname;
+    SDL_VideoDevice *_this = SDL_GetVideoDevice();
+    if (_this && _this->GetLayoutKey) {
+        return _this->GetLayoutKey(_this, physicalKey)
+            | (physicalKey & SDL_KEY_KEYPAD_BIT);
+    } else {
+        return physicalKey;
+    }
+}
 
-    if (key < SDL_arraysize(SDL_keynames)) {
-        keyname = SDL_keynames[key];
+const char *
+SDL_GetKeyName(SDLKey layoutKey)
+{
+    const char *keyname = NULL;
+
+    if ((layoutKey & SDL_KEY_LAYOUT_SPECIAL_BIT) != 0) {
+        SDL_VideoDevice *_this = SDL_GetVideoDevice();
+        if (_this && _this->GetSpecialKeyName) {
+            keyname = _this->GetSpecialKeyName(_this, layoutKey);
+        }
+    } else if ((layoutKey & SDL_KEY_CAN_BE_PHYSICAL_BIT) == 0) {
+        /* SDLK_INDEX(layoutKey) is the unicode code point of the character generated by the key */
+        static char buffer[9];  /* 6 (maximal UTF-8 char length) + 2 ([] for keypad) + 1 (null teminator) */
+        char *bufferPtr = &buffer[1];
+        SDL_iconv_t cd;
+        size_t inbytesleft = 4, outbytesleft = 8;
+        Uint32 codepoint = SDLK_INDEX(layoutKey);
+        const char *codepointPtr = (const char *) &codepoint;
+
+        /* Unaccented letter keys on latin keyboards are normally labeled in upper case (and probably on others like Greek or Cyrillic too, so if you happen to know for sure, please adapt this). */
+        if (codepoint >= 'a' && codepoint <= 'z') {
+            codepoint -= 32;
+        }
+
+        cd = SDL_iconv_open("UTF-8", "UCS-4");
+        if (cd == (SDL_iconv_t) (-1))
+            return "";
+        SDL_iconv(cd, &codepointPtr, &inbytesleft, &bufferPtr, &outbytesleft);
+        SDL_iconv_close(cd);
+        *bufferPtr = '\0';
+
+        if ((layoutKey & SDL_KEY_KEYPAD_BIT) != 0) {
+            buffer[0] = '[';
+            *bufferPtr++ = ']';
+            *bufferPtr = '\0';
+            keyname = buffer;
         } else {
-        keyname = NULL;
+            keyname = &buffer[1];
         }
-    if (keyname == NULL) {
-        if (key < 256) {
-            static char temp[4];
-            char *cvt;
-            temp[0] = (char) key;
-            temp[1] = '\0';
-            cvt = SDL_iconv_string("UTF-8", "ISO-8859-1", temp, 1);
-            if (cvt) {
-                SDL_strlcpy(temp, cvt, SDL_arraysize(temp));
-                SDL_free(cvt);
-            }
-            keyname = temp;
     } else {
-            keyname = "unknown key";
+        /* SDLK_INDEX(layoutKey) is a physical key number */
+        if (SDLK_INDEX(layoutKey) < SDL_arraysize(SDL_keynames)) {
+            keyname = SDL_keynames[SDLK_INDEX(layoutKey)];
         }
     }
+
+    if (keyname == NULL) {
+        keyname = SDL_keynames[SDLK_INDEX(SDLK_UNKNOWN)];
+    }
+
     return keyname;
 }
 
+void
+SDL_SetKeyName(SDLKey physicalKey, const char *name)
+{
+    physicalKey = SDLK_INDEX(physicalKey);
+    if (physicalKey < SDL_arraysize(SDL_keynames)) {
+        SDL_keynames[physicalKey] = name;
+    }
+}
+
 void
 SDL_SetKeyboardFocus(int index, SDL_WindowID windowID)
 {
@@ -513,26 +327,27 @@ SDL_SetKeyboardFocus(int index, SDL_WindowID windowID)
 }
 
 int
-SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode, SDLKey key)
+SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode,
+                    SDLKey physicalKey)
 {
     SDL_Keyboard *keyboard = SDL_GetKeyboard(index);
     int posted;
     Uint16 modstate;
     Uint8 type;
 
-    if (!keyboard) {
+    if (!keyboard || physicalKey == SDLK_NONE) {
         return 0;
     }
 #if 0
-    printf("The '%s' key has been %s\n", SDL_GetKeyName(key),
+    printf("The '%s' key has been %s\n", SDL_GetKeyName(physicalKey),
            state == SDL_PRESSED ? "pressed" : "released");
 #endif
     if (state == SDL_PRESSED) {
         modstate = keyboard->modstate;
-        switch (key) {
+        switch (physicalKey) {
         case SDLK_UNKNOWN:
             break;
-        case SDLK_NUMLOCK:
+        case SDLK_KP_NUMLOCKCLEAR:
             keyboard->modstate ^= KMOD_NUM;
             break;
         case SDLK_CAPSLOCK:
@@ -569,10 +384,10 @@ SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode, SDLKey key)
             break;
         }
     } else {
-        switch (key) {
+        switch (physicalKey) {
         case SDLK_UNKNOWN:
             break;
-        case SDLK_NUMLOCK:
+        case SDLK_KP_NUMLOCKCLEAR:
         case SDLK_CAPSLOCK:
             break;
         case SDLK_LCTRL:
@@ -621,9 +436,9 @@ SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode, SDLKey key)
         return 0;
     }
 
-    if (key != SDLK_UNKNOWN) {
+    if (physicalKey != SDLK_UNKNOWN) {
         /* Drop events that don't change state */
-        if (keyboard->keystate[key] == state) {
+        if (keyboard->keystate[SDLK_INDEX(physicalKey)] == state) {
 #if 0
             printf("Keyboard event didn't change state - dropped!\n");
 #endif
@@ -631,7 +446,7 @@ SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode, SDLKey key)
         }
 
         /* Update internal keyboard state */
-        keyboard->keystate[key] = state;
+        keyboard->keystate[SDLK_INDEX(physicalKey)] = state;
     }
 
     /* Post the event, if desired */
@@ -642,7 +457,7 @@ SDL_SendKeyboardKey(int index, Uint8 state, Uint8 scancode, SDLKey key)
         event.key.which = (Uint8) index;
         event.key.state = state;
         event.key.keysym.scancode = scancode;
-        event.key.keysym.sym = (Uint16) key;
+        event.key.keysym.sym = physicalKey;
         event.key.keysym.mod = modstate;
         event.key.keysym.unicode = 0;
         event.key.windowID = keyboard->focus;

src/events/SDL_keyboard_c.h

@@ -65,6 +65,12 @@ extern void SDL_DelKeyboard(int index);
 /* Clear the state of a keyboard at an index */
 extern void SDL_ResetKeyboard(int index);
 
+/* Set a platform-dependent key name, overriding the default platform-agnostic
+   name. Encoded as UTF-8. The string is not copied, thus the pointer given to
+   this function must stay valid forever (or at least until the call to
+   VideoQuit()). */
+extern void SDL_SetKeyName(SDLKey physicalKey, const char *name);
+
 /* Set the keyboard focus window */
 extern void SDL_SetKeyboardFocus(int index, SDL_WindowID windowID);
 

src/video/SDL_sysvideo.h

@@ -25,6 +25,7 @@
 #define _SDL_sysvideo_h
 
 #include "SDL_mouse.h"
+#include "SDL_keysym.h"
 
 /* The SDL video driver */
 
@@ -256,6 +257,45 @@ struct SDL_VideoDevice
      */
     void (*PumpEvents) (_THIS);
 
+    /* Get the layout key code corresponding to the given physical key code
+     * according to the OS' current keyboard layout.
+     *
+     * - For character keys, this should return the Unicode code point of the
+     * character that is generated when the key is pressed without shift or
+     * any other modifiers.
+     * - For non-character keys, this should return one of the SDLK_* constants
+     * (usually the argument itself since these keys are typically layout-
+     * independent). Make sure that all of these values returned by this
+     * function have a suitable name defined, either the default from
+     * SDL_keynames.h, or one set using SDL_SetKeyName() in VideoInit(). In
+     * particular, if this function can return any of the codes whose default
+     * names start with "SDLK_" (usually, it shouldn't, since these are layout-
+     * dependent character keys), these names should be replaced by proper
+     * user-readable names.
+     * - If there are keys that cannot be adequately described by either a
+     * single Unicode character or an SDLK_* constant, this function may return
+     * a code with SDL_KEY_LAYOUT_SPECIAL_BIT set in the most significant byte
+     * and an arbitrary value in the less significant 3 bytes. The
+     * GetSpecialKeyName() function must then be implemented to take this code
+     * and return a human-readable key name for it.
+     * If the argument is not a physical key code or if translation of the key
+     * code by the OS' keyboard layout fails for any reason, the argument must
+     * be returned unchanged.
+     *
+     * On platforms that don't have the notion of a user-configurable keyboard
+     * layout, this may be left unimplemented. The default implementation of
+     * SDL_GetLayoutKey() then acts as the identity. The note about defining
+     * key names above particularly applies in this case.
+     */
+      SDLKey(*GetLayoutKey) (_THIS, SDLKey physicalKey);
+
+    /* Get a human-readable name for a special layout key code.
+     * This only needs to be implemented if this driver's implementation of
+     * GetLayoutKey() generates such codes (with SDL_KEY_LAYOUT_SPECIAL_BIT
+     * set) - see above.
+     */
+    const char *(*GetSpecialKeyName) (_THIS, SDLKey layoutKey);
+
     /* * * */
     /* Data common to all drivers */
     int num_displays;

src/video/cocoa/SDL_cocoakeyboard.h

@@ -26,6 +26,7 @@
 
 extern void Cocoa_InitKeyboard(_THIS);
 extern void Cocoa_HandleKeyEvent(_THIS, NSEvent * event);
+extern SDLKey Cocoa_GetLayoutKey(_THIS, SDLKey physicalKey);
 extern void Cocoa_QuitKeyboard(_THIS);
 
 #endif /* _SDL_cocoakeyboard_h */

src/video/cocoa/SDL_cocoakeyboard.m

@@ -26,6 +26,8 @@
 
 #include "../../events/SDL_keyboard_c.h"
 
+#include <Carbon/Carbon.h>
+
 
 #ifndef NX_DEVICERCTLKEYMASK
     #define NX_DEVICELCTLKEYMASK    0x00000001
@@ -52,192 +54,6 @@
     #define NX_DEVICERCTLKEYMASK    0x00002000
 #endif
 
-static void
-InitKeymap (SDLKey *keymap)
-{
-    const void *KCHRPtr;
-    UInt32 state;
-    UInt32 value;
-    int i;
-
-    for ( i=0; i<256; ++i )
-        keymap[i] = SDLK_UNKNOWN;
-
-    /* This keymap is almost exactly the same as the OS 9 one */
-    keymap[KEY_ESCAPE] = SDLK_ESCAPE;
-    keymap[KEY_F1] = SDLK_F1;
-    keymap[KEY_F2] = SDLK_F2;
-    keymap[KEY_F3] = SDLK_F3;
-    keymap[KEY_F4] = SDLK_F4;
-    keymap[KEY_F5] = SDLK_F5;
-    keymap[KEY_F6] = SDLK_F6;
-    keymap[KEY_F7] = SDLK_F7;
-    keymap[KEY_F8] = SDLK_F8;
-    keymap[KEY_F9] = SDLK_F9;
-    keymap[KEY_F10] = SDLK_F10;
-    keymap[KEY_F11] = SDLK_F11;
-    keymap[KEY_F12] = SDLK_F12;
-    keymap[KEY_F13] = SDLK_F13;
-    keymap[KEY_F14] = SDLK_F14;
-    keymap[KEY_F15] = SDLK_F15;
-/*
-    keymap[KEY_PRINT] = SDLK_PRINT;
-    keymap[KEY_SCROLLOCK] = SDLK_SCROLLOCK;
-    keymap[KEY_PAUSE] = SDLK_PAUSE;
-*/
-    keymap[KEY_POWER] = SDLK_POWER;
-    keymap[KEY_BACKQUOTE] = SDLK_BACKQUOTE;
-    keymap[KEY_1] = SDLK_1;
-    keymap[KEY_2] = SDLK_2;
-    keymap[KEY_3] = SDLK_3;
-    keymap[KEY_4] = SDLK_4;
-    keymap[KEY_5] = SDLK_5;
-    keymap[KEY_6] = SDLK_6;
-    keymap[KEY_7] = SDLK_7;
-    keymap[KEY_8] = SDLK_8;
-    keymap[KEY_9] = SDLK_9;
-    keymap[KEY_0] = SDLK_0;
-    keymap[KEY_MINUS] = SDLK_MINUS;
-    keymap[KEY_EQUALS] = SDLK_EQUALS;
-    keymap[KEY_BACKSPACE] = SDLK_BACKSPACE;
-    keymap[KEY_INSERT] = SDLK_INSERT;
-    keymap[KEY_HOME] = SDLK_HOME;
-    keymap[KEY_PAGEUP] = SDLK_PAGEUP;
-    keymap[KEY_NUMLOCK] = SDLK_NUMLOCK;
-    keymap[KEY_KP_EQUALS] = SDLK_KP_EQUALS;
-    keymap[KEY_KP_DIVIDE] = SDLK_KP_DIVIDE;
-    keymap[KEY_KP_MULTIPLY] = SDLK_KP_MULTIPLY;
-    keymap[KEY_TAB] = SDLK_TAB;
-    keymap[KEY_q] = SDLK_q;
-    keymap[KEY_w] = SDLK_w;
-    keymap[KEY_e] = SDLK_e;
-    keymap[KEY_r] = SDLK_r;
-    keymap[KEY_t] = SDLK_t;
-    keymap[KEY_y] = SDLK_y;
-    keymap[KEY_u] = SDLK_u;
-    keymap[KEY_i] = SDLK_i;
-    keymap[KEY_o] = SDLK_o;
-    keymap[KEY_p] = SDLK_p;
-    keymap[KEY_LEFTBRACKET] = SDLK_LEFTBRACKET;
-    keymap[KEY_RIGHTBRACKET] = SDLK_RIGHTBRACKET;
-    keymap[KEY_BACKSLASH] = SDLK_BACKSLASH;
-    keymap[KEY_DELETE] = SDLK_DELETE;
-    keymap[KEY_END] = SDLK_END;
-    keymap[KEY_PAGEDOWN] = SDLK_PAGEDOWN;
-    keymap[KEY_KP7] = SDLK_KP7;
-    keymap[KEY_KP8] = SDLK_KP8;
-    keymap[KEY_KP9] = SDLK_KP9;
-    keymap[KEY_KP_MINUS] = SDLK_KP_MINUS;
-    keymap[KEY_CAPSLOCK] = SDLK_CAPSLOCK;
-    keymap[KEY_a] = SDLK_a;
-    keymap[KEY_s] = SDLK_s;
-    keymap[KEY_d] = SDLK_d;
-    keymap[KEY_f] = SDLK_f;
-    keymap[KEY_g] = SDLK_g;
-    keymap[KEY_h] = SDLK_h;
-    keymap[KEY_j] = SDLK_j;
-    keymap[KEY_k] = SDLK_k;
-    keymap[KEY_l] = SDLK_l;
-    keymap[KEY_SEMICOLON] = SDLK_SEMICOLON;
-    keymap[KEY_QUOTE] = SDLK_QUOTE;
-    keymap[KEY_RETURN] = SDLK_RETURN;
-    keymap[KEY_KP4] = SDLK_KP4;
-    keymap[KEY_KP5] = SDLK_KP5;
-    keymap[KEY_KP6] = SDLK_KP6;
-    keymap[KEY_KP_PLUS] = SDLK_KP_PLUS;
-    keymap[KEY_LSHIFT] = SDLK_LSHIFT;
-    keymap[KEY_RSHIFT] = SDLK_RSHIFT;
-    keymap[KEY_z] = SDLK_z;
-    keymap[KEY_x] = SDLK_x;
-    keymap[KEY_c] = SDLK_c;
-    keymap[KEY_v] = SDLK_v;
-    keymap[KEY_b] = SDLK_b;
-    keymap[KEY_n] = SDLK_n;
-    keymap[KEY_m] = SDLK_m;
-    keymap[KEY_COMMA] = SDLK_COMMA;
-    keymap[KEY_PERIOD] = SDLK_PERIOD;
-    keymap[KEY_SLASH] = SDLK_SLASH;
-    keymap[KEY_UP] = SDLK_UP;
-    keymap[KEY_KP1] = SDLK_KP1;
-    keymap[KEY_KP2] = SDLK_KP2;
-    keymap[KEY_KP3] = SDLK_KP3;
-    keymap[KEY_KP_ENTER] = SDLK_KP_ENTER;
-    keymap[KEY_LCTRL] = SDLK_LCTRL;
-    keymap[KEY_LALT] = SDLK_LALT;
-    keymap[KEY_LMETA] = SDLK_LMETA;
-    keymap[KEY_RCTRL] = SDLK_RCTRL;
-    keymap[KEY_RALT] = SDLK_RALT;
-    keymap[KEY_RMETA] = SDLK_RMETA;
-    keymap[KEY_SPACE] = SDLK_SPACE;
-    keymap[KEY_LEFT] = SDLK_LEFT;
-    keymap[KEY_DOWN] = SDLK_DOWN;
-    keymap[KEY_RIGHT] = SDLK_RIGHT;
-    keymap[KEY_KP0] = SDLK_KP0;
-    keymap[KEY_KP_PERIOD] = SDLK_KP_PERIOD;
-    keymap[KEY_IBOOK_ENTER] = SDLK_KP_ENTER;
-    keymap[KEY_IBOOK_RIGHT] = SDLK_RIGHT;
-    keymap[KEY_IBOOK_DOWN] = SDLK_DOWN;
-    keymap[KEY_IBOOK_UP]      = SDLK_UP;
-    keymap[KEY_IBOOK_LEFT] = SDLK_LEFT;
-
-    /* 
-        Up there we setup a static scancode->keysym map. However, it will not
-        work very well on international keyboard. Hence we now query Mac OS X
-        for its own keymap to adjust our own mapping table. However, this is
-        basically only useful for ascii char keys. This is also the reason
-        why we keep the static table, too.
-     */
-
-    /* Get a pointer to the systems cached KCHR */
-    KCHRPtr = (void *)GetScriptManagerVariable(smKCHRCache);
-    if (KCHRPtr) {
-        /* Loop over all 127 possible scan codes */
-        for (i = 0; i < 0x7F; i++) {
-            /* We pretend a clean start to begin with (i.e. no dead keys active */
-            state = 0;
-
-            /* Now translate the key code to a key value */
-            value = KeyTranslate(KCHRPtr, i, &state) & 0xff;
-
-            /* If the state become 0, it was a dead key. We need to translate again,
-                passing in the new state, to get the actual key value */
-            if (state != 0)
-                value = KeyTranslate(KCHRPtr, i, &state) & 0xff;
-
-            /* Now we should have a latin1 value, which are SDL keysyms */
-            if (value >= 32 && value <= 255) {
-                keymap[i] = value;
-            }
-        }
-    }
-
-    /* 
-        The keypad codes are re-setup here, because the loop above cannot
-        distinguish between a key on the keypad and a regular key. We maybe
-        could get around this problem in another fashion: NSEvent's flags
-        include a "NSNumericPadKeyMask" bit; we could check that and modify
-        the symbol we return on the fly. However, this flag seems to exhibit
-        some weird behaviour related to the num lock key
-    */
-    keymap[KEY_KP0] = SDLK_KP0;
-    keymap[KEY_KP1] = SDLK_KP1;
-    keymap[KEY_KP2] = SDLK_KP2;
-    keymap[KEY_KP3] = SDLK_KP3;
-    keymap[KEY_KP4] = SDLK_KP4;
-    keymap[KEY_KP5] = SDLK_KP5;
-    keymap[KEY_KP6] = SDLK_KP6;
-    keymap[KEY_KP7] = SDLK_KP7;
-    keymap[KEY_KP8] = SDLK_KP8;
-    keymap[KEY_KP9] = SDLK_KP9;
-    keymap[KEY_KP_MINUS] = SDLK_KP_MINUS;
-    keymap[KEY_KP_PLUS] = SDLK_KP_PLUS;
-    keymap[KEY_KP_PERIOD] = SDLK_KP_PERIOD;
-    keymap[KEY_KP_EQUALS] = SDLK_KP_EQUALS;
-    keymap[KEY_KP_DIVIDE] = SDLK_KP_DIVIDE;
-    keymap[KEY_KP_MULTIPLY] = SDLK_KP_MULTIPLY;
-    keymap[KEY_KP_ENTER] = SDLK_KP_ENTER;
-}
-
 /* This is the original behavior, before support was added for 
  * differentiating between left and right versions of the keys.
  */
@@ -433,8 +249,8 @@ HandleCapsLock(int keyboard, unsigned short scancode,
     newMask = newMods & NSNumericPadKeyMask;
 
     if (oldMask != newMask) {
-        SDL_SendKeyboardKey(keyboard, SDL_PRESSED, (Uint8)scancode, SDLK_NUMLOCK);
-        SDL_SendKeyboardKey(keyboard, SDL_RELEASED, (Uint8)scancode, SDLK_NUMLOCK);
+        SDL_SendKeyboardKey(keyboard, SDL_PRESSED, (Uint8)scancode, SDLK_KP_NUMLOCKCLEAR);
+        SDL_SendKeyboardKey(keyboard, SDL_RELEASED, (Uint8)scancode, SDLK_KP_NUMLOCKCLEAR);
     }
 }
 
@@ -513,14 +329,19 @@ Cocoa_InitKeyboard(_THIS)
     SDL_Keyboard keyboard;
     NSAutoreleasePool *pool;
 
-    InitKeymap(data->keymap);
-
     pool = [[NSAutoreleasePool alloc] init];
     data->fieldEdit = [[NSTextView alloc] initWithFrame:NSMakeRect(0.0, 0.0, 0.0, 0.0)];
     [pool release];
     
     SDL_zero(keyboard);
     data->keyboard = SDL_AddKeyboard(&keyboard, -1);
+    
+    /* Set our own names for the platform-dependent but layout-independent keys */
+    SDL_SetKeyName(SDLK_KP_NUMLOCKCLEAR, "clear");
+    SDL_SetKeyName(SDLK_LALT, "left option");
+    SDL_SetKeyName(SDLK_LMETA, "left command");
+    SDL_SetKeyName(SDLK_RALT, "right option");
+    SDL_SetKeyName(SDLK_RMETA, "right command");
 }
 
 void
@@ -528,20 +349,33 @@ Cocoa_HandleKeyEvent(_THIS, NSEvent *event)
 {
     SDL_VideoData *data = (SDL_VideoData *) _this->driverdata;
     unsigned short scancode = [event keyCode];
+    SDLKey physicalKey;
     const char *text;
 
-    if (scancode >= 256) {
+    if ((scancode == 10 || scancode == 50) && KBGetLayoutType(LMGetKbdType()) == kKeyboardISO) {
+        /* see comments in SDL_cocoakeys.h */
+        scancode = 60 - scancode;
+    }
+    if (scancode < SDL_arraysize(macToSDLKey)) {
+        physicalKey = macToSDLKey[scancode];
+    }
+    else {
         /* Hmm, does this ever happen?  If so, need to extend the keymap... */
-        return;
+        physicalKey = SDLK_UNKNOWN;
     }
 
     switch ([event type]) {
     case NSKeyDown:
         if (![event isARepeat]) {
-            SDL_SendKeyboardKey(data->keyboard, SDL_PRESSED, (Uint8)scancode,
-                                data->keymap[scancode]);
+            SDL_SendKeyboardKey(data->keyboard, SDL_PRESSED, (Uint8)scancode, physicalKey);
+#if 1
+            if (physicalKey == SDLK_UNKNOWN) {
+                fprintf(stderr, "The key you just pressed is not recognized by SDL. To help get this fixed, report this to the SDL mailing list <sdl@libsdl.org> or to Christian Walther <cwalther@gmx.ch>. Mac virtual key code is %d.\n", scancode);
+            }
+#endif
         }
         if (SDL_EventState(SDL_TEXTINPUT, SDL_QUERY)) {
+            /* FIXME CW 2007-08-16: only send those events to the field editor for which we actually want text events, not e.g. esc or function keys. Arrow keys in particular seem to produce crashes sometimes. */
             [data->fieldEdit interpretKeyEvents:[NSArray arrayWithObject:event]];
             text = [[event characters] UTF8String];
             if(text && *text) {
@@ -550,12 +384,136 @@ Cocoa_HandleKeyEvent(_THIS, NSEvent *event)
         }
         break;
     case NSKeyUp:
-        SDL_SendKeyboardKey(data->keyboard, SDL_RELEASED, (Uint8)scancode,
-                            data->keymap[scancode]);
+        SDL_SendKeyboardKey(data->keyboard, SDL_RELEASED, (Uint8)scancode, physicalKey);
         break;
     case NSFlagsChanged:
+        /* FIXME CW 2007-08-14: check if this whole mess that takes up half of this file is really necessary */
         HandleModifiers(_this, scancode, [event modifierFlags]);
         break;
+    default: /* just to avoid compiler warnings */
+        break;
+    }
+}
+
+SDLKey
+Cocoa_GetLayoutKey(_THIS, SDLKey physicalKey)
+{
+    switch (physicalKey) {
+        /* Many of these keys would generate a character in the translation by keyboard layout, but an inappropriate one, so we catch them before. */
+        case SDLK_UNKNOWN:
+        case SDLK_RETURN:
+        case SDLK_ESCAPE:
+        case SDLK_BACKSPACE:
+        case SDLK_TAB:
+        case SDLK_SPACE:
+        case SDLK_CAPSLOCK:
+        case SDLK_F1:
+        case SDLK_F2:
+        case SDLK_F3:
+        case SDLK_F4:
+        case SDLK_F5:
+        case SDLK_F6:
+        case SDLK_F7:
+        case SDLK_F8:
+        case SDLK_F9:
+        case SDLK_F10:
+        case SDLK_F11:
+        case SDLK_F12:
+        case SDLK_PRINTSCREEN:
+        case SDLK_SCROLLLOCK:
+        case SDLK_PAUSE:
+        case SDLK_INSERT:
+        case SDLK_HOME:
+        case SDLK_PAGEUP:
+        case SDLK_DELETE:
+        case SDLK_END:
+        case SDLK_PAGEDOWN:
+        case SDLK_RIGHT:
+        case SDLK_LEFT:
+        case SDLK_DOWN:
+        case SDLK_UP:
+        case SDLK_KP_NUMLOCKCLEAR:
+        case SDLK_KP_ENTER:
+        case SDLK_APPLICATION:
+        case SDLK_POWER:
+        case SDLK_F13:
+        case SDLK_F14:
+        case SDLK_F15:
+        case SDLK_F16:
+        case SDLK_LCTRL:
+        case SDLK_LSHIFT:
+        case SDLK_LALT:
+        case SDLK_LMETA:
+        case SDLK_RCTRL:
+        case SDLK_RSHIFT:
+        case SDLK_RALT:
+        case SDLK_RMETA:
+            return physicalKey;
+        
+        /* For the rest, we try the translation first. */
+        default: {
+            UInt16 vkey = 0;
+            KeyboardLayoutRef layout;
+            KeyboardLayoutKind kind;
+            UInt32 keyboardType = LMGetKbdType();
+            
+            /* Look up pkey to get a Mac virtual key code - linear search isn't terribly efficient, this might have to be optimized. */
+            while (vkey < 128 && physicalKey != macToSDLKey[vkey]) vkey++;
+            if (vkey == 128) return physicalKey;
+            if ((vkey == 10 || vkey == 50) && KBGetLayoutType(keyboardType) == kKeyboardISO) vkey = 60 - vkey; /* see comments in SDL_cocoakeys.h */
+            
+            if (KLGetCurrentKeyboardLayout(&layout) != noErr) return physicalKey;
+            if (KLGetKeyboardLayoutProperty(layout, kKLKind, (const void **)&kind) != noErr) return physicalKey;
+            if (kind == kKLKCHRuchrKind || kind == kKLuchrKind) {
+                UniChar utf16String[4];
+                UInt32 deadKeyState = 0;
+                UniCharCount actualStringLength;
+                const UCKeyboardLayout *uchrData;
+                
+                if (KLGetKeyboardLayoutProperty(layout, kKLuchrData, (const void **)&uchrData) != noErr) return physicalKey;
+                if (UCKeyTranslate(uchrData, vkey, kUCKeyActionDisplay, 0, keyboardType, 0, &deadKeyState, 4, &actualStringLength, utf16String) != noErr) return physicalKey;
+                /* kUCKeyActionDisplay (instead of kUCKeyActionDown) seems to take care of dead keys, so no need to check for that case and simulate a second key press */
+                
+                if (actualStringLength == 0) return physicalKey;
+                
+                /* Decode the first character from UTF-16. I'm not sure if this is appropriate for keyboard layouts that generate more than 1 character, or if we would have to use SDL_KEY_LAYOUT_SPECIAL_BIT in that case. */
+                if (utf16String[0] < 0xD800 || utf16String[0] > 0xDFFF) {
+                    return utf16String[0];
+                }
+                else if (utf16String[0] > 0xDBFF || utf16String[1] < 0xDC00 || utf16String[1] > 0xDFFF) {
+                    /* invalid UTF-16 */
+                    return physicalKey;
+                }
+                else {
+                    return (((utf16String[0] & 0x3FF) << 10) | (utf16String[1] & 0x3FF)) + 0x10000;
+                }
+            }
+            else { /* kind == kKLKCHRKind */
+                const void *kchrData;
+                UInt32 state = 0;
+                UInt8 charCode;
+                SInt32 scriptCode;
+                TextEncoding keyboardEncoding;
+                CFStringRef conversionString;
+                UniChar codepoint;
+                
+                if (KLGetKeyboardLayoutProperty(layout, kKLKCHRData, &kchrData) != noErr) return physicalKey;
+                charCode = KeyTranslate(kchrData, vkey, &state) & 0xFF; /* Actually returns a UInt32 containing two character codes (and two 'reserved' bytes), but we're only interested in the second (or only) one */
+                if (charCode == 0) {
+                    /* It's a dead key, so simulate a second key press */
+                    charCode = KeyTranslate(kchrData, vkey, &state) & 0xFF;
+                    /* Still zero? Give up. */
+                    if (charCode == 0) return physicalKey;
+                }
+                if (KLGetKeyboardLayoutProperty(layout, kKLGroupIdentifier, (const void **)&scriptCode) != noErr) return physicalKey; /* That the group identifier is actually a script code is not documented, but confirmed here: <http://lists.apple.com/archives/carbon-dev/2005/Jan/msg00533.html> */
+                if (UpgradeScriptInfoToTextEncoding(scriptCode, kTextLanguageDontCare, kTextRegionDontCare, NULL, &keyboardEncoding) != noErr) return physicalKey;
+                
+                conversionString = CFStringCreateWithBytes(kCFAllocatorDefault, &charCode, 1, keyboardEncoding, FALSE);
+                codepoint = CFStringGetCharacterAtIndex(conversionString, 0);
+                CFRelease(conversionString);
+                return codepoint;
+            }
+        }
     }
 }
 

src/video/cocoa/SDL_cocoakeys.h

@@ -19,128 +19,142 @@
     Sam Lantinga
     slouken@libsdl.org
 */
-#include "SDL_config.h"
 
-/* These are the Macintosh key scancode constants -- from Inside Macintosh */
-
-#define KEY_ESCAPE		0x35
-#define KEY_F1			0x7A
-#define KEY_F2			0x78
-#define KEY_F3			0x63
-#define KEY_F4			0x76
-#define KEY_F5			0x60
-#define KEY_F6			0x61
-#define KEY_F7			0x62
-#define KEY_F8			0x64
-#define KEY_F9			0x65
-#define KEY_F10			0x6D
-#define KEY_F11			0x67
-#define KEY_F12			0x6F
-#define KEY_F13			0x69
-#define KEY_F14			0x6B
-#define KEY_F15			0x71
-/*
-#define KEY_PRINT		0x69
-#define KEY_SCROLLOCK    0x6B
-#define KEY_PAUSE		0x71
+/* Mac virtual key code to SDLKey mapping table
+   Sources:
+   - Inside Macintosh: Text <http://developer.apple.com/documentation/mac/Text/Text-571.html>
+   - Apple USB keyboard driver source <http://darwinsource.opendarwin.org/10.4.6.ppc/IOHIDFamily-172.8/IOHIDFamily/Cosmo_USB2ADB.c>
+   - experimentation on various ADB and USB ISO keyboards and one ADB ANSI keyboard
 */
-#define KEY_POWER		0x7F
-#define KEY_BACKQUOTE	0x32
-#define KEY_1			0x12
-#define KEY_2			0x13
-#define KEY_3			0x14
-#define KEY_4			0x15
-#define KEY_5			0x17
-#define KEY_6			0x16
-#define KEY_7			0x1A
-#define KEY_8			0x1C
-#define KEY_9			0x19
-#define KEY_0			0x1D
-#define KEY_MINUS		0x1B
-#define KEY_EQUALS		0x18
-#define KEY_BACKSPACE	0x33
-#define KEY_INSERT		0x72
-#define KEY_HOME			0x73
-#define KEY_PAGEUP		0x74
-#define KEY_NUMLOCK		0x47
-#define KEY_KP_EQUALS	0x51
-#define KEY_KP_DIVIDE	0x4B
-#define KEY_KP_MULTIPLY	0x43
-#define KEY_TAB			0x30
-#define KEY_q			0x0C
-#define KEY_w			0x0D
-#define KEY_e			0x0E
-#define KEY_r			0x0F
-#define KEY_t			0x11
-#define KEY_y			0x10
-#define KEY_u			0x20
-#define KEY_i			0x22
-#define KEY_o			0x1F
-#define KEY_p			0x23
-#define KEY_LEFTBRACKET	0x21
-#define KEY_RIGHTBRACKET	0x1E
-#define KEY_BACKSLASH	0x2A
-#define KEY_DELETE		0x75
-#define KEY_END			0x77
-#define KEY_PAGEDOWN		0x79
-#define KEY_KP7			0x59
-#define KEY_KP8			0x5B
-#define KEY_KP9			0x5C
-#define KEY_KP_MINUS		0x4E
-#define KEY_CAPSLOCK		0x39
-#define KEY_a			0x00
-#define KEY_s			0x01
-#define KEY_d			0x02
-#define KEY_f			0x03
-#define KEY_g			0x05
-#define KEY_h			0x04
-#define KEY_j			0x26
-#define KEY_k			0x28
-#define KEY_l			0x25
-#define KEY_SEMICOLON	0x29
-#define KEY_QUOTE		0x27
-#define KEY_RETURN		0x24
-#define KEY_KP4			0x56
-#define KEY_KP5			0x57
-#define KEY_KP6			0x58
-#define KEY_KP_PLUS		0x45
-#define KEY_LSHIFT		0x38
-#define KEY_z			0x06
-#define KEY_x			0x07
-#define KEY_c			0x08
-#define KEY_v			0x09
-#define KEY_b			0x0B
-#define KEY_n			0x2D
-#define KEY_m			0x2E
-#define KEY_COMMA		0x2B
-#define KEY_PERIOD		0x2F
-#define KEY_SLASH		0x2C
-#if 1                           /* Panther now defines right side keys */
-#define KEY_RSHIFT		0x3C
-#endif
-#define KEY_UP			0x7E
-#define KEY_KP1			0x53
-#define KEY_KP2			0x54
-#define KEY_KP3			0x55
-#define KEY_KP_ENTER		0x4C
-#define KEY_LCTRL		0x3B
-#define KEY_LALT			0x3A
-#define KEY_LMETA		0x37
-#define KEY_SPACE		0x31
-#if 1                           /* Panther now defines right side keys */
-#define KEY_RMETA		0x36
-#define KEY_RALT			0x3D
-#define KEY_RCTRL		0x3E
-#endif
-#define KEY_LEFT			0x7B
-#define KEY_DOWN			0x7D
-#define KEY_RIGHT		0x7C
-#define KEY_KP0			0x52
-#define KEY_KP_PERIOD	0x41
-
-/* Wierd, these keys are on my iBook under Mac OS X */
-#define KEY_IBOOK_ENTER		0x34
-#define KEY_IBOOK_LEFT		0x3B
-#define KEY_IBOOK_RIGHT		0x3C
-#define KEY_IBOOK_DOWN		0x3D
-#define KEY_IBOOK_UP			0x3E
+/* *INDENT-OFF* */
+static SDLKey macToSDLKey[128] = {
+    /*   0 */   SDLK_A,
+    /*   1 */   SDLK_S,
+    /*   2 */   SDLK_D,
+    /*   3 */   SDLK_F,
+    /*   4 */   SDLK_H,
+    /*   5 */   SDLK_G,
+    /*   6 */   SDLK_Z,
+    /*   7 */   SDLK_X,
+    /*   8 */   SDLK_C,
+    /*   9 */   SDLK_V,
+    /*  10 */   SDLK_NONUSBACKSLASH, /* SDLK_NONUSBACKSLASH on ANSI and JIS keyboards (if this key would exist there), SDLK_GRAVE on ISO. (The USB keyboard driver actually translates these usage codes to different virtual key codes depending on whether the keyboard is ISO/ANSI/JIS. That's why you have to help it identify the keyboard type when you plug in a PC USB keyboard. It's a historical thing - ADB keyboards are wired this way.) */
+    /*  11 */   SDLK_B,
+    /*  12 */   SDLK_Q,
+    /*  13 */   SDLK_W,
+    /*  14 */   SDLK_E,
+    /*  15 */   SDLK_R,
+    /*  16 */   SDLK_Y,
+    /*  17 */   SDLK_T,
+    /*  18 */   SDLK_1,
+    /*  19 */   SDLK_2,
+    /*  20 */   SDLK_3,
+    /*  21 */   SDLK_4,
+    /*  22 */   SDLK_6,
+    /*  23 */   SDLK_5,
+    /*  24 */   SDLK_EQUALS,
+    /*  25 */   SDLK_9,
+    /*  26 */   SDLK_7,
+    /*  27 */   SDLK_HYPHENMINUS,
+    /*  28 */   SDLK_8,
+    /*  29 */   SDLK_0,
+    /*  30 */   SDLK_RIGHTBRACKET,
+    /*  31 */   SDLK_O,
+    /*  32 */   SDLK_U,
+    /*  33 */   SDLK_LEFTBRACKET,
+    /*  34 */   SDLK_I,
+    /*  35 */   SDLK_P,
+    /*  36 */   SDLK_RETURN,
+    /*  37 */   SDLK_L,
+    /*  38 */   SDLK_J,
+    /*  39 */   SDLK_APOSTROPHE,
+    /*  40 */   SDLK_K,
+    /*  41 */   SDLK_SEMICOLON,
+    /*  42 */   SDLK_BACKSLASH,
+    /*  43 */   SDLK_COMMA,
+    /*  44 */   SDLK_SLASH,
+    /*  45 */   SDLK_N,
+    /*  46 */   SDLK_M,
+    /*  47 */   SDLK_PERIOD,
+    /*  48 */   SDLK_TAB,
+    /*  49 */   SDLK_SPACE,
+    /*  50 */   SDLK_GRAVE, /* SDLK_GRAVE on ANSI and JIS keyboards, SDLK_NONUSBACKSLASH on ISO (see comment about virtual key code 10 above) */
+    /*  51 */   SDLK_BACKSPACE,
+    /*  52 */   SDLK_KP_ENTER, /* keyboard enter on portables */
+    /*  53 */   SDLK_ESCAPE,
+    /*  54 */   SDLK_RMETA,
+    /*  55 */   SDLK_LMETA,
+    /*  56 */   SDLK_LSHIFT,
+    /*  57 */   SDLK_CAPSLOCK,
+    /*  58 */   SDLK_LALT,
+    /*  59 */   SDLK_LCTRL,
+    /*  60 */   SDLK_RSHIFT,
+    /*  61 */   SDLK_RALT,
+    /*  62 */   SDLK_RCTRL,
+    /*  63 */   SDLK_NONE, /* fn on portables, acts as a hardware-level modifier already, so we don't generate events for it */
+    /*  64 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  65 */   SDLK_KP_PERIOD,
+    /*  66 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  67 */   SDLK_KP_MULTIPLY,
+    /*  68 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  69 */   SDLK_KP_PLUS,
+    /*  70 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  71 */   SDLK_KP_NUMLOCKCLEAR,
+    /*  72 */   SDLK_VOLUMEUP,
+    /*  73 */   SDLK_VOLUMEDOWN,
+    /*  74 */   SDLK_MUTE,
+    /*  75 */   SDLK_KP_DIVIDE,
+    /*  76 */   SDLK_KP_ENTER, /* keypad enter on external keyboards, fn-return on portables */
+    /*  77 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  78 */   SDLK_KP_MINUS,
+    /*  79 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  80 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  81 */   SDLK_KP_EQUALS,
+    /*  82 */   SDLK_KP_0,
+    /*  83 */   SDLK_KP_1,
+    /*  84 */   SDLK_KP_2,
+    /*  85 */   SDLK_KP_3,
+    /*  86 */   SDLK_KP_4,
+    /*  87 */   SDLK_KP_5,
+    /*  88 */   SDLK_KP_6,
+    /*  89 */   SDLK_KP_7,
+    /*  90 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /*  91 */   SDLK_KP_8,
+    /*  92 */   SDLK_KP_9,
+    /*  93 */   SDLK_INTERNATIONAL3, /* Cosmo_USB2ADB.c says "Yen (JIS)" */
+    /*  94 */   SDLK_INTERNATIONAL1, /* Cosmo_USB2ADB.c says "Ro (JIS)" */
+    /*  95 */   SDLK_KP_COMMA, /* Cosmo_USB2ADB.c says ", JIS only" */
+    /*  96 */   SDLK_F5,
+    /*  97 */   SDLK_F6,
+    /*  98 */   SDLK_F7,
+    /*  99 */   SDLK_F3,
+    /* 100 */   SDLK_F8,
+    /* 101 */   SDLK_F9,
+    /* 102 */   SDLK_LANG2, /* Cosmo_USB2ADB.c says "Eisu" */
+    /* 103 */   SDLK_F11,
+    /* 104 */   SDLK_LANG1, /* Cosmo_USB2ADB.c says "Kana" */
+    /* 105 */   SDLK_PRINTSCREEN, /* On ADB keyboards, this key is labeled "F13/print screen". Problem: USB has different usage codes for these two functions. On Apple USB keyboards, the key is labeled "F13" and sends the F13 usage code (SDLK_F13). I decided to use SDLK_PRINTSCREEN here nevertheless since SDL applications are more likely to assume the presence of a print screen key than an F13 key. */
+    /* 106 */   SDLK_F16,
+    /* 107 */   SDLK_SCROLLLOCK, /* F14/scroll lock, see comment about F13/print screen above */
+    /* 108 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /* 109 */   SDLK_F10,
+    /* 110 */   SDLK_APPLICATION, /* windows contextual menu key, fn-enter on portables */
+    /* 111 */   SDLK_F12,
+    /* 112 */   SDLK_UNKNOWN, /* unknown (unused?) */
+    /* 113 */   SDLK_PAUSE, /* F15/pause, see comment about F13/print screen above */
+    /* 114 */   SDLK_INSERT, /* the key is actually labeled "help" on Apple keyboards, and works as such in Mac OS, but it sends the "insert" usage code even on Apple USB keyboards */
+    /* 115 */   SDLK_HOME,
+    /* 116 */   SDLK_PAGEUP,
+    /* 117 */   SDLK_DELETE,
+    /* 118 */   SDLK_F4,
+    /* 119 */   SDLK_END,
+    /* 120 */   SDLK_F2,
+    /* 121 */   SDLK_PAGEDOWN,
+    /* 122 */   SDLK_F1,
+    /* 123 */   SDLK_LEFT,
+    /* 124 */   SDLK_RIGHT,
+    /* 125 */   SDLK_DOWN,
+    /* 126 */   SDLK_UP,
+    /* 127 */   SDLK_POWER
+};
+/* *INDENT-ON* */

src/video/cocoa/SDL_cocoavideo.h

@@ -42,7 +42,6 @@
 typedef struct SDL_VideoData
 {
     SInt32 osversion;
-    SDLKey keymap[256];
     unsigned int modifierFlags;
     int mouse;
     int keyboard;

src/video/cocoa/SDL_cocoavideo.m

@@ -75,6 +75,7 @@ Cocoa_CreateDevice(int devindex)
     device->GetDisplayModes = Cocoa_GetDisplayModes;
     device->SetDisplayMode = Cocoa_SetDisplayMode;
     device->PumpEvents = Cocoa_PumpEvents;
+    device->GetLayoutKey = Cocoa_GetLayoutKey;
 
     device->CreateWindow = Cocoa_CreateWindow;
     device->CreateWindowFrom = Cocoa_CreateWindowFrom;

test/common.c

@@ -803,14 +803,20 @@ PrintEvent(SDL_Event * event)
         }
         break;
     case SDL_KEYDOWN:
-        fprintf(stderr, "Keyboard %d: key %s pressed in window %d",
-                event->key.which, SDL_GetKeyName(event->key.keysym.sym),
-                event->key.windowID);
+        fprintf(stderr,
+                "Keyboard %d: key pressed  in window %d: physical 0x%08X = %s, layout 0x%08X = %s",
+                event->key.which, event->key.windowID, event->key.keysym.sym,
+                SDL_GetKeyName(event->key.keysym.sym),
+                SDL_GetLayoutKey(event->key.keysym.sym),
+                SDL_GetKeyName(SDL_GetLayoutKey(event->key.keysym.sym)));
         break;
     case SDL_KEYUP:
-        fprintf(stderr, "Keyboard %d: key %s released in window %d",
-                event->key.which, SDL_GetKeyName(event->key.keysym.sym),
-                event->key.windowID);
+        fprintf(stderr,
+                "Keyboard %d: key released in window %d: physical 0x%08X = %s, layout 0x%08X = %s",
+                event->key.which, event->key.windowID, event->key.keysym.sym,
+                SDL_GetKeyName(event->key.keysym.sym),
+                SDL_GetLayoutKey(event->key.keysym.sym),
+                SDL_GetKeyName(SDL_GetLayoutKey(event->key.keysym.sym)));
         break;
     case SDL_TEXTINPUT:
         fprintf(stderr, "Keyboard %d: text input \"%s\" in window %d",