Commit | Line | Data |
---|---|---|
7b0356d1 | 1 | # Layouts: Using a Keymap with Multiple Keyboards |
d2ff66a9 | 2 | |
bb53635f | 3 | The `layouts/` folder contains different physical key layouts that can apply to different keyboards. |
d2ff66a9 JH |
4 | |
5 | ``` | |
6 | layouts/ | |
7 | + default/ | |
8 | | + 60_ansi/ | |
9 | | | + readme.md | |
10 | | | + layout.json | |
11 | | | + a_good_keymap/ | |
12 | | | | + keymap.c | |
13 | | | | + readme.md | |
14 | | | | + config.h | |
15 | | | | + rules.mk | |
16 | | | + <keymap folder>/ | |
17 | | | + ... | |
18 | | + <layout folder>/ | |
19 | + community/ | |
20 | | + <layout folder>/ | |
21 | | + ... | |
22 | ``` | |
23 | ||
bb53635f | 24 | 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. |
d2ff66a9 JH |
25 | |
26 | 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: | |
27 | ||
28 | ```md | |
29 | # 60_ansi | |
30 | ||
31 | LAYOUT_60_ansi | |
32 | ``` | |
33 | ||
34 | New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue. | |
35 | ||
7b0356d1 | 36 | ## Supporting a Layout |
d2ff66a9 | 37 | |
2018df1a | 38 | 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): |
d2ff66a9 JH |
39 | |
40 | #define LAYOUT_60_ansi KEYMAP_ANSI | |
41 | ||
2018df1a | 42 | The name of the layout must match this regex: `[a-z0-9_]+` |
43 | ||
d2ff66a9 JH |
44 | The folder name must be added to the keyboard's `rules.mk`: |
45 | ||
46 | LAYOUTS = 60_ansi | |
47 | ||
800ec55d | 48 | `LAYOUTS` can be set in any keyboard folder level's `rules.mk`: |
d2ff66a9 | 49 | |
800ec55d | 50 | LAYOUTS = 60_iso |
d2ff66a9 | 51 | |
800ec55d | 52 | but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well. |
d2ff66a9 | 53 | |
40e67a30 | 54 | ## Building a Keymap |
55 | ||
56 | You should be able to build the keyboard keymap with a command in this format: | |
57 | ||
58 | make <keyboard>:<layout> | |
59 | ||
60 | ### Conflicting layouts | |
61 | When a keyboard supports multiple layout options, | |
62 | ||
63 | LAYOUTS = ortho_4x4 ortho_4x12 | |
64 | ||
65 | And a layout exists for both options, | |
66 | ``` | |
67 | layouts/ | |
68 | + community/ | |
69 | | + ortho_4x4/ | |
70 | | | + <layout>/ | |
71 | | | | + ... | |
72 | | + ortho_4x12/ | |
73 | | | + <layout>/ | |
74 | | | | + ... | |
75 | | + ... | |
76 | ``` | |
77 | ||
78 | The FORCE_LAYOUT argument can be used to specify which layout to build | |
79 | ||
80 | make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4 | |
81 | make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12 | |
82 | ||
7b0356d1 | 83 | ## Tips for Making Layouts Keyboard-Agnostic |
d2ff66a9 | 84 | |
08c682c1 ET |
85 | ### Includes |
86 | ||
800ec55d | 87 | 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: |
d2ff66a9 JH |
88 | |
89 | #include QMK_KEYBOARD_H | |
90 | ||
d2ff66a9 JH |
91 | If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement: |
92 | ||
800ec55d | 93 | * `KEYBOARD_<folder1>_<folder2>` |
d2ff66a9 JH |
94 | |
95 | For example: | |
96 | ||
97 | ```c | |
98 | #ifdef KEYBOARD_planck | |
800ec55d | 99 | #ifdef KEYBOARD_planck_rev4 |
d2ff66a9 JH |
100 | planck_rev4_function(); |
101 | #endif | |
102 | #endif | |
103 | ``` | |
104 | ||
c8bdc75e | 105 | Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly. |
08c682c1 ET |
106 | |
107 | ### Keymaps | |
108 | ||
109 | 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. |