Can someone help me understand how to define and use chords?

[brandonbeaumia]

Hey everyone,

I have a very specific and (I think) simple use case for Kanata. I would like to be able to press the Tab key to tab, but hold the Tab key and press a number on the top row to Tab that number of times.

TL;DR: How do I accomplish the above using chords?

So far I've already defined my macros in the format of 2tab (macro tab 10 tab) for numbers zero through nine.

Unfortunately, I've now been banging my head against this config file trying to learn how chords work. I've read kanata.kbd and config.adoc at least half a dozen times each plus a few sample configs in the discussions, and have tried copy/pasting and making modifications but have not had the "aha" moment yet.

Using

(defchords tabch 500
(tab 1) @1tab
(tab 2) @2tab
[...]

results in coord group 'tabch' defines unused key 'tab', did you forget to bind '(chord tabch tab)?

So I bound that to my Tab key in the default layer, but got an error about the numbers not being bound. Out of desperation just to get the config to parse, I bound those to my numbers in the default layer, and it finally parses but now my tab and number keys only work as chords and not as the original keys. Halfway expected that at least, which is why I didn't try it from the start.

Perhaps the "arbitrary labels" part of this is throwing me off?:

Note that unlike with defseq, these keys do not directly correspond to real keys and are merely arbitrary labels that make sense within the context of the chord. They are mapped to real keys in layers by configuring the key in the layer to map to a (chord name key) action where name is the name of the chords group (above example) and key is one of these arbitrary labels.

On top of the "arbitrary label" confusion: if all input chord options need to be bound somewhere, I'm not sure what the benefit of chords even is. If I need to make another layer just to put my chords in there, then wouldn't using layers be the solution anyway and I would bind the macro directly?

Anyway, I apologize for rambling through my confusion. Maybe chords just don't work how I am expecting and it's making it impossible for me to understand the config. There's so much to clear up that it might be a much easier start for someone to just throw the answer at me instead of trying to help me understand where I've gone wrong (though I would greatly appreciate it, as I think learning Kanata could open up a lot of efficiencies for me!)

Here is where my (obviously erroneous) config stands now:

;; Left Control, Space, Escape to quit Kanata
;; https://github.com/jtroo/kanata/blob/main/docs/config.adoc

(defsrc
  1    2    3    4    5    6    7    8    9    0
  tab
)

(deflayer default
  1    2    3    4    5    6    7    8    9    0
  (chord tabch tab)
)

(defchords tabch 500
  (tab 1) @1tab
  (tab 2) @2tab
  (tab 3) @3tab 
  (tab 4) @4tab
  (tab 5) @5tab
  (tab 6) @6tab
  (tab 7) @7tab
  (tab 8) @8tab
  (tab 9) @9tab
  (tab 0) @10tab
)

(defalias
  ;; macro accepts keys, chords, and numbers (a delay in ms). Note that numbers
  ;; will be parsed as delays, so they will need to be aliased to be used.
  1tab (macro tab)            
  2tab (macro tab 10 tab)
  3tab (macro tab 10 tab 10 tab)
  4tab (macro tab 10 tab 10 tab 10 tab)
  5tab (macro tab 10 tab 10 tab 10 tab 10 tab)
  6tab (macro tab 10 tab 10 tab 10 tab 10 tab 10 tab)
  7tab (macro tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab)
  8tab (macro tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab)
  9tab (macro tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab)
  10tab (macro tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10 tab 10)
)

[rszyma]

I have a very specific and (I think) simple use case for Kanata. I would like to be able to press the Tab key to tab, but hold the Tab key and press a number on the top row to Tab that number of times.

TL;DR: How do I accomplish the above using chords?

sounds like a job for tap-hold, not chords

[brandonbeaumia]

This is where I started, actually: using the 'tap' of Tab as a regular tab and 'hold' of Tab as a layer shift that allowed me to set macros on the numbers. I was able to get it to function as expected, but the hold delay kind of killed it for me in regards to high-speed data entry. I figured chords would be the way to eliminate the delay? Rather than holding for a specified time to layer shift, tab plus a number could immediately activate a macro. Again, this is just my outsider's perspective on what a chord is. It's very possible I'm misunderstanding Kanata's implementation/terminology.

[jtroo]

Have a read through the tap-hold variants. One of them might suit your needs for faster activation.

Chords also have some input latency.

[rszyma]

specifically take a look at tap-hold-press, I use this one myself on Tab for tap-hold functionality and the experience is seamless

[brandonbeaumia]

Thank you! tap-hold-press is much closer to what I was hoping for.

If there is a press of a different key, the hold action is activated even if the hold timeout hasn’t expired yet.

(defalias tabhold (tap-hold-press 200 200 tab (layer-while-held tablayer)))

So while holding tab, keydown of e.g. 6 activates the "hold" of my tap-hold-press (new layer), and then the keyup of 6 now kicks off the macro because I'm in the new layer? I think I get it now. Thank you both very much!