docs/feature_layouts.md

   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 reposistories 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 ```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
  36 ## Supporting a layout
  37
  38 For a keyboard to support a layout, the variable (`[a-z0-9_]`) must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferrably the physical layout):
  39
  40     #define LAYOUT_60_ansi KEYMAP_ANSI
  41
  42 The folder name must be added to the keyboard's `rules.mk`:
  43
  44     LAYOUTS = 60_ansi
  45
  46 `LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
  47
  48     LAYOUTS = 60_iso
  49
  50 but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
  51
  52 ## Tips for making layouts keyboard-agnostic
  53
  54 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:
  55
  56     #include QMK_KEYBOARD_H
  57
  58 In your config.h, you can also use this variable to include the keyboard's `config.h`:
  59
  60     #include QMK_KEYBOARD_CONFIG_H
  61
  62 If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
  63
  64 * `KEYBOARD_<folder1>_<folder2>`
  65
  66 For example:
  67
  68 ```c
  69 #ifdef KEYBOARD_planck
  70     #ifdef KEYBOARD_planck_rev4
  71         planck_rev4_function();
  72     #endif
  73 #endif
  74 ```
  75
  76 Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.