Community Layouts
The layouts/ folder contains different physical key layouts that can apply to different keyboards.
1
layouts/
2
+ default/
3
| + 60_ansi/
4
| | + readme.md
5
| | + layout.json
6
| | + a_good_keymap/
7
| | | + keymap.c
8
| | | + readme.md
9
| | | + config.h
10
| | | + rules.mk
11
| | + <keymap folder>/
12
| | + ...
13
| + <layout folder>/
14
+ community/
15
| + <layout folder>/
16
| + ...
Copied!
The layouts/default/ and layouts/community/ are two examples of layout "repositories" - currently default will contain all of the information concerning the layout, and one default keymap named default_<layout>, for users to use as a reference. community contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into layouts/. QMK searches through all folders in layouts/, so it's possible to have multiple repositories here.
Each layout folder is named ([a-z0-9_]) after the physical aspects of the layout, in the most generic way possible, and contains a readme.md with the layout to be defined by the keyboard:
1
# 60_ansi
2
3
LAYOUT_60_ansi
Copied!
New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.

Supporting a Layout

For a keyboard to support a layout, the variable must be defined in it's <keyboard>.h, and match the number of arguments/keys (and preferably the physical layout):
1
#define LAYOUT_60_ansi KEYMAP_ANSI
Copied!
The name of the layout must match this regex: [a-z0-9_]+
The folder name must be added to the keyboard's rules.mk:
1
LAYOUTS = 60_ansi
Copied!
LAYOUTS can be set in any keyboard folder level's rules.mk:
1
LAYOUTS = 60_iso
Copied!
but the LAYOUT_<layout> variable must be defined in <folder>.h as well.

Building a Keymap

You should be able to build the keyboard keymap with a command in this format:
1
make <keyboard>:<layout>
Copied!

Conflicting layouts

When a keyboard supports multiple layout options,
1
LAYOUTS = ortho_4x4 ortho_4x12
Copied!
And a layout exists for both options,
1
layouts/
2
+ community/
3
| + ortho_4x4/
4
| | + <layout>/
5
| | | + ...
6
| + ortho_4x12/
7
| | + <layout>/
8
| | | + ...
9
| + ...
Copied!
The FORCE_LAYOUT argument can be used to specify which layout to build
1
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
2
make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
Copied!

Tips for Making Layouts Keyboard-Agnostic

Includes

Instead of using #include "planck.h", you can use this line to include whatever <keyboard>.h (<folder>.h should not be included here) file that is being compiled:
1
#include QMK_KEYBOARD_H
Copied!
If you want to keep some keyboard-specific code, you can use these variables to escape it with an #ifdef statement:
    KEYBOARD_<folder1>_<folder2>
For example:
1
#ifdef KEYBOARD_planck
2
#ifdef KEYBOARD_planck_rev4
3
planck_rev4_function();
4
#endif
5
#endif
Copied!
Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.

Keymaps

In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic LAYOUT_<layout name> macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use LAYOUT_ortho_4x12 instead of LAYOUT_planck_grid or just {} for a C array.
Last modified 2yr ago