logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

feature_layouts.md (3415B)

    

  1. # Layouts: Using a Keymap with Multiple Keyboards
  3. The `layouts/` folder contains different physical key layouts that can apply to different keyboards.
  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. ```
  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.
  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:
  28. ```markdown
  29. # 60_ansi
  31.    LAYOUT_60_ansi
  32. ```
  34. New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
  36. ## Supporting a Layout
  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):
  40. ```c
  41. #define LAYOUT_60_ansi KEYMAP_ANSI
  42. ```
  44. The name of the layout must match this regex: `[a-z0-9_]+`
  46. The folder name must be added to the keyboard's `rules.mk`:
  48. ```
  49. LAYOUTS = 60_ansi
  50. ```
  52. `LAYOUTS` can be set in any keyboard folder level's `rules.mk`:
  54. ```
  55. LAYOUTS = 60_iso
  56. ```
  58. but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
  60. ## Building a Keymap
  62. You should be able to build the keyboard keymap with a command in this format:
  64. ```
  65. make <keyboard>:<layout>
  66. ```
  68. ### Conflicting layouts
  69. When a keyboard supports multiple layout options,
  71. ```
  72. LAYOUTS = ortho_4x4 ortho_4x12
  73. ```
  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. ```
  88. The FORCE_LAYOUT argument can be used to specify which layout to build
  90. ```
  91. make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x4
  92. make <keyboard>:<layout> FORCE_LAYOUT=ortho_4x12
  93. ```
  95. ## Tips for Making Layouts Keyboard-Agnostic
  97. ### Includes
  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:
  101. ```c
  102. #include QMK_KEYBOARD_H
  103. ```
  105. If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
  107. * `KEYBOARD_<folder1>_<folder2>`
  109. For example:
  111. ```c
  112. #ifdef KEYBOARD_planck
  113.     #ifdef KEYBOARD_planck_rev4
  114.         planck_rev4_function();
  115.     #endif
  116. #endif
  117. ```
  119. Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
  121. ### Keymaps
  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.