layer_lock.h (3338B)
1 // Copyright 2022-2023 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 /** 16 * @file layer_lock.h 17 * @brief Layer Lock, a key to stay in the current layer. 18 * 19 * Overview 20 * -------- 21 * 22 * Layers are often accessed by holding a button, e.g. with a momentary layer 23 * switch `MO(layer)` or layer tap `LT(layer, key)` key. But you may sometimes 24 * want to "lock" or "toggle" the layer so that it stays on without having to 25 * hold down a button. One way to do that is with a tap-toggle `TT` layer key, 26 * but here is an alternative. 27 * 28 * This library implements a "Layer Lock key". When tapped, it "locks" the 29 * highest layer to stay active, assuming the layer was activated by one of the 30 * following keys: 31 * 32 * * `MO(layer)` momentary layer switch 33 * * `LT(layer, key)` layer tap 34 * * `OSL(layer)` one-shot layer 35 * * `TT(layer)` layer tap toggle 36 * * `LM(layer, mod)` layer-mod key (the layer is locked, but not the mods) 37 * 38 * Tapping the Layer Lock key again unlocks and turns off the layer. 39 * 40 * @note When a layer is "locked", other layer keys such as `TO(layer)` or 41 * manually calling `layer_off(layer)` will override and unlock the layer. 42 * 43 * Configuration 44 * ------------- 45 * 46 * Optionally, a timeout may be defined so that Layer Lock disables 47 * automatically if not keys are pressed for `LAYER_LOCK_IDLE_TIMEOUT` 48 * milliseconds. Define `LAYER_LOCK_IDLE_TIMEOUT` in your config.h, for instance 49 * 50 * #define LAYER_LOCK_IDLE_TIMEOUT 60000 // Turn off after 60 seconds. 51 * 52 * For full documentation, see 53 * <https://getreuer.info/posts/keyboards/layer-lock> 54 */ 55 56 #pragma once 57 58 #include <stdint.h> 59 #include <stdbool.h> 60 #include "action_layer.h" 61 #include "action_util.h" 62 63 /** Returns true if `layer` is currently locked. */ 64 bool is_layer_locked(uint8_t layer); 65 66 /** Locks and turns on `layer`. */ 67 void layer_lock_on(uint8_t layer); 68 69 /** Unlocks and turns off `layer`. */ 70 void layer_lock_off(uint8_t layer); 71 72 /** Unlocks and turns off all locked layers. */ 73 void layer_lock_all_off(void); 74 75 /** Toggles whether `layer` is locked. */ 76 void layer_lock_invert(uint8_t layer); 77 78 /** 79 * Optional callback that gets called when a layer is locked or unlocked. 80 * 81 * This is useful to represent the current lock state, e.g. by setting an LED or 82 * playing a sound. In your keymap, define 83 * 84 * void layer_lock_set_user(layer_state_t locked_layers) { 85 * // Do something like `set_led(is_layer_locked(NAV));` 86 * } 87 * 88 * @param locked_layers Bitfield in which the kth bit represents whether the 89 * kth layer is on. 90 */ 91 bool layer_lock_set_kb(layer_state_t locked_layers); 92 bool layer_lock_set_user(layer_state_t locked_layers); 93 94 /** Handle various background tasks */ 95 void layer_lock_task(void); 96 97 /** Update any configured timeouts */ 98 void layer_lock_activity_trigger(void);