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

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 the name of an SDL virtual keysym
+ * \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.
+ *
+ * \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++ */