]> git.donarmstrong.com Git - qmk_firmware.git/blob - docs/Macros.md
Clean up and improve the macro documentation
[qmk_firmware.git] / docs / Macros.md
1 # Macros - Send multiple keystrokes when pressing just one key
2
3 QMK has a number of ways to define and use macros. These can do anything you want- type common phrases for you, copypasta, repetitive game movements, or even help you code. 
4
5 **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets ahold of your keyboard will be able to access that information by opening a text editor.
6
7 # Macro Definitions
8
9 By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
10
11 ```c
12 const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
13     if (record->event.pressed) {
14         switch(id) {
15             case 0:
16                 return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
17             case 1:
18                 return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
19         }
20     }
21     return MACRO_NONE;
22 };
23 ```
24
25 This defines two macros which will be run when the key they are assigned to is pressed. If you'd like them to run when the release is released instead you can change the if statement:
26
27 ```c
28     if (!record->event.pressed) {
29 ```
30
31 ## Macro Commands
32
33 A macro can include the following commands:
34
35 * I() change interval of stroke in milliseconds.
36 * D() press key.
37 * U() release key.
38 * T() type key(press and release).
39 * W() wait (milliseconds).
40 * END end mark.
41
42 ## Sending strings
43
44 Sometimes you just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string for you instead of having to build a `MACRO()`. Right now it assumes a US keymap with a QWERTY layout, so if you are using something else it may not behave as you expect.
45
46 For example:
47
48 ```c
49 const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
50     if (record->event.pressed) {
51         switch(id) {
52             case 0:
53                 SEND_STRING("QMK is the best thing ever!");
54                 return false;
55         }
56     }
57     return MACRO_NONE;
58 };
59 ```
60
61 ## Mapping a Macro to a key
62
63 Use the `M()` function within your `KEYMAP()` to call a macro. For example, here is the keymap for a 2-key keyboard:
64
65 ```c
66 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
67     [0] = KEYMAP(
68         M(0), M(1)
69     ),
70 };
71
72 const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
73     if (record->event.pressed) {
74         switch(id) {
75             case 0:
76                 return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
77             case 1:
78                 return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
79         }
80     }
81     return MACRO_NONE;
82 };
83 ```
84
85 When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!".
86
87 ## Naming your macros
88
89 If you have a bunch of macros you want to refer to from your keymap, while keeping the keymap easily readable, you can name them using `#define` at the top of your file.
90
91 ```c
92 #define M_HI M(0)
93 #define M_BYE M(1)
94
95 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
96     [0] = KEYMAP(
97         M_HI, M_BYE
98     ),
99 };
100 ```
101
102 ## Advanced macro functions
103
104 To get more control over the keys/actions your keyboard takes, the following functions are available to you in the `action_get_macro()` function block:
105
106 ### `record->event.pressed`
107
108 This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
109
110 ```c
111     if (record->event.pressed) {
112         // on keydown
113     } else {
114         // on keyup
115     }
116 ```
117
118 ### `register_code(<kc>);`
119
120 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`.
121
122 ### `unregister_code(<kc>);`
123
124 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.
125
126 ### `layer_on(<n>);`
127
128 This will turn on the layer `<n>` - the higher layer number will always take priority. Make sure you have `KC_TRNS` for the key you're pressing on the layer you're switching to, or you'll get stick there unless you have another plan.
129
130 ### `layer_off(<n>);`
131
132 This will turn off the layer `<n>`.
133
134 ### `clear_keyboard();`
135
136 This will clear all mods and keys currently pressed.
137
138 ### `clear_mods();`
139
140 This will clear all mods currently pressed.
141
142 ### `clear_keyboard_but_mods();`
143
144 This will clear all keys besides the mods currently pressed.
145
146 ### `update_tri_layer(layer_1, layer_2, layer_3);`
147
148 If the user attempts to activate layer 1 AND layer 2 at the same time (for example, by hitting their respective layer keys), layer 3 will be activated. Layers 1 and 2 will _also_ be activated, for the purposes of fallbacks (so a given key will fall back from 3 to 2, to 1 -- and only then to 0).
149
150 # Example: Single-key copy/paste (hold to copy, tap to paste)
151
152 With QMK, it's easy to make one key do two things, as long as one of those things is being a modifier. :) So if you want a key to act as Ctrl when held and send the letter R when tapped, that's easy: `CTL_T(KC_R)`. But what do you do when you want that key to send Ctrl-V (paste) when tapped, and Ctrl-C (copy) when held?
153
154 Here's what you do:
155
156 ```c
157 const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
158     switch(id) {
159         case 0: {
160             if (record->event.pressed) {
161                 return MACRO( D(LCTL), T(C), U(LCTL), END  );
162             } else {
163                 return MACRO( D(LCTL), T(V), U(LCTL), END  );
164             }
165             break;
166         }
167     }
168     return MACRO_NONE;
169 };
170 ```
171
172 To assign this macro to a key on your keyboard layout, you just use `M(0)` on the key you want to press for copy/paste.
173
174 # Dynamic macros: record and replay macros in runtime
175
176 In addition to the static macros described above, you may enable the dynamic macros which you may record while writing. They are forgotten as soon as the keyboard is unplugged. Only two such macros may be stored at the same time, with the total length of 64 keypresses (by default).
177
178 To enable them, first add a new element to the `planck_keycodes` enum — `DYNAMIC_MACRO_RANGE`:
179
180     enum planck_keycodes {
181       QWERTY = SAFE_RANGE,
182       COLEMAK,
183       DVORAK,
184       PLOVER,
185       LOWER,
186       RAISE,
187       BACKLIT,
188       EXT_PLV,
189       DYNAMIC_MACRO_RANGE,
190     };
191
192 It must be the last element because `dynamic_macros.h` will add some more keycodes after it.
193
194 Below it include the `dynamic_macro.h` header:
195
196     #include "dynamic_macro.h"`
197
198 Add the following keys to your keymap:
199
200 - `DYN_REC_START1` — start recording the macro 1,
201 - `DYN_REC_START2` — start recording the macro 2,
202 - `DYN_MACRO_PLAY1` — replay the macro 1,
203 - `DYN_MACRO_PLAY2` — replay the macro 2,
204 - `DYN_REC_STOP` — finish the macro that is currently being recorded.
205
206 Add the following code to the very beginning of your `process_record_user()` function:
207
208 ```c
209     if (!process_record_dynamic_macro(keycode, record)) {
210         return false;
211     }
212 ```
213
214 That should be everything necessary. To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`. To finish the recording, press the `DYN_REC_STOP` layer button. To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.
215
216 Note that it's possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again.
217
218 For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, use the following snippet instead of the one above:
219
220 ```c
221     uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode);
222     
223     if (!process_record_dynamic_macro(macro_kc, record)) {
224         return false;
225     }
226 ```
227
228 If the LED's start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header).
229
230 For the details about the internals of the dynamic macros, please read the comments in the `dynamic_macro.h` header.