From c534a4c775098f2b6cc8e7f36d35cf642f4323a5 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Mon, 18 Mar 2019 14:22:02 -0700 Subject: [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 * Update docs/feature_macros.md Co-Authored-By: drashna * Update docs/flashing.md Co-Authored-By: drashna * Update docs/flashing.md Co-Authored-By: drashna * Update docs/keymap.md Co-Authored-By: drashna * Update docs/newbs_flashing.md Co-Authored-By: drashna * Update docs/newbs_flashing.md Co-Authored-By: drashna * Update docs/custom_quantum_functions.md Co-Authored-By: drashna * Update docs/faq_build.md Co-Authored-By: drashna * Update docs/feature_macros.md Co-Authored-By: drashna * Update docs/keymap.md Co-Authored-By: drashna * Fix up Common functions doc * Make pre-init example accurate * Update docs/custom_quantum_functions.md Co-Authored-By: drashna * Zadig Driver catchall * Spelling Depriciated * Completely remove fn_actions section --- docs/feature_macros.md | 97 +++++++++++++++++++++++++++----------------------- 1 file changed, 53 insertions(+), 44 deletions(-) (limited to 'docs/feature_macros.md') diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 79419abd2..743fc3ad5 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -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();` + +This sends the `` 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();` + +Parallel to `register_code` function, this sends the `` keyup event to the computer. If you don't use this, the key will be held down until it's sent. + +### `tap_code();` + +This will send `register_code()` and then `unregister_code()`. 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();`, `unregister_code16();` and `tap_code16();` + +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();` - -This sends the `` 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();` - -Parallel to `register_code` function, this sends the `` keyup event to the computer. If you don't use this, the key will be held down until it's sent. - -### `tap_code();` - -This will send `register_code()` and then `unregister_code()`. 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. -- cgit v1.2.3-24-g4f1b