repeat_key.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#pragma once
16
17#include <stdint.h>
18#include <stdbool.h>
19#include "action.h"
20#include "keyboard.h"
21
22uint16_t get_last_keycode(void);             /**< Keycode of the last key. */
23uint8_t  get_last_mods(void);                /**< Mods active with the last key. */
24void     set_last_keycode(uint16_t keycode); /**< Sets the last key. */
25void     set_last_mods(uint8_t mods);        /**< Sets the last mods. */
26
27/** @brief Gets the record for the last key. */
28keyrecord_t* get_last_record(void);
29
30/** @brief Sets keycode and record info for the last key. */
31void set_last_record(uint16_t keycode, keyrecord_t* record);
32
33/**
34 * @brief Signed count of times the key has been repeated or alternate repeated.
35 *
36 * @note The count is nonzero only while a repeated or alternate-repeated key is
37 *       being processed.
38 *
39 * When a key is pressed normally, the count is 0. When the Repeat Key is used
40 * to repeat a key, the count is 1 on the first repeat, 2 on the second repeat,
41 * and continuing up to 127.
42 *
43 * Negative counts are used similarly for alternate repeating. When the
44 * Alternate Repeat Key is used, the count is -1 on the first alternate repeat,
45 * -2 on the second, continuing down to -127.
46 */
47int8_t get_repeat_key_count(void);
48
49/**
50 * @brief Calls `process_record()` on a generated record repeating the last key.
51 * @param event Event information in the generated record.
52 */
53void repeat_key_invoke(const keyevent_t* event);
54
55#ifndef NO_ALT_REPEAT_KEY
56
57/**
58 * @brief Keycode to be used for alternate repeating.
59 *
60 * Alternate Repeat performs this keycode based on the last eligible pressed key
61 * and mods, get_last_keycode() and get_last_mods(). For example, when the last
62 * key was KC_UP, this function returns KC_DOWN. The function returns KC_NO if
63 * the last key doesn't have a defined alternate.
64 */
65uint16_t get_alt_repeat_key_keycode(void);
66
67/**
68 * @brief Calls `process_record()` to alternate repeat the last key.
69 * @param event Event information in the generated record.
70 */
71void alt_repeat_key_invoke(const keyevent_t* event);
72
73/**
74 * @brief Optional user callback to define additional alternate keys.
75 *
76 * When `get_alt_repeat_key_keycode()` is called, it first calls this callback.
77 * It should return a keycode representing the "alternate" of the given keycode
78 * and mods. Returning KC_NO defers to the default definitions in
79 * `get_alt_repeat_key_keycode()`.
80 */
81uint16_t get_alt_repeat_key_keycode_user(uint16_t keycode, uint8_t mods);
82
83#endif // NO_ALT_REPEAT_KEY