Cleanup

Clean up code and documentation for glfwGetKeyScancode and add
implementation for Wayland and Mir.

Related to #830.

README.md

@@ -100,7 +100,7 @@ information on what to include when reporting a bug.
 ## Changelog
 
 - Added `glfwGetKeyScancode` function that allows retrieving platform depen-
-  dent scancodes for keys
+  dent scancodes for keys (#830)
 - Bugfix: Calling `glfwMaximizeWindow` on a full screen window was not ignored
 
 
@@ -222,6 +222,7 @@ skills.
  - Patrick Snape
  - Julian Squires
  - Johannes Stein
+ - Michael Stocker
  - Justin Stoecker
  - Elviss Strazdins
  - Nathan Sweet
@@ -245,7 +246,6 @@ skills.
  - Santi Zupancic
  - Jonas Ådahl
  - Lasse Öörni
- - Michael Stocker
  - All the unmentioned and anonymous contributors in the GLFW community, for bug
    reports, patches, feedback, testing and encouragement
 

docs/input.dox

@@ -225,16 +225,13 @@ arguments can always be passed unmodified to this function.
 
 @subsection input_key_scancode Key scancodes
 
-If you need the platform dependent scancode for any given key, you can query
-it with @ref glfwGetKeyScancode.
+If you need the platform dependent scancode for a [named key](@ref keys), you
+can query it with @ref glfwGetKeyScancode.
 
 @code
-const short int scancode = glfwGetKeyScancode(GLFW_KEY_X);
+const int scancode = glfwGetKeyScancode(GLFW_KEY_X);
 set_key_mapping(scancode, swap_weapons);
-@encode
-
-If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
-method will return `-1`.
+@endcode
 
 
 @section input_mouse Mouse input

docs/news.dox

@@ -5,7 +5,7 @@
 @section news_33 New features in 3.3
 
 
-@subsection new_33_keyscancode Platform dependent scancodes
+@subsection news_33_keyscancode Platform-specific key scancode query
 
 GLFW now supports querying the platform dependent scancode of any key with
 @ref glfwGetKeyScancode.

include/GLFW/glfw3.h

@@ -3012,10 +3012,11 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
  *  method will return `-1`.
  *
  *  @param[in] key The key to query.
- *  @return The platform dependent scancode for the key, or `-1`.
+ *  @return The platform dependent scancode for the key, or `-1` if an
+ *  [error](@ref error_handling) occurred.
  *
- *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
- *  GLFW_PLATFORM_ERROR.
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
+ *  GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
  *
  *  @thread_safety This function may be called from any thread.
  *
@@ -3025,7 +3026,7 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
  *
  *  @ingroup input
  */
-GLFWAPI const short int glfwGetKeyScancode(int key);
+GLFWAPI int glfwGetKeyScancode(int key);
 
 /*! @brief Returns the last reported state of a keyboard key for the specified
  *  window.

src/cocoa_window.m

@@ -1511,13 +1511,8 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.ns.keyName;
 }
 
-const short int _glfwPlatformGetKeyScancode(int key)
+int _glfwPlatformGetKeyScancode(int key)
 {
-    if(key <= -1 || key >= (sizeof(_glfw.ns.nativeKeys) / sizeof(_glfw.ns.nativeKeys[0])))
-    {
-        return -1;
-    }
-
     return _glfw.ns.nativeKeys[key];
 }
 

src/input.c

@@ -256,9 +256,16 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode)
     return _glfwPlatformGetKeyName(key, scancode);
 }
 
-GLFWAPI const short int glfwGetKeyScancode(int key)
+GLFWAPI int glfwGetKeyScancode(int key)
 {
     _GLFW_REQUIRE_INIT_OR_RETURN(-1);
+
+    if (key < GLFW_KEY_SPACE || key > GLFW_KEY_LAST)
+    {
+        _glfwInputError(GLFW_INVALID_ENUM, "Invalid key %i", key);
+        return GLFW_RELEASE;
+    }
+
     return _glfwPlatformGetKeyScancode(key);
 }
 

src/internal.h

@@ -545,7 +545,7 @@ const char* _glfwPlatformGetKeyName(int key, int scancode);
 /*! @copydoc glfwGetKeyScancode
  *  @ingroup platform
  */
-const short int _glfwPlatformGetKeyScancode(int key);
+int _glfwPlatformGetKeyScancode(int key);
 
 /*! @copydoc glfwGetMonitors
  *  @ingroup platform

src/mir_window.c

@@ -744,11 +744,9 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return NULL;
 }
 
-const int _glfwPlatformGetKeyScancode(int key)
+int _glfwPlatformGetKeyScancode(int key)
 {
-    _glfwInputError(GLFW_PLATFORM_ERROR,
-                    "Mir: Unsupported function %s", __PRETTY_FUNCTION__);
-    return NULL;
+    return _glfw.mir.nativeKeys[key];
 }
 
 void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string)

src/win32_window.c

@@ -1511,13 +1511,8 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.win32.keyName;
 }
 
-const short int _glfwPlatformGetKeyScancode(int key)
+int _glfwPlatformGetKeyScancode(int key)
 {
-    if(key <= -1 || key >= (sizeof(_glfw.win32.nativeKeys) / sizeof(_glfw.win32.nativeKeys[0])))
-    {
-        return -1;
-    }
-
     return _glfw.win32.nativeKeys[key];
 }
 

src/wl_window.c

@@ -686,10 +686,9 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return NULL;
 }
 
-const int _glfwPlatformGetKeyScancode(int key)
+int _glfwPlatformGetKeyScancode(int key)
 {
-    // TODO
-	return -1;
+    return _glfw.wl.nativeKeys[key];
 }
 
 int _glfwPlatformCreateCursor(_GLFWcursor* cursor,

src/x11_window.c

@@ -2186,13 +2186,8 @@ const char* _glfwPlatformGetKeyName(int key, int scancode)
     return _glfw.x11.keyName;
 }
 
-const short int _glfwPlatformGetKeyScancode(int key)
+int _glfwPlatformGetKeyScancode(int key)
 {
-    if(key <= -1 || key >= (sizeof(_glfw.x11.nativeKeys) / sizeof(_glfw.x11.nativeKeys[0])))
-    {
-        return -1;
-    }
-
     return _glfw.x11.nativeKeys[key];
 }