[Feature request] Add Caps Word as a Vial feature.

[getreuer]

Overview

Caps Word has been available as a core QMK feature since 2022 and available in Oryx since 2023. It is a popular feature, especially for home row mods users to limit the need to hold Shift.

It would be great for Vial's users to expose Caps Word in the Quantum tab. I am interested to contribute PRs to making that happen, but I need help on clarifying the right approach. That's what I hope to discuss in this issue. Or if not here, let me know where better to discuss this.

Outline

Here is an outline of how I think a "Caps Word" button could be added in Vial:

1. In vial-kb/vial-gui, define the Caps Word keycode "CW_TOGG" (= 0x7C73 in Vial's v6 keycodes) in src/main/python/keycodes/.

2. Add "CW_TOGG" to KEYCODES_QUANTUM in src/main/python/keycodes/keycodes.py. Then (?), Caps Word will appear as an available button under Vial's Quantum tab.

3. In vial-kb/vial-qmk, enable Caps Word in the keyboard firmware. This would (?) be done independently for each keyboard that opts to do so by adding "CAPS_WORD_ENABLE = yes" in <keyboard>/keymaps/vial/rules.mk.

4. In vial-kb/vial-kb.github.io, document the Caps Word feature (perhaps?).

Questions

Keycode CW_TOGG would of course only work where the firmware was built with CAPS_WORD_ENABLE = yes. How to handle this consistently between the keyboard and GUI? Does Vial enable certain features by default for all keyboards, rather than what I said in (3) above with enabling per keyboard? Or is there a protocol for the keyboard to communicate to the GUI which features it has been built with so that disabled keycodes can be hidden, anything like this?

Is it relevant to update only the v6 keycodes? Or do people still build Vial firmware using the v5 keycodes? CW_TOGG did exist prior to QMK's refactoring to data-defined keycodes, which I think is what Vial's v5 keycodes refer to.

Does the above outline need anything further? Let me know what else I'm missing.

Thanks for your help!

[xyzz]

Thanks for filing this issue, I really appreciate the amount of research you've done already here and here's to answer some questions and comment on the other pieces:

In vial-kb/vial-qmk, enable Caps Word in the keyboard firmware. This would (?) be done independently for each keyboard that opts to do so by adding "CAPS_WORD_ENABLE = yes" in /keymaps/vial/rules.mk.

Generally Vial policy is to enable every feature by default and then it can be disabled for keyboards in the repo that run out of memory

In vial-kb/vial-kb.github.io, document the Caps Word feature (perhaps?).

That's not really required, people can refer to QMK docs.

Or is there a protocol for the keyboard to communicate to the GUI which features it has been built with so that disabled keycodes can be hidden, anything like this?

This isn't in place yet, but it really should be - I'm thinking we should stuff bits in the dynamic_vial_get_number_of_entries message since it's semantically the same thing even though it's talking about "number of entries" https://github.com/vial-kb/vial-qmk/blob/1c129915f059c004155a3e69df9068089ca753bb/quantum/vial.c#L222 e.g. starting from msg[3] here you can put the least significant bit for whether CAPS_WORD is enabled and we can add more on top in the future.

Is it relevant to update only the v6 keycodes? Or do people still build Vial firmware using the v5 keycodes? CW_TOGG did exist prior to QMK's refactoring to data-defined keycodes, which I think is what Vial's v5 keycodes refer to.

There's no need to put the new keycode into v5 in this case, but keep in mind that v5 firmware should still work (i.e. vial gui shouldn't throw exceptions when a v5 keyboard is connected).

There's unfortunately a lot of nastiness in the keycode stuff as keycodes were implemented as a global originally but now we of course understand they belong to the keyboard so there's a ton of hacks that attempt to dynamically keep these global arrays up to date based on which keyboard version is connected & what features it has (like number of layers or tapdances). Ideally eventually it should be refactored, but it's of course not a burden I'd put on contributors so if you can get that feature in place in a way that doesn't make the rest of the gui keycode mess collapse on itself then that's just fine.