[Core] Add Caps Word feature to core

[getreuer]

Description

This PR adds a new "Caps Word" feature to core, basically, a Caps Lock that turns off when the next work-breaking letter is typed. I previously published a userspace implementation of this at

https://github.com/getreuer/qmk-keymap

Of all the features in that repo, most of the feedback I hear is about Caps Word. People especially like how Caps Word can be used without a dedicated key, using left+right shift to turn it on. Of course, users could have made an effect like this with a combo, but the attractive thing is Caps Word comes "out of the box" with this working.

Thanks to @drashna for encouraging me to make Caps Word a core QMK feature.

Compared to my userspace implementation linked above, there are some minor changes:

• While the left+right shift activation is hardcoded in the userspace implementation, I change it to a config option (BOTH_SHIFTS_TURNS_ON_CAPS_WORD). This gives flexibility to users who might want to use left+right shift for another purpose.

• I added an option to turn on Caps Word by double-tapping left shift (DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD). An effect like this could have been done with a tap dance, but again, the point is having a few easy options that don't require figuring out other QMK features.

• Idle timeout is done by default, turning off Caps Word after 5 seconds. I've found this timeout helpful since sometimes I forget that I'm leaving Caps Word active.

• I renamed some APIs to try to match the conventions of existing QMK features.

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[drashna]

Oh, one concern here, is that if the COMMAND feature is enabled, by default it uses both shifts as well. That may cause overlap here. it may be worth checking if command is enabled, and if IS_COMMAND is set to both shifts.

Eg, the default is:

#    define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)

[getreuer]

Oh, one concern here, is that if the COMMAND feature is enabled, by default it uses both shifts as well. That may cause overlap here. it may be worth checking if command is enabled, and if IS_COMMAND is set to both shifts.

Thanks for pointing this out! Having both features use the same key combination could lead to confusing behavior, plus, many keyboards have Command enabled by default. This could be a common problem for people to fall into without even being aware what Command is.

Unfortunately with the limitations of the C preprocessor, it isn't possible to test at compile time what IS_COMMAND() is defined as. But what we can do is test whether config.h left it undefined, meaning Command uses the default Left Shift + Right Shift key combination. I added a check with the form

#if defined(COMMAND_ENABLED) && !defined(IS_COMMAND)
#error "(link to documentation section explaining the error)."
#endif

[precondition]

The other day, someone on the QMK discord asked if there was a split data sync option allowing the use of is_caps_word_on() on the slave side in order to display that info on their OLED screen. Since your implementation relies on shifts instead of caps lock, it is not as if users could query the pre-existing HID caps lock host LED status. In the end, we solved the problem with a bit of custom code by sending and receiving a boolean variable "caps_word_status" using transaction_rpc_send and transaction_rpc_recv in housekeeping_task_user, as explained in the section on custom data sync but a built-in option would have clearly been simpler than the relatively complex user code necessary for custom data sync.

Food for thought.

[filterpaper]

I have also noticed a number of similar caps word code implemented with Shift mod instead of caps lock. Are there use-cases where Shift is preferred over caps lock?

[drashna]

You could, in theory, still query the mod status, though.

And to be honest, a custom data struct would be best for querying this sort of info.

As for caps lock vs shift, I think that depends on the OS being used.

[getreuer]

I have also noticed a number of similar caps word code implemented with Shift mod instead of caps lock. Are there use-cases where Shift is preferred over caps lock?

This comes out of my use case, though I suspect it is fairly common among laptop users who use Emacs or Vim. I use a laptop and switch between typing on the integrated keyboard and a QMK-powered external keyboard. For using the integrated keyboard with Vim, I have remapped KC_CAPS at the OS level to Esc. Unfortunately, this means existing Caps Word implementations using KC_CAPS won't capitalize as intended. My initial motivation with writing a Caps Word implementation was to get around this for something that works with this configuration.

[getreuer]

The other day, someone on the QMK discord asked if there was a split data sync option allowing the use of is_caps_word_on() on the slave side in order to display that info on their OLED screen. Since your implementation relies on shifts instead of caps lock, it is not as if users could query the pre-existing HID caps lock host LED status. In the end, we solved the problem with a bit of custom code by sending and receiving a boolean variable "caps_word_status" using transaction_rpc_send and transaction_rpc_recv in housekeeping_task_user, as explained in the section on custom data sync but a built-in option would have clearly been simpler than the relatively complex user code necessary for custom data sync.

Food for thought.

Thanks, these are great points! Data sync hadn't occurred to me, and I agree this is worth working out. I'll read up on this on the links you shared.

[drashna]

Also, should be noted that Mac's are a bit ... finicky about caps lock, too.

I was thinking that maybe have caps lock as an option, but ... on second though, I think actively avoiding using caps lock is probably the right decision. It's a key that has too many oddities to be safe to use.

[filterpaper]

Thank you @getreuer for sharing the use-cases for this implementation.

[drashna]

Oh, one last thing. info.json support for the feature would be awesome.

For reference, just added this to the autocorrect PR, and you can see that here:
695779a

Or for a more in depth example:
92a61aa

[getreuer]

Oh, one last thing. info.json support for the feature would be awesome.

For reference, just added this to the autocorrect PR, and you can see that here: 695779a

Or for a more in depth example: 92a61aa

Done! Thanks for the examples, these were very helpful.

[getreuer]

Oops, I thought I was closing a thread, but closed the PR. Reopening...