feat(behaviors): Add macro-pause-for-layer behavior

[aaronkollasch]

Description

This PR adds a macro_pause_for_layer behavior that pauses the current macro and resumes it on the next layer change.

Motivation

The callum layout has a "swap win" key that sends Cmd+Tab and holds Cmd between presses.

In ZMK, binding the "swap win" key to LG(TAB) only allows swapping between the top two windows, as Cmd is released between presses.

Solution

The macro_pause_for_layer behavior allows "swap win" to be bound to a macro that presses Cmd, taps Tab, then waits for the Nav layer to change before releasing Cmd. With this binding, Nav+"swap win" behaves similarly to Cmd+Tab on a conventional keyboard.

Unlike on_macro_binding_released(), macro_layer_state_changed_listener() does not receive the current binding to resume. Therefore, the macro_pause_for_layer behavior instead saves a queue of scheduled macro states to resume (1 for each time the macro is pressed). Then, when the layer changes, all of these states are resumed. The queue size is 16 * 8 = 128 currently 16 * 20 = 320 bytes allocated statically.

If the queue size limit is reached, any subsequent &macro_pause_for_layers are bypassed and their macros processed immediately in full. This isn't an issue for the Cmd+Tab example as the number of macro_release calls equals the number of macro_press calls, and Cmd retains some macro_press calls until the layer changes and all the queued macro_release calls are executed.

Potential improvements

• I wonder if behavior_macro_scheduled_state can get away with storing char* pointers for each behavior_dev? This would require less memory, simplify the code, and also prevent issues with truncated labels. (now added)
• macro_pause_for_release and macro_pause_for_layer cannot be used in the same macro, but that should be possible if a separate release_state is kept for each trigger.

[caksoylar]

Dropping this here for reference: Use case sounds like #997, another possible solution is #1366.

[caksoylar]

I think being more specific here will be nice: is it watching for the layer that the macro is on to be turned off? Or any change in the currently active set of layers?

[aaronkollasch]

Right now it's the latter: any change in the active set of layers will release all scheduled states. The former could be nice, but it would add some complexity to allow for storing scheduled states from different layers and releasing only some of them at a time.

[aaronkollasch]

Question: if I wanted to get the layer the macro was in, would I store the zmk_behavior_binding_event->layer int passed into on_macro_binding_pressed()?

And then to check if the layer is turned off in macro_layer_state_changed_listener(), see if any bit in the stored layer int has been switched off?

Edit: never mind, I figured it out.

[aaronkollasch]

I added a commit that enables the first behavior you suggested - it now watches for the layer the macro is on to be turned off. I also edited the documentation to be more specific.

[caksoylar]

I think that's intuitive but either way could have been fine as long as it is documented.

One thing I am curious is how it behaves when the macro is not invoked directly from a layer binding, like

• a combo
• nested in another behavior (hold-tap, mod-morph, another macro etc.)

I am not sure it needs to work with combos since it doesn't make much sense, but maybe a warning note will be warranted.

[aaronkollasch]

Yeah, I added that behavior because I thought it would be more intuitive as well, so that adding another layer wouldn't trigger all continuations. However, it does limit macro_pause_for_layer to be used only on non-default layers.

I just tested with a combo and it seems to count as layer 0 even if a different layer is active at the time, so it would not work with the current behavior.

Perhaps one way a combo would make sense is where app switch could be repeatedly activated with a combo in the base layer, and momentarily entering any other layer would then exit the app switcher. Not the way I'm used to using Alt+Tab, but perhaps useful for someone who is averse to holding multiple keys.

This use would require going back to the original behavior of continuing on any layer change, rather than waiting for the current layer's deactivation.

[aaronkollasch]

I've rebased the PR on main, including support for parameterized macros (#1232).

In order to support parameterized macros, as well as the zmk_behavior_binding* parameter in queue_macro() function, behavior_macro_scheduled_state now stores the full struct zmk_behavior_binding instead of just the char* behavior_dev. This increases the size of the queue from 196 to 320 bytes.

[aaronkollasch]

Adding another force-push for the deprecated label property refactor (#2028).