Add keyboard state tracker (#4746)

Related #4410

## What's new?

- Adds `KeyboardStateTracker` to provide global keyboard state tracking.
This is meant as a utility class to be used with input triggers to
provide a consistent global view of keyboard states:

https://github.com/canonical/mir/blob/594cfcf01add05d4f46c1d9a1dffbf3fab4d0440/src/server/frontend_wayland/wl_seat.cpp#L163

https://github.com/canonical/mir/blob/84f77ea995ad6ce5760359b371b99db779dcde13/src/server/frontend_wayland/input_trigger_registration_v1.cpp#L192

https://github.com/canonical/mir/blob/84f77ea995ad6ce5760359b371b99db779dcde13/src/server/frontend_wayland/input_trigger_registration_v1.cpp#L217

## How to test

- Run mir unit tests with `--gtest_filter=KeyboardStateTracker*`

## Checklist

- [x] Tests added and pass
- [x] Adequate documentation added
- [ ] ~(optional) Added Screenshots or videos~

Author: tarek-y-ismail

src/server/frontend_wayland/CMakeLists.txt

@@ -67,6 +67,7 @@ set(
   linux_drm_syncobj.cpp         linux_drm_syncobj.h
   data_control_v1.cpp           data_control_v1.h
   surface_registry.cpp          surface_registry.h
+  keyboard_state_tracker.cpp    keyboard_state_tracker.h
 )
 
 if (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang" AND ${CMAKE_CXX_COMPILER_VERSION} VERSION_LESS 18.2)

src/server/frontend_wayland/keyboard_state_tracker.cpp

@@ -0,0 +1,144 @@
+/*
+ * Copyright © Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 or 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "keyboard_state_tracker.h"
+#include "mir_toolkit/events/enums.h"
+
+#include <mir/events/keyboard_event.h>
+#include <mir/fatal.h>
+
+#include <xkbcommon/xkbcommon.h>
+
+#include <algorithm>
+
+namespace mf = mir::frontend;
+
+namespace
+{
+// xkb scancodes are offset by 8 from evdev scancodes for compatibility with
+// the X protocol. This matches the same helper used in xkb_mapper.cpp.
+uint32_t constexpr to_xkb_scan_code(uint32_t evdev_scan_code)
+{
+    return evdev_scan_code + 8;
+}
+} // namespace
+
+void mf::KeyboardStateTracker::XkbKeyState::update_keymap(
+    std::shared_ptr<mir::input::Keymap> const& new_keymap, xkb_context* context)
+{
+    if (!new_keymap)
+        mir::fatal_error("KeyboardStateTracker: received null keymap");
+
+    if (current_keymap && current_keymap->matches(*new_keymap))
+        return;
+
+    current_keymap = new_keymap;
+    compiled_keymap = new_keymap->make_unique_xkb_keymap(context);
+    state = {xkb_state_new(compiled_keymap.get()), xkb_state_unref};
+}
+
+void mf::KeyboardStateTracker::XkbKeyState::update_key(uint32_t xkb_keycode, MirKeyboardAction action)
+{
+    xkb_state_update_key(state.get(), xkb_keycode, action == mir_keyboard_action_down ? XKB_KEY_DOWN : XKB_KEY_UP);
+}
+
+void mf::KeyboardStateTracker::XkbKeyState::rederive_keysyms_from_scancodes(
+    std::unordered_map<uint32_t, xkb_keysym_t>& scancode_to_keysym) const
+{
+
+    for (auto& [sc, ks] : scancode_to_keysym)
+    {
+        auto const derived = xkb_state_key_get_one_sym(state.get(), to_xkb_scan_code(sc));
+        if (derived != XKB_KEY_NoSymbol)
+            ks = derived;
+    }
+}
+
+mf::KeyboardStateTracker::KeyboardStateTracker()
+    : context{xkb_context_new(XKB_CONTEXT_NO_FLAGS), xkb_context_unref}
+{
+    if (!context)
+        fatal_error("KeyboardStateTracker: failed to create XKB context");
+}
+
+bool mf::KeyboardStateTracker::process(MirEvent const& event)
+{
+    if (event.type() != mir_event_type_input)
+        return false;
+
+    auto const& input_event = event.to_input();
+
+    if (input_event->input_type() != mir_input_event_type_key)
+        return false;
+
+    auto const* key_event = input_event->to_keyboard();
+    auto const keysym = key_event->keysym();
+    auto const scancode = key_event->scan_code();
+    auto const action = key_event->action();
+    auto const modifiers = key_event->modifiers();
+
+    auto& [scancode_to_keysym, shift_state, xkb_key_state] =
+        device_states[input_event->device_id()];
+
+    xkb_key_state.update_keymap(key_event->keymap(), context.get());
+
+    // Keep xkb_key_state in sync with every key event so that its modifier
+    // tracking stays accurate for subsequent keysym queries.
+    auto const xkb_keycode = to_xkb_scan_code(static_cast<uint32_t>(scancode));
+    xkb_key_state.update_key(xkb_keycode, action);
+
+    auto const prev_shift_state = shift_state;
+    shift_state = modifiers & (mir_input_event_modifier_shift | mir_input_event_modifier_shift_left |
+                               mir_input_event_modifier_shift_right);
+
+    auto processed = false;
+    if (action == mir_keyboard_action_down)
+    {
+        scancode_to_keysym[scancode] = keysym;
+        processed = true;
+    }
+    else if (action == mir_keyboard_action_up)
+    {
+        // Remove by scancode so that a mismatched key-up keysym (caused by a
+        // modifier change while the key was held) does not leave stale entries.
+        scancode_to_keysym.erase(scancode);
+        processed = true;
+    }
+
+    // When the shift state changes, re-derive every pressed keysym from its
+    // scancode using the layout-aware XKB state.
+    if (prev_shift_state != shift_state)
+        xkb_key_state.rederive_keysyms_from_scancodes(scancode_to_keysym);
+
+    return processed;
+}
+
+auto mf::KeyboardStateTracker::keysym_is_pressed(MirInputDeviceId device, xkb_keysym_t keysym) const -> bool
+{
+    if (!device_states.contains(device))
+        return false;
+
+    return std::ranges::any_of(
+        device_states.at(device).scancode_to_keysym, [keysym](auto const& pair) { return pair.second == keysym; });
+}
+
+auto mf::KeyboardStateTracker::scancode_is_pressed(MirInputDeviceId device, int32_t scancode) const -> bool
+{
+    if (!device_states.contains(device))
+        return false;
+
+    return device_states.at(device).scancode_to_keysym.contains(scancode);
+}

src/server/frontend_wayland/keyboard_state_tracker.h

@@ -0,0 +1,113 @@
+/*
+ * Copyright © Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 or 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef MIR_FRONTEND_WAYLAND_KEYBOARD_STATE_TRACKER_H_
+#define MIR_FRONTEND_WAYLAND_KEYBOARD_STATE_TRACKER_H_
+
+#include "mir_toolkit/events/enums.h"
+#include <mir/events/event.h>
+#include <mir/input/keymap.h>
+
+#include <memory>
+#include <unordered_map>
+
+namespace mir
+{
+namespace frontend
+{
+/// Maintains the set of currently-pressed keysyms and scancodes by processing
+/// keyboard \c MirEvents via \c process().
+///
+/// Callers feed every keyboard event into \c process() as it arrives, then
+/// query the resulting state with \c keysym_is_pressed() or \c
+/// scancode_is_pressed() to test whether a particular key is currently held
+/// down. This decouples state accumulation from the individual objects that
+/// need to inspect it, so a single tracker instance can be shared across many
+/// objects without each one having to maintain its own pressed-key set.
+///
+/// Shift-key transitions are handled specially: when the shift state changes,
+/// all currently-pressed keysyms are re-derived from their scancodes using the
+/// layout-aware XKB state. This keeps the stored keysyms consistent with what
+/// the keyboard layer reports as the logical key for subsequent events.
+///
+/// Keysyms are stored per scancode so that a key-up event always removes the
+/// keysym that was recorded at key-down, regardless of any modifier changes
+/// that occurred while the key was held (e.g. pressing Shift while holding
+/// a digit key).
+class KeyboardStateTracker
+{
+public:
+    KeyboardStateTracker();
+
+    // Returns true if the passed in event was an up or down keyboard event and
+    // was processed, false otherwise.
+    bool process(MirEvent const& event);
+
+    auto keysym_is_pressed(MirInputDeviceId device, xkb_keysym_t keysym) const -> bool;
+
+    auto scancode_is_pressed(MirInputDeviceId device, int32_t scancode) const -> bool;
+
+private:
+    /// Owns the per-device XKB keymap and state used to resolve keysyms from
+    /// scancodes in a layout- and modifier-aware way.
+    struct XkbKeyState
+    {
+        /// Update the compiled keymap and XKB state when a new keymap arrives.
+        /// \param new_keymap  The keymap carried on the incoming event. Must not be null.
+        /// \param context     The shared XKB context owned by the tracker.
+        void update_keymap(std::shared_ptr<mir::input::Keymap> const& new_keymap, xkb_context* context);
+
+        /// Feed a key press or release into the XKB state so that modifier
+        /// tracking stays accurate for subsequent keysym queries.
+        /// \param xkb_keycode  The XKB keycode for the key.
+        /// \param action       The keyboard action.
+        void update_key(uint32_t xkb_keycode, MirKeyboardAction action);
+
+        /// Re-derive every keysym in \a scancode_to_keysym from its scancode
+        /// using the current modifier state of the XKB state machine.
+        void rederive_keysyms_from_scancodes(
+            std::unordered_map<uint32_t, xkb_keysym_t>& scancode_to_keysym) const;
+
+    private:
+        /// The keymap currently in use for this device, used to detect keymap
+        /// changes and rebuild compiled_keymap/state when they occur.
+        std::shared_ptr<mir::input::Keymap> current_keymap;
+
+        /// The compiled keymap and live XKB state, kept in sync with every
+        /// key event so that modifier state is accurate for keysym queries.
+        std::unique_ptr<xkb_keymap, void(*)(xkb_keymap*)> compiled_keymap{nullptr, xkb_keymap_unref};
+        std::unique_ptr<xkb_state, void(*)(xkb_state*)> state{nullptr, xkb_state_unref};
+    };
+
+    struct DeviceState
+    {
+        /// Maps each currently-pressed scancode to the keysym that was recorded
+        /// when it was pressed (updated on shift-state transitions).
+        std::unordered_map<uint32_t, xkb_keysym_t> scancode_to_keysym;
+        MirInputEventModifiers shift_state{0};
+        XkbKeyState xkb_key_state;
+    };
+
+    /// Shared XKB context — one per tracker, reused across all devices.
+    std::unique_ptr<xkb_context, void(*)(xkb_context*)> context;
+
+    std::unordered_map<MirInputDeviceId, DeviceState> device_states;
+};
+}
+}
+
+
+#endif

tests/unit-tests/frontend_wayland/CMakeLists.txt

@@ -5,6 +5,7 @@ list(
   ${CMAKE_CURRENT_SOURCE_DIR}/test_desktop_file_manager.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/test_g_desktop_file_cache.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/test_output_manager.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/test_keyboard_state_tracker.cpp
 )
 
 set(UNIT_TEST_SOURCES ${UNIT_TEST_SOURCES} PARENT_SCOPE)