Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Improve Unicode documentation #8676

Merged
merged 10 commits into from
Jun 20, 2020
94 changes: 50 additions & 44 deletions docs/feature_macros.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,38 +2,41 @@

Macros allow you to send multiple keystrokes when pressing just one key. 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.

!> **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.
!> **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.
vomindoraan marked this conversation as resolved.
Show resolved Hide resolved


## The New Way: `SEND_STRING()` & `process_record_user`

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 (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`).
Sometimes you 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 (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`).

?> For sending Unicode strings, check out the [Unicode feature](feature_unicode.md) and, specifically, [`send_unicode_string()`](feature_unicode.md#send_unicode_string).

Here is an example `keymap.c` for a two-key keyboard:

```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKBEST = SAFE_RANGE,
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;

}
return true;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{QMKBEST, KC_ESC}
}
[0] = {
{QMKBEST, KC_ESC},
// ...
},
};
```

Expand All @@ -49,42 +52,45 @@ You can do that by adding another keycode and adding another case to the switch

```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO,
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;

case QMKURL:
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;

case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO},
// ...
},
};
```

Expand Down
Loading