auri.ee
keyboard stuff
1# Layer Lock
2
3Some [layer switches](../feature_layers#switching-and-toggling-layers) access
4the layer by holding the key, including momentary layer `MO(layer)` and layer
5tap `LT(layer, key)` keys. You may sometimes need to stay on the layer for a
6long period of time. Layer Lock "locks" the current layer to stay on, supposing
7it was accessed by one of:
8
9 * `MO(layer)` momentary layer switch
10 * `LT(layer, key)` layer tap
11 * `OSL(layer)` one-shot layer
12 * `TT(layer)` layer tap toggle
13 * `LM(layer, mod)` layer-mod key (the layer is locked, but not the mods)
14
15Press the Layer Lock key again to unlock the layer. Additionally, when a layer
16is locked, layer switch keys that turn off the layer such as `TO(other_layer)`
17will unlock it.
18
19
20## How do I enable Layer Lock
21
22In your rules.mk, add:
23
24```make
25LAYER_LOCK_ENABLE = yes
26```
27
28Pick a key in your keymap on a layer you intend to lock, and assign it the
29keycode `QK_LAYER_LOCK` (short alias `QK_LLCK`). Note that locking the base
30layer has no effect, so typically, this key is used on layers above the base
31layer.
32
33
34## Example use
35
36Consider a keymap with the following base layer.
37
38
39
40The highlighted key is a momentary layer switch `MO(NAV)`. Holding it accesses a
41navigation layer.
42
43
44
45
46Holding the NAV key is fine for brief use, but awkward to continue holding when
47using navigation functions continuously. The Layer Lock key comes to the rescue:
48
491. Hold the NAV key, activating the navigation layer.
502. Tap Layer Lock.
513. Release NAV. The navigation layer stays on.
524. Make use of the arrow keys, etc.
535. Tap Layer Lock or NAV again to turn the navigation layer back off.
54
55A variation that would also work is to put the Layer Lock key on the base layer
56and make other layers transparent (`KC_TRNS`) in that position. Pressing the
57Layer Lock key locks (or unlocks) the highest active layer, regardless of which
58layer the Layer Lock key is on.
59
60
61## Idle timeout
62
63Optionally, Layer Lock may be configured to unlock if the keyboard is idle
64for some time. In config.h, define `LAYER_LOCK_IDLE_TIMEOUT` in units of
65milliseconds:
66
67```c
68#define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds.
69```
70
71
72## Functions
73
74Use the following functions to query and manipulate the layer lock state.
75
76| Function | Description |
77|----------------------------|------------------------------------|
78| `is_layer_locked(layer)` | Checks whether `layer` is locked. |
79| `layer_lock_on(layer)` | Locks and turns on `layer`. |
80| `layer_lock_off(layer)` | Unlocks and turns off `layer`. |
81| `layer_lock_invert(layer)` | Toggles whether `layer` is locked. |
82
83
84## Representing the current Layer Lock state
85
86There is an optional callback `layer_lock_set_user()` that gets called when a
87layer is locked or unlocked. This is useful to represent the current lock state
88for instance by setting an LED. In keymap.c, define
89
90```c
91bool layer_lock_set_user(layer_state_t locked_layers) {
92 // Do something like `set_led(is_layer_locked(NAV));`
93 return true;
94}
95```
96
97The argument `locked_layers` is a bitfield in which the kth bit is on if the kth
98layer is locked. Alternatively, you can use `is_layer_locked(layer)` to check if
99a given layer is locked.
100
101
102## Combine Layer Lock with a mod-tap
103
104It is possible to create a [mod-tap MT key](../mod_tap) that acts as a modifier
105on hold and Layer Lock on tap. Since Layer Lock is not a [basic
106keycode](../keycodes_basic), attempting `MT(mod, QK_LLCK)` is invalid does not
107work directly, yet this effect can be achieved through [changing the tap
108function](../mod_tap#changing-tap-function). For example, the following
109implements a `SFTLLCK` key that acts as Shift on hold and Layer Lock on tap:
110
111```c
112#define SFTLLCK LSFT_T(KC_0)
113
114// Use SFTLLCK in your keymap...
115
116bool process_record_user(uint16_t keycode, keyrecord_t *record) {
117 switch (keycode) {
118 case SFTLLCK:
119 if (record->tap.count) {
120 if (record->event.pressed) {
121 // Toggle the lock on the highest layer.
122 layer_lock_invert(get_highest_layer(layer_state));
123 }
124 return false;
125 }
126 break;
127
128 // Other macros...
129 }
130 return true;
131}
132```
133
134In the above, `KC_0` is an arbitrary placeholder for the tapping keycode. This
135keycode will never be sent, so any basic keycode will do. In
136`process_record_user()`, the tap press event is changed to toggle the lock on
137the highest layer. Layer Lock can be combined with a [layer-tap LT
138key](../feature_layers#switching-and-toggling-layers) similarly.
139