diff options
Diffstat (limited to 'docs/zh-cn/custom_quantum_functions.md')
| -rw-r--r-- | docs/zh-cn/custom_quantum_functions.md | 367 |
1 files changed, 177 insertions, 190 deletions
diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md index 1ae996e392..29c5089052 100644 --- a/docs/zh-cn/custom_quantum_functions.md +++ b/docs/zh-cn/custom_quantum_functions.md @@ -1,31 +1,35 @@ -# 如何定制你键盘的功能 +# 如何定制化键盘功能 -对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。 +<!--- + original document: 0.15.12:docs/custom_quantum_functions.md + git diff 0.15.12 HEAD -- docs/custom_quantum_functions.md | cat +--> -本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。 +对于很多人来说对客制化键盘的诉求不只是向电脑输入按下的键。你肯定想实现比简单按键和宏更复杂的功能。QMK支持基于注入点的代码注入，功能重写，另外还可以自定义键盘在不同情况下的行为。 -## A Word on Core vs 键盘 vs 布局 +本页不要求任何额外的QMK知识基础，但阅读[理解QMK](zh-cn/understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。 -我们把qmk组织成一个层次结构： +## 核心/键盘/键映射的概念 :id=a-word-on-core-vs-keyboards-vs-keymap + +QMK基于如下层级组成： * Core (`_quantum`) * Keyboard/Revision (`_kb`) * Keymap (`_user`) -下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。 +该文后续部分所提及的函数在定义时皆可添加 `_kb()` 或 `_user()` 后缀，我们建议在键盘及其子版本中使用 `_kb()` 后缀，而在键映射中使用 `_user()` 后缀。 -在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。 -<!-- 翻译问题：上面那句翻译的不太好--> +在键盘及其子版本中定义函数时，一个重要的点是在 `_kb()` 函数执行任何逻辑前，应先调用 `_user()` 函数，否则这些键映射中的函数将没有机会被执行。 # 自定义键码 到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。 ## 定义一个新键码 -创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。 +创建键码的第一步，是先定义其枚举值，也就是给键码起个名字并分配一个唯一值。QMK没有直接限制最大可用的键码值，而是提供了一个 `SAFE_RANGE` 宏。你可以在定义枚举时用 `SAFE_RANGE` 来保证你取得了唯一的键码值。 -这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。 +这有定义两个键码的枚举值的例子。添加以下代码块至 `keymap.c` 后你就可以在布局中使用 `FOO` 和 `BAR` 了。 ```c enum my_keycodes { @@ -34,15 +38,15 @@ enum my_keycodes { }; ``` -## 为键码的行为编程 +## 编程设计你的键码的行为 :id=programming-the-behavior-of-any-keycode -当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。 +当你覆盖一个已存在按键的行为时，或是给新按键设计功能时，请使用 `process_record_kb()` 和 `process_record_user()` 函数。QMK会在响应并处理按键事件前调用这些函数，如果这些函数返回值为 `true`，QMK将继续用常规的方式处理键码，这样可以很方便的扩展键码的功能而不需要替换代码实现。如果函数返回`false` QMK会跳过常规的键处理逻辑，需要发送的按键按下或抬起事件则需交由你负责完成。 -当某个键按下或释放时这俩函数会被调用。 +任意按键在按下或抬起时，每次都会调用这些函数。 -### process_record_user()`函数示例实现 +### process_record_user()` 实现示例 -这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。 +这个例子做了两个事。自定义了一个叫做 `FOO` 的键码的行为，并提供了在按下回车时播放音符的功能。 ```c bool process_record_user(uint16_t keycode, keyrecord_t *record) { @@ -51,7 +55,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { if (record->event.pressed) { // 按下时做些什么 } else { - // 释放时做些什么 + // 抬起时做些什么 } return false; // 跳过此键的所有进一步处理 case KC_ENTER: @@ -59,21 +63,21 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { if (record->event.pressed) { PLAY_SONG(tone_qwerty); } - return true; // 让QMK触发回车按下/释放事件 + return true; // 让QMK响应回车按下/抬起事件 default: - return true; // 正常处理其他键码 + return true; // 正常响应其他键码 } } ``` -### `process_record_*` 函数文档 +### `process_record_*` 实现示例 -* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` -* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` +* 键盘/各子版本：`bool process_record_kb(uint16_t keycode, keyrecord_t *record)` +* 键映射：`bool process_record_user(uint16_t keycode, keyrecord_t *record)` -`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。 +`keycode` 参数为键映射中形如 `MO(1)`，`KC_L` 等定义的键值项。 应使用 `switch...case` 代码块来处理这些事件。 -`record`参数含有实际按键的信息： +`record` 参数含有按键的真实状态信息： ```c keyrecord_t record { @@ -88,108 +92,31 @@ keyrecord_t record { } ``` -# LED控制 - -qmk提供了读取HID规范包含的5个LED的方法。: - -* `USB_LED_NUM_LOCK` -* `USB_LED_CAPS_LOCK` -* `USB_LED_SCROLL_LOCK` -* `USB_LED_COMPOSE` -* `USB_LED_KANA` - -这五个常量对应于主机LED状态的位置位。 -有两种方法可以获得主机LED状态： - -* 通过执行 `led_set_user()` -* 通过调用 `host_keyboard_leds()` - -## `led_set_user()` - -当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。 -使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。 - -!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。 - -### `led_set_user()`函数示例实现 - -```c -void led_set_user(uint8_t usb_led) { - if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { - writePinLow(B0); - } else { - writePinHigh(B0); - } - if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { - writePinLow(B1); - } else { - writePinHigh(B1); - } - if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { - writePinLow(B2); - } else { - writePinHigh(B2); - } - if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { - writePinLow(B3); - } else { - writePinHigh(B3); - } - if (IS_LED_ON(usb_led, USB_LED_KANA)) { - writePinLow(B4); - } else { - writePinHigh(B4); - } -} -``` - -### `led_set_*`函数文档 - -* 键盘/修订: `void led_set_kb(uint8_t usb_led)` -* 布局: `void led_set_user(uint8_t usb_led)` - -## `host_keyboard_leds()` - -调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码). -为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。 - -## 设置物理LED状态 - -一些键盘实现了为设置物理LED的状态提供了方便的方法。 - -### Ergodox Boards - -Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。 - -此外，还可以使用`ergodox_led_all_set(uint8_t n)`指定所有LED的亮度级别；针对每个LED用`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`；使用索引的话用`ergodox_right_led_set(uint8_t led, uint8_t n)`。 - -Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高). - # 键盘初始化代码 -键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。 +键盘初始化过程须经过几个步骤，而你的目的决定了你需要关注哪些函数。 有三个主要初始化函数，按调用顺序列出。 -* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。 -* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。 -* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。 +* `keyboard_pre_init_*` - 会在大多数其他功能运行前执行。适用于那些需要尽早执行的硬件初始化工作。 +* `matrix_init_*` - 在固件启动过程中被调用。此时硬件已初始化，但部分功能还不可用。 +* `keyboard_post_init_*` - 在固件启动过程的最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。 -!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。 +!> 对于大多数人来说 `keyboard_post_init_user` 是你想要关注的函数。例如, 你可以在这里启动RGB背光灯。 ## 键盘预初始化代码 -这代码极早运行，甚至都在USB初始化前运行。 +这部分代码执行的非常早，甚至是在USB通信功能启动之前。 -在这之后不久矩阵就被初始化了。 +在这之后不久即会完成矩阵的初始化。 -对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。 +对于大多数用户来说不应在此处进行修改，因为它主要用于硬件初始化。 -但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的). +但如果你有硬件须初始化的话放在这里再好不过了（比如初始化LED引脚）. -### `keyboard_pre_init_user()`函数示例实现 +### `keyboard_pre_init_user()` 实现示例 -本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。 +本例中，在键盘层将 B0, B1, B2, B3, 和 B4 引脚设置为LED引脚。 ```c void keyboard_pre_init_user(void) { @@ -206,95 +133,110 @@ void keyboard_pre_init_user(void) { ### `keyboard_pre_init_*` 函数文档 -* 键盘/修订: `void keyboard_pre_init_kb(void)` -* 布局: `void keyboard_pre_init_user(void)` +* 键盘/各子版本：`void keyboard_pre_init_kb(void)` +* 键映射：`void keyboard_pre_init_user(void)` ## 矩阵初始化代码 -这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。 +在矩阵初始化后被调用。此时一部分硬件已设置完成，但一些功能尚未完成初始化。 -这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。 +此处可以用来设置一些与硬件无关，且对初始化位置没有特殊要求的功能。 -### `matrix_init_*`函数文档 +### `matrix_init_*` 函数文档 -* 键盘/修订: `void matrix_init_kb(void)` -* 布局: `void matrix_init_user(void)` +* 键盘/各子版本：`void matrix_init_kb(void)` +* 键映射：`void matrix_init_user(void)` +### 低级矩阵函数的重写 :id=low-level-matrix-overrides -## 键盘后初始化代码 +* GPIO引脚初始化：`void matrix_init_pins(void)` + * 此处须完成低级行列引脚的初始化。默认实现中，这里会参考可选的键盘设置项 `ROW2COL`，`COL2ROW` 及 `DIRECT_PINS` 来初始化所有 `MATRIX_ROW_PINS` 及 `MATRIX_COL_PINS` 中定义的GPIO引脚的输入/输出状态。当键盘设计者重写该函数后，QMK本身不会进行任何引脚的初始化，只会听从重写的函数的实现逻辑。 +* `COL2ROW`-从行中读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` +* `ROW2COL`-从列中读: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `DIRECT_PINS`-直读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` + * 以上三个函数须参考矩阵类别，从底层矩阵的相关引脚状态中获取输入信息，并且应该只需要实现三者之一。默认情况下，在遍历 `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` 时，会根据是否设置了 `ROW2COL`，`COL2ROW` 或 `DIRECT_PINS` 来配置输入输出方式。当键盘设计者重写该函数后，QMK本身不会进行任何矩阵GPIO引脚状态的变更，只会听从重写的函数的实现逻辑。 -这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。 +## 键盘后初始化代码 +这是键盘初始化过程中的最后一个任务。此时您可以配置并调整某些特性，因为此时这些特性已初始化完毕。 -### `keyboard_post_init_user()`示例实现 +### `keyboard_post_init_user()` 实现示例 -本示例在所有初始化完成后运行，配置RGB灯。 +本示例在所有初始化完成后运行，配置RGB背光。 ```c void keyboard_post_init_user(void) { // 调用后初始化代码 rgblight_enable_noeeprom(); // 使能Rgb，不保存设置 - rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存 - rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存 + rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)，不保存设置 + rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式，不保存设置 } ``` ### `keyboard_post_init_*` 函数文档 -* 键盘/修订: `void keyboard_post_init_kb(void)` +* 键盘/各子版本：`void keyboard_post_init_kb(void)` * 布局: `void keyboard_post_init_user(void)` -# 矩阵扫描代码 +# 矩阵扫描码 -可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。 +应尽量使用 `process_record_*()` 实现所需的键盘自定义以及事件监听，以确保这些代码不会对键盘性能产生负面的影响。然而，在极少数情况下需要在矩阵扫描中添加监听，此时需要极端留意这些函数代码的性能表现，因为这些函数每秒可能被执行十数次。 -### `matrix_scan_*`示例实现 +### `matrix_scan_*` 实现示例 -这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh). +这个例子被故意省略了。在监听处理这样一个对性能及其敏感的部分之前，您应该足够了解qmk的内部结构，才可以在没有示例的情况下编写。如果你需要帮助，请[新建一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh). ### `matrix_scan_*` 函数文档 -* 键盘/修订: `void matrix_scan_kb(void)` +* 键盘/各子版本：`void matrix_scan_kb(void)` * 布局: `void matrix_scan_user(void)` 该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。 -你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。 +在需要自定义矩阵扫描代码时可以使用该函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户没有输入时你也想定期运行的功能。 + +# Keyboard housekeeping + +* 键盘/各子版本：`void housekeeping_task_kb(void)` +* 键映射：`void housekeeping_task_user(void)` + +该函数在所有QMK处理工作完毕后，下一轮开始执行前被执行。可以放心地假设此时QMK已对最新的矩阵扫描结果完成了所有的处理工作 -- 更新层状态，发送USB事件，更新LED状态，刷新显示屏。 +与 `matrix_scan_*` 类似，这些函数会频繁调用直至MCU处理能力上限。为了确保键盘的响应能力，建议在这些函数中尽量做最少的事情，在你确实需要在这里实现特别的功能时，可能会影响到其它功能的表现。 # 键盘 空闲/唤醒 代码 -如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。 +在主控板支持情况下，暂停大部分功能可以实现“空闲”状态，例如RGB灯光和背光。既可以节省电量消耗，也可能增强键盘的表现。 -用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。 +这由两个函数控制: `suspend_power_down_*` 和 `suspend_wakeup_init_*`，分别在主控板空闲和唤醒时被调用。 -### suspend_power_down_user()和suspend_wakeup_init_user()示例实现 +### suspend_power_down_user() 和 suspend_wakeup_init_user() 的实现示例 ```c void suspend_power_down_user(void) { - // code will run multiple times while keyboard is suspended + // 当键盘挂起时会被多次调用的代码 } void suspend_wakeup_init_user(void) { - // code will run on keyboard wakeup + // 键盘唤醒时被调用的代码 } ``` ### 键盘 挂起/唤醒 函数文档 -* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)` -* 布局: `void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)` +* 键盘/各子版本：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)` +* 键映射：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)` -# 层改变代码 +# 层切换代码 :id=layer-change-code -每当层改变这个就运行代码。这对于层指示或自定义层处理很有用。 +每当层发生切换时被执行，可用于感知层切换事件，或自定义层处理逻辑。 -### `layer_state_set_*` 示例实现 +### `layer_state_set_*` 实现示例 -本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应 +本例中，通过Planck键盘示范了如何将[RGB背光灯](zh-cn/feature_rgblight.md)设置为与层同步。 ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -311,36 +253,41 @@ layer_state_t layer_state_set_user(layer_state_t state) { case _ADJUST: rgblight_setrgb (0x7A, 0x00, 0xFF); break; - default: // for any other layers, or the default layer + default: // 默认层及其它层 rgblight_setrgb (0x00, 0xFF, 0xFF); break; } return state; } ``` + +可以通过 `IS_LAYER_ON_STATE(state, layer)` 和 `IS_LAYER_OFF_STATE(state, layer)` 宏来确认常规层的状态。 + +如果不在 `layer_state_set_*` 函数中，可以通过 `IS_LAYER_ON(layer)` 和 `IS_LAYER_OFF(layer)` 宏来确认全局的层状态。 + ### `layer_state_set_*` 函数文档 -* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)` +* 键盘/各子版本：`uint32_t layer_state_set_kb(uint32_t state)` * 布局: `layer_state_t layer_state_set_user(layer_state_t state)` -该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态) +此处的 `state` 为当前活跃层的位掩码, 详见[键映射概述](zh-cn/keymap.md#keymap-layer-status) -# 掉电保存配置 (EEPROM) +# 配置的持久存储（EEPROM） -这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。 +该功能可以让键盘的配置持久存储下来。这些配置存储在控制器的EEPROM中，即便掉电后依旧可以留存下来。可以通过 `eeconfig_read_kb` 和 `eeconfig_read_user` 来读取，通过 `eeconfig_update_kb` and `eeconfig_update_user` 来进行保存。该功能常用于保存一些开关状态（比如rgb层指示灯）。此外，可以通过 `eeconfig_init_kb` 和 `eeconfig_init_user` 来设置EEPROM的默认配置值。 -最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。 +复杂的地方是，有很多方法可以存储和访问EEPROM数据，并且没有哪种方法是“正确”的。但是，每个功能只有一个双字(四字节)空间可用。 -记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。 +记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有这些配置信息会写到EEPROM中。如果你写入过于频繁，你的MCU寿命将会急速减少。 -* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。 +* 如果您不理解这个例子，那么您可以不使用这个特性，因为它相当复杂。 -### 示例实现 - -本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！ +### 实现示例 +本例讲解了如何添加并读写设置项。本例使用用户键映射来实现。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多前述的函数来工作！ +（译注：该示例由于英文行文，可能会觉得看得稀里糊涂。实现的功能很简单，即开启了层指示功能（RGB_LYR）时，rgb背光灯会展示当前层的特定颜色用以指示层状态，而触发任何改变rgb背光颜色的键码时，rgb背光灯将回归普通的背光灯角色，不再作为层指示器） 在你的keymap.c文件中，将以下代码添加至顶部: ```c @@ -354,14 +301,14 @@ typedef union { user_config_t user_config; ``` -以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 +以上代码建立了一个32位的结构体，用于在内存及EEPROM中存储配置项。此时不再需要再单独声明变量，因为都已经在该结构体中定义了。须记住 `bool`（布尔）值占用1位，`uint8_t` 占用8位，`uint16_t` 占用16位。你可以混合搭配使用，但改变这些顺序会因为错误的读写而招致问题。 - `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。 +我们在 `layer_state_set_*` 函数中会使用 `rgb_layer_change`。通过 `keyboard_post_init_user` 和 `process_record_user` 来配置所需的一切。 -首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： +在编写 `keyboard_post_init_user` 时，你需要使用 `eeconfig_read_user()` 来计算并填充你刚刚创建的结构体。然后即可以使用结构体数据来控制键映射中的功能。就像这样： ```c void keyboard_post_init_user(void) { - // 调用布局级别的矩阵初始化 + // 调用键映射级别的矩阵初始化 // 从EEPROM读用户配置 user_config.raw = eeconfig_read_user(); @@ -374,7 +321,7 @@ void keyboard_post_init_user(void) { } } ``` -以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 +以上函数会在读EEPROM配置后立即设置默认层的RGB颜色。"raw"值将被转换为上述创建的实际使用的"union"结构体。 ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -398,7 +345,7 @@ layer_state_t layer_state_set_user(layer_state_t state) { return state; } ``` -这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为： +这样仅在相关值使能时才会改变RGB背光灯。若要配置该值, 为 `process_record_user` 创建一个新键码 `RGB_LYR`。此时我们想实现的是，如果触发了常规的RGB码，以上示例中的逻辑都将不生效，形如： ```c bool process_record_user(uint16_t keycode, keyrecord_t *record) { @@ -407,7 +354,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { if (record->event.pressed) { // 按下时做点什么 } else { - // 释放时做点什么 + // 抬起时做点什么 } return false; // 跳过此键的进一步处理 case KC_ENTER: @@ -415,76 +362,116 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { if (record->event.pressed) { PLAY_SONG(tone_qwerty); } - return true; // 让QMK产生回车按下/释放事件 - case RGB_LYR: // 本句让underglow作为层指示，或正常使用。 + return true; // 让QMK产生回车按下/抬起事件 + case RGB_LYR: // 这允许我们将背光灯作为层指示，或正常用途 if (record->event.pressed) { user_config.rgb_layer_change ^= 1; // 切换状态 eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态 - if (user_config.rgb_layer_change) { // 如果层状态被使能 + if (user_config.rgb_layer_change) { // 如果层指示功能被使能 layer_state_set(layer_state); // 那么立刻更新层颜色 } } return false; - case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考) - if (record->event.pressed) { //本句失能层指示，假设你改变了这个…你要把它禁用 + case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (参考 quantum_keycodes.h, 400 行处) + if (record->event.pressed) { // 本句失能层指示功能，假设你现在要调整该功能…你要把它禁用 if (user_config.rgb_layer_change) { // 仅当使能时 - user_config.rgb_layer_change = false; // 失能，然后 + user_config.rgb_layer_change = false; // 失能，然后 eeconfig_update_user(user_config.raw); // 向EEPROM写入设置 } } return true; break; default: - return true; // 按其他键正常 + return true; // 其他键码正常处理 } } ``` -最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值 +最后，须添加 `eeconfig_init_user` 函数，从而当EEPROM重置时，可以指定默认值, 甚至自定义操作。若想强制重置EEPROM，请用 `EEP_RST` 键码或[Bootmagic](zh-cn/feature_bootmagic.md) 功能。比如，在你想重置RGB层指示配置，并保存默认值时。 ```c -void eeconfig_init_user(void) { // EEPROM正被重置 +void eeconfig_init_user(void) { // EEPROM被重置 user_config.raw = 0; user_config.rgb_layer_change = true; // 我们想要默认使能 eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值 - // use the non noeeprom versions, 还要向EEPROM写入这些值 + // 通过使用非'noeeprom'版本的函数，可以同时写入这些配置到EEPROM中。 rgblight_enable(); // 默认使能RGB rgblight_sethsv_cyan(); // 默认设置青色 rgblight_mode(1); // 默认设置长亮 } ``` -然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 +一切已就绪，RGB层指示将在需要时生效。这个设置会持久存储，即便是拔下键盘。如果你使用其他RGB码，层指示将失效，从而可以停留在期望的模式及颜色下。 ### 'EECONFIG' 函数文档 -* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)` -* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)` +* 键盘/各子版本：`void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` 和 `void eeconfig_update_kb(uint32_t val)` +* 键映射：`void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` 和 `void eeconfig_update_user(uint32_t val)` `val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。 -# 自定义击键-长按临界值(TAPPING_TERM) -默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。 - -想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。 +### 定时执行 :id=deferred-execution +QMK支持在特定时间间隔后执行回调，以代替手动的计时器管理。 -## `get_tapping_term`示例实现 +#### 定时回调函数 -想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码: +所有的 _定时回调函数_ 使用同样的函数签名，如下： ```c -uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case SFT_T(KC_SPC): - return TAPPING_TERM + 1250; - case LT(1, KC_GRV): - return 130; - default: - return TAPPING_TERM; - } +uint32_t my_callback(uint32_t trigger_time, void *cb_arg) { + /* 处理了一些工作 */ + bool repeat = my_deferred_functionality(); + return repeat ? 500 : 0; } ``` -### `get_tapping_term` 函数文档 +第一个参数 `trigger_time` 为预期的执行时间，如果因为其它事情造成了延迟未能在准确的时间点执行，可以利用这个参数“追赶”或者跳过这次间隔，取决于你的目的是什么。 + +第二个参数 `cb_arg` 为下述的 `defer_exec()` 传入的参数，由此可以获取调用时的状态信息。 + +返回值为该函数下一次期望被回调的时间间隔毫秒数 -- 若返回 `0` 则会自动被注销掉。上例中，通过执行假想的 `my_deferred_functionality()` 函数来决策回调是否继续下去 -- 若是，则给出一个 `500` 毫秒的延迟计划，否则，返回 `0` 来告知定时处理后台任务该计划已执行完毕。 + +?> 须留意返回的延时时间是相对原定的触发时间点的，而不是回调执行完的时间点。这样可以防止偶发的执行延迟影响稳定的定时事件计划。 + +#### 注册定时回调 + +在定义好回调后，通过如下API进行定时回调注册： + +```c +deferred_token my_token = defer_exec(1500, my_callback, NULL); +``` + +第一个参数为执行 `my_callback` 的毫秒时间延迟 -- 上例中为 `1500` 毫秒，即 1.5 秒。 + +第三个参数为回调执行时传入的 `cb_arg` 参数。须确保该值在回调时依旧有效 -- 局部函数内的变量会在回调执行前就被释放掉因此不能用。如果并不需要这个参数，可以传入 `NULL`。 + +返回值 `deferred_token` 可被用于在回调执行前取消该定时计划。如果该函数调用失败，会返回 `INVALID_DEFERRED_TOKEN`，一般错误原因是延时值被设置为 `0` 或回调函数参数为 `NULL`，还有一种可能是已有过量的回调在等待被处理 -- 可以按照下述方法修改这个阈值。 + +#### 延长定时回调时间 + +由 `defer_exec()` 返回的 `deferred_token` 可以用来修改回调执行所需等待的时延值： +```c +// 重新调整 my_token 后续的执行计划为当前时间起800ms后 +extend_deferred_exec(my_token, 800); +``` + +#### 取消定时回调 + +由 `defer_exec()` 返回的 `deferred_token` 可以用来取消掉后续的执行计划： +```c +// 取消 my_token 的后续回调 +cancel_deferred_exec(my_token); +``` + +一旦 token 被取消了，即视为不再可用。重新使用该 token 是不支持的。 + +#### 定时回调的限制 + +可安排的定时回调计划数量是有限的，由 `MAX_DEFERRED_EXECUTORS` 定义的值确定。 + +如果定时回调注册失败了，可以在对应的键盘或键映射下的 `config.h` 文件中修改该值，比如将默认的 8 改为 16： + +```c +#define MAX_DEFERRED_EXECUTORS 16 +``` -不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。 |