Macro Help: sticky shift

[WindChimeRan]

Hi, I read the extended macro engine docs and many related issues, but I don't pretty understand many concepts such as gestures and shortcuts. May I ask to add more examples in the docs?

I want to implement a thumb sticky shift macro key in my key cluster module, in addition to my two existing standard shifts. I think that would be more ergonomic!

A sticky shift, in this case, would be: press-shift -> release-shift -> add a shift modifier to the next pressed key

[kareltucek]

Hi, I read the extended macro engine docs and many related issues, but I don't pretty understand many concepts such as gestures and shortcuts.

Well, you use shortcuts if you want to map an action to a combination of keys. E.g, if I want map z+x -> Control+x, z+c -> Control+c, z+v -> Control+v, I will map following macro on the z key:

    ifShortcut 88 final tapKey C-x
    ifShortcut 89 final tapKey C-c
    ifShortcut 90 final tapKey C-v
    holdKey z

If you use ifGesture instead, tapping z and then tapping x will produce Control+x, and so on.

May I ask to add more examples in the docs?

I have tried to simplify it a bit in https://github.com/kareltucek/firmware/commit/16d2d701755eee6a32e61c02f3841041f05d94e0 .

Please suggest how to improve the docs further.

I want to implement a thumb sticky shift macro key in my key cluster module, in addition to my two existing standard shifts. I think that would be more ergonomic!

A sticky shift, in this case, would be: press-shift -> release-shift -> add a shift modifier to the next pressed key

I believe we call these "One shot keys". They are discussed in #464, but are not available (yet).

[WindChimeRan]

Thank you so much for the detailed explanation!

Now I understand the semantics of gesture and shortcut. But I am still not sure about the motivations: from my understanding, we can use an additional layer in the basic agent to simulate the more advanced shortcut (gesture is like a one-shot layer). Am I right? e.g., primary z, secondary fn5, and assign C-x ...

Discussion in #464 is very helpful! I'm experimenting with your script now.

[kareltucek]

Motivation:

• number of layers is limited.
• recursive layers are more-or-less unsupported by design, so you cannot do complex chords. (with above syntax, you can do ifShortcut 88 89 90 tapKeySeq a b c d)
• reusing layers across keymaps is complicated.
• with layers you can do "shortcuts". You cannot do "gestures" that way.
• ifShortcut is basically a time machine, so you can query future keystrokes... yet have all actions still take place if the shortcut is not matched in the end. Simulating that with layers in a way which does not break down would be a nightmare.

[WindChimeRan]

Wow, that's amazing. I think it would be better if you include the motivations of the shortcut/gesture in the docs.

Is it possible to make the docs on a website like qmk/zmk? The doc would be less overwhelming if users can read it section by section, and we may contribute more examples/use cases then.

[kareltucek]

Wow, that's amazing. I think it would be better if you include the motivations of the shortcut/gesture in the docs.

I prefer focusing on "what features do" rather than on explaining motivations too broadly. Still, specific rephrasing suggestions are welcome.

Is it possible to make the docs on a website like qmk/zmk? The doc would be less overwhelming if users can read it section by section, and we may contribute more examples/use cases the

I fear that maintaining such documentation would be time consuming. Also, at the moment navigation in the docs relies on the docs being easily searchable, which mostly implies that they need to be a single page.

If you think you can make high-quality versioned with a reasonable amount of effort, and want to contribute to the project, I would love to see such documentation.

@mondalaci any thoughts on the docs? I remember you had something similar in mind. Not sure what the state of affairs and plans is.

[mondalaci]

I plan to gradually review and make extended macro commands non-extended and add them to the informal documentation (Agent sidebar). After a certain point, the number of commands will be quite overwhelming for a single page. Adding an interactive sidebar to the informal documentation would make navigation far easier. I like the layout and feature set of the lodash documentation, and I'd love to have something similar.

I'm not against splitting the documentation into multiple pages like QMK if it provides better usability.

I'm fine with exposing the informal documentation over GitHub pages. I'm also fine exposing both the informal and formal documentation (macro reference), but ultimately, I prefer to merge the two as a single resource as it'd be easier to digest it than having two separate resources.

[kareltucek]

@mondalaci I guess this can be closed?