feature_layouts.md (3415B)
1 # Layouts: Using a Keymap with Multiple Keyboards 2 3 The `layouts/` folder contains different physical key layouts that can apply to different keyboards. 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 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. 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 ```markdown 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 36 ## Supporting a Layout 37 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): 39 40 ```c 41 #define LAYOUT_60_ansi KEYMAP_ANSI 42 ``` 43 44 The name of the layout must match this regex: `[a-z0-9_]+` 45 46 The folder name must be added to the keyboard's `rules.mk`: 47 48 ``` 49 LAYOUTS = 60_ansi 50 ``` 51 52 `LAYOUTS` can be set in any keyboard folder level's `rules.mk`: 53 54 ``` 55 LAYOUTS = 60_iso 56 ``` 57 58 but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well. 59 60 ## Building a Keymap 61 62 You should be able to build the keyboard keymap with a command in this format: 63 64 ``` 65 make <keyboard>:<layout> 66 ``` 67 68 ### Conflicting layouts 69 When a keyboard supports multiple layout options, 70 71 ``` 72 LAYOUTS = ortho_4x4 ortho_4x12 73 ``` 74 75 And a layout exists for both options, 76 ``` 77 layouts/ 78 + community/ 79 | + ortho_4x4/ 80 | | + <layout>/ 81 | | | + ... 82 | + ortho_4x12/ 83 | | + <layout>/ 84 | | | + ... 85 | + ... 86 ``` 87 88 The FORCE_LAYOUT argument can be used to specify which layout to build 89 90 ``` 91 make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4 92 make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12 93 ``` 94 95 ## Tips for Making Layouts Keyboard-Agnostic 96 97 ### Includes 98 99 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: 100 101 ```c 102 #include QMK_KEYBOARD_H 103 ``` 104 105 If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement: 106 107 * `KEYBOARD_<folder1>_<folder2>` 108 109 For example: 110 111 ```c 112 #ifdef KEYBOARD_planck 113 #ifdef KEYBOARD_planck_rev4 114 planck_rev4_function(); 115 #endif 116 #endif 117 ``` 118 119 Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly. 120 121 ### Keymaps 122 123 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.