kmx git

Commit	Date	Message
b21a58d0	2025-07-01T14:52:11	Add support for all level indices to LevelN constants Note that serialization must use numbers instead of names for levels > 8, to ensure backward compatibility.
e73d1a4d	2025-07-01T13:05:44	Add support for all layout indices to GroupN constants This commit enables to use the pattern `Group<INDEX>` for any valid group index `<INDEX>`. Note that the original code in xkbcomp allows constants up to `Group8`, but then will fail if the resulting group is > 4. There does not seem to be any use case for this for such “feature”; it seems rather to be a relic from times were the 4-groups limit was not hopelessly fixed in X. So for consistency in our code base, starting with this commit we now disallow `Group5`..`Group8` for keymap format v1, since it is limited to 4 groups. Also fixed a regression in the serialization of group action, when the group is relative.
84914512	2025-07-01T18:37:22	chore: Rename indexes to indices Before this commit there was a mix between the two forms. While “indexes” is correct, “indices” is more usual and also the historical form used in this project.
3d00222e	2025-06-21T18:26:34	keymap: Add option `unlockOnPress` for LatchMods() It mirrors the feature of `SetMods()`, so that `StickyKeys` can be implemented.
d192b3b6	2025-06-19T21:57:46	keymap: Add option `unlockOnPress` for SetMods() It enables e.g. to deactivate `CapsLock` on press rather than on release, as in other platforms such as Windows. It fixes a [18-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [18-year old issue]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/issues/74 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions
7a7a3b38	2024-02-14T09:47:15	keymap: Canonically map unmapped virtual modifiers Traditionally, virtual modifiers were merely name aliases for real modifiers (X core modifiers), e.g. `NumLock` was usually mapped to `Mod2` (see `modifier_map` statement). Virtual modifiers that were never mapped to a real ones had no effect on the keymap state. xkbcommon already supports the concept of “pure” virtual modifiers, i.e. virtual modifiers that are encoded using the full 32-bit range, not just the first 8 bits corresponding to the real modifiers. But until this commit, one had to declare such mapping explicitly: e.g. `virtual_modifiers M = 0x100;`. This has at least two drawbacks: - Numerical values may look quite arbitrary and are not user-friendly. It’s OK in the resulting compiled keymap, but it requires careful sync between sections when developing KcCGST files. - If the modifier is also mapped implicitly using the traditional `vmodmap`/`modifier_map`, then both mappings are OR-combined. This patch enables to automatically map unmapped virtual modifiers to their canonical mapping, i.e. themselves: their corresponding virtual and real modifier masks are identical: `1u << mod_index`. Since this feature is incompatible with X11, this is guarded by requiring at least keymap text format v2. Note that for now, canonical virtual modifiers cannot be used in an interpret action’s `AnyOf()`. An interpret action for a canonical virtual modifier must be `AnyOfOrNone()` to take effect: virtual_modifiers APureMod, …; interpret a+AnyOfOrNone(all) { virtualModifier= APureMod; action= SetMods(modifiers=APureMod); }; The above adds a virtual modifier `APureMod` for keysym `a`. It will be canonical iff it is not mapped implicitly.
69c3d257	2025-06-17T16:43:05	keymap: Add parameter `latchOnPress` for LatchMods() Some keyboard layouts use `ISO_Level3_Latch` or `ISO_Level5_Latch` to define “built-in” dead keys: - they do not rely on the installation of custom Compose file; - they do not clash with other layouts. However, layout projects usually want the exact same behavior on all OS, but the XKB latch behavior (often misunderstood) also acts as a set modifier, which is not expected. The usual behavior of a dead key on Linux, macOS and Windows is: - latch on press; - deactivate as soon as another (non-modifier) key is pressed. Added the parameter `latchOnPress` to `LatchMods()` to enable the aforementioned behavior. As it is incompatible with X11, this feature is available only using the keymap text format v2. [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions
c58c7df1	2025-06-17T21:05:08	Serialize multiple actions per level to VoidAction() in v1 format When using `XKB_KEYMAP_FORMAT_TEXT_V1`, multiple actions per level are now serialized using `VoidAction()`, in order to maintain compatibility with X11.
ee50e0c9	2025-06-12T20:14:50	keymap: Add option `unlockOnPress` for LockMods() It enables e.g. to deactivate CapsLock on press rather than on release, as in other platforms such as Windows. The specification of `LockMods()` is changed to: - On key press: - If `unlockOnPress` is true and some of the target modifiers were locked before the key press, then unlock them if `noUnlock` false. - Otherwise: - add target modifiers to depressed modifiers; - if `noLock` is false, add target modifiers to the locked modifiers. - On key release: - If `unlockOnPress` is true and triggered unlocking on key press, do nothing. - Otherwise: - remove modifiers from the depressed modifiers, if no other key that affect the same modifiers is down; - if `noUnlock` is false and if any target modifiers was locked before the key press, unlock them. It fixes a [12-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [12-year old issue]: https://gitlab.freedesktop.org/xorg/xserver/-/issues/312 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions
d9d82355	2025-06-12T09:13:27	keymap: Add option `lockOnRelease` for LockGroup() It enables to use e.g. the combination `Control + Shift` alone to switch layouts, while keeping the use of `Control + Shift + other key` (typically for keyboard shortcuts). The specification of `LockGroup()` is changed to: - On key press: - If `lockOnRelease` is set, then key press has no effect. - Otherwise: - if the `group` is absolute, key press sets the locked keyboard group to `group`; - otherwise, key press adds `group` to the locked keyboard group. In either case, the resulting locked and effective group is brought back into range depending on the value of the `GroupsWrap` control for the keyboard. - On key release: - If `lockOnRelease` is not set, then key release has no effect. - Otherwise, if any other key was pressed after the locking key, then key release has no effect. - Otherwise, it has the same effect than a key press without `lockOnRelease` set. This is really useful for people coming from other platforms, such as Windows. It fixes a [20-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [20-year old issue]: https://gitlab.freedesktop.org/xorg/xserver/-/issues/258 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions
f7a61da7	2025-06-10T17:33:24	doc: Update new layout count ranges
6d67bce5	2025-06-08T10:01:02	doc: Towards and exhaustive compatibility page We need to track the compatibility with X11 with as much details as possible: - Transparency; - Facilitate answering issues by just pointing to the relevant page item; - Efficient reference documentation for development.
27ba56ae	2025-05-07T10:55:24	doc: Add initial documention for XKB_KEYMAP_FORMAT_TEXT_V2
66f71890	2025-03-31T08:01:29	symbols: Enable writing keysyms list as UTF-8 strings Each Unicode code point of the string will be translated to their respective keysym, if possible. An empty string denotes `NoSymbol`. When such conversion is not possible, this will raise a syntax error. This introduces the following syntax: ```c // Empty string = `NoSymbol` key <1> {[""]}; // NoSymbol // Single code point = single keysym key <2> {["é"]}; // eacute // String = translate each code point to their respective keysym key <3> {["sßξك🎺"]}; // {s, ssharp, Greek_xi, Arabic_kaf, U1F3BA} // Mix string and keysyms key <4> {[{"ξ", Greek_kappa, "β"}]}; // { Greek_xi, Greek_kappa, Greek_beta} ``` It can also be used wherever a keysym is required, e.g. in `interpret` and `modifier_map` statements. In these cases a single keysym is expected, so the string should contain exactly one Unicode code point.
8594adc4	2025-03-31T13:52:36	doc: Mention that `alternate` merge mode is not supported
343c49cc	2025-03-30T09:54:02	doc: Optional components
23598fa1	2025-03-25T22:52:06	Enable merge mode “replace” in include statements Previously only the merge modes “override” and “augment” were available in include statements, using the prefix ‘+’ and ‘\|’ respectively. While on one hand `replace` include statement can be used in keymap files, on the other hand rules files have no way to express the replace mode. This commit enables the merge mode “replace” using the prefix `^`. This prefix was chosen due to its similarity with the `XOR` bit operator, which convey mutual exclusion. Other candidates: - `!` conveys some kind of higher precedence, akin to CSS `!important`. But it conflicts with the section header `!`, which is a token in the current parser. It would require special handling, not worth it. It also convey the meaning of negation, which is confusing. - `&` has the advantage of not corresponding to a token in the rules parser. `^` seems however to stand out more and it is less likely to trigger erroneous comparison with `\|` and `&` bit operators.
6fc6e64b	2025-03-26T10:35:22	rules: Added extended wild cards <none>, <some> and <any> Added the following wild cards to the rules file syntax, in addition to the current `` legacy wild card: - `<none>`: Match empty* value. - `<some>`: Match non-empty value. - `<any>`: Match any (optionally empty) value. Its behavior does not depend on the context, contrary to the legacy wild card ``. This will enable writing much simpler rules, see [!764] for an example of tricky rules in the `xkeyboard-config` project, that would benefit from the new wild cards. [!764]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/merge_requests/764 The verbose wild cards are preferred to single characters: - More intuitive: self-explanatory. - Does not steal syntax from other token. - Extensible syntax, should we need it. A previous proposal used the characters (`!`, `+`, `?`) for their similarity with the corresponding syntax of regular expressions (negative assertion & quantifiers), in line with ``. But `!` is not that intuitive after all and conflict with its role as section header. Furthermore, `+` is also used as a merge mode. Finally, nothing beats whole short words for readability.
ecde6ade	2025-03-28T10:31:28	doc: Document floating-point parsing difference with Xorg xkbcomp
7697c712	2024-09-16T16:09:11	rules: Resolve relative include statements using XKB paths Contrary to keymap files, the `! include` statement in rules does not lookup include paths added to `xkb_context`. So it is not possible e.g. to import another file in the same folder without using an absolute path. - Added path utils: `is_absolute(path)`. - Added XKB paths lookup to enable e.g. `! include evdev` to work. - Added test.
fc664cf1	2023-05-13T05:30:11	Improve documentation - Add introduction to XKB - Embrace Doxygen features - More cross links

b21a58d0

2025-07-01T14:52:11

Add support for all level indices to LevelN constants Note that serialization must use numbers instead of names for levels > 8, to ensure backward compatibility.

e73d1a4d

2025-07-01T13:05:44

Add support for all layout indices to GroupN constants This commit enables to use the pattern `Group<INDEX>` for any valid group index `<INDEX>`. Note that the original code in xkbcomp allows constants up to `Group8`, but then will fail if the resulting group is > 4. There does not seem to be any use case for this for such “feature”; it seems rather to be a relic from times were the 4-groups limit was not hopelessly fixed in X. So for consistency in our code base, starting with this commit we now disallow `Group5`..`Group8` for keymap format v1, since it is limited to 4 groups. Also fixed a regression in the serialization of group action, when the group is relative.

84914512

2025-07-01T18:37:22

chore: Rename indexes to indices Before this commit there was a mix between the two forms. While “indexes” is correct, “indices” is more usual and also the historical form used in this project.

3d00222e

2025-06-21T18:26:34

keymap: Add option `unlockOnPress` for LatchMods() It mirrors the feature of `SetMods()`, so that `StickyKeys` can be implemented.

d192b3b6

2025-06-19T21:57:46

keymap: Add option `unlockOnPress` for SetMods() It enables e.g. to deactivate `CapsLock` *on press* rather than on release, as in other platforms such as Windows. It fixes a [18-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [18-year old issue]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/issues/74 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions

7a7a3b38

2024-02-14T09:47:15

keymap: Canonically map unmapped virtual modifiers Traditionally, *virtual* modifiers were merely name aliases for *real* modifiers (X *core* modifiers), e.g. `NumLock` was usually mapped to `Mod2` (see `modifier_map` statement). Virtual modifiers that were never mapped to a real ones had no effect on the keymap state. xkbcommon already supports the concept of “pure” virtual modifiers, i.e. virtual modifiers that are *encoded* using the full 32-bit range, not just the first 8 bits corresponding to the real modifiers. But until this commit, one had to declare such mapping *explicitly*: e.g. `virtual_modifiers M = 0x100;`. This has at least two drawbacks: - Numerical values may look quite arbitrary and are not user-friendly. It’s OK in the resulting compiled keymap, but it requires careful sync between sections when developing KcCGST files. - If the modifier is *also* mapped *implicitly* using the traditional `vmodmap`/`modifier_map`, then both mappings are OR-combined. This patch enables to automatically map unmapped virtual modifiers to their *canonical* mapping, i.e. themselves: their corresponding virtual and real modifier masks are identical: `1u << mod_index`. Since this feature is incompatible with X11, this is guarded by requiring at least keymap text format **v2**. Note that for now, canonical virtual modifiers cannot be used in an interpret action’s `AnyOf()`. An interpret action for a canonical virtual modifier must be `AnyOfOrNone()` to take effect: virtual_modifiers APureMod, …; interpret a+AnyOfOrNone(all) { virtualModifier= APureMod; action= SetMods(modifiers=APureMod); }; The above adds a virtual modifier `APureMod` for keysym `a`. It will be canonical iff it is not mapped implicitly.

69c3d257

2025-06-17T16:43:05

keymap: Add parameter `latchOnPress` for LatchMods() Some keyboard layouts use `ISO_Level3_Latch` or `ISO_Level5_Latch` to define “built-in” dead keys: - they do not rely on the installation of custom Compose file; - they do not clash with other layouts. However, layout projects usually want the exact same behavior on all OS, but the XKB latch behavior (often misunderstood) also acts as a *set* modifier, which is not expected. The usual behavior of a dead key on Linux, macOS and Windows is: - latch on press; - deactivate as soon as another (non-modifier) key is pressed. Added the parameter `latchOnPress` to `LatchMods()` to enable the aforementioned behavior. As it is incompatible with X11, this feature is available only using the keymap text format v2. [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions

c58c7df1

2025-06-17T21:05:08

Serialize multiple actions per level to VoidAction() in v1 format When using `XKB_KEYMAP_FORMAT_TEXT_V1`, multiple actions per level are now serialized using `VoidAction()`, in order to maintain compatibility with X11.

ee50e0c9

2025-06-12T20:14:50

keymap: Add option `unlockOnPress` for LockMods() It enables e.g. to deactivate CapsLock on press rather than on release, as in other platforms such as Windows. The specification of `LockMods()` is changed to: - On key *press*: - If `unlockOnPress` is true and some of the target modifiers were *locked* before the key press, then unlock them if `noUnlock` false. - Otherwise: - add target modifiers to *depressed* modifiers; - if `noLock` is false, add target modifiers to the *locked* modifiers. - On key *release*: - If `unlockOnPress` is true and triggered unlocking on key press, do nothing. - Otherwise: - remove modifiers from the *depressed* modifiers, if no other key that affect the same modifiers is down; - if `noUnlock` is false and if any target modifiers was locked before the key press, *unlock* them. It fixes a [12-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [12-year old issue]: https://gitlab.freedesktop.org/xorg/xserver/-/issues/312 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions

d9d82355

2025-06-12T09:13:27

keymap: Add option `lockOnRelease` for LockGroup() It enables to use e.g. the combination `Control + Shift` *alone* to switch layouts, while keeping the use of `Control + Shift + other key` (typically for keyboard shortcuts). The specification of `LockGroup()` is changed to: - On key *press*: - If `lockOnRelease` is set, then key press has no effect. - Otherwise: - if the `group` is absolute, key press sets the *locked* keyboard group to `group`; - otherwise, key press adds `group` to the *locked* keyboard group. In either case, the resulting *locked* and *effective* group is brought back into range depending on the value of the `GroupsWrap` control for the keyboard. - On key *release*: - If `lockOnRelease` is not set, then key release has no effect. - Otherwise, if any other key was *pressed* after the locking key, then key release has no effect. - Otherwise, it has the same effect than a key press *without* `lockOnRelease` set. This is really useful for people coming from other platforms, such as Windows. It fixes a [20-year old issue] inherited from the X11 ecosystem, by extending the [XKB protocol key actions]. As it is incompatible with X11, this feature is available only using the keymap text format v2. [20-year old issue]: https://gitlab.freedesktop.org/xorg/xserver/-/issues/258 [XKB protocol key actions]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Key_Actions

f7a61da7

2025-06-10T17:33:24

doc: Update new layout count ranges

6d67bce5

2025-06-08T10:01:02

doc: Towards and exhaustive compatibility page We need to track the compatibility with X11 with as much details as possible: - Transparency; - Facilitate answering issues by just pointing to the relevant page item; - Efficient reference documentation for development.

27ba56ae

2025-05-07T10:55:24

doc: Add initial documention for XKB_KEYMAP_FORMAT_TEXT_V2

66f71890

2025-03-31T08:01:29

symbols: Enable writing keysyms list as UTF-8 strings Each Unicode code point of the string will be translated to their respective keysym, if possible. An empty string denotes `NoSymbol`. When such conversion is not possible, this will raise a syntax error. This introduces the following syntax: ```c // Empty string = `NoSymbol` key <1> {[""]}; // NoSymbol // Single code point = single keysym key <2> {["é"]}; // eacute // String = translate each code point to their respective keysym key <3> {["sßξك🎺"]}; // {s, ssharp, Greek_xi, Arabic_kaf, U1F3BA} // Mix string and keysyms key <4> {[{"ξ", Greek_kappa, "β"}]}; // { Greek_xi, Greek_kappa, Greek_beta} ``` It can also be used wherever a keysym is required, e.g. in `interpret` and `modifier_map` statements. In these cases a single keysym is expected, so the string should contain *exactly one* Unicode code point.

8594adc4

2025-03-31T13:52:36

doc: Mention that `alternate` merge mode is not supported

343c49cc

2025-03-30T09:54:02

doc: Optional components

23598fa1

2025-03-25T22:52:06

Enable merge mode “replace” in include statements Previously only the merge modes “override” and “augment” were available in include statements, using the prefix ‘+’ and ‘|’ respectively. While on one hand `replace` include statement can be used in keymap files, on the other hand *rules* files have no way to express the *replace* mode. This commit enables the merge mode “replace” using the prefix `^`. This prefix was chosen due to its similarity with the `XOR` bit operator, which convey *mutual exclusion*. Other candidates: - `!` conveys some kind of higher precedence, akin to CSS `!important`. But it conflicts with the section header `!`, which is a token in the current parser. It would require special handling, not worth it. It also convey the meaning of negation, which is confusing. - `&` has the advantage of not corresponding to a token in the rules parser. `^` seems however to stand out more and it is less likely to trigger erroneous comparison with `|` and `&` bit operators.

6fc6e64b

2025-03-26T10:35:22

rules: Added extended wild cards <none>, <some> and <any> Added the following wild cards to the rules file syntax, in addition to the current `*` legacy wild card: - `<none>`: Match *empty* value. - `<some>`: Match *non-empty* value. - `<any>`: Match *any* (optionally empty) value. Its behavior does not depend on the context, contrary to the legacy wild card `*`. This will enable writing much simpler rules, see [!764] for an example of tricky rules in the `xkeyboard-config` project, that would benefit from the new wild cards. [!764]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/merge_requests/764 The verbose wild cards are preferred to single characters: - More intuitive: self-explanatory. - Does not steal syntax from other token. - Extensible syntax, should we need it. A previous proposal used the characters (`!`, `+`, `?`) for their similarity with the corresponding syntax of regular expressions (negative assertion & quantifiers), in line with `*`. But `!` is not that intuitive after all and conflict with its role as section header. Furthermore, `+` is also used as a merge mode. Finally, nothing beats whole short words for readability.

ecde6ade

2025-03-28T10:31:28

doc: Document floating-point parsing difference with Xorg xkbcomp

7697c712

2024-09-16T16:09:11

rules: Resolve relative include statements using XKB paths Contrary to keymap files, the `! include` statement in rules does not lookup include paths added to `xkb_context`. So it is not possible e.g. to import another file in the same folder without using an absolute path. - Added path utils: `is_absolute(path)`. - Added XKB paths lookup to enable e.g. `! include evdev` to work. - Added test.

fc664cf1

2023-05-13T05:30:11

Improve documentation - Add introduction to XKB - Embrace Doxygen features - More cross links

kc3-lang/libxkbcommon/doc/compatibility.md

doc/compatibility.md

Log