Can someone make a tutorial for Custom Layouts?

[jirkacapek123]

I just can't find a good source of information on how to create your own layouts, or what keycodes to use or just the general rules on how to write the custom layout. I would be so glad for this and I also think others would also want this.

[BlackyHawky]

I haven't found a tutorial on this subject either, but if you read the Layout.md file carefully, you'll already be able to do a lot of customization.

In addition, don't hesitate to take a look at what's already there (for example, the custom AZERTY layout in the "Languages & Layouts" setting or the numpad layout in the "Advanced" setting).

Finally, don't hesitate to ask the community; personally, I'm pretty quick to respond on these kinds of topics, having spent a few hours working out my custom layout.

Edit: @jirkacapek123
You can find many examples here.

[jirkacapek123]

I haven't found a tutorial on this subject either, but if you read the Layout.md file carefully, you'll already be able to do a lot of customization.

In addition, don't hesitate to take a look at what's already there (for example, the custom AZERTY layout in the "Languages & Layouts" setting or the numpad layout in the "Advanced" setting).

Finally, don't hesitate to ask the community; personally, I'm pretty quick to respond on these kinds of topics, having spent a few hours working out my custom layout.

Edit: @jirkacapek123
You can find many examples here.

This is awesome, thank you so much for your effort. Now it's gonna be a lot easier with something I can refer to.

[jirkacapek123]

@BlackyHawky
Oh and by the way do you know how to add TAB key to the custom layout?

[BlackyHawky]

@jirkacapek123

Oh and by the way do you know how to add TAB key to the custom layout?

Of course ; simply write:

{ "label": "tab", "type": "normal", "width": 0.1 },

[jirkacapek123]

Thanks a lot

[Helium314]

Btw I recently added a GitHub wiki and made it editable for everyone. So if someone has a tutorial, or otherwise more helpful information than what I put in the layouts file, that's where they could share it.

[BlackyHawky]

@Helium314
The Layouts.md file is already very complete, even if it calls on other Heliboard files such as KeyCode.kt or KeyLabel.kt. This makes it difficult to read on a cell phone, but easier on a computer.

Anyway, knowing that, I don't really see what could be added to the wiki...

The only indication missing (in my opinion) from the Layouts.md file is the conversion of the labelFlags attributes.
@devycarol gave us the tip here:
"If you use DuckDuckGo, you can easily convert hex to base ten by searching for 0x##. e.g. searching 0x40 will show you 64."

[BlackyHawky]

Or perhaps I can simply edit the wiki using the information contained in the Layout.md file, without having to link to several other files... 🤔

[BlackyHawky]

Finally, I updated the wiki.
I don't know if it's better than what's already in the Layouts.md file, but it'll at least serve as a basis.

[Helium314]

Thanks!
The layouts.md is probably mostly useful for users who already have some basic knowledge and want to look up specific things, but when you start from scratch it's not that helpful.

The only indication missing (in my opinion) from the Layouts.md file is the conversion of the labelFlags attributes.

That's a good point. I'll put the conversion as comment into the attrs file, and maybe add some extra explanation.

[aspiers]

I'm also finding it surprisingly difficult to figure out how to get started with creating a custom layout. This is not due to difficulties with JSON, as I have plenty of experience working with JSON (and code in general), but rather a lack of clear information on the high-level approach needed. So I strongly agree with the OP that a tutorial would be super helpful.

In the absence of a tutorial, I tried to read as much of the relevant docs as possible. I found both of these:

• https://github.com/Helium314/HeliBoard/blob/main/layouts.md
• https://github.com/Helium314/HeliBoard/wiki/Layouts

but they both seemed to focus on the file format of layouts and didn't explain anything about how to test a new layout file. At first I got the impression that the only way to create a new layout was to fork the repo, follow these instructions, and then build and sideload a custom version of the app, which would be very time-consuming for anyone not super familiar with Android development.

But then I found https://github.com/Helium314/HeliBoard/wiki/Customization#layouts which explains a different way which apparently allows adding new layouts directly within the app, without any code changes or recompilations required. So I added a new section at the top of this wiki page trying to make it easier for others to find this out.

However now I can't find a good JSON layout as a starting point. I found pcqwerty.json but that doesn't seem to match the default US/UK QWERTY layouts I'm already using. I also found subtype_en_GB but I couldn't see any obvious reference from that to whichever layout it's based on. I also didn't find any explanation of subtypes other than this, which left several questions:

• Is it possible to add subtypes without changing code and rebuilding the app?
• What are the pros and cons of creating a new subtype vs. a new layout?
• If I want a new layout similar to an existing one such as UK/USA QWERTY, without having to make code changes, what's a good starting point?

I'm also confused why there are these two documents with overlapping content. Should we just use one and ignore the other? Or do we need to read both? Can't they just be merged into a single source of truth to avoid confusion?

Would be really grateful for answers to any/all of these questions, as I'm currently very confused.