diff options
author | Jack Humbert <jack.humb@gmail.com> | 2017-08-23 22:29:07 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-08-23 22:29:07 -0400 |
commit | d2ff66a985b938e87fffe55c1d9f1dc55e356f91 (patch) | |
tree | 561b3e203033849573a17f5ac6248077ab687676 /docs/feature_layouts.md | |
parent | 7260fc3eef98fb7b0e2ed24d3d0d14cf2e613000 (diff) | |
download | qmk_firmware-d2ff66a985b938e87fffe55c1d9f1dc55e356f91.tar.gz |
Creates a layouts/ folder for keymaps shared between keyboards (#1609)
* include variables and .h files as pp directives
* start layout compilation
* split ergodoxes up
* don't compile all layouts for everything
* might seg fault
* reset layouts variable
* actually reset layouts
* include rules.mk instead
* remove includes from rules.mk
* update variable setting
* load visualizer from path
* adds some more examples
* adds more layouts
* more boards added
* more boards added
* adds documentation for layouts
* use lowercase names for LAYOUT_
* add layout.json files for each layout
* add community folder, default keymaps for layouts
* touch-up default layouts
* touch-up layouts, some keyboard rules.mk
* update documentation for layouts
* fix up serial/i2c switches
Diffstat (limited to 'docs/feature_layouts.md')
-rw-r--r-- | docs/feature_layouts.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/docs/feature_layouts.md b/docs/feature_layouts.md new file mode 100644 index 000000000..4d75270dc --- /dev/null +++ b/docs/feature_layouts.md @@ -0,0 +1,77 @@ +# Layouts: Using a keymap with multiple keyboards + +The `layouts/` folder contains different physical key layouts that can apply to different keyboards. + +``` +layouts/ ++ default/ +| + 60_ansi/ +| | + readme.md +| | + layout.json +| | + a_good_keymap/ +| | | + keymap.c +| | | + readme.md +| | | + config.h +| | | + rules.mk +| | + <keymap folder>/ +| | + ... +| + <layout folder>/ ++ community/ +| + <layout folder>/ +| + ... +``` + +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. + +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: + +```md +# 60_ansi + + LAYOUT_60_ansi +``` + +New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue. + +## Supporting a layout + +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): + + #define LAYOUT_60_ansi KEYMAP_ANSI + +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 += 60_iso + +but the `LAYOUT_<layout>` variable must be defined in `<subproject>.h` as well. + +## Tips for making layouts keyboard-agnostic + +Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<subproject>.h` should not be included here) file that is being compiled: + + #include QMK_KEYBOARD_H + +In your config.h, you can also use this variable to include the keyboard's `config.h`: + + #include QMK_KEYBOARD_CONFIG_H + +If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement: + +* `KEYBOARD_<keyboard>` +* `SUBPROJECT_<subproject>` + +For example: + +```c +#ifdef KEYBOARD_planck + #ifdef SUBPROJECT_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 |