aboutsummaryrefslogtreecommitdiff
path: root/docs/feature_macros.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/feature_macros.md')
-rw-r--r--docs/feature_macros.md113
1 files changed, 6 insertions, 107 deletions
diff --git a/docs/feature_macros.md b/docs/feature_macros.md
index 36fa761d2..aa1ebc337 100644
--- a/docs/feature_macros.md
+++ b/docs/feature_macros.md
@@ -4,7 +4,7 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has
4 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 a hold of your keyboard will be able to access that information by opening a text editor. 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 a hold of your keyboard will be able to access that information by opening a text editor.
6 6
7## The New Way: `SEND_STRING()` & `process_record_user` 7## `SEND_STRING()` & `process_record_user`
8 8
9Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). 9Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`).
10 10
@@ -262,15 +262,15 @@ This will clear all keys besides the mods currently pressed.
262This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. 262This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows.
263 263
264```c 264```c
265bool is_alt_tab_active = false; # ADD this near the begining of keymap.c 265bool is_alt_tab_active = false; // ADD this near the begining of keymap.c
266uint16_t alt_tab_timer = 0; # we will be using them soon. 266uint16_t alt_tab_timer = 0; // we will be using them soon.
267 267
268enum custom_keycodes { # Make sure have the awesome keycode ready 268enum custom_keycodes { // Make sure have the awesome keycode ready
269 ALT_TAB = SAFE_RANGE, 269 ALT_TAB = SAFE_RANGE,
270}; 270};
271 271
272bool process_record_user(uint16_t keycode, keyrecord_t *record) { 272bool process_record_user(uint16_t keycode, keyrecord_t *record) {
273 switch (keycode) { # This will do most of the grunt work with the keycodes. 273 switch (keycode) { // This will do most of the grunt work with the keycodes.
274 case ALT_TAB: 274 case ALT_TAB:
275 if (record->event.pressed) { 275 if (record->event.pressed) {
276 if (!is_alt_tab_active) { 276 if (!is_alt_tab_active) {
@@ -287,7 +287,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
287 return true; 287 return true;
288} 288}
289 289
290void matrix_scan_user(void) { # The very important timer. 290void matrix_scan_user(void) { // The very important timer.
291 if (is_alt_tab_active) { 291 if (is_alt_tab_active) {
292 if (timer_elapsed(alt_tab_timer) > 1000) { 292 if (timer_elapsed(alt_tab_timer) > 1000) {
293 unregister_code(KC_LALT); 293 unregister_code(KC_LALT);
@@ -296,104 +296,3 @@ void matrix_scan_user(void) { # The very important timer.
296 } 296 }
297} 297}
298``` 298```
299
300---
301
302## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
303
304!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
305
306By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
307
308```c
309const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
310 if (record->event.pressed) {
311 switch(id) {
312 case 0:
313 return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
314 case 1:
315 return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
316 }
317 }
318 return MACRO_NONE;
319};
320```
321
322This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
323
324 if (!record->event.pressed) {
325
326### Macro Commands
327
328A macro can include the following commands:
329
330* I() change interval of stroke in milliseconds.
331* D() press key.
332* U() release key.
333* T() type key(press and release).
334* W() wait (milliseconds).
335* END end mark.
336
337### Mapping a Macro to a Key
338
339Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard:
340
341```c
342const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
343 [0] = LAYOUT(
344 M(0), M(1)
345 ),
346};
347
348const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
349 if (record->event.pressed) {
350 switch(id) {
351 case 0:
352 return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
353 case 1:
354 return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
355 }
356 }
357 return MACRO_NONE;
358};
359```
360
361When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!".
362
363### Naming Your Macros
364
365If 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.
366
367```c
368#define M_HI M(0)
369#define M_BYE M(1)
370
371const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
372 [0] = LAYOUT(
373 M_HI, M_BYE
374 ),
375};
376```
377
378
379## Advanced Example:
380
381### Single-Key Copy/Paste
382
383This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
384
385```c
386const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
387 switch(id) {
388 case 0: {
389 if (record->event.pressed) {
390 return MACRO( D(LCTL), T(C), U(LCTL), END );
391 } else {
392 return MACRO( D(LCTL), T(V), U(LCTL), END );
393 }
394 break;
395 }
396 }
397 return MACRO_NONE;
398};
399```