X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Ffeature_layouts.md;h=b34fd442d5c2f92d0ac460355591ecf894dab84e;hb=3538955778c253e68779605cc67c27e15d195729;hp=4d75270dcdf1a3a6ab6e7ebeb0f5cfbe72eb1f06;hpb=d2ff66a985b938e87fffe55c1d9f1dc55e356f91;p=qmk_firmware.git diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md index 4d75270dc..b34fd442d 100644 --- a/docs/feature_layouts.md +++ b/docs/feature_layouts.md @@ -1,6 +1,6 @@ -# Layouts: Using a keymap with multiple keyboards +# Layouts: Using a Keymap with Multiple Keyboards -The `layouts/` folder contains different physical key layouts that can apply to different keyboards. +The `layouts/` folder contains different physical key layouts that can apply to different keyboards. ``` layouts/ @@ -21,7 +21,7 @@ layouts/ | + ... ``` -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_`, 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. +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_`, 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: @@ -33,45 +33,77 @@ Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layo New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue. -## Supporting a layout +## Supporting a Layout -For a keyboard to support a layout, the variable (`[a-z0-9_]`) must be defined in it's `.h`, and match the number of arguments/keys (and preferrably the physical layout): +For a keyboard to support a layout, the variable must be defined in it's `.h`, and match the number of arguments/keys (and preferably the physical layout): #define LAYOUT_60_ansi KEYMAP_ANSI +The name of the layout must match this regex: `[a-z0-9_]+` + The folder name must be added to the keyboard's `rules.mk`: LAYOUTS = 60_ansi -`LAYOUTS` can be appended in the subproject's `rules.mk`: +`LAYOUTS` can be set in any keyboard folder level's `rules.mk`: - LAYOUTS += 60_iso + LAYOUTS = 60_iso -but the `LAYOUT_` variable must be defined in `.h` as well. +but the `LAYOUT_` variable must be defined in `.h` as well. -## Tips for making layouts keyboard-agnostic +## Building a Keymap -Instead of using `#include "planck.h"`, you can use this line to include whatever `.h` (`.h` should not be included here) file that is being compiled: +You should be able to build the keyboard keymap with a command in this format: - #include QMK_KEYBOARD_H + make : + +### Conflicting layouts +When a keyboard supports multiple layout options, -In your config.h, you can also use this variable to include the keyboard's `config.h`: + LAYOUTS = ortho_4x4 ortho_4x12 + +And a layout exists for both options, +``` +layouts/ ++ community/ +| + ortho_4x4/ +| | + / +| | | + ... +| + ortho_4x12/ +| | + / +| | | + ... +| + ... +``` - #include QMK_KEYBOARD_CONFIG_H +The FORCE_LAYOUT argument can be used to specify which layout to build + + make : FORCE_LAYOUT=ortho_4x4 + make : FORCE_LAYOUT=ortho_4x12 + +## Tips for Making Layouts Keyboard-Agnostic + +### Includes + +Instead of using `#include "planck.h"`, you can use this line to include whatever `.h` (`.h` should not be included here) file that is being compiled: + + #include QMK_KEYBOARD_H If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement: -* `KEYBOARD_` -* `SUBPROJECT_` +* `KEYBOARD__` For example: ```c #ifdef KEYBOARD_planck - #ifdef SUBPROJECT_rev4 + #ifdef KEYBOARD_planck_rev4 planck_rev4_function(); #endif #endif ``` -Note that the names are lowercase and match the folder/file names for the keyboard/subproject exactly. \ No newline at end of file +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_` 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.