Refactor `IInputApi`, replacing 1 method, adding 1, plus doc comments

src/BizHawk.Client.Common/Api/Classes/InputApi.cs

@@ -24,7 +24,7 @@ namespace BizHawk.Client.Common
 			return buttons;
 		}
 
-		public Dictionary<string, object> GetMouse()
+		public IReadOnlyDictionary<string, object> GetMouse()
 		{
 			var (pos, scroll, lmb, mmb, rmb, x1mb, x2mb) = _inputManager.GetMainFormMouseInfo();
 			// TODO - need to specify whether in "emu" or "native" coordinate space.
@@ -41,5 +41,13 @@ namespace BizHawk.Client.Common
 				["Wheel"] = scroll
 			};
 		}
+
+		public IReadOnlyDictionary<string, int> GetPressedAxes()
+			=> _inputManager.ControllerInputCoalescer.AxisValues().ToDictionary(static kvp => kvp.Key, static kvp => kvp.Value);
+
+		public IReadOnlyList<string> GetPressedButtons()
+			=> _inputManager.ControllerInputCoalescer.BoolButtons().Where(static kvp => kvp.Value)
+				.Select(static kvp => kvp.Key).ToList();
 	}
 }
+

src/BizHawk.Client.Common/Api/Interfaces/IInputApi.cs

@@ -1,10 +1,58 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 
 namespace BizHawk.Client.Common
 {
+	/// <summary>for querying host input</summary>
+	/// <seealso cref="IJoypadApi"/>
 	public interface IInputApi : IExternalApi
 	{
+		/// <returns>
+		/// Map of key/button names (of host) to their pressed state.<br/>
+		/// Only pressed buttons will appear (with a value of <see langword="true"/>), unpressed buttons are omitted.
+		/// </returns>
+		/// <remarks>
+		/// Includes gamepad axes (<c>!axis.isNeutral</c>, with sticks as 4 "buttons" suffixed <c>"Up"</c>/<c>"Down"</c>/<c>"Left"</c>/<c>"Right"</c>).<br/>
+		/// Includes mouse buttons, but not axes (cursor position and wheel rotation).
+		/// Unlike <see cref="GetMouse"/>, these have the names <c>"WMouse L"</c>, <c>"WMouse R"</c>, <c>"WMouse C"</c>, <c>"WMouse 1"</c>, and <c>"WMouse 2"</c> for LMB, RMB, MMB, Mouse4, and Mouse5, respectively.<br/>
+		/// See <see cref="DistinctKey"/> for keyboard key names, though some are overridden by <see cref="DistinctKeyNameOverrides"/> (check the source).
+		/// </remarks>
+		/// <seealso cref="GetPressedButtons"/>
+		[Obsolete]
 		Dictionary<string, bool> Get();
-		Dictionary<string, object> GetMouse();
+
+		/// <returns>
+		/// Map of (host) mouse button/axis names to their state:
+		/// either <see cref="bool"/> for a button (<c>button.isPressed</c>), or <see cref="int"/> for an axis.
+		/// </returns>
+		/// <remarks>
+		/// Buttons are <c>"Left"</c>, <c>"Right"</c>, <c>"Middle"</c>, <c>"XButton1"</c>, and <c>"XButton2"</c> for LMB, RMB, MMB, Mouse4, and Mouse5, respectively.
+		/// Mouse position is axes <c>"X"</c> and <c>"Y"</c>. Mouse wheel rotation is the <c>"Wheel"</c> axis.
+		/// </remarks>
+		IReadOnlyDictionary<string, object> GetMouse();
+
+		/// <returns>
+		/// Map of (host) axis names to their state.<br/>
+		/// Axes may not appear if they have never been seen with a value other than <c>0</c>
+		/// (for example, if the gamepad has been set down on a table since launch, or if it was recently reconnected).
+		/// </returns>
+		/// <remarks>
+		/// Includes mouse cursor position axes, but not mouse wheel rotation.
+		/// Unlike <see cref="GetMouse"/>, these have the names <c>"WMouse X"</c> and <c>"WMouse Y"</c>.
+		/// </remarks>
+		IReadOnlyDictionary<string, int> GetPressedAxes();
+
+		/// <returns>
+		/// List of (host) key/button names which are pressed
+		/// (i.e. were pressed when EmuHawk last polled; this is distinct from virtual gamepad polling/latching).
+		/// Unpressed buttons are omitted.
+		/// </returns>
+		/// <remarks>
+		/// Includes gamepad axes (<c>!axis.isNeutral</c>, with sticks as 4 "buttons" suffixed <c>"Up"</c>/<c>"Down"</c>/<c>"Left"</c>/<c>"Right"</c>).<br/>
+		/// Includes mouse buttons, but not axes (cursor position and wheel rotation).
+		/// Unlike <see cref="GetMouse"/>, these have the names <c>"WMouse L"</c>, <c>"WMouse R"</c>, <c>"WMouse C"</c>, <c>"WMouse 1"</c>, and <c>"WMouse 2"</c> for LMB, RMB, MMB, Mouse4, and Mouse5, respectively.<br/>
+		/// See <see cref="DistinctKey"/> for keyboard key names, though some are overridden by <see cref="DistinctKeyNameOverrides"/> (check the source).
+		/// </remarks>
+		IReadOnlyList<string> GetPressedButtons();
 	}
 }

src/BizHawk.Client.Common/Api/Interfaces/IJoypadApi.cs

@@ -2,6 +2,8 @@
 
 namespace BizHawk.Client.Common
 {
+	/// <summary>for querying or modifying virtual input</summary>
+	/// <seealso cref="IInputApi"/>
 	public interface IJoypadApi : IExternalApi
 	{
 		IReadOnlyDictionary<string, object> Get(int? controller = null);

src/BizHawk.Client.Common/controllers/SimpleController.cs

@@ -44,7 +44,9 @@ namespace BizHawk.Client.Common
 
 		public void SetHapticChannelStrength(string name, int strength) => HapticFeedback[name] = strength;
 
-		public IDictionary<string, bool> BoolButtons() => Buttons;
+		public IReadOnlyDictionary<string, int> AxisValues() => Axes;
+
+		public IReadOnlyDictionary<string, bool> BoolButtons() => Buttons;
 
 		public void AcceptNewAxis(string axisId, int value)
 		{

src/BizHawk.Client.Common/lua/CommonLibs/InputLuaLibrary.cs

@@ -11,10 +11,12 @@ namespace BizHawk.Client.Common
 
 		public override string Name => "input";
 
+#pragma warning disable CS0612
 		[LuaMethodExample("local nlinpget = input.get( );")]
 		[LuaMethod("get", "Returns a lua table of all the buttons the user is currently pressing on their keyboard and gamepads\nAll buttons that are pressed have their key values set to true; all others remain nil.")]
 		public LuaTable Get()
 			=> _th.DictToTable(APIs.Input.Get());
+#pragma warning restore CS0612
 
 		[LuaMethodExample("local nlinpget = input.getmouse( );")]
 		[LuaMethod("getmouse", "Returns a lua table of the mouse X/Y coordinates and button states. Table keys are X, Y, Left, Middle, Right, XButton1, XButton2, Wheel.")]