[pull] master from beyond-all-reason:master

cont/LuaUI/Headers/keysym.h.lua

@@ -13,7 +13,7 @@
 
 -- From SDL_keysym.h
 
-KEYSYMS = {
+local KEYSYM_VALUES = {
 
   UNKNOWN    = 0,
   FIRST      = 0,
@@ -273,3 +273,98 @@ KEYSYMS = {
   -- Add any other keys here
   LAST   = 323
 }
+
+
+-- KEYSYMS is deprecated in favour of Spring.GetKeyCode(name) (see issue #2611:
+-- these legacy SDL1.2 values can't represent keys like F13-F20). It stays fully
+-- available for now - same values, still iterable - but warns on use to nudge
+-- migration. Deprecation only; no behaviour change.
+local warnedKeys = {}
+local warnedSites = {}
+
+-- first stack frame outside this shim, so the warning points at the offending
+-- widget line instead of the proxy. skips C frames (no line) and the shim itself.
+local function callerSite()
+  if not (debug and debug.getinfo) then return nil end
+  for lvl = 2, 8 do
+    local info = debug.getinfo(lvl, "Sl")
+    if not info then return nil end
+    local src = info.short_src or ""
+    if info.currentline and info.currentline > 0 and not src:find("keysym") then
+      return src .. ":" .. info.currentline
+    end
+  end
+  return nil
+end
+
+-- SDL2 folded these keys into another one, so nothing produces their old value
+-- and GetKeySymbol cannot find them; name the surviving key by hand
+local RENAMED_KEYS = {
+  BREAK  = "pause",
+  LSUPER = "meta",
+  RSUPER = "rmeta",
+}
+
+local function warnKeysym(key, value)
+  -- default (empty) section: on release its floor is INFO, so a DEPRECATED
+  -- message gets through; named sections floor at WARNING and would swallow it.
+  if not (Spring and Spring.Log and LOG and LOG.DEPRECATED) then return end
+
+  local name = (key ~= nil) and tostring(key) or "*"
+  if warnedKeys[name] then return end
+  warnedKeys[name] = true
+
+  -- collapse a loop over KEYSYMS to one warning per source line, not one per key
+  local site = callerSite()
+  if site then
+    if warnedSites[site] then return end
+    warnedSites[site] = true
+  end
+
+  -- GetKeySymbol is the runtime inverse of GetKeyCode: it turns the legacy value
+  -- back into the current key name, so the message can name the exact replacement
+  local replacement, unsupported
+  if key ~= nil and value ~= nil then
+    local keyName = RENAMED_KEYS[key]
+    if not keyName and Spring.GetKeySymbol then
+      keyName = Spring.GetKeySymbol(value)
+      if keyName and keyName:sub(1, 2) == "0x" then keyName = nil end
+    end
+    if keyName then
+      replacement = 'Spring.GetKeyCode("' .. keyName .. '")'
+    else
+      -- nothing names this value, so SDL2 dropped the key rather than renaming it
+      unsupported = true
+    end
+  end
+
+  local msg
+  if key == nil then
+    msg = "pairs(KEYSYMS) is deprecated, use Spring.GetKeySymbol() for a reverse mapping and check https://recoilengine.org/articles/ui-keys-reference/ for a listing of available keys"
+  elseif unsupported then
+    msg = "KEYSYMS." .. name .. " is deprecated and SDL2 no longer supports this key; "
+      .. "move the functionality to a key Spring.GetKeyCode can resolve"
+  else
+    msg = "KEYSYMS." .. name .. " is deprecated, use "
+      .. (replacement or "Spring.GetKeyCode() with the key's name") .. " instead"
+  end
+  if site then
+    msg = msg .. "  [" .. site .. "]"
+  end
+
+  Spring.Log("", LOG.DEPRECATED, msg)
+end
+
+-- proxy: warns on access/iteration, returns the original values (no drift), and
+-- keeps pairs() working via __pairs (backported into this Lua from 5.2)
+KEYSYMS = setmetatable({}, {
+  __index = function(_, key)
+    local value = KEYSYM_VALUES[key]
+    warnKeysym(key, value)
+    return value
+  end,
+  __pairs = function()
+    warnKeysym(nil, nil)
+    return next, KEYSYM_VALUES, nil
+  end,
+})

cont/LuaUI/callins.lua

@@ -23,6 +23,7 @@ CallInsList = {
 	"MiniMapGeometryChanged",
 	"CommandNotify",
 
+	"KeyBindingsChanged",
 	"KeyMapChanged",
 	"KeyPress",
 	"KeyRelease",

cont/LuaUI/widgets.lua

@@ -195,6 +195,7 @@ local callInLists = {
   'AddConsoleLine',
   'ViewResize',
   'DrawScreen',
+  'KeyBindingsChanged',
   'KeyMapChanged',
   'KeyPress',
   'KeyRelease',
@@ -1416,6 +1417,12 @@ end
 --  Keyboard call-ins
 --
 
+function widgetHandler:KeyBindingsChanged()
+  for _,w in ipairs(self.KeyBindingsChangedList) do
+    w:KeyBindingsChanged()
+  end
+end
+
 function widgetHandler:KeyMapChanged()
   for _,w in ipairs(self.KeyMapChangedList) do
     w:KeyMapChanged()

cont/base/springcontent/LuaGadgets/callins.lua

@@ -192,6 +192,7 @@ CALLIN_LIST = {
 	"GroupChanged",
 
 	-- moved from LuaUI
+	"KeyBindingsChanged",
 	"KeyPress",
 	"KeyRelease",
 	"TextInput",

cont/base/springcontent/LuaGadgets/gadgets.lua

@@ -2060,6 +2060,13 @@ end
 --------------------------------------------------------------------------------
 --------------------------------------------------------------------------------
 
+function gadgetHandler:KeyBindingsChanged()
+  for _,g in r_ipairs(self.KeyBindingsChangedList) do
+    g:KeyBindingsChanged()
+  end
+end
+
+
 function gadgetHandler:KeyPress(key, mods, isRepeat, label, unicode, scanCode)
   for _,g in r_ipairs(self.KeyPressList) do
     if (g:KeyPress(key, mods, isRepeat, label, unicode, scanCode)) then

cont/base/springcontent/LuaHandler/Utilities/keysym.lua

@@ -13,7 +13,7 @@
 
 -- From SDL_keysym.h
 
-KEYSYMS = {
+local KEYSYM_VALUES = {
 
   UNKNOWN    = 0,
   FIRST      = 0,
@@ -273,3 +273,98 @@ KEYSYMS = {
   -- Add any other keys here
   LAST   = 323
 }
+
+
+-- KEYSYMS is deprecated in favour of Spring.GetKeyCode(name) (see issue #2611:
+-- these legacy SDL1.2 values can't represent keys like F13-F20). It stays fully
+-- available for now - same values, still iterable - but warns on use to nudge
+-- migration. Deprecation only; no behaviour change.
+local warnedKeys = {}
+local warnedSites = {}
+
+-- first stack frame outside this shim, so the warning points at the offending
+-- widget line instead of the proxy. skips C frames (no line) and the shim itself.
+local function callerSite()
+  if not (debug and debug.getinfo) then return nil end
+  for lvl = 2, 8 do
+    local info = debug.getinfo(lvl, "Sl")
+    if not info then return nil end
+    local src = info.short_src or ""
+    if info.currentline and info.currentline > 0 and not src:find("keysym") then
+      return src .. ":" .. info.currentline
+    end
+  end
+  return nil
+end
+
+-- SDL2 folded these keys into another one, so nothing produces their old value
+-- and GetKeySymbol cannot find them; name the surviving key by hand
+local RENAMED_KEYS = {
+  BREAK  = "pause",
+  LSUPER = "meta",
+  RSUPER = "rmeta",
+}
+
+local function warnKeysym(key, value)
+  -- default (empty) section: on release its floor is INFO, so a DEPRECATED
+  -- message gets through; named sections floor at WARNING and would swallow it.
+  if not (Spring and Spring.Log and LOG and LOG.DEPRECATED) then return end
+
+  local name = (key ~= nil) and tostring(key) or "*"
+  if warnedKeys[name] then return end
+  warnedKeys[name] = true
+
+  -- collapse a loop over KEYSYMS to one warning per source line, not one per key
+  local site = callerSite()
+  if site then
+    if warnedSites[site] then return end
+    warnedSites[site] = true
+  end
+
+  -- GetKeySymbol is the runtime inverse of GetKeyCode: it turns the legacy value
+  -- back into the current key name, so the message can name the exact replacement
+  local replacement, unsupported
+  if key ~= nil and value ~= nil then
+    local keyName = RENAMED_KEYS[key]
+    if not keyName and Spring.GetKeySymbol then
+      keyName = Spring.GetKeySymbol(value)
+      if keyName and keyName:sub(1, 2) == "0x" then keyName = nil end
+    end
+    if keyName then
+      replacement = 'Spring.GetKeyCode("' .. keyName .. '")'
+    else
+      -- nothing names this value, so SDL2 dropped the key rather than renaming it
+      unsupported = true
+    end
+  end
+
+  local msg
+  if key == nil then
+    msg = "pairs(KEYSYMS) is deprecated, use Spring.GetKeySymbol() for a reverse mapping and check https://recoilengine.org/articles/ui-keys-reference/ for a listing of available keys"
+  elseif unsupported then
+    msg = "KEYSYMS." .. name .. " is deprecated and SDL2 no longer supports this key; "
+      .. "move the functionality to a key Spring.GetKeyCode can resolve"
+  else
+    msg = "KEYSYMS." .. name .. " is deprecated, use "
+      .. (replacement or "Spring.GetKeyCode() with the key's name") .. " instead"
+  end
+  if site then
+    msg = msg .. "  [" .. site .. "]"
+  end
+
+  Spring.Log("", LOG.DEPRECATED, msg)
+end
+
+-- proxy: warns on access/iteration, returns the original values (no drift), and
+-- keeps pairs() working via __pairs (backported into this Lua from 5.2)
+KEYSYMS = setmetatable({}, {
+  __index = function(_, key)
+    local value = KEYSYM_VALUES[key]
+    warnKeysym(key, value)
+    return value
+  end,
+  __pairs = function()
+    warnKeysym(nil, nil)
+    return next, KEYSYM_VALUES, nil
+  end,
+})

doc/pr-changelogs/3081.md

@@ -0,0 +1,2 @@
+### Features
+ * added `wupget:KeyBindingsChanged()` unsynced callin. Called whenever a valid `/bind` or similar command is called.

doc/pr-changelogs/3105.md

@@ -0,0 +1,2 @@
+* `Spring.GetKeyCode` now supports most of keys defined in `keysyms.lua`, except a few that SDL2 dropped.
+* deprecation notice: basecontent's `LuaHandler/Utilities/keysym.lua` and the loose `LuaUI/Headers/keysym.h.lua‎` distributed with engine installs are deprecated and will be removed. For now they work unchanged, but print helpful migration suggestions when used.

doc/site/content/articles/ui-keys-reference.md

@@ -128,6 +128,7 @@ see rts/Game/UI/KeyBindings.cpp
 | $             | 0x024    |
 | %             | 0x025    |
 | &             | 0x026    |
+| |        | 0x07C    |
 | '             | 0x027    |
 | (             | 0x028    |
 | )             | 0x029    |
@@ -163,8 +164,11 @@ see rts/Game/UI/KeyBindings.cpp
 | a             | 0x061    |
 | alt           | 0x134    |
 | b             | 0x062    |
+| backquote     | 0x060    |
 | backspace     | 0x008    |
 | c             | 0x063    |
+| capslock      | 0x12D    |
+| caret         | 0x05E    |
 | clear         | 0x00C    |
 | ctrl          | 0x132    |
 | d             | 0x064    |
@@ -193,32 +197,20 @@ see rts/Game/UI/KeyBindings.cpp
 | f9            | 0x122    |
 | g             | 0x067    |
 | h             | 0x068    |
+| help          | 0x13B    |
 | home          | 0x116    |
 | i             | 0x069    |
 | insert        | 0x115    |
 | j             | 0x06A    |
-| joy0          | 0x12C    |
-| joy1          | 0x12D    |
-| joy2          | 0x12E    |
-| joy3          | 0x12F    |
-| joy4          | 0x130    |
-| joy5          | 0x131    |
-| joy6          | 0x132    |
-| joy7          | 0x133    |
-| joydown       | 0x141    |
-| joyleft       | 0x142    |
-| joyright      | 0x143    |
-| joyup         | 0x140    |
-| joyw          | 0x193    |
-| joyx          | 0x190    |
-| joyy          | 0x191    |
-| joyz          | 0x192    |
 | k             | 0x06B    |
 | l             | 0x06C    |
 | left          | 0x114    |
 | m             | 0x06D    |
+| menu          | 0x13F    |
 | meta          | 0x136    |
+| mode          | 0x139    |
 | n             | 0x06E    |
+| numlock       | 0x12C    |
 | numpad*       | 0x10C    |
 | numpad+       | 0x10E    |
 | numpad-       | 0x10D    |
@@ -241,24 +233,31 @@ see rts/Game/UI/KeyBindings.cpp
 | pagedown      | 0x119    |
 | pageup        | 0x118    |
 | pause         | 0x013    |
+| power         | 0x140    |
+| print         | 0x13C    |
 | printscreen   | 0x13C    |
 | q             | 0x071    |
 | r             | 0x072    |
+| ralt          | 0x133    |
+| rctrl         | 0x131    |
 | return        | 0x00D    |
 | right         | 0x113    |
+| rmeta         | 0x135    |
+| rshift        | 0x12F    |
 | s             | 0x073    |
+| scrollock     | 0x12E    |
 | shift         | 0x130    |
 | space         | 0x020    |
+| sysreq        | 0x13D    |
 | t             | 0x074    |
 | tab           | 0x009    |
+| tilde         | 0x060    |
 | u             | 0x075    |
+| undo          | 0x142    |
 | up            | 0x111    |
 | v             | 0x076    |
 | w             | 0x077    |
 | x             | 0x078    |
 | y             | 0x079    |
 | z             | 0x07A    |
-| {             | 0x07B    |
-| |        | 0x07C    |
-| }             | 0x07D    |
 | ~             | 0x07E    |