qmk_firmware/static/Features/Layouts.html

170 lines
15 KiB
HTML
Raw Permalink Normal View History

2018-05-06 19:34:47 +00:00
<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
<title>Layouts - QMK Firmware</title>
<meta name="description" content="Keyboard controller firmware for Atmel AVR and ARM USB families">
<meta name="author" content="QMK Community">
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
2018-05-08 04:02:24 +00:00
<link rel="icon" href="../themes/daux/img/favicon-navy.png" type="image/x-icon">
2018-05-06 19:34:47 +00:00
<!-- Mobile -->
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Font -->
<!-- CSS -->
2018-05-08 04:02:24 +00:00
<link href='../themes/daux/css/theme-navy.min.css' rel='stylesheet' type='text/css'>
2018-05-06 19:34:47 +00:00
<!-- Tipue Search -->
<link href="../tipuesearch/tipuesearch.css" rel="stylesheet">
<!--[if lt IE 9]>
<script src="../themes/daux/js/html5shiv-3.7.3.min.js"></script>
<![endif]-->
</head>
<body class=" ">
<div class="Columns content">
<aside class="Columns__left Collapsible">
<button type="button" class="Button Collapsible__trigger">
<span class="Collapsible__trigger__bar"></span>
<span class="Collapsible__trigger__bar"></span>
<span class="Collapsible__trigger__bar"></span>
</button>
<a class="Brand" href="../index.html">QMK Firmware</a>
<div class="Search">
<svg class="Search__icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 451 451">
<path d="M447.05 428l-109.6-109.6c29.4-33.8 47.2-77.9 47.2-126.1C384.65 86.2 298.35 0 192.35 0 86.25 0 .05 86.3.05 192.3s86.3 192.3 192.3 192.3c48.2 0 92.3-17.8 126.1-47.2L428.05 447c2.6 2.6 6.1 4 9.5 4s6.9-1.3 9.5-4c5.2-5.2 5.2-13.8 0-19zM26.95 192.3c0-91.2 74.2-165.3 165.3-165.3 91.2 0 165.3 74.2 165.3 165.3s-74.1 165.4-165.3 165.4c-91.1 0-165.3-74.2-165.3-165.4z"/>
</svg>
<input type="search" id="tipue_search_input" class="Search__field" placeholder="Search..." autocomplete="on"
results=25 autosave=text_search>
</div>
<div class="Collapsible__content">
<!-- Navigation -->
2018-05-08 04:02:24 +00:00
<ul class='Nav'><li class='Nav__item has-children'><a href="../Getting_Started/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Getting Started</a><ul class='Nav'><li class='Nav__item has-children'><a href="../Getting_Started/Install_Build_Tools/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Install Build Tools</a><ul class='Nav'><li class='Nav__item '><a href="../Getting_Started/Install_Build_Tools/Vagrant.html">Vagrant</a></li></ul></li><li class='Nav__item '><a href="../Getting_Started/Build_Compile_Instructions.html">Build Compile Instructions</a></li><li class='Nav__item '><a href="../Getting_Started/Flashing_Firmware.html">Flashing Firmware</a></li><li class='Nav__item '><a href="../Getting_Started/Contributing.html">Contributing</a></li><li class='Nav__item '><a href="../Getting_Started/How_to_Use_GitHub.html">How to Use GitHub</a></li><li class='Nav__item '><a href="../Getting_Started/Getting_Help.html">Getting Help</a></li></ul></li><li class='Nav__item has-children'><a href="../Complete_Newbs_Guide/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Complete Newbs Guide</a><ul class='Nav'><li class='Nav__item '><a href="../Complete_Newbs_Guide/Complete_Newbie's_Guide.html">Complete Newbie's Guide</a></li><li class='Nav__item '><a href="../Complete_Newbs_Guide/Building_Your_First_Firmware.html">Building Your First Firmware</a></li><li class='Nav__item '><a href="../Complete_Newbs_Guide/Flashing_Firmware.html">Flashing Firmware</a></li><li class='Nav__item '><a href="../Complete_Newbs_Guide/Testing_and_Debugging.html">Testing and Debugging</a></li></ul></li><li class='Nav__item has-children'><a href="../FAQ/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>FAQ</a><ul class='Nav'><li class='Nav__item '><a href="../FAQ/General_FAQ.html">General FAQ</a></li><li class='Nav__item '><a href="../FAQ/Build_Compile_QMK.html">Build Compile QMK</a></li><li class='Nav__item '><a href="../FAQ/Debugging_and_Troubleshooting.html">Debugging and Troubleshooting</a></li><li class='Nav__item '><a href="../FAQ/Keymaps.html">Keymaps</a></li></ul></li><li class='Nav__item has-children'><a href="../Hardware/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Hardware</a><ul class='Nav'><li class='Nav__item '><a href="../Hardware/AVR_Processors.html">AVR Processors</a></li><li class='Nav__item '><a href="../Hardware/Drivers.html">Drivers</a></li></ul></li><li class='Nav__item Nav__item--open has-children'><a href="../Features/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Features</a><ul class='Nav'><li class='Nav__item '><a href="../Features/Advanced_Keycodes.html">Advanced Keycodes</a></li><li class='Nav__item '><a href="../Features/Audio.html">Audio</a></li><li class='Nav__item '><a href="../Features/Auto_Shift.html">Auto Shift</a></li><li class='Nav__item '><a href="../Features/Backlight.html">Backlight</a></li><li class='Nav__item '><a href="../Features/Bluetooth.html">Bluetooth</a></li><li class='Nav__item '><a href="../Features/Bootmagic.html">Bootmagic</a></li><li class='Nav__item '><a href="../Features/Command.html">Command</a></li><li class='Nav__item '><a href="../Features/Dynamic_Macros.html">Dynamic Macros</a></li><li class='Nav__item '><a href="../Features/Grave_Escape.html">Grave Escape</a></li><li class='Nav__item '><a href="../Features/Key_Lock.html">Key Lock</a></li><li class='Nav__item Nav__item--active'><a href="../Features/Layouts.html">Layouts</a></li><li class='Nav__item '><a href="../Features/Leader_Key.html">Leader Key</a></li><li class='Nav__item '><a href="../Features/Macros.html">Macros</a></li><li class='Nav__item '><a href="../Features/Mouse_Keys.html">Mouse Keys</a></li><li class='Nav__item '><a href="../Features/Pointing_Device.html">Pointing Device</a></li><li class='Nav__item '><a href="../Features/PS_2_Mouse.html">PS 2 Mouse</a></li><li class='Nav__item '><a href="../Features/RGB_Lighting.html">RGB Lighting</a></li><li class='Nav__item '><a href="../Features/Space_Cadet_Shift.html">Space Cadet Shift</a></li><li class='Nav__item
2018-05-06 19:34:47 +00:00
<div class="Links">
2018-05-08 04:02:24 +00:00
</div>
2018-05-06 19:34:47 +00:00
</div>
</aside>
<div class="Columns__right Columns__right--full">
<div class="Columns__right__content">
<div class="doc_content">
<article class="Page">
<div class="Page__header">
<h1><a href="../Features/index.html">Features</a> <svg class="Page__header--separator" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 477.175 477.175"><path d="M360.73 229.075l-225.1-225.1c-5.3-5.3-13.8-5.3-19.1 0s-5.3 13.8 0 19.1l215.5 215.5-215.5 215.5c-5.3 5.3-5.3 13.8 0 19.1 2.6 2.6 6.1 4 9.5 4 3.4 0 6.9-1.3 9.5-4l225.1-225.1c5.3-5.2 5.3-13.8.1-19z"/></svg> <a href="../Features/Layouts.html">Layouts</a></h1>
2018-05-08 04:02:24 +00:00
<span class="EditOn">
<a href="https://github.com/qmk/qmk_firmware/blob/master/docs/05_Features/Layouts.md" target="_blank">
Edit on GitHub </a>
</span>
</div>
2018-05-06 19:34:47 +00:00
<div class="s-content">
<ul class="TableOfContents">
<li>
<p><a href="#page_Layouts-Using-a-Keymap-with-Multiple-Keyboards">Layouts: Using a Keymap with Multiple Keyboards</a></p>
<ul class="TableOfContents">
<li>
<p><a href="#page_Supporting-a-Layout">Supporting a Layout</a></p>
</li>
<li>
<p><a href="#page_Tips-for-Making-Layouts-Keyboard-Agnostic">Tips for Making Layouts Keyboard-Agnostic</a></p>
</li>
</ul>
</li>
</ul>
<h1 id="page_Layouts-Using-a-Keymap-with-Multiple-Keyboards">Layouts: Using a Keymap with Multiple Keyboards</h1>
<p>The <code>layouts/</code> folder contains different physical key layouts that can apply to different keyboards.</p>
<pre><code>layouts/
+ default/
| + 60_ansi/
| | + readme.md
| | + layout.json
| | + a_good_keymap/
| | | + keymap.c
| | | + readme.md
| | | + config.h
| | | + rules.mk
| | + &lt;keymap folder&gt;/
| | + ...
| + &lt;layout folder&gt;/
+ community/
| + &lt;layout folder&gt;/
| + ...
</code></pre>
<p>The <code>layouts/default/</code> and <code>layouts/community/</code> are two examples of layout &quot;repositories&quot; - currently <code>default</code> will contain all of the information concerning the layout, and one default keymap named <code>default_&lt;layout&gt;</code>, for users to use as a reference. <code>community</code> contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into <code>layouts/</code>. QMK searches through all folders in <code>layouts/</code>, so it's possible to have multiple repositories here.</p>
<p>Each layout folder is named (<code>[a-z0-9_]</code>) after the physical aspects of the layout, in the most generic way possible, and contains a <code>readme.md</code> with the layout to be defined by the keyboard:</p>
<pre><code class="language-md"># 60_ansi
LAYOUT_60_ansi
</code></pre>
<p>New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.</p>
<h2 id="page_Supporting-a-Layout">Supporting a Layout</h2>
<p>For a keyboard to support a layout, the variable must be defined in it's <code>&lt;keyboard&gt;.h</code>, and match the number of arguments/keys (and preferably the physical layout):</p>
<pre><code>#define LAYOUT_60_ansi KEYMAP_ANSI
</code></pre>
<p>The name of the layout must match this regex: <code>[a-z0-9_]+</code></p>
<p>The folder name must be added to the keyboard's <code>rules.mk</code>:</p>
<pre><code>LAYOUTS = 60_ansi
</code></pre>
<p><code>LAYOUTS</code> can be set in any keyboard folder level's <code>rules.mk</code>:</p>
<pre><code>LAYOUTS = 60_iso
</code></pre>
<p>but the <code>LAYOUT_&lt;layout&gt;</code> variable must be defined in <code>&lt;folder&gt;.h</code> as well.</p>
<h2 id="page_Tips-for-Making-Layouts-Keyboard-Agnostic">Tips for Making Layouts Keyboard-Agnostic</h2>
<p>Instead of using <code>#include &quot;planck.h&quot;</code>, you can use this line to include whatever <code>&lt;keyboard&gt;.h</code> (<code>&lt;folder&gt;.h</code> should not be included here) file that is being compiled:</p>
<pre><code>#include QMK_KEYBOARD_H
</code></pre>
<p>If you want to keep some keyboard-specific code, you can use these variables to escape it with an <code>#ifdef</code> statement:</p>
<ul>
<li>
<code>KEYBOARD_&lt;folder1&gt;_&lt;folder2&gt;</code>
</li>
</ul>
<p>For example:</p>
<pre><code class="language-c">#ifdef KEYBOARD_planck
#ifdef KEYBOARD_planck_rev4
planck_rev4_function();
#endif
#endif
</code></pre>
<p>Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.</p>
</div>
<nav>
<ul class="Pager">
<li class=Pager--prev><a href="../Features/Key_Lock.html">Previous</a></li> <li class=Pager--next><a href="../Features/Leader_Key.html">Next</a></li> </ul>
</nav>
</article>
</div>
</div>
</div>
</div>
<!-- JS -->
<script src="../themes/daux/js/jquery-1.11.3.min.js"></script><script src="../themes/daux/js/highlight.pack.js"></script><script src="../themes/daux/js/daux.js"></script>
<!-- Tipue Search -->
<script type="text/javascript" src="../tipuesearch/tipuesearch.js"></script>
<script>
window.onunload = function(){}; // force $(document).ready to be called on back/forward navigation in firefox
$(function() {
tipuesearch({
'base_url': '../'
});
});
</script>
</body>
</html>