[Docs] Smallish overhaul of the docs (#5281)

* Fix up Common functions doc

* Add to extra commands to flashing doc

* Rearrange and touch up Macros

* Expand Newbs Flashing guide

* Update process_record documentation

* Add git to best practices name in sidebar

* Expand FAQ for build/flashing

* Add deprecated info to functions

* Update docs/feature_macros.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/feature_macros.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/flashing.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/flashing.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/keymap.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/newbs_flashing.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/newbs_flashing.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/custom_quantum_functions.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/faq_build.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/feature_macros.md

Co-Authored-By: drashna <drashna@live.com>

* Update docs/keymap.md

Co-Authored-By: drashna <drashna@live.com>

* Fix up Common functions doc

* Make pre-init example accurate

* Update docs/custom_quantum_functions.md

Co-Authored-By: drashna <drashna@live.com>

* Zadig Driver catchall

* Spelling Depriciated

* Completely remove fn_actions section
This commit is contained in:
Drashna Jaelre 2019-03-18 14:22:02 -07:00 committed by MechMerlin
parent 28e182bc8a
commit c534a4c775
8 changed files with 172 additions and 126 deletions

View file

@ -146,9 +146,59 @@ send_string(my_str);
SEND_STRING(".."SS_TAP(X_END));
```
## The Old Way: `MACRO()` & `action_get_macro`
?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
## Advanced Macro Functions
There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
### `record->event.pressed`
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `register_code(<kc>);`
This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
### `unregister_code(<kc>);`
Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
### `tap_code(<kc>);`
This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
### `clear_keyboard();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
@ -222,49 +272,8 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
};
```
## Advanced Macro Functions
There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
### `record->event.pressed`
This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
```c
if (record->event.pressed) {
// on keydown
} else {
// on keyup
}
```
### `register_code(<kc>);`
This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
### `unregister_code(<kc>);`
Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
### `tap_code(<kc>);`
This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
### `clear_keyboard();`
This will clear all mods and keys currently pressed.
### `clear_mods();`
This will clear all mods currently pressed.
### `clear_keyboard_but_mods();`
This will clear all keys besides the mods currently pressed.
## Advanced Example: Single-Key Copy/Paste
### Advanced Example: Single-Key Copy/Paste
This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.