logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

layer_lock.md (4743B)

    

  1. # Layer Lock
  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:
  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)
  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.
  20. ## How do I enable Layer Lock
  22. In your rules.mk, add:
  24. ```make
  25. LAYER_LOCK_ENABLE = yes
  26. ```
  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.
  34. ## Example use
  36. Consider a keymap with the following base layer.
  38. ![Base layer with a MO(NAV) key.](https://i.imgur.com/DkEhj9x.png)
  40. The highlighted key is a momentary layer switch `MO(NAV)`. Holding it accesses a
  41. navigation layer.
  43. ![Nav layer with a Layer Lock key.](https://i.imgur.com/2wUZNWk.png)
  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:
  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.
  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.
  61. ## Idle timeout
  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:
  67. ```c
  68. #define LAYER_LOCK_IDLE_TIMEOUT 60000  // Turn off after 60 seconds.
  69. ```
  72. ## Functions
  74. Use the following functions to query and manipulate the layer lock state.
  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. |
  84. ## Representing the current Layer Lock state
  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
  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. ```
  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.
  102. ## Combine Layer Lock with a mod-tap
  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:
  111. ```c
  112. #define SFTLLCK LSFT_T(KC_0)
  114. // Use SFTLLCK in your keymap...
  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;
  128.         // Other macros...
  129.     }
  130.     return true;
  131. }
  132. ```
  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.