layer_lock.h

 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. */
64bool is_layer_locked(uint8_t layer);
65
66/** Locks and turns on `layer`. */
67void layer_lock_on(uint8_t layer);
68
69/** Unlocks and turns off `layer`. */
70void layer_lock_off(uint8_t layer);
71
72/** Unlocks and turns off all locked layers. */
73void layer_lock_all_off(void);
74
75/** Toggles whether `layer` is locked. */
76void 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 */
91bool layer_lock_set_kb(layer_state_t locked_layers);
92bool layer_lock_set_user(layer_state_t locked_layers);
93
94/** Handle various background tasks */
95void layer_lock_task(void);
96
97/** Update any configured timeouts */
98void layer_lock_activity_trigger(void);