mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-07-18 21:52:02 +00:00
16 lines
12 KiB
JavaScript
16 lines
12 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.Cauyuiy8.js";
|
||
const __pageData = JSON.parse('{"title":"Layer Lock","description":"","frontmatter":{},"headers":[],"relativePath":"features/layer_lock.md","filePath":"features/layer_lock.md","lastUpdated":null}');
|
||
const _sfc_main = { name: "features/layer_lock.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="layer-lock" tabindex="-1">Layer Lock <a class="header-anchor" href="#layer-lock" aria-label="Permalink to "Layer Lock""></a></h1><p>Some <a href="./../feature_layers#switching-and-toggling-layers">layer switches</a> access the layer by holding the key, including momentary layer <code>MO(layer)</code> and layer tap <code>LT(layer, key)</code> keys. You may sometimes need to stay on the layer for a long period of time. Layer Lock "locks" the current layer to stay on, supposing it was accessed by one of:</p><ul><li><code>MO(layer)</code> momentary layer switch</li><li><code>LT(layer, key)</code> layer tap</li><li><code>OSL(layer)</code> one-shot layer</li><li><code>TT(layer)</code> layer tap toggle</li><li><code>LM(layer, mod)</code> layer-mod key (the layer is locked, but not the mods)</li></ul><p>Press the Layer Lock key again to unlock the layer. Additionally, when a layer is locked, layer switch keys that turn off the layer such as <code>TO(other_layer)</code> will unlock it.</p><h2 id="how-do-i-enable-layer-lock" tabindex="-1">How do I enable Layer Lock <a class="header-anchor" href="#how-do-i-enable-layer-lock" aria-label="Permalink to "How do I enable Layer Lock""></a></h2><p>In your rules.mk, add:</p><div class="language-make vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">make</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LAYER_LOCK_ENABLE = yes</span></span></code></pre></div><p>Pick a key in your keymap on a layer you intend to lock, and assign it the keycode <code>QK_LAYER_LOCK</code> (short alias <code>QK_LLCK</code>). Note that locking the base layer has no effect, so typically, this key is used on layers above the base layer.</p><h2 id="example-use" tabindex="-1">Example use <a class="header-anchor" href="#example-use" aria-label="Permalink to "Example use""></a></h2><p>Consider a keymap with the following base layer.</p><p><img src="https://i.imgur.com/DkEhj9x.png" alt="Base layer with a MO(NAV) key."></p><p>The highlighted key is a momentary layer switch <code>MO(NAV)</code>. Holding it accesses a navigation layer.</p><p><img src="https://i.imgur.com/2wUZNWk.png" alt="Nav layer with a Layer Lock key."></p><p>Holding the NAV key is fine for brief use, but awkward to continue holding when using navigation functions continuously. The Layer Lock key comes to the rescue:</p><ol><li>Hold the NAV key, activating the navigation layer.</li><li>Tap Layer Lock.</li><li>Release NAV. The navigation layer stays on.</li><li>Make use of the arrow keys, etc.</li><li>Tap Layer Lock or NAV again to turn the navigation layer back off.</li></ol><p>A variation that would also work is to put the Layer Lock key on the base layer and make other layers transparent (<code>KC_TRNS</code>) in that position. Pressing the Layer Lock key locks (or unlocks) the highest active layer, regardless of which layer the Layer Lock key is on.</p><h2 id="idle-timeout" tabindex="-1">Idle timeout <a class="header-anchor" href="#idle-timeout" aria-label="Permalink to "Idle timeout""></a></h2><p>Optionally, Layer Lock may be configured to unlock if the keyboard is idle for some time. In config.h, define <code>LAYER_LOCK_IDLE_TIMEOUT</code> in units of milliseconds:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LAYER_LOCK_IDLE_TIMEOUT</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60000</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Turn off after 60 seconds.</span></span></code></pre></div><h2 id="functions" tabindex="-1">Functions <a class="header-anchor" href="#functions" aria-label="Permalink to "Functions""></a></h2><p>Use the following functions to query and manipulate the layer lock state.</p><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>is_layer_locked(layer)</code></td><td>Checks whether <code>layer</code> is locked.</td></tr><tr><td><code>layer_lock_on(layer)</code></td><td>Locks and turns on <code>layer</code>.</td></tr><tr><td><code>layer_lock_off(layer)</code></td><td>Unlocks and turns off <code>layer</code>.</td></tr><tr><td><code>layer_lock_invert(layer)</code></td><td>Toggles whether <code>layer</code> is locked.</td></tr></tbody></table><h2 id="representing-the-current-layer-lock-state" tabindex="-1">Representing the current Layer Lock state <a class="header-anchor" href="#representing-the-current-layer-lock-state" aria-label="Permalink to "Representing the current Layer Lock state""></a></h2><p>There is an optional callback <code>layer_lock_set_user()</code> that gets called when a layer is locked or unlocked. This is useful to represent the current lock state for instance by setting an LED. In keymap.c, define</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_lock_set_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">layer_state_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> locked_layers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Do something like `set_led(is_layer_locked(NAV));`</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The argument <code>locked_layers</code> is a bitfield in which the kth bit is on if the kth layer is locked. Alternatively, you can use <code>is_layer_locked(layer)</code> to check if a given layer is locked.</p><h2 id="combine-layer-lock-with-a-mod-tap" tabindex="-1">Combine Layer Lock with a mod-tap <a class="header-anchor" href="#combine-layer-lock-with-a-mod-tap" aria-label="Permalink to "Combine Layer Lock with a mod-tap""></a></h2><p>It is possible to create a <a href="./../mod_tap">mod-tap MT key</a> that acts as a modifier on hold and Layer Lock on tap. Since Layer Lock is not a <a href="./../keycodes_basic">basic keycode</a>, attempting <code>MT(mod, QK_LLCK)</code> is invalid does not work directly, yet this effect can be achieved through <a href="./../mod_tap#changing-tap-function">changing the tap function</a>. For example, the following implements a <code>SFTLLCK</code> key that acts as Shift on hold and Layer Lock on tap:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SFTLLCK</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LSFT_T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_0)</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Use SFTLLCK in your keymap...</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> process_record_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> keycode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">keyrecord_t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">record</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> switch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (keycode) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> SFTLLCK:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (record</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tap.count) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (record->event.pressed) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Toggle the lock on the highest layer.</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_lock_invert</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get_highest_layer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(layer_state));</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> break</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Other macros...</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>In the above, <code>KC_0</code> is an arbitrary placeholder for the tapping keycode. This keycode will never be sent, so any basic keycode will do. In <code>process_record_user()</code>, the tap press event is changed to toggle the lock on the highest layer. Layer Lock can be combined with a <a href="./../feature_layers#switching-and-toggling-layers">layer-tap LT key</a> similarly.</p>', 30);
|
||
const _hoisted_31 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_31);
|
||
}
|
||
const layer_lock = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
layer_lock as default
|
||
};
|