layer_lock.md (4705B)
1 # Layer Lock 2 3 Some [layer switches](../feature_layers#switching-and-toggling-layers) access 4 the layer by holding the key, including momentary layer `MO(layer)` and layer 5 tap `LT(layer, key)` keys. You may sometimes need to stay on the layer for a 6 long period of time. Layer Lock "locks" the current layer to stay on, supposing 7 it 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 15 Press the Layer Lock key again to unlock the layer. Additionally, when a layer 16 is locked, layer switch keys that turn off the layer such as `TO(other_layer)` 17 will unlock it. 18 19 20 ## How do I enable Layer Lock 21 22 In your rules.mk, add: 23 24 ```make 25 LAYER_LOCK_ENABLE = yes 26 ``` 27 28 Pick a key in your keymap on a layer you intend to lock, and assign it the 29 keycode `QK_LAYER_LOCK` (short alias `QK_LLCK`). Note that locking the base 30 layer has no effect, so typically, this key is used on layers above the base 31 layer. 32 33 34 ## Example use 35 36 Consider a keymap with the following base layer. 37 38  39 40 The highlighted key is a momentary layer switch `MO(NAV)`. Holding it accesses a 41 navigation layer. 42 43  44 45 46 Holding the NAV key is fine for brief use, but awkward to continue holding when 47 using navigation functions continuously. The Layer Lock key comes to the rescue: 48 49 1. Hold the NAV key, activating the navigation layer. 50 2. Tap Layer Lock. 51 3. Release NAV. The navigation layer stays on. 52 4. Make use of the arrow keys, etc. 53 5. Tap Layer Lock or NAV again to turn the navigation layer back off. 54 55 A variation that would also work is to put the Layer Lock key on the base layer 56 and make other layers transparent (`KC_TRNS`) in that position. Pressing the 57 Layer Lock key locks (or unlocks) the highest active layer, regardless of which 58 layer the Layer Lock key is on. 59 60 61 ## Idle timeout 62 63 Optionally, Layer Lock may be configured to unlock if the keyboard is idle 64 for some time. In config.h, define `LAYER_LOCK_IDLE_TIMEOUT` in units of 65 milliseconds: 66 67 ```c 68 #define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds. 69 ``` 70 71 72 ## Functions 73 74 Use 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 86 There is an optional callback `layer_lock_set_user()` that gets called when a 87 layer is locked or unlocked. This is useful to represent the current lock state 88 for instance by setting an LED. In keymap.c, define 89 90 ```c 91 bool 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 97 The argument `locked_layers` is a bitfield in which the kth bit is on if the kth 98 layer is locked. Alternatively, you can use `is_layer_locked(layer)` to check if 99 a given layer is locked. 100 101 102 ## Combine Layer Lock with a mod-tap 103 104 It is possible to create a [mod-tap MT key](../mod_tap) that acts as a modifier 105 on hold and Layer Lock on tap. Since Layer Lock is not a [basic 106 keycode](../keycodes_basic), attempting `MT(mod, QK_LLCK)` is invalid does not 107 work directly, yet this effect can be achieved through [changing the tap 108 function](../mod_tap#changing-tap-function). For example, the following 109 implements 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 116 bool 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 134 In the above, `KC_0` is an arbitrary placeholder for the tapping keycode. This 135 keycode 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 137 the highest layer. Layer Lock can be combined with a [layer-tap LT 138 key](../feature_layers#switching-and-toggling-layers) similarly. 139