logo

qmk_firmware

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

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.
  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.  */
  56. #pragma once
  58. #include <stdint.h>
  59. #include <stdbool.h>
  60. #include "action_layer.h"
  61. #include "action_util.h"
  63. /** Returns true if `layer` is currently locked. */
  64. bool is_layer_locked(uint8_t layer);
  66. /** Locks and turns on `layer`. */
  67. void layer_lock_on(uint8_t layer);
  69. /** Unlocks and turns off `layer`. */
  70. void layer_lock_off(uint8_t layer);
  72. /** Unlocks and turns off all locked layers. */
  73. void layer_lock_all_off(void);
  75. /** Toggles whether `layer` is locked. */
  76. void layer_lock_invert(uint8_t layer);
  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);
  94. /** Handle various background tasks */
  95. void layer_lock_task(void);
  97. /** Update any configured timeouts */
  98. void layer_lock_activity_trigger(void);