Bilateral combinations

[DanielSincere]

Description

This PR brings @manna-harbour 's Bilateral Combinations feature. I also implemented Per Key Bilateral Combinations, as requested by @cfarvidson and others. I have updated the docs as well.

I tried to implement unit tests, and the trace's match what I expected. However, the expectation macros couldn't be convinced to pass. If you would like to see the progress tests for this feature please see my branch at https://github.com/FullQueueDeveloper/qmk_firmware/tree/bilateral_combinations_tests

Types of Changes

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

Issues Fixed or Closed by This PR

• Bilateral Combinations manna-harbour/qmk_firmware#29

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).

[filterpaper]

Add an explicit example

[zvecr]

Two different states for the same config option is probably going to make data driven config more complicated.

[manna-harbour]

Nice!

I recommend going through manna-harbour#29 and the issues linked from there. In particular, I suggest to:

• Add the flashing mods issue to the docs. See Flashing Mods manna-harbour/qmk_firmware#27.
• Start from the branch linked from Support Irregular Matrices manna-harbour/qmk_firmware#17 (comment). BILATERAL_COMBINATIONS_HANDS is a general solution to the handedness determination problem. See the rest of Support Irregular Matrices manna-harbour/qmk_firmware#17 for background.
• Remove weak bilateral_combinations_left() and BILATERAL_COMBINATIONS_COLS, also included in the BILATERAL_COMBINATIONS_HANDS branch above but originally from Add customisable hand determination manna-harbour/qmk_firmware#28. With BILATERAL_COMBINATIONS_HANDS they should be unnecessary (although they may still be a more convenient alternative for some, as they don't require the extra layer). BILATERAL_COMBINATIONS_HANDS can be used with existing layout mapping macros for userpace keymaps, so no additional customisation for different physical layouts is required in that case, whereas bilateral_combinations_left() or BILATERAL_COMBINATIONS_COLS would need to be adjusted for each physical layout.
• Implement Per-Key Customisation manna-harbour/qmk_firmware#42 instead of BILATERAL_COMBINATIONS_PER_KEY. That would mean users need only add a layer (needed anyway for BILATERAL_COMBINATIONS_HANDS above) instead of having to implement get_enable_bilateral_combinations_per_key.

Best of luck with the PR!

[zvecr]

A few notes for above, mostly on BILATERAL_COMBINATIONS_HANDS_LAYER

Using a keymap layer for configuration is very unlikely to be accepted as this does not align with the existing configuration points. Something like swap hands is probably the closer, but the existing get_enable_bilateral_combinations_per_key is fairly consistent to other features.

[manna-harbour]

A few notes for above, mostly on BILATERAL_COMBINATIONS_HANDS_LAYER

Using a keymap layer for configuration is very unlikely to be accepted as this does not align with the existing configuration points. Something like swap hands is probably the closer, but the existing get_enable_bilateral_combinations_per_key is fairly consistent to other features.

get_enable_bilateral_combinations_per_key is fine for keycode exclusion, but the main point of BILATERAL_COMBINATIONS_HANDS is matrix independent hands determination, and once you have that it can easily also accommodate exclusion. The difference in practice being that get_enable_bilateral_combinations_per_key specifies exclusions per keycode for the purpose of adding cheats, whereas doing it via BILATERAL_COMBINATIONS_HANDS specifies the key position in the keymap as the intention is to support keys that might naturally be used with either hand. Given that, it might actually be worth including both.

The current implementation was definitely a hack, but BILATERAL_COMBINATIONS_HANDS could just as well be implemented with a separate array by re-implementing keymap_key_to_keycode(). The important thing is that the keyboard (and userspace keymap mapping) layout macros can be applied directly so that everything can be specified relative to the keymap, and not to the matrix for each keyboard as is required with swap hands.

[getreuer]

I very much like the concept of Bilateral Combinations and Positional Hold and it would be fantastic to add some form of this to QMK core. I wrote a userspace library Achordion that does something similar and have some thoughts regarding interface.

I believe Bilateral Combinations' opposite hands rule for what counts as a hold is a great default. However, it is practical to make a few tweaks on top of it:

• You might want to prohibit hold behavior for certain cross-handed tap-hold key + other key chords, say because they are very common bigrams. Such bigrams are especially prevalent when using home row mods on Colemak or other alternative keyboard layouts. Precondition's home row mods guide describes how cancelling holds for specific bigrams can be useful to reduce accidental mod triggers.
• Conversely, you might want to enable hold behavior for certain same-handed tap-hold key + other key chords, say to use particular hotkeys with one hand.
• Also, you probably want to exempt some keys such as thumb keys from the opposite hands rule.

Those first two points would involve customization based on the tap-hold key + other key chord, not just the tap-hold key alone. Achordion facilitates these chord-adaptive customizations with a callback with the signature

bool achordion_chord(uint16_t tap_hold_keycode,
                     keyrecord_t* tap_hold_record,
                     uint16_t other_keycode,
                     keyrecord_t* other_record);

where returning true settles the chord as a hold and false as a tap. The user can use this callback to define tweaks on top of the opposite hands rule as described here.

Some other thoughts:

• It may be useful to customize the Bilateral Combinations timeout time individually for each tap-hold key (see achordion_timeout()).
• A big drawback with Bilateral Combinations is when holding a Shift mod-tap key + clicking the mouse to highlight something. For the Shift modifier to register, you have to first wait out the tapping term and the Bilateral Combinations timeout, which is awfully sluggish. To reduce this delay, I added an option in Achordion that modifiers may be eagerly applied.

[github-actions]

Thank you for your contribution!
This pull request has been automatically marked as stale because it has not had activity in the last 45 days. It will be closed in 30 days if no further activity occurs. Please feel free to give a status update now, or re-open when it's ready.
For maintainers: Please label with bug, awaiting review, breaking_change, in progress, or on hold to prevent the issue from being re-flagged.

[sunaku]

The "Flashing Mods" issue should be fixed in my PR for Miryoku: manna-harbour#48

[github-actions]

Thank you for your contribution!
This pull request has been automatically marked as stale because it has not had activity in the last 45 days. It will be closed in 30 days if no further activity occurs. Please feel free to give a status update now, or re-open when it's ready.
For maintainers: Please label with bug, awaiting review, breaking_change, in progress, or on hold to prevent the issue from being re-flagged.

[github-actions]

Thank you for your contribution!
This pull request has been automatically closed because it has not had activity in the last 30 days. Please feel free to give a status update now, ping for review, or re-open when it's ready.
// [stale-action-closed]

[grota]

guys, just a quick question, there is no follow up to this pr right?

I mean, I can still use it (rebasing it in my fork) but wanted to know if you were discussing the development for bilateral combinations to go in a specific direction or not.

[getreuer]

@grota right, this PR has stalled, unfortunately. As @zvecr said (and I agree), the main problem was:

Using a keymap layer for configuration is very unlikely to be accepted as this does not align with the existing configuration points. Something like swap hands is probably the closer, but the existing get_enable_bilateral_combinations_per_key is fairly consistent to other features.

If a new PR in this direction is made, it would be better to follow how swap hands configuration works.

As an alternative to modifying core, you might be interested in Achordion. It is a userspace library with behavior similar to Bilateral Combinations.