opensteno_qmk/docs/feature_layouts.md
Jack Humbert d2ff66a985 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
2017-08-23 22:29:07 -04:00

2.5 KiB

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:

# 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:

#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.