How to use functional key layouts?

[novoid]

In #1195 Samscryption pointed me to "functional key layouts".

In my HeliBoard 2.2 settings, I found "Advanced ..." -> "Customize functional key layouts": selection one of:

1. Functional keys
2. Functional keys (Symbols)
3. Functional keys (More symbols)

Where "Functional keys" looks like

So I guess I've found some default settings for functional key configuration I could already use and extend.

However, I was not able to find out how to actually use it. I presume I need to long-press some key and get "shift", "delete", "symbol_alpha" and so forth.

(1) Is this assumption true so far?
(2) Where do I need to long-press in order to see the functional keys configured above?
(3) What are the differences between "Functional keys", "Functional keys (Symbols)" and "Functional keys (More symbols)"?
(4) What is the process of adding my own keys to specific existing keys for long-press use?

I've read https://github.com/Helium314/HeliBoard/wiki/Layouts#what-a-json-file-looks-like-for-heliboard but it only explains syntax.

I've read #947 but I did not understand it. E.g., when I follow #947 (reply in thread) and copy my QWERTY to "QWERTY2", I end up with a file with q, w, e, ... each one as a character per line. It doesn't look like the syntax from the layouts wiki page at all.

So far, it's very confusing to me and I could not find any documentation on that.

Thanks for your help!

[Helium314]

Is this assumption true so far?

No. The functional keys are the layout "around" your (letter) keyboard. So it's the shift, delete, space, enter, ... keys.

What are the differences between "Functional keys", "Functional keys (Symbols)" and "Functional keys (More symbols)"?

When you go to symbols layout (the ?123 key) you will get a slightly different functional key layout, same for the more symbosl layout (behind < \ ?).
Though since I added the keyboard_state_selector this difference is not relevant any more, so the symbols / more symbols functional keys are mostly there for historic reasons (backwards compatibility so users don't need to change the layout on upgrades).

What is the process of adding my own keys

You can just add a key, e.g. change the part

...
    { "label": "space" },
    { "label": "period", "labelFlags": 1073741824 },
    { "label": "action", "width": 0.15 }
...

to

...
    { "label": "space" },
    { "label": "zwnj" },
    { "label": "period", "labelFlags": 1073741824 },
    { "label": "action", "width": 0.15 }
...

to add a zwnj key.
For the popup keys you need to modify / add the popup property (see link below).

So far, it's very confusing to me and I could not find any documentation on that.

There are two layout formats, a simple one (used for qwerty) and the more complex and more customizable json (used for functional keys and some others like dvorak).
Did you see https://github.com/Helium314/HeliBoard/blob/main/layouts.md? If not maybe you have an idea where is could be linked to make it more discoverable?