[Feature Pitch] Key Overrides

[JonasGessner]

I have been working on a feature I call 'key override' over on my fork of QMK. I think it could be an interesting addition to the main repo that a lot of people would love to use.

Feature Request Type

• Core functionality
• Add-on hardware support (eg. audio, RGB, OLED screen, etc.)
• Alteration (enhancement/optimization) of existing feature(s)
• New behavior

Description

This feature is already implemented. View the diff here.

See the draft of the documentation here.

The feature works as follows: You can define custom actions for arbitrary modifier+key combinations: if modifiers x + key y are pressed, send modifiers w + key z instead of modifiers x + key y. This feature basically gives you the power of layers without having to use dedicated layer keys, allowing you to use modifier keys instead.

A very simple example of one way I apply this feature: On my keyboard I use a key override that sends the delete key when shift + backspace is pressed.

When the necessary keys are pressed (in the above example: shift + backspace), the override is 'activated' and the override key (+ optionally extra modifiers) is sent in the keyboard report (delete), while the trigger key (backspace) is removed from the keyboard report. The trigger modifiers may be removed from the keyboard report upon activation of an override (customizable, in this example shift is removed from the report). The override is 'deactivated' in certain customizable situations, like when one of the trigger keys (shift or backspace) is lifted. The override key is then removed from the keyboard report and whichever keys are still held down may be re-added to the keyboard report (this is customizable).

Some more examples where I use this feature:

• I have a 65% board, so the ^ key, which in the German layout is usually left of the 1, is taken up by the esc key. Hence I have an override that maps the combination ctrl + esc to ^. The shifted version of this key types °, which works with this key override too: press ctrl + shift + esc to type °. Key overrides make the grave escape feature obsolete and even overcome the caveats of the grave escape feature.
• I have dedicated vol up/down keys, but no dedicated brightness up/down keys. Ctrl + vol up does brightness up, alt + vol up does a small increment of vol up, ctrl + alt + vol up does a small increment of brightness up. Same for vol/brightness down.
• I also have a 'next track' key, but no 'previous track' key. Ctrl + 'next track' does 'previous track'.

See below for a more complex example.

I only have one fn key on my keyboard (due to space limitations), so instead of having to limit myself to the fn key for custom actions I can use all modifier keys (and combinations thereof) to trigger custom actions/keycodes. Moreover, one might want to change the behavior of a common shortcut (e.g. cmd/ctrl+z), and can do so purely using the key override feature rather than having to install extra software on their PC OS.

Overrides have very fine grained control: You control which modifiers need to be pressed down to activate the override, you can control exactly which modifier+key combination is sent as a replacement. You control if the override is deactivated if certain other keys are pressed down while the override is active, and more.

It seems there is a lot of demand for this type of feature (see here, here, here, #108, #1495), but no solid solution has yet been implemented (#2900, #4795). I think my implementation of key overrides covers a lot of use cases by being very flexible, yet easy to use for beginners, while also being well engineered and tested.

Difference to Combos

The two main differences to combos are the following:

1. There is no tapping term involved. The key combinations do not need to be pressed within a small period of time. Instead, since it relies on modifiers, it works like normal keyboard shortcuts: E.g. hold down control, and eventually press another key to do action x.
2. It is mainly focused on modifier + key combinations (although it can also create custom actions for a single key press without modifiers). This feature cannot be used to create a custom action for when two or more basic keys are held down simultaneously — this is what combos should be used for.

In addition, with the fine grained options for when an override is activated and deactivated, this feature really gives you maximum control over overrides in a way what combos does not.

Implementation

This feature is already implemented in my fork, and is already quite clean. It is gated behind a rule KEY_OVERRIDE_ENABLE, and I tried following most conventions of other features. I have tested and refined it quite a bit over the last ~6 months, but it is certainly not perfect and I would still need to write docs, perhaps unit tests, etc before it could go into the main repo I am deliberately not opening a PR because I first want to hear the reactions to this pitch.

A clean diff of mainline QMK <-> my fork can be viewed here. The feature is mostly implemented in the files key_override.h/c, with small supporting modifications in core QMK/TMK files.

The code includes a few changes in the QMK/TMK core, most notably adding a new bitfield of weak modifiers used exclusively for overrides, and a bit field of suppressed mods, which is used to eliminate modifiers that are held down from the keyboard report (see here). This is to be able to replace arbitrary modifier+key combinations that are physically held down with other arbitrary modifier+key combinations part of an override.

Overrides are defined as structs that are pointed to from an array containing all active overrides. The fields of the key_override_t struct are well documented in the file key_override.h. See below for an example.

Examples

My use of key overrides can be seen in my keymap here, which includes all the examples mentioned here.

Here is an example of the shift + backspace = delete override, created with the macro ko_make_basic:

const key_override_t backspace_delete_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE);

// Null terminated array defines all overrides.
const key_override_t **key_overrides = (const key_override_t *[]){ &backspace_delete_override, NULL };

To simplify the creation of key overrides, the macros ko_make_xxx exist, which simplify the creation of key overrides by not having to create the full key_override_t struct with all its fields manually. For the simpler macros, like ko_make_basic, the most 'standard' options are used. Most people would not have to come to grips with all the options of a key override and could rely on the simple macros, while advanced users can tinker and fine-tune as much as they want by manually defining a key_override_t struct.

Complex Example

Perhaps the most complex example is this: I use a German layout, so I have umlaut keys (ö, ä and ü) in the places where UK/US keyboards have braces/brackets. Brackets are hidden somewhere in alt + number combinations in the German layout, which can be quite inconvenient to reach when having to type many brackets while programming. I rarely use umlauts when I program, so I use key overrides to map brackets to these keys. Using the key override feature I map the ö and ä key to { and } (when no modifiers are pressed!). When shift is held these keys type [ and ]. When control is held they go back to their normal state of ö and ä, even when other modifiers are held (like shift to get Ö and Ä).

This is really hard to get right because typing a {, for example, is done by sending alt + 8 in the German layout. Hence pressing the ö key sends alt + 8 in the keyboard report. Now add the shift key and using a key override, a [ is typed, which is done by sending alt + 5 in the keyboard report. Now if the ctrl key is also held down (in addition to shift and ö already being held), the ö key goes back to its original use, hence shift + ö will be sent in the keyboard report. Imagine holding ö and ä down randomly in combination with mashing and holding different modifiers repeatedly. This creates a lot of complexity in terms of transitions between active overrides. Without a careful implementation you might end up with ghosted stuck keys or wrong characters being typed. I actually tried implementing these umlaut -> bracket overrides manually using custom keycodes and handling them in process_record_user. Even after a decent amount of work I could still find edge cases where stuck or incorrect keys would be sent in the keyboard report. Using key overrides I have not encountered any seriously wrong behavior in edge cases, and the desired behavior is quite easy to define.

[ceriinas]

Though the usual approach of changing your mods to a layer key and having everything on that layer transparent or mod(key) works, I think this would be very helpful if it works with other features (intercepting tap_code and the like) and not just simple user input.

Note the existence of #4795, a much smaller and similar pull. I'm not sure what the functional differences between these two are.

[JonasGessner]

You're right about the possibility of having a layer with mod(key) for similar functionality, but these key overrides can do much more. For example doing a custom action when two modifiers are held, which already wouldn't work (or would be much harder) with the change-mod-key-to-layer-key approach. Not to mention the pain it would be to manually fill an extra layer with a mod(xxx) copies of a full keymap and keep it in sync.

This currently does not intercept stuff like tap_code, as it intercepts key presses in process_record_quantum.

Thanks for pointing to #4795, I did not know about this pull request. The PR you linked is in fact a bit slimmer than the key override feature, and it would probably be easier to use when first getting into it as it has fewer options. My implementation for key overrides started out in a similarly simple fashion. Having used and refined my code over time I found the need for all the small options that are built into it to really make it work well even in weird edge cases.

With the simplicity of #4795 comes much less power, making many of the examples I mentioned above impossible, and having many possible bugs. It seems like it does not address many edge cases I deliberately addressed in my implementation, like making sure the modifiers in the key map stay correct after deactivation, using weak modifiers which are already used in other places, leading to conflicts and more. @sigpro already addresses a lot of issues in his review on that PR. Fixing a lot of the issues in #4795 would probably result in a code that is similar in size.

For some of the functionality that would only be possible with key overrides but not #4795:
-negative_modifier_mask: 'blacklisting' certain modifiers that when pressed, deactivate an override (and prevent the override from activating, but this would be possible with a little manual work in #4795)

• Controlling whether the trigger key is re-registered on deactivation if it is still held down
• Handling cases where the necessary modifier(s) are pressed after the required basic key is already being held
• Activating a new override in the same process_record event in which a currently active override is deactivated. Or in short: allowing overrides to activate on key-up events.

Take the example of the umlaut/bracket overrides I mentioned, and the complexity involved in correctly activating and deactivating the various overrides when ö, ä and modifiers are pressed and held randomly repeatedly. Trying to recreate something like this with #4795 would not work, starting with the fact that #4795 only activates overrides on key-down events, while activating overrides on a key-up event would be necessary too. The lax handling of deregistering/registering modifiers in #4795 would become a big issue too.

Ambiguities can also be resolved very explicitly using the key overrides feature. By ambiguities I mean a case when the necessary keys for two different overrides are pressed. By using negative_mask it can be made clear which override should be activated in such cases. For example, check my overrides for vol/brightness and little vol/little brightness up. There are many key combinations that could activate several overrides, but they are disambiguated using the negative_mask. Especially on deactivation of an override, I believe #4795 could run into major trouble when there are ambiguous overrides, since it does not keep track of which override is activated.

I even went and tried the code from #4795 and could not get this simple override to work: map shift + ö to alt + 5(which would type [ for me). Here is the code I tried to use to replicate my umlaut/bracket overrides:

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    switch (keycode) {
        case DE_OE:
            return custom_keycode_on_modifiers(MOD_BIT(KC_LSFT), -1, record, A(5)) ||   // shift + ö: [
                   custom_keycode_on_modifiers(MOD_BIT(KC_LCTL), -1, record, DE_OE) ||  // ctrl + ö: ö
                   custom_keycode_on_modifiers(0, -1, record, A(8));                    // just ö: {
        case DE_AE:
            return custom_keycode_on_modifiers(MOD_BIT(KC_LSFT), -1, record, A(6)) ||  // shift + ä: ]
                   custom_keycode_on_modifiers(MOD_BIT(KC_LCTL), -1, record, DE_AE) || // ctrl + ä: ä
                   custom_keycode_on_modifiers(0, -1, record, A(9));                   // just ä: {
    }

    return true;
}

None of the specified overrides in the code snippet above work, and output looks something like this Ö∫Ö∫Ö∫Ö∫Ö∫Ö∫Ö∫Ö∫Ö including two keys being printed for one press and modifiers going crazy.

[JonasGessner]

To improve the usability of key overrides, I just added macros ko_make_xxx, of which the simplest version takes just three arguments (trigger modifiers, trigger basic key, replacement complex key). These macros expand to a key override definition using the default options. Using these macros allows a novice to easily get started with key overrides, and these macros can get you very far. Yet, an advanced user can still manually define a key_override_t struct and tinker with all its options.

With this macro, the example of shift + backspace = delete can be turned into a one-liner:

const key_override_t **key_overrides = (const key_override_t *[]){ &ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE), NULL };

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.
For maintainers: Please label with bug, in progress, on hold, discussion or to do to prevent the issue from being re-flagged.

[phntsm]

Really glad to see stale was removed from this and it appears to be in consideration. I've been searching for a way to swap parenthesis from zero and nine keys for about a month now when I have time, I like to have my number row start with zero instead of one and have just gotten by with having the parenthesis as is. While I have found a few different methods to accomplish this in a round-about way or give up and use space cadet parenthesis - this method looks absolutely perfect, as if I sent my thoughts back in time to the author and they knew just the thing to make it work hahaha
In any case, I don't know if commenting is appropriate in this forum but I just wanted to say that like many others referenced by the author, I would very much benefit from this and hope to see it integrated into QMK. Best of luck to @JonasGessner — I'm really stoked about this and really hope to be able to use this feature someday soon. Cheers!

[drashna]

Closing this.

This was added in #11422, which is merged in develop, and should be merged into master at the end of august.