Add mouse controls to virtualhid UI

Extend the native control tool to create, inspect, reset, and remove virtual mice alongside gamepads. This adds keyboard-navigable mouse motion, button, and wheel actions, plus delayed browser-test scheduling for focus-sensitive mouse validation. Update the shared control model tests and refresh README and Windows/platform/store-review docs to reflect driver-backed mouse support and its licensing requirements.

Author: ReenigneArcher

README.md

@@ -19,7 +19,7 @@
 <div align="center">
   <h2>🎮 Windows Virtual HID Driver License</h2>
   <p>
-    <strong>A license is required to create virtual gamepads with the Windows driver.</strong><br>
+    <strong>A license is required to create virtual gamepads or Raw Input-visible mice with the Windows driver.</strong><br>
     This requirement is Windows-only; non-Windows backends do not currently require a license.<br>
     Yearly and lifetime options are available.
   </p>
@@ -48,12 +48,13 @@ behind backend implementations.
 - Descriptor-driven PlayStation gamepads through Linux `uhid`; Generic, Xbox,
   and Switch Pro gamepads plus keyboard, mouse, touchscreen, trackpad, and pen
   tablet devices through `uinput`.
-- Windows gamepads through a user-mode UMDF2 control driver backed by Virtual
-  HID Framework, with keyboard and mouse support through normal Win32 APIs.
+- Windows gamepads and Raw Input-visible mice through a user-mode UMDF2 control
+  driver backed by Virtual HID Framework, with keyboard and fallback mouse
+  support through normal Win32 APIs.
 - Output callbacks for profile-specific feedback such as rumble, LEDs,
   adaptive triggers, and raw HID output reports when available.
 - An optional `virtualhid_control` native UI tool for creating, removing,
-  controlling, and inspecting test gamepads through the public C++ API.
+  controlling, and inspecting test gamepads and mice through the public C++ API.
 - CMake consumption through installed packages, vendored source,
   `add_subdirectory`, or `FetchContent`.
 

docs/maintainer/store-review-validation.md

@@ -15,7 +15,7 @@ Paste this into the Partner Center certification notes field:
 ```text
 This package installs the libvirtualhid Windows user-mode UMDF/VHF virtual HID driver and local broker service. Applications consume it through the libvirtualhid client API, and the MSI includes a native diagnostic UI for local validation.
 
-Every virtual gamepad creation requires an active license. A currently granted review license key with an available device activation is supplied separately in the Partner Center certification credentials or notes. The key is not embedded in the package or this document.
+Every virtual gamepad or driver-backed Raw Input mouse creation requires an active license. A currently granted review license key with an available device activation is supplied separately in the Partner Center certification credentials or notes. The key is not embedded in the package or this document.
 
 Launch the validation tool below.
 
@@ -31,17 +31,20 @@ Required validation:
 $installRoot = Join-Path $env:ProgramFiles "libvirtualhid"
 Start-Process "$installRoot\tools\windows\virtualhid_control.exe"
 
-In the libvirtualhid control window, paste the supplied review key into the License key field and click Activate license. Confirm the status changes to Licensed. Then leave the default Xbox Series profile selected and click Create. Use the button and axis controls in the UI to submit input to the virtual controller.
+In the libvirtualhid control window, paste the supplied review key into the License key field and click Activate license. Confirm the status changes to Licensed. Then leave the default Xbox Series profile selected and click Create. Use the button and axis controls in the UI to submit input to the virtual controller. Next, change Device type to Mouse and click Create. Use Tab or the arrow keys to highlight the mouse controls and Space or Enter to activate relative movement, momentary button, and wheel input without using the physical mouse.
 
 Expected result:
-- The backend status reports windows-umdf with gamepad support available
+- The backend status reports windows-umdf with gamepad and mouse support available
 - The libvirtualhid_broker service is running
 - License validation succeeds and the license status reports Licensed
 - A virtual HID gamepad is created and appears in the device list
 - A virtual HID gamepad child device starts with the Xbox Series HID ID
   HID\VID_045E&PID_0B12&IG_00
 - Button, axis, and Share values in the UI can be pressed or moved without
   errors
+- A driver-backed virtual HID mouse is created and appears in the device list
+- Keyboard activation of the mouse controls moves the pointer, changes button
+  state, and scrolls without errors
 
 Optional browser validation:
 $installRoot = Join-Path $env:ProgramFiles "libvirtualhid"
@@ -55,6 +58,12 @@ Use the libvirtualhid control window to press buttons or move axes while the bro
 Expected result:
 - The browser Gamepad API sees an Xbox-compatible controller
 - Button and axis values change while controls are used in the validation UI
+
+For a browser mouse-event tester, create a mouse in the validation UI and enable Delayed browser test. Leave the pointer over the browser test target, activate a movement, button, or wheel action with the keyboard, then switch to the browser before the displayed countdown expires.
+
+Expected result:
+- The browser receives the queued mouse action while it owns focus
+- A queued button action produces one press followed by one release
 ```
 
 ## Manual Review Steps
@@ -66,7 +75,8 @@ Expected result:
 4. Run the required validation tool from the submission notes.
 5. Activate the review key supplied through Partner Center.
 6. Create the default gamepad and exercise its controls.
-7. Optionally, run the browser validation steps.
+7. Create a mouse and exercise its controls with keyboard navigation.
+8. Optionally, run the browser validation steps.
 
 If the default install location was changed during MSI installation, replace
 `$env:ProgramFiles\libvirtualhid` with the selected install directory.
@@ -84,5 +94,5 @@ HID-only and intentionally does not emulate the Xbox 360 XUSB stack.
 
 The reviewer-visible success signal is the installed `ROOT\LIBVIRTUALHID`
 control device, the `\\.\LibVirtualHid` control path, the running
-`libvirtualhid_broker` service, and a started HID gamepad child device while
-`virtualhid_control.exe` has a gamepad created.
+`libvirtualhid_broker` service, and started HID child devices while
+`virtualhid_control.exe` has a gamepad and mouse created.

docs/platform-support.md

@@ -25,8 +25,9 @@ Use capability queries for behavior such as:
 ## Windows
 
 The Windows backend keeps the normal C++ library buildable with MSVC and
-MinGW/UCRT64. Keyboard and mouse input use Win32 APIs. Gamepad creation uses a
-user-mode UMDF2 control driver and Windows Virtual HID Framework.
+MinGW/UCRT64. Gamepad creation and Raw Input-visible relative mouse input use a
+user-mode UMDF2 control driver and Windows Virtual HID Framework. Keyboard,
+absolute mouse input, and the mouse fallback use Win32 APIs.
 
 The C++ library communicates with the driver through fixed-size protocol
 structures and `DeviceIoControl`, not C++ STL types. This keeps the public API
@@ -199,6 +200,13 @@ libraries. Many distro toolchains intentionally omit some static archives, so
 release packaging should keep full static linking as a packaging-mode choice
 rather than an unconditional default.
 
+The UI can create and exercise both gamepads and mice. Its mouse movement,
+button, and wheel controls participate in Dear ImGui keyboard navigation; use
+Tab or the arrow keys to highlight them and Space or Enter to activate them.
+Mouse buttons are momentary. A delayed browser-test mode queues an action long
+enough to switch focus to an external event tester, sending button actions as a
+single press-and-release click.
+
 ### Permissions
 
 Linux deployment requires both device-node permissions and the kernel modules

docs/windows-driver.md

@@ -29,8 +29,9 @@ Virtual HID Driver installs the user-mode driver component used by compatible
 applications to create virtual HID gamepads and mice on Windows.
 
 The package includes a local diagnostic UI for creating and testing virtual
-gamepads. Compatible applications can also request virtual HID gamepads or mice,
-and Windows applications that understand standard HID devices can discover them.
+gamepads and mice. Compatible applications can also request virtual HID gamepads
+or mice, and Windows applications that understand standard HID devices can
+discover them.
 ```
 
 ## Architecture
@@ -182,7 +183,7 @@ The WiX installer also places validation files under the default install root,
 The source-tree validation scripts remain developer and CI helpers. They are not
 packaged as reviewer-facing MSI validation scripts because the native
 `virtualhid_control.exe` tool can create, exercise, and inspect virtual
-gamepads interactively.
+gamepads and mice interactively.
 
 The install helper stages the INF with `pnputil`, updates an existing
 `ROOT\LIBVIRTUALHID` device when present, and creates that root-enumerated
@@ -228,18 +229,33 @@ For interactive local validation, run:
 tools\windows\virtualhid_control.exe
 ```
 
-The native UI can create, remove, control, and monitor gamepads that it owns.
-Buttons are momentary by default, with an explicit lock mode for held inputs.
-The UI also shows supported profile features, battery input state, device nodes,
-and normalized feedback reports such as rumble, RGB LED, adaptive trigger, and
-raw output events. Devices created by another process are not listed yet; that
-requires a future Windows control-protocol extension for cross-process
-diagnostics.
+The native UI can create, remove, control, and monitor gamepads and mice that it
+owns. Gamepad buttons are momentary by default, with an explicit lock mode for
+held inputs. Mouse controls provide relative movement, five momentary buttons,
+vertical scrolling, and horizontal panning. Use Tab or the arrow keys to
+highlight a mouse control and Space or Enter to activate it, avoiding use of the
+physical mouse while testing the virtual device. A mouse button remains pressed
+only while its activation key is held.
+
+For an external mouse-event tester, enable **Delayed browser test**, choose a
+delay, and activate the desired action. Switch to the browser before the
+countdown expires while leaving the pointer over its test target. Movement and
+wheel actions are submitted once the browser owns focus; a delayed button action
+submits one press-and-release click. The scheduler continues while the control
+window is unfocused or minimized.
+
+The UI identifies a driver-backed HID mouse separately from the `SendInput`
+fallback and also shows supported profile features, battery input state, device
+nodes, and normalized gamepad feedback reports such as rumble, RGB LED,
+adaptive trigger, and raw output events. Devices created by another process are
+not listed yet; that requires a future Windows control-protocol extension for
+cross-process diagnostics.
 
 On Windows, the UI also shows broker license status. It can activate a license
 key, refresh validation, deactivate the current machine, and open
-compiled purchase or account-management URLs. License management and normal
-virtual HID device use do not require elevation.
+compiled purchase or account-management URLs. The Create button is enabled for
+both gamepads and mice only while the broker reports a current machine license.
+License management and normal virtual HID device use do not require elevation.
 
 ## Installation Notes
 

tests/unit/test_virtualhid_control_model.cpp

@@ -100,6 +100,58 @@ TEST(VirtualHidControlModelTest, MapsProfileChoicesToProfiles) {
   EXPECT_FALSE(control::profile_for_choice(invalid).has_value());
 }
 
+TEST(VirtualHidControlModelTest, ExposesGamepadAndMouseDeviceChoices) {
+  ASSERT_EQ(control::device_type_choices.size(), 2U);
+  EXPECT_EQ(control::device_type_choices[0].type, lvh::DeviceType::gamepad);
+  EXPECT_EQ(control::device_type_choices[1].type, lvh::DeviceType::mouse);
+
+  ASSERT_EQ(control::mouse_button_choices.size(), 5U);
+  EXPECT_EQ(control::mouse_button_choices[0].button, lvh::MouseButton::left);
+  EXPECT_EQ(control::mouse_button_choices[1].button, lvh::MouseButton::middle);
+  EXPECT_EQ(control::mouse_button_choices[2].button, lvh::MouseButton::right);
+  EXPECT_EQ(control::mouse_button_choices[3].button, lvh::MouseButton::side);
+  EXPECT_EQ(control::mouse_button_choices[4].button, lvh::MouseButton::extra);
+}
+
+TEST(VirtualHidControlModelTest, MapsKeyboardMouseActionsToEvents) {
+  using enum control::MouseControlAction;
+
+  const auto left = control::mouse_event_for_action(move_left, 25, 120);
+  EXPECT_EQ(left.kind, lvh::MouseEventKind::relative_motion);
+  EXPECT_EQ(left.x, -25);
+  EXPECT_EQ(left.y, 0);
+
+  const auto right = control::mouse_event_for_action(move_right, 25, 120);
+  EXPECT_EQ(right.x, 25);
+  const auto up = control::mouse_event_for_action(move_up, 25, 120);
+  EXPECT_EQ(up.y, -25);
+  const auto down = control::mouse_event_for_action(move_down, 25, 120);
+  EXPECT_EQ(down.y, 25);
+
+  const auto wheel_up_event = control::mouse_event_for_action(wheel_up, 25, 120);
+  EXPECT_EQ(wheel_up_event.kind, lvh::MouseEventKind::vertical_scroll);
+  EXPECT_EQ(wheel_up_event.high_resolution_scroll, 120);
+  const auto wheel_down_event = control::mouse_event_for_action(wheel_down, 25, 120);
+  EXPECT_EQ(wheel_down_event.high_resolution_scroll, -120);
+  const auto pan_left_event = control::mouse_event_for_action(pan_left, 25, 120);
+  EXPECT_EQ(pan_left_event.kind, lvh::MouseEventKind::horizontal_scroll);
+  EXPECT_EQ(pan_left_event.high_resolution_scroll, -120);
+  const auto pan_right_event = control::mouse_event_for_action(pan_right, 25, 120);
+  EXPECT_EQ(pan_right_event.high_resolution_scroll, 120);
+}
+
+TEST(VirtualHidControlModelTest, BuildsMomentaryMouseButtonEvents) {
+  const auto press = control::mouse_button_event(lvh::MouseButton::side, true);
+  EXPECT_EQ(press.kind, lvh::MouseEventKind::button);
+  EXPECT_EQ(press.button, lvh::MouseButton::side);
+  EXPECT_TRUE(press.pressed);
+
+  const auto release = control::mouse_button_event(lvh::MouseButton::side, false);
+  EXPECT_EQ(release.kind, lvh::MouseEventKind::button);
+  EXPECT_EQ(release.button, lvh::MouseButton::side);
+  EXPECT_FALSE(release.pressed);
+}
+
 TEST(VirtualHidControlModelTest, ConvertsSliderValues) {
   EXPECT_EQ(control::axis_to_slider(-2.0F), -control::slider_scale);
   EXPECT_EQ(control::axis_to_slider(-0.5F), -50);
@@ -132,6 +184,7 @@ TEST(VirtualHidControlModelTest, FormatsRawHex) {
 TEST(VirtualHidControlModelTest, SummarizesProfileFeatures) {
   const auto generic = lvh::profiles::generic_gamepad();
   const auto dualsense = lvh::profiles::dualsense();
+  const auto mouse = lvh::profiles::mouse();
 
   EXPECT_TRUE(control::supports_normalized_feedback(generic));
   EXPECT_TRUE(control::supports_normalized_feedback(dualsense));
@@ -144,6 +197,11 @@ TEST(VirtualHidControlModelTest, SummarizesProfileFeatures) {
     control::profile_feature_summary(dualsense),
     L"Features: battery yes | rumble yes | trigger rumble no | RGB LED yes | adaptive triggers yes | raw output yes"
   );
+  EXPECT_EQ(
+    control::device_feature_summary(mouse),
+    L"Features: relative motion | five buttons | vertical wheel | horizontal wheel"
+  );
+  EXPECT_EQ(control::device_feature_summary(generic), control::profile_feature_summary(generic));
 }
 
 TEST(VirtualHidControlModelTest, UpdatesVisibleControlsForProfiles) {