state: add server API for updating latched and locked mods & layout

wismill · bluetech · wismill · commit 341a4909af7b · 2025-05-09T01:30:35.000+02:00
Up to now, the “server state” `xkb_state` API only offered one entry point to update the server state – `xkb_state_update_key`, which reflects the direct keyboard keys state. But some updates come out-of-band from keyboard input events stream, for example, a GUI layout switcher. The X11 XKB protocol has a request which allows for such updates, `XkbLatchLockState`[^1], but xkbcommon does not have similar functionality. So server applications ended up using `xkb_state_update_state` for this, but that’s a function intended for client applications, not servers. Add support for updating the latched & locked state of the mods and layout. Note that the depressed states cannot be updated in this way -- XKB does not expect them to be updated out of band. [^1]: https://www.x.org/releases/X11R7.7/doc/kbproto/xkbproto.html#Querying_and_Changing_Keyboard_State Fixes: #310 Signed-off-by: Ran Benita <ran@unusedvar.com> Co-authored-by: Ran Benita <ran@unusedvar.com> Co-authored-by: Pierre Le Marre <dev@wismill.eu>
diff --git a/include/xkbcommon/xkbcommon.h b/include/xkbcommon/xkbcommon.h
@@ -1520,6 +1520,63 @@ XKB_EXPORT enum xkb_state_component
 xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
                      enum xkb_key_direction direction);
 
+/**
+ * Update the keyboard state to change the latched and locked state of
+ * the modifiers and layout.
+ *
+ * This entry point is intended for *server* applications and should not be used
+ * by *client* applications; see @ref server-client-state for details.
+ *
+ * Use this function to update the latched and locked state according to
+ * “out of band” (non-device) inputs, such as UI layout switchers.
+ *
+ * @par Layout out of range
+ * @parblock
+ *
+ * If the effective layout, after taking into account the depressed, latched and
+ * locked layout, is out of range (negative or greater than the maximum layout),
+ * it is brought into range. Currently, the layout is wrapped using integer
+ * modulus (with negative values wrapping from the end). The wrapping behavior
+ * may be made configurable in the future.
+ *
+ * @endparblock
+ *
+ * @param state The keyboard state object.
+ * @param affect_latched_mods
+ * @param latched_mods
+ *     Modifiers to set as latched or unlatched. Only modifiers in
+ *     `affect_latched_mods` are considered.
+ * @param affect_latched_layout
+ * @param latched_layout
+ *     Layout to latch. Only considered if `affect_latched_layout` is true.
+ *     Maybe be out of range (including negative) -- see note above.
+ * @param affect_locked_mods
+ * @param locked_mods
+ *     Modifiers to set as locked or unlocked. Only modifiers in
+ *     `affect_locked_mods` are considered.
+ * @param affect_locked_layout
+ * @param locked_layout
+ *     Layout to lock. Only considered if `affect_locked_layout` is true.
+ *     Maybe be out of range (including negative) -- see note above.
+ *
+ * @returns A mask of state components that have changed as a result of
+ * the update.  If nothing in the state has changed, returns 0.
+ *
+ * @memberof xkb_state
+ *
+ * @sa xkb_state_update_mask()
+ */
+XKB_EXPORT enum xkb_state_component
+xkb_state_update_latched_locked(struct xkb_state *state,
+                                xkb_mod_mask_t affect_latched_mods,
+                                xkb_mod_mask_t latched_mods,
+                                bool affect_latched_layout,
+                                int32_t latched_layout,
+                                xkb_mod_mask_t affect_locked_mods,
+                                xkb_mod_mask_t locked_mods,
+                                bool affect_locked_layout,
+                                int32_t locked_layout);
+
 /**
  * Update a keyboard state from a set of explicit masks.
  *
diff --git a/src/keymap-priv.c b/src/keymap-priv.c
@@ -147,8 +147,8 @@ action_equal(const union xkb_action *a, const union xkb_action *b)
         return false;
 
     /* Ensure we support all action types */
-    static_assert(ACTION_TYPE_PRIVATE == 15 &&
-                  ACTION_TYPE_PRIVATE + 1 == _ACTION_TYPE_NUM_ENTRIES,
+    static_assert(ACTION_TYPE_INTERNAL == 16 &&
+                  ACTION_TYPE_INTERNAL + 1 == _ACTION_TYPE_NUM_ENTRIES,
                   "Missing action type");
 
     switch (a->type) {
@@ -188,6 +188,9 @@ action_equal(const union xkb_action *a, const union xkb_action *b)
                 a->ctrls.ctrls == b->ctrls.ctrls);
     case ACTION_TYPE_PRIVATE:
         return (a->priv.data == b->priv.data);
+    case ACTION_TYPE_INTERNAL:
+        return (a->internal.flags == b->internal.flags) &&
+               (a->internal.clear_latched_mods == b->internal.clear_latched_mods);
     default:
         assert(!"Unsupported action");
         return false;
diff --git a/src/keymap.h b/src/keymap.h
@@ -92,6 +92,7 @@ enum xkb_action_type {
     ACTION_TYPE_CTRL_SET,
     ACTION_TYPE_CTRL_LOCK,
     ACTION_TYPE_PRIVATE,
+    ACTION_TYPE_INTERNAL, /* Action specific and internal to xkbcommon */
     _ACTION_TYPE_NUM_ENTRIES
 };
 
@@ -189,6 +190,21 @@ struct xkb_private_action {
     uint8_t data[7];
 };
 
+enum xkb_internal_action_flags {
+    INTERNAL_BREAKS_GROUP_LATCH = (1 << 0),
+    INTERNAL_BREAKS_MOD_LATCH = (1 << 1),
+};
+
+/* Action specific and internal to xkbcommon */
+struct xkb_internal_action {
+    enum xkb_action_type type;
+    enum xkb_internal_action_flags flags;
+    union {
+        /* flag == INTERNAL_BREAKS_MOD_LATCH */
+        xkb_mod_mask_t clear_latched_mods;
+    };
+};
+
 union xkb_action {
     enum xkb_action_type type;
     struct xkb_mod_action mods;
@@ -199,6 +215,7 @@ union xkb_action {
     struct xkb_pointer_action ptr;
     struct xkb_pointer_button_action btn;
     struct xkb_private_action priv;
+    struct xkb_internal_action internal;
 };
 
 struct xkb_key_type_entry {
diff --git a/src/state.c b/src/state.c
@@ -295,7 +295,9 @@ xkb_filter_group_lock_func(struct xkb_state *state,
 }
 
 static bool
-xkb_action_breaks_latch(const union xkb_action *action)
+xkb_action_breaks_latch(const union xkb_action *action,
+                        enum xkb_internal_action_flags flag,
+                        xkb_mod_mask_t mask)
 {
     switch (action->type) {
     case ACTION_TYPE_NONE:
@@ -306,6 +308,9 @@ xkb_action_breaks_latch(const union xkb_action *action)
     case ACTION_TYPE_SWITCH_VT:
     case ACTION_TYPE_TERMINATE:
         return true;
+    case ACTION_TYPE_INTERNAL:
+        return (action->internal.flags & flag) &&
+               ((action->internal.clear_latched_mods & mask) == mask);
     default:
         return false;
     }
@@ -389,7 +394,8 @@ xkb_filter_group_latch_func(struct xkb_state *state,
                  */
                 continue;
             }
-            else if (xkb_action_breaks_latch(&(actions[k]))) {
+            else if (xkb_action_breaks_latch(&(actions[k]),
+                                             INTERNAL_BREAKS_GROUP_LATCH, 0)) {
                 /* Breaks the latch */
                 state->components.latched_group -= priv.group_delta;
                 filter->func = NULL;
@@ -547,9 +553,11 @@ xkb_filter_mod_latch_func(struct xkb_state *state,
                 /* XXX beep beep! */
                 return XKB_FILTER_CONSUME;
             }
-            else if (xkb_action_breaks_latch(&(actions[k]))) {
+            else if (xkb_action_breaks_latch(&(actions[k]),
+                                             INTERNAL_BREAKS_MOD_LATCH,
+                                             filter->action.mods.mods.mask)) {
                 /* XXX: This may be totally broken, we might need to break the
-                *      latch in the next run after this press? */
+                 *      latch in the next run after this press? */
                 state->components.latched_mods &= ~filter->action.mods.mods.mask;
                 filter->func = NULL;
                 return XKB_FILTER_CONTINUE;
@@ -892,6 +900,114 @@ xkb_state_update_key(struct xkb_state *state, xkb_keycode_t kc,
     return get_state_component_changes(&prev_components, &state->components);
 }
 
+/* We need fake keys for `update_latch_modifiers` and `update_latch_group`.
+ * These keys must have at least one level in order to break latches. We need 2
+ * keys with specific actions in order to update group/mod latches without
+ * affecting each other. */
+static struct xkb_key_type_entry synthetic_key_level_entry = { 0 };
+static struct xkb_key_type synthetic_key_type = {
+     .num_entries = 1,
+     .num_levels = 1,
+     .entries = &synthetic_key_level_entry
+};
+static const struct xkb_key synthetic_key = { 0 };
+
+/* Transcription from xserver: XkbLatchModifiers */
+static void
+update_latch_modifiers(struct xkb_state *state,
+                       xkb_mod_mask_t mask, xkb_mod_mask_t latches)
+{
+    /* Clear affected latched modifiers */
+    const xkb_mod_mask_t clear = mask & ~latches;
+    state->components.latched_mods &= ~clear;
+
+    /* Clear any pending latch to locks using ad hoc action:
+     * only affect corresponding modifier latches and no group latch. */
+    struct xkb_level synthetic_key_level_break_mod_latch = {
+        .num_syms = 0,
+        .num_actions = 1,
+        .upper = XKB_KEY_NoSymbol,
+        .s.sym = XKB_KEY_NoSymbol,
+        .a.action.internal = {
+            .type = ACTION_TYPE_INTERNAL,
+            .flags = INTERNAL_BREAKS_MOD_LATCH,
+            .clear_latched_mods = clear
+        }
+    };
+    struct xkb_group synthetic_key_group_break_mod_latch = {
+        .type = &synthetic_key_type,
+        .levels = &synthetic_key_level_break_mod_latch
+    };
+    const struct xkb_key synthetic_key_break_mod_latch = {
+        .num_groups = 1,
+        .groups = &synthetic_key_group_break_mod_latch
+    };
+    xkb_filter_apply_all(state, &synthetic_key_break_mod_latch, XKB_KEY_DOWN);
+
+    /* Finally set the latched mods by simulate tapping a key with the
+     * corresponding action */
+    const struct xkb_key* const key = &synthetic_key;
+    const union xkb_action latch_mods = {
+        .mods = {
+            .type = ACTION_TYPE_MOD_LATCH,
+            .mods = { .mask = mask & latches },
+            .flags = 0,
+        },
+    };
+    struct xkb_filter* const filter = xkb_filter_new(state);
+    filter->key = key;
+    filter->func = xkb_filter_mod_latch_func;
+    filter->action = latch_mods;
+    xkb_filter_mod_latch_new(state, filter);
+    /* We added the filter manually, so only fire “up” event */
+    xkb_filter_mod_latch_func(state, filter, key, XKB_KEY_UP);
+}
+
+/* Transcription from xserver: XkbLatchGroup */
+static void
+update_latch_group(struct xkb_state *state, int32_t group)
+{
+    /* Clear any pending latch to locks. */
+    static struct xkb_level synthetic_key_level_break_group_latch = {
+        .num_syms = 0,
+        .num_actions = 1,
+        .upper = XKB_KEY_NoSymbol,
+        .s.sym = XKB_KEY_NoSymbol,
+        .a.action.internal = {
+            .type = ACTION_TYPE_INTERNAL,
+            .flags = INTERNAL_BREAKS_GROUP_LATCH,
+            .clear_latched_mods = 0
+        }
+    };
+    static struct xkb_group synthetic_key_group_break_group_latch = {
+        .type = &synthetic_key_type,
+        .levels = &synthetic_key_level_break_group_latch
+    };
+    static const struct xkb_key synthetic_key_break_group_latch = {
+        .num_groups = 1,
+        .groups = &synthetic_key_group_break_group_latch
+    };
+    xkb_filter_apply_all(state, &synthetic_key_break_group_latch, XKB_KEY_DOWN);
+
+    /* Simulate tapping a key with a group latch action, but in isolation: i.e.
+     * without affecting the other filters. */
+    const struct xkb_key* const key = &synthetic_key;
+    const union xkb_action latch_group = {
+        .group = {
+            .type = ACTION_TYPE_GROUP_LATCH,
+            .flags = ACTION_ABSOLUTE_SWITCH,
+            .group = group,
+        },
+    };
+    struct xkb_filter* const filter = xkb_filter_new(state);
+    filter->key = key;
+    filter->func = xkb_filter_group_latch_func;
+    filter->action = latch_group;
+    xkb_filter_group_latch_new(state, filter);
+    /* We added the filter manually, so only fire “up” event */
+    xkb_filter_group_latch_func(state, filter, key, XKB_KEY_UP);
+}
+
 /**
  * Compute the resolved effective mask of an arbitrary input.
  *
@@ -913,6 +1029,46 @@ resolve_to_canonical_mods(struct xkb_keymap *keymap, xkb_mod_mask_t mods)
                                mods & ~keymap->canonical_state_mask);
 }
 
+enum xkb_state_component
+xkb_state_update_latched_locked(struct xkb_state *state,
+                                xkb_mod_mask_t affect_latched_mods,
+                                xkb_mod_mask_t latched_mods,
+                                bool affect_latched_layout,
+                                int32_t latched_layout,
+                                xkb_mod_mask_t affect_locked_mods,
+                                xkb_mod_mask_t locked_mods,
+                                bool affect_locked_layout,
+                                int32_t locked_layout)
+{
+    const struct state_components prev_components = state->components;
+
+    /* Update locks */
+    affect_locked_mods =
+        resolve_to_canonical_mods(state->keymap, affect_locked_mods);
+    if (affect_locked_mods) {
+        locked_mods = resolve_to_canonical_mods(state->keymap, locked_mods);
+        state->components.locked_mods &= ~affect_locked_mods;
+        state->components.locked_mods |= locked_mods & affect_locked_mods;
+    }
+    if (affect_locked_layout) {
+        state->components.locked_group = locked_layout;
+    }
+
+    /* Update latches */
+    affect_latched_mods =
+        resolve_to_canonical_mods(state->keymap, affect_latched_mods);
+    if (affect_latched_mods) {
+        latched_mods = resolve_to_canonical_mods(state->keymap, latched_mods);
+        update_latch_modifiers(state, affect_latched_mods, latched_mods);
+    }
+    if (affect_latched_layout) {
+        update_latch_group(state, latched_layout);
+    }
+
+    xkb_state_update_derived(state);
+    return get_state_component_changes(&prev_components, &state->components);
+}
+
 /**
  * Updates the state from a set of explicit masks as gained from
  * xkb_state_serialize_mods and xkb_state_serialize_groups.  As noted in the
diff --git a/test/data/rules/evdev b/test/data/rules/evdev
@@ -993,7 +993,9 @@
   grp:alt_space_toggle	=	+group(alt_space_toggle)
   grp:menu_toggle	=	+group(menu_toggle)
   grp:lwin_toggle	=	+group(lwin_toggle)
+  grp:lwin_latch	=	+group(lwin_latch)
   grp:rwin_toggle	=	+group(rwin_toggle)
+  grp:rwin_latch_lock_clear	=	+group(rwin_latch_lock_clear)
   grp:lshift_toggle	=	+group(lshift_toggle)
   grp:rshift_toggle	=	+group(rshift_toggle)
   grp:rctrl_switch	=	+group(rctrl_switch)
@@ -1146,6 +1148,7 @@
   lv3:caps_switch_latch              =       +level3(caps_switch_latch)
   lv3:bksl_switch_latch              =       +level3(bksl_switch_latch)
   lv3:lsgt_switch_latch              =       +level3(lsgt_switch_latch)
+  lv3:lsgt_latch                     =       +level3(lsgt_latch)
   lv5:lsgt_switch                 =       +level5(lsgt_switch)
   lv5:ralt_switch                 =       +level5(ralt_switch)
   lv5:lsgt_switch_lock            =       +level5(lsgt_switch_lock)
diff --git a/test/data/symbols/group b/test/data/symbols/group
@@ -34,6 +34,14 @@ xkb_symbols "lwin_switch" {
     };
 };
 
+partial modifier_keys
+xkb_symbols "lwin_latch" {
+	key <LWIN> {
+		symbols[1] = [ ISO_Group_Latch ],
+		actions[1] = [ LatchGroup(group=+1) ]
+	};
+};
+
 // The right Win key (while pressed) chooses the second keyboard group.
 // (Using this map, you should declare your keyboard as pc101 or pc102
 // instead of pc104 or pc105.)
@@ -45,6 +53,14 @@ xkb_symbols "rwin_switch" {
     };
 };
 
+partial modifier_keys
+xkb_symbols "rwin_latch_lock_clear" {
+	key <RWIN> {
+		symbols[1] = [ ISO_Group_Latch ],
+		actions[1] = [ LatchGroup(group=+1, latchToLock, clearLocks) ]
+	};
+};
+
 // The right Menu key (while pressed) chooses the second keyboard group.
 // while Shift+Menu acts as Menu.
 partial modifier_keys
diff --git a/test/data/symbols/level3 b/test/data/symbols/level3
@@ -210,6 +210,14 @@ xkb_symbols "lsgt_switch_latch" {
   include "level3(modifier_mapping)"
 };
 
+partial modifier_keys
+xkb_symbols "lsgt_latch" {
+  key <LSGT> {
+    type[Group1]="ONE_LEVEL",
+    symbols[Group1] = [ ISO_Level3_Latch ]
+  };
+};
+
 // Number key 4 chooses third shift level when pressed in isolation.
 partial modifier_keys
 xkb_symbols "4_switch_isolated" {
diff --git a/test/state.c b/test/state.c
diff --git a/test/test.h b/test/test.h
diff --git a/xkbcommon.map b/xkbcommon.map
