Shortcut tweak v3

changes/api/+753.feature.md

@@ -0,0 +1,19 @@
+Added options to configure the active layout when specific modifiers are active,
+enabling controlling which layout is used with keyboard shortcuts.
+
+Examples of use cases (they may overlap):
+- Latin shortcuts for non-Latin layouts
+- Qwerty/Qwertz/Azerty/etc. shortcuts for non-standard Latin layouts
+- Shortcuts independent of the active layout in setups with multiple layouts
+
+It works by specifying:
+- A *modifier mask* to watch, typically `Control`, `Alt` and `Super`.
+- A *mapping*: source layout → target shortcuts layout.
+
+Then whenever the active modifiers contain *some* of the modifiers of the mask
+defined hereinabove, the active layout is switched to the target layout defined
+in the mapping, if any, otherwise it is left unchanged.
+
+Added API:
+- `xkb_state_machine_options::xkb_state_machine_options_shortcuts_update_mods()`
+- `xkb_state_machine_options::xkb_state_machine_options_shortcuts_set_mapping()`

include/xkbcommon/xkbcommon.h

@@ -2114,6 +2114,45 @@ xkb_state_machine_options_update_a11y_flags(
     enum xkb_state_accessibility_flags flags
 );
 
+/**
+ * Set the modifiers that trigger keyboard shortcuts tweak.
+ *
+ * @param options The state options object to modify.
+ * @param affect  See @p mask.
+ * @param mask    Modifiers to set. Only the modifiers in @p affect
+ * are considered.
+ *
+ * @sa `xkb_state_machine_options_shortcuts_set_mapping()`
+ * @since 1.14.0
+ * @memberof xkb_state_machine_options
+ */
+XKB_EXPORT int
+xkb_state_machine_options_shortcuts_update_mods(
+    struct xkb_state_machine_options* restrict options,
+    xkb_mod_mask_t affect, xkb_mod_mask_t mask
+);
+
+/**
+ * Set layout mapping for keyboard shortcuts tweak.
+ *
+ * Enable tweaking keyboard shortcuts by switching the effective layout when
+ * any modifier set by `xkb_state_machine_options_shortcuts_update_mods()`
+ * is active.
+ *
+ * @param options The state options object to modify.
+ * @param source  Source layout.
+ * @param target  Target layout.
+ *
+ * @sa `xkb_state_machine_options_shortcuts_update_mods()`
+ * @since 1.14.0
+ * @memberof xkb_state_machine_options
+ */
+XKB_EXPORT int
+xkb_state_machine_options_shortcuts_set_mapping(
+    struct xkb_state_machine_options* restrict options,
+    xkb_layout_index_t source, xkb_layout_index_t target
+);
+
 /**
  * @struct xkb_event
  * Opaque keyboard state event object.