xkb_machine_builder_shortcut_override_update Struct Reference

#include <xkbcommon.h>

Data Fields
uint32_t	size
xkb_layout_index_t	source
xkb_layout_index_t	target
xkb_mod_mask_t	affect_mods
xkb_mod_mask_t	mods

Detailed Description

Update a layout substitution of the shortcut layout overrides for xkb_machine_builder::xkb_machine_builder_update_shortcut_override().

When any of the specified modifiers (see mods and affect_mods) is active, the effective layout source is substituted with layout target in key processing. This ensures a consistent user experience with keyboard shortcuts across the layouts.

Example: substitute layout #0 with layout #1 when any of the modifiers Control, Alt and Super triggers shortcut overrides.

struct xkb_keymap *keymap = xkb_machine_builder_get_keymap(builder);
 
const xkb_mod_mask_t ctrl = xkb_keymap_mod_get_mask(keymap, XKB_MOD_NAME_CTRL);
const xkb_mod_mask_t alt = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_ALT);
const xkb_mod_mask_t super = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_SUPER);
const xkb_mod_mask_t mods = ctrl | alt | super;
 
const struct xkb_machine_builder_shortcut_override_update update = {
    .size = sizeof(update),
    .source = 0,
    .target = 1,
    .affect_mods = mods,
    .mods = mods,
};
const enum xkb_error_code error =
    xkb_machine_builder_update_shortcut_override(builder, &update);
if (error != XKB_SUCCESS) {
    // handle error
    assert(!"error");
}

Example: all layouts will behave as if using the first layout any of the modifiers Control, Alt and Super triggers shortcut overrides.

struct xkb_keymap *keymap = xkb_machine_builder_get_keymap(builder);
 
const xkb_mod_mask_t ctrl = xkb_keymap_mod_get_mask(keymap, XKB_MOD_NAME_CTRL);
const xkb_mod_mask_t alt = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_ALT);
const xkb_mod_mask_t super = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_SUPER);
const xkb_mod_mask_t mods = ctrl | alt | super;
 
const xkb_layout_index_t num_layouts = xkb_keymap_num_layouts(keymap);
for (xkb_layout_index_t source = num_layouts; source-- > 1;) {
    const struct xkb_machine_builder_shortcut_override_update update = {
        .size = sizeof(update),
        .source = source,
        .target = 0,
        .affect_mods = mods,
        .mods = mods,
    };
    const enum xkb_error_code error =
        xkb_machine_builder_update_shortcut_override(builder, &update);
    if (error != XKB_SUCCESS) {
        // handle error
        assert(!"error");
    }
}

Example: substitute layout #0 with #2 for modifiers Control and Alt, substitute layout #1 with #3 for modifier Super.

struct xkb_keymap *keymap = xkb_machine_builder_get_keymap(builder);
 
const xkb_mod_mask_t ctrl = xkb_keymap_mod_get_mask(keymap, XKB_MOD_NAME_CTRL);
const xkb_mod_mask_t alt = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_ALT);
const xkb_mod_mask_t super = xkb_keymap_mod_get_mask(keymap, XKB_VMOD_NAME_SUPER);
 
struct xkb_machine_builder_shortcut_override_update update = {
    .size = sizeof(update),
    .source = 0,
    .target = 2,
    .affect_mods = ctrl | alt,
    .mods = ctrl | alt,
};
enum xkb_error_code error =
    xkb_machine_builder_update_shortcut_override(builder, &update);
if (error != XKB_SUCCESS) {
    // handle error
    assert(!"error");
}
update = (struct xkb_machine_builder_shortcut_override_update) {
    .size = sizeof(update),
    .source = 1,
    .target = 3,
    .affect_mods = super,
    .mods = super,
};
error = xkb_machine_builder_update_shortcut_override(builder, &update);
if (error != XKB_SUCCESS) {
    // handle error
    assert(!"error");
}

Note

This struct uses a size-based versioning; see Extensible structure ABI contract for further details.

See also

xkb_layout_index_t

Modifiers encoding

xkb_machine_builder::xkb_machine_builder_update_shortcut_override()

Since

1.14.0

Field Documentation

size

uint32_t xkb_machine_builder_shortcut_override_update::size

Size of this structure in bytes.

See also

Extensible structure ABI contract

Since

1.14.0

source

xkb_layout_index_t xkb_machine_builder_shortcut_override_update::source

Source layout to substitute.

If set to XKB_LAYOUT_INVALID, then source and target are ignored and all the active substitution entries are modified with the other fields.

Since

1.14.0

target

xkb_layout_index_t xkb_machine_builder_shortcut_override_update::target

Target layout to substitute to source when any of the specified modifiers (see mods and affect_mods) are active.

If set to XKB_LAYOUT_INVALID or source, then the substitution is deactivated for layout source.

Since

1.14.0

affect_mods

xkb_mod_mask_t xkb_machine_builder_shortcut_override_update::affect_mods

Modifiers affected by the update, using their encoding.

If set to 0, then affect_mods and mods are ignored.

See mods.

Since

1.14.0

mods

xkb_mod_mask_t xkb_machine_builder_shortcut_override_update::mods

Modifiers triggering the layout substitution, using their encoding.

• If there was no previous mapping (source, target):
  • Modifiers in both affect_mods and mods are set.
• Otherwise:
  • Previous modifiers in affect_mods but not in mods are cleared.
  • Previous modifiers outside affect_mods are left unchanged.
  • Modifiers in affect_mods and mods but not in previous modifiers are added.

Since

1.14.0

---

The documentation for this struct was generated from the following file:

• include/xkbcommon/xkbcommon.h