From e0a0d80bd329b4a289e3c4f817c96857c25b0f16 Mon Sep 17 00:00:00 2001 From: ymzcdg <49898694+ymzcdg@users.noreply.github.com> Date: Wed, 5 Jun 2019 02:06:17 +0800 Subject: docs to Mandarin Chinese (#5960) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * faq_general.md to Chinese faq_general.md to Chinese faq finished * custom_quantum_functions.md to Chinese custom_quantum_functions.md to Chinese * custom_quantum_functions.md fix custom_quantum_functions.md fix * custom_quantum_functions.md fix translate custom_quantum_functions.md fix translate * !ver.English! _summary.md bug fix _summary.md bug fix of English doc. add".md" behind "feature_combo" * !ver.English! custom_quantum_functions.md fix#5869 custom_quantum_functions.md in English : delete redundant "is" . issue#5869 * !ver.English! how_keyboards_work.md link fix change https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input to https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input "#Hexadecimal_code_input" not exist * !English! how_keyboards_work.md add missing "t" Tied to a specific OS a a time (need recompilation when changing OS); change to Tied to a specific OS at a time (need recompilation when changing OS); * _summary.md improve translation _summary.md improve translation * reference_glossary.md into Chinese reference_glossary.md into Chinese 术语表翻译，这个术语表英文版似乎不太全，应该补充英文版，并在中文版添加其他具有中国特色的术语。 --- docs/zh-cn/custom_quantum_functions.md | 490 +++++++++++++++++++++++++++++++++ 1 file changed, 490 insertions(+) create mode 100644 docs/zh-cn/custom_quantum_functions.md (limited to 'docs/zh-cn/custom_quantum_functions.md') diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md new file mode 100644 index 0000000000..42ceba9cac --- /dev/null +++ b/docs/zh-cn/custom_quantum_functions.md @@ -0,0 +1,490 @@ +# ζ̵Ĺ + +ںܶ˵ƻ̿ɲֻĵԷ㰴Ǹô򵥡϶ʵֱȼ򵥰ͺӵĹܡQMKעĹ, ǹ, ⣬ԶڲͬµΪ + +ҳٶκQMK֪ʶĶ[QMK](understanding_qmk.md)ڸIJⷢʲô + +## A Word on Core vs vs + +ǰqmk֯һνṹ + +* Core (`_quantum`) + * Keyboard/Revision (`_kb`) + * Keymap (`_user`) + +ÿһڶϼһ`_kb()` `_user()` ׺ ڼ/޶ʹ`_kb()`׺ڲֲʹ`_user()`׺ + +ڼ/޶㶨庯ʱ`_kb()`ִκδǰȵ`_user()`DZҪģȻֲ㺯ͲҪá + +# Զ + +ĿǰΪֹǸмΪ򴴽µļ롣ӴǶЩơ + +## һ¼ + +һöٳȫҲǸֲΨһֵQMKûֱֵСṩһ`SAFE_RANGE`ꡣöʱ`SAFE_RANGE`֤ȡΨһļֵ + + +öӡӵ`keymap.c`Ļڲ`FOO``BAR`ˡ + +```c +enum my_keycodes { + FOO = SAFE_RANGE, + BAR +}; +``` + +## ΪΪ + +㸲һѴڰΪʱΪ¼ʱҪ`process_record_kb()``process_record_user()`ڼʵ¼ǰQMKá`true`QMKķʽ롣ԺܷչĹܶ滻`false` QMKȻͼ̧ǰ¼ˡ + +ij»ͷʱᱻá + +### process_record_user()`ʾʵ + +¡Զһ`FOO`ļΪڰ»سʱ + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // ʱЩʲô + } else { + // ͷʱЩʲô + } + return false; // ˼нһ + case KC_ENTER: + // »سʱ + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // QMKس/ͷ¼ + default: + return true; // + } +} +``` + +### `process_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` Щ¼ + +`record`ʵʰϢ + +```c +keyrecord_t record { + keyevent_t event { + keypos_t key { + uint8_t col + uint8_t row + } + bool pressed + uint16_t time + } +} +``` + +# LED + +qmkṩ˶ȡHID淶5LEDķ: + +* `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()` + +5LEDκһ״̬Ҫıʱ˺á˺ͨ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_post_init_user`Ҫõĺ, ʱRGBƷ⡣ + +## Ԥʼ + +뼫УUSBʼǰС + +֮󲻾þͱʼˡ + +ڴû˵,òΪҪӲijʼ + +ӲʼĻٺò(ʼLEDһ). + +### `keyboard_pre_init_user()`ʾʵ + +ڼ̼趨 B0, B1, B2, B3, B4 LEDš + +```c +void keyboard_pre_init_user(void) { + // üԤʼ + + // LEDΪģʽ + setPinOutput(B0); + setPinOutput(B1); + setPinOutput(B2); + setPinOutput(B3); + setPinOutput(B4); +} +``` + +### `keyboard_pre_init_*` ĵ + +* /޶: `void keyboard_pre_init_kb(void)` +* : `void keyboard_pre_init_user(void)` + +## ʼ + +⽫ھʼʱãijЩӲúú󣬵һЩܱʼǰ + +طõĶʱãӲ޹أҲλá + + +### `matrix_init_*`ĵ + +* /޶: `void matrix_init_kb(void)` +* : `void matrix_init_user(void)` + + +## ̺ʼ + +Ǽ̳ʼеһijЩԣãΪʱӦöǽгʼ + + +### `keyboard_post_init_user()`ʾʵ + +ʾгʼɺУ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); // ÿٺģʽ +} +``` + +### `keyboard_post_init_*` ĵ + +* /޶: `void keyboard_post_init_kb(void)` +* : `void keyboard_post_init_user(void)` + +# ɨ + +ܵĻҪ`process_record_*()`Զַ̣ʽӵ¼Уȷ벻Լ̲Ӱ졣Ȼڼ£бҪоɨ衣ЩҪرעܣΪÿٱ10Ρ + +### `matrix_scan_*`ʾʵ + +ӱʡˡhookһܼе֮ǰӦ㹻˽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_user(void)` + +úÿξɨʱãMCUͬдҪΪкܶΡ + +ԶɨʱõҲԶ״̬(LEDƻĻ)ûҲ붨еĹܡ + + +# / + +֧־ͿֹͨͣһƱﵽ""RGBƺͱǺܺõӡԽԼܺģҲ̷ζѡ + +: `suspend_power_down_*``suspend_wakeup_init_*`, ֱϵͳкͻʱá + + +### suspend_power_down_user()suspend_wakeup_init_user()ʾʵ + + +```c +void suspend_power_down_user(void) { + rgb_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) { + rgb_matrix_set_suspend_state(false); +} +``` + +### / ĵ + +* /޶: `void suspend_power_down_kb(void)` `void suspend_wakeup_init_user(void)` +* : `void suspend_power_down_kb(void)` `void suspend_wakeup_init_user(void)` + +# ı + +ÿıд롣ڲָʾԶ㴦á + +### `layer_state_set_*` ʾʵ + +ʹPlanckʾ [RGB](feature_rgblight.md)ʹ֮Ӧ + +```c +uint32_t layer_state_set_user(uint32_t state) { + switch (biton32(state)) { + case _RAISE: + rgblight_setrgb (0x00, 0x00, 0xFF); + break; + case _LOWER: + rgblight_setrgb (0xFF, 0x00, 0x00); + break; + case _PLOVER: + rgblight_setrgb (0x00, 0xFF, 0x00); + break; + case _ADJUST: + rgblight_setrgb (0x7A, 0x00, 0xFF); + break; + default: // for any other layers, or the default layer + rgblight_setrgb (0x00, 0xFF, 0xFF); + break; + } + return state; +} +``` +### `layer_state_set_*` ĵ + +* /޶: `uint32_t layer_state_set_kb(uint32_t state)` +* : `uint32_t layer_state_set_user(uint32_t state)` + + +`״̬`ǻbitmask, [ָ](keymap.md#ֵIJ״̬) + + +# 籣 (EEPROM) + +óڵıڼСЩñصEEPROM粻ʧ ÿ`eeconfig_read_kb``eeconfig_read_user`ȡ`eeconfig_update_kb``eeconfig_update_user`д롣ϣܹлĹܺ(лRGBָʾ⣬`eeconfig_init_kb``eeconfig_init_user`EEPROMĬֵ + +ӵIJֿǣкܶ෽ͨEEPROM洢ͷݣҲûַǡȷġÿֻһ˫(ֽ)ռ䡣 + +סEEPROMдġдܸߣDzֻдEEPROMСдƵMCU̡ + +* ӣôϣʹԣΪ൱ӡ + +### ʾʵ + +ãҶдʹû֡һӵĺкܶҪʵϣʹ˺ܶ + + +keymap.cļУ´: +```c +typedef union { + uint32_t raw; + struct { + bool rgb_layer_change :1; + }; +} user_config_t; + +user_config_t user_config; +``` + +ϴ뽨һṹ壬ýṹԴ洢òдEEPROM㽫趨ΪڽṹȻ塣Ҫס`bool` ()ֵʹ1λ, `uint8_t`ʹ8λ, `uint16_t`ʹ16λԻϴʹã˳Ǵܻ鷳Ϊǻıддֵ + + `layer_state_set_*`ʹ`rgb_layer_change`ʹ`keyboard_post_init_user``process_record_user`һС + +Ҫʹ`keyboard_post_init_userҪ`eeconfig_read_user()`ոմĽṹ塣ȻʹṹIJеĹܡ +```c +void keyboard_post_init_user(void) { + // òּľʼ + + // EEPROMû + user_config.raw = eeconfig_read_user(); + + // ʹܣĬϲ + if (user_config.rgb_layer_change) { + rgblight_enable_noeeprom(); + rgblight_sethsv_noeeprom_cyan(); + rgblight_mode_noeeprom(1); + } +} +``` +ϺڶEEPROMúʹøĬϲRGBɫ"raw"ֵǴ"union"Ľṹתġ + +```c +uint32_t layer_state_set_user(uint32_t state) { + switch (biton32(state)) { + case _RAISE: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } + break; + case _LOWER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } + break; + case _PLOVER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } + break; + case _ADJUST: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } + break; + default: // Ĭϲ + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } + break; + } + return state; +} +``` +ֵʹʱıRGBơֵ, Ϊ`process_record_user`һ¼`RGB_LYR`ҪȷʹRGB룬ʹʾرգ뽫Ϊ +```c + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // ʱʲô + } else { + // ͷʱʲô + } + return false; // ˼Ľһ + case KC_ENTER: + // ڰ»سʱ + if (record->event.pressed) { + PLAY_NOTE_ARRAY(tone_qwerty); + } + return true; // QMKس/ͷ¼ + case RGB_LYR: // underglowΪָʾʹá + if (record->event.pressed) { + user_config.rgb_layer_change ^= 1; // л״̬ + eeconfig_update_user(user_config.raw); // EEPROMд״̬ + if (user_config.rgb_layer_change) { // ״̬ʹ + layer_state_set(layer_state); // ô̸²ɫ + } + } + return false; break; + case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // еRGB (see quantum_keycodes.h, L400 Բο) + if (record->event.pressed) { //ʧָܲʾıҪ + if (user_config.rgb_layer_change) { // ʹʱ + user_config.rgb_layer_change = false; // ʧܣȻ + eeconfig_update_user(user_config.raw); // EEPROMд + } + } + return true; break; + default: + return true; // + } +} +``` +Ҫ`eeconfig_init_user`ԵEEPROMʱָĬֵ, ԶǿEEPROM`EEP_RST`[Bootmagic](feature_bootmagic.md)磬ҪĬRGBָʾĬֵ + +```c +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дЩֵ + rgblight_enable(); // ĬʹRGB + rgblight_sethsv_cyan(); // Ĭɫ + rgblight_mode(1); // Ĭó +} +``` + +Ȼˡ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)` + +`val` дEEPROMֵ`eeconfig_read_*`EEPROMһ32λ(˫)ֵ + +# Զ-ٽֵ(TAPPING_TERM) +Ĭ,-ٽֵȫͳһģҲͨáڴû˵ܺáЩ£`LT`˵ʱ˫ܼ󣬿ΪЩļװסΪ˲ÿԶ룬ܿΪÿ`TAPPING_TERM` + +ʹܵĻ, Ҫ`config.h``#define TAPPING_TERM_PER_KEY` + + +## `get_tapping_term`ʾʵ + +Ҫ޸Ļڼ`TAPPING TERM`,Ҫ`keymap.c`ļ´: + +```c +uint16_t get_tapping_term(uint16_t keycode) { + switch (keycode) { + case SFT_T(KC_SPC): + return TAPPING_TERM + 1250; + case LT(1, KC_GRV): + return 130; + default: + return TAPPING_TERM; + } +} +``` + +### `get_tapping_term` ĵ + +ƪ,Ҫquantum߼̼ĺֻҪûɡ -- cgit v1.2.3