Support Keymap.key_get_mods_for_level()

.github/workflows/run-tests.yml

@@ -7,21 +7,18 @@ jobs:
 
     strategy:
       matrix:
-        os: ['ubuntu-20.04', 'ubuntu-22.04']
-        python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11']
-        exclude:
-          - os: 'ubuntu-22.04'
-            python-version: '3.6'
+        os: ['ubuntu-22.04']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install libxkbcommon-dev
         run: |
           sudo apt-get install libxkbcommon-dev
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

tests/test_xkb.py

@@ -252,6 +252,15 @@ def test_keymap_num_levels_for_key(self):
         key = next(iter(self.km))
         self.assertEqual(self.km.num_levels_for_key(key, 0), 1)
 
+    def test_keymap_key_get_mods_for_level(self):
+        first_invalid_mask = 1 << self.km.num_mods()
+        for key in self.km:
+            for layout in range(self.km.num_layouts_for_key(key)):
+                for level in range(self.km.num_levels_for_key(key, layout)):
+                    r = self.km.key_get_mods_for_level(key, layout, level)
+                    for mm in r:
+                        self.assertLess(mm, first_invalid_mask)
+
     def test_keymap_key_get_syms_by_level(self):
         for key in self.km:
             r = self.km.key_get_syms_by_level(key, 0, 0)

xkbcommon/ffi_build.py

@@ -1,7 +1,7 @@
 from cffi import FFI
 ffibuilder = FFI()
 
-# Currently implemented with reference to libxkbcommon-0.6.0
+# Currently implemented with reference to libxkbcommon-1.0.0
 
 ffibuilder.set_source("xkbcommon._ffi", """
 #include <stdarg.h>
@@ -253,6 +253,14 @@
 xkb_keymap_num_levels_for_key(struct xkb_keymap *keymap, xkb_keycode_t key,
                               xkb_layout_index_t layout);
 
+size_t
+xkb_keymap_key_get_mods_for_level(struct xkb_keymap *keymap,
+                                  xkb_keycode_t key,
+                                  xkb_layout_index_t layout,
+                                  xkb_level_index_t level,
+                                  xkb_mod_mask_t *masks_out,
+                                  size_t masks_size);
+
 int
 xkb_keymap_key_get_syms_by_level(struct xkb_keymap *keymap,
                                  xkb_keycode_t key,

xkbcommon/xkb.py

@@ -618,6 +618,29 @@ def num_levels_for_key(self, key, layout):
         """
         return lib.xkb_keymap_num_levels_for_key(self._keymap, key, layout)
 
+    def key_get_mods_for_level(self, key, layout, level):
+        """Retrieves every possible modifier mask that produces the specified
+        shift level for a specific key and layout.
+
+        This API is useful for inverse key transformation;
+        i.e. finding out which modifiers need to be active in order to
+        be able to type the keysym(s) corresponding to the specific
+        key code, layout and level.
+
+        If layout is out of range for this key (that is, larger or
+        equal to the value returned by Keymap.num_layouts_for_key()),
+        it is brought back into range in a manner consistent with
+        State.key_get_layout().
+        """
+        masks_size = 4
+        while True:
+            masks_out = ffi.new(f"xkb_mod_mask_t[{masks_size}]")
+            r = lib.xkb_keymap_key_get_mods_for_level(
+                self._keymap, key, layout, level, masks_out, masks_size)
+            if r < masks_size:
+                return [masks_out[n] for n in range(r)]
+            masks_size = masks_size << 1
+
     def key_get_syms_by_level(self, key, layout, level):
         """Get the keysyms obtained from pressing a key in a given layout and
         shift level.