aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRyan <fauxpark@gmail.com>2021-08-15 00:18:20 +1000
committerGitHub <noreply@github.com>2021-08-15 00:18:20 +1000
commitfce12f007560834fc761b2f1ee53b32f0353e24e (patch)
treeec58a14f71ffff9323d98318cd8e7617e7be67a6
parentde29364827063c5ee79d2e9d0eec33af63286408 (diff)
downloadqmk_firmware-fce12f007560834fc761b2f1ee53b32f0353e24e.tar.gz
qmk_firmware-fce12f007560834fc761b2f1ee53b32f0353e24e.zip
Rework keymap_extras docs (#13949)
Diffstat
-rw-r--r--docs/reference_keymap_extras.md155
1 files changed, 80 insertions, 75 deletions
diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md
index 40a195684..ae3d54e4d 100644
--- a/docs/reference_keymap_extras.md
+++ b/docs/reference_keymap_extras.md
@@ -1,86 +1,91 @@
1# Language-specific Keycodes 1# Language-specific Keycodes
2 2
3Keyboards are able to support a wide range of languages. However, they do not send the actual characters produced by pressing their keys - instead, they send numerical codes. In the USB HID spec, these are called "usages", although they are more often referred to as "scancodes" or "keycodes" when in the context of keyboards. 3Keyboards are able to support a wide range of languages. However, this support is not actually achieved within the keyboard itself - instead, it sends numerical codes, which the operating system maps to the appropriate characters depending on the user's configured keyboard layout. By default (and per the HID spec), this is the US ANSI layout. For example, when a Swedish person presses the key with the `å` character printed on it, the keyboard is *actually* sending the keycode for `[`.
4Less than 256 usages are defined in the HID Keyboard/Keypad usage page, and some of those do nothing on modern operating systems. So, how is this language support achieved?
5 4
6In a nutshell, the operating system maps the usages it receives to the appropriate character based on the user's configured keyboard layout. For example, when a Swedish person presses the key with the `å` character printed on it, the keyboard is *actually* sending the keycode for `[`. 5Obviously, this can get confusing, so QMK provides language-specific keycode aliases for many keyboard layouts. These won't do much on their own - you still have to set the matching keyboard layout in your OS settings. Think of them more as keycap labels for your keymap.
7 6
8Obviously, this could get confusing, so QMK provides language-specific keycode aliases for many keyboard layouts. These won't do much on their own - you still have to set the matching keyboard layout in your OS settings. Think of them more as keycap labels for your keymap. 7Simply `#include` one of the keycode headers below at the top of your `keymap.c`, and assign the keycodes defined in the header in place of the `KC_` prefixed ones.
9 8
10To use these, simply `#include` the corresponding [header file](https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras) in your `keymap.c`, and add the keycodes defined in them in place of the `KC_` prefixed ones: 9## Sendstring Support
11 10
12|Layout |Header | 11By default, `SEND_STRING()` assumes a US ANSI keyboard layout is set. If you are using a different layout, you can include one of the Sendstring LUT headers below in your `keymap.c` to override the lookup tables used for mapping ASCII characters to keycodes. You do not need to include the corresponding `keymap_*.h` header, as it is implicit when including the Sendstring header.
13|---------------------------|--------------------------------|
14|Canadian Multilingual (CSA)|`keymap_canadian_multilingual.h`|
15|Croatian |`keymap_croatian.h` |
16|Czech |`keymap_czech.h` |
17|Danish |`keymap_danish.h` |
18|Dutch (Belgium) |`keymap_belgian.h` |
19|English (Ireland) |`keymap_irish.h` |
20|English (UK) |`keymap_uk.h` |
21|English (US Extended) |`keymap_us_extended.h` |
22|English (US International) |`keymap_us_international.h` |
23|English (US International, Linux)|`keymap_us_international_linux.h`|
24|Estonian |`keymap_estonian.h` |
25|Finnish |`keymap_finnish.h` |
26|French |`keymap_french.h` |
27|French (AFNOR) |`keymap_french_afnor.h` |
28|French (BÉPO) |`keymap_bepo.h` |
29|French (Belgium) |`keymap_belgian.h` |
30|French (Switzerland) |`keymap_fr_ch.h` |
31|French (macOS, ISO) |`keymap_french_osx.h` |
32|German |`keymap_german.h` |
33|German (Switzerland) |`keymap_german_ch.h` |
34|German (macOS) |`keymap_german_osx.h` |
35|German (Neo2)* |`keymap_neo2.h` |
36|Greek* |`keymap_greek.h` |
37|Hebrew* |`keymap_hebrew.h` |
38|Hungarian |`keymap_hungarian.h` |
39|Icelandic |`keymap_icelandic.h` |
40|Italian |`keymap_italian.h` |
41|Italian (macOS, ANSI) |`keymap_italian_osx_ansi.h` |
42|Italian (macOS, ISO) |`keymap_italian_osx_iso.h` |
43|Japanese |`keymap_jp.h` |
44|Korean |`keymap_korean.h` |
45|Latvian |`keymap_latvian.h` |
46|Lithuanian (ĄŽERTY) |`keymap_lithuanian_azerty.h` |
47|Lithuanian (QWERTY) |`keymap_lithuanian_qwerty.h` |
48|Norwegian |`keymap_norwegian.h` |
49|Polish |`keymap_polish.h` |
50|Portuguese |`keymap_portuguese.h` |
51|Portuguese (macOS, ISO) |`keymap_portuguese_osx_iso.h` |
52|Portuguese (Brazil) |`keymap_br_abnt2.h` |
53|Romanian |`keymap_romanian.h` |
54|Russian* |`keymap_russian.h` |
55|Serbian* |`keymap_serbian.h` |
56|Serbian (Latin) |`keymap_serbian_latin.h` |
57|Slovak |`keymap_slovak.h` |
58|Slovenian |`keymap_slovenian.h` |
59|Spanish |`keymap_spanish.h` |
60|Spanish (Dvorak) |`keymap_spanish_dvorak.h` |
61|Swedish |`keymap_swedish.h` |
62|Turkish (F) |`keymap_turkish_f.h` |
63|Turkish (Q) |`keymap_turkish_q.h` |
64 12
65There are also a few which are not quite language-specific, but useful if you are not using a QWERTY layout: 13An important thing to note here is that `SEND_STRING()` only operates on [ASCII text](https://en.wikipedia.org/wiki/ASCII#Character_set). This means that you cannot pass it a string containing Unicode characters - this unfortunately includes accented characters that may be present in your desired layout.
14Many layouts make certain characters, such as Grave or Tilde, available only as [dead keys](https://en.wikipedia.org/wiki/Dead_key), so you must add a space immediately after it in the string you want to send, to prevent it from potentially combining with the next character.
15Certain other layouts have no Sendstring header as they do not use a Latin-derived alphabet (for example Greek and Russian), and thus there is no way to input most of the ASCII character set.
66 16
67|Layout |Header | 17## Header Files
68|-------------------|------------------------|
69|Colemak |`keymap_colemak.h` |
70|Dvorak |`keymap_dvorak.h` |
71|Dvorak (French) |`keymap_dvorak_fr.h` |
72|Dvorak (Programmer)|`keymap_dvp.h` |
73|Norman |`keymap_norman.h` |
74|Plover* |`keymap_plover.h` |
75|Plover (Dvorak)* |`keymap_plover_dvorak.h`|
76|Steno* |`keymap_steno.h` |
77|Workman |`keymap_workman.h` |
78|Workman (ZXCVM) |`keymap_workman_zxcvm.h`|
79 18
80## Sendstring Support 19These headers are located in [`quantum/keymap_extras/`](https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras).
81 20
82By default, `SEND_STRING()` assumes a US ANSI keyboard layout is set. If you are using a different layout, you can also `#include "sendstring_*.h"` (as above) in your keymap to override the lookup tables used for mapping ASCII characters to keycodes. 21|Layout |Keycodes Header |Sendstring LUT Header |
22|---------------------------------|---------------------------------|------------------------------------|
23|Canadian Multilingual (CSA) |`keymap_canadian_multilingual.h` |`sendstring_canadian_multilingual.h`|
24|Croatian |`keymap_croatian.h` |`sendstring_croatian.h` |
25|Czech |`keymap_czech.h` |`sendstring_czech.h` |
26|Danish |`keymap_danish.h` |`sendstring_danish.h` |
27|Dutch (Belgium) |`keymap_belgian.h` |`sendstring_belgian.h` |
28|English (Ireland) |`keymap_irish.h` | |
29|English (UK) |`keymap_uk.h` |`sendstring_uk.h` |
30|English (US Extended) |`keymap_us_extended.h` | |
31|English (US International) |`keymap_us_international.h` |`sendstring_us_international.h` |
32|English (US International, Linux)|`keymap_us_international_linux.h`| |
33|Estonian |`keymap_estonian.h` |`sendstring_estonian.h` |
34|Finnish |`keymap_finnish.h` |`sendstring_finnish.h` |
35|French |`keymap_french.h` |`sendstring_french.h` |
36|French (AFNOR) |`keymap_french_afnor.h` |`sendstring_french_afnor.h` |
37|French (BÉPO) |`keymap_bepo.h` |`sendstring_bepo.h` |
38|French (Belgium) |`keymap_belgian.h` |`sendstring_belgian.h` |
39|French (Switzerland) |`keymap_fr_ch.h` |`sendstring_fr_ch.h` |
40|French (macOS, ISO) |`keymap_french_osx.h` |`sendstring_french_osx.h` |
41|German |`keymap_german.h` |`sendstring_german.h` |
42|German (Switzerland) |`keymap_german_ch.h` |`sendstring_german_ch.h` |
43|German (macOS) |`keymap_german_osx.h` |`sendstring_german_osx.h` |
44|German (Neo2) |`keymap_neo2.h` | |
45|Greek |`keymap_greek.h` | |
46|Hebrew |`keymap_hebrew.h` | |
47|Hungarian |`keymap_hungarian.h` |`sendstring_hungarian.h` |
48|Icelandic |`keymap_icelandic.h` |`sendstring_icelandic.h` |
49|Italian |`keymap_italian.h` |`sendstring_italian.h` |
50|Italian (macOS, ANSI) |`keymap_italian_osx_ansi.h` |`sendstring_italian_osx_ansi.h` |
51|Italian (macOS, ISO) |`keymap_italian_osx_iso.h` |`sendstring_italian_osx_iso.h` |
52|Japanese |`keymap_jp.h` |`sendstring_jis.h` |
53|Korean |`keymap_korean.h` | |
54|Latvian |`keymap_latvian.h` |`sendstring_latvian.h` |
55|Lithuanian (ĄŽERTY) |`keymap_lithuanian_azerty.h` |`sendstring_lithuanian_azerty.h` |
56|Lithuanian (QWERTY) |`keymap_lithuanian_qwerty.h` |`sendstring_lithuanian_qwerty.h` |
57|Norwegian |`keymap_norwegian.h` |`sendstring_norwegian.h` |
58|Polish |`keymap_polish.h` | |
59|Portuguese |`keymap_portuguese.h` |`sendstring_portuguese.h` |
60|Portuguese (macOS, ISO) |`keymap_portuguese_osx_iso.h` |`sendstring_portuguese_osx_iso.h` |
61|Portuguese (Brazil) |`keymap_br_abnt2.h` |`sendstring_br_abnt2.h` |
62|Romanian |`keymap_romanian.h` |`sendstring_romanian.h` |
63|Russian |`keymap_russian.h` | |
64|Serbian |`keymap_serbian.h` | |
65|Serbian (Latin) |`keymap_serbian_latin.h` |`sendstring_serbian_latin.h` |
66|Slovak |`keymap_slovak.h` |`sendstring_slovak.h` |
67|Slovenian |`keymap_slovenian.h` |`sendstring_slovenian.h` |
68|Spanish |`keymap_spanish.h` |`sendstring_spanish.h` |
69|Spanish (Dvorak) |`keymap_spanish_dvorak.h` |`sendstring_spanish_dvorak.h` |
70|Swedish |`keymap_swedish.h` |`sendstring_swedish.h` |
71|Swedish (macOS, ANSI) |`keymap_swedish_osx_ansi.h` | |
72|Swedish (macOS, ISO) |`keymap_swedish_osx_iso.h` | |
73|Swedish Pro (macOS, ANSI) |`keymap_swedish_pro_osx_ansi.h` | |
74|Swedish Pro (macOS, ISO) |`keymap_swedish_pro_osx_iso.h` | |
75|Turkish (F) |`keymap_turkish_f.h` |`sendstring_turkish_f.h` |
76|Turkish (Q) |`keymap_turkish_q.h` |`sendstring_turkish_q.h` |
83 77
84An important thing to note here is that `SEND_STRING()` only operates on [ASCII text](https://en.wikipedia.org/wiki/ASCII#Character_set). This means that you cannot pass it a string containing Unicode characters - this unfortunately includes accented characters that may be present in your desired layout. 78There are also a few which are not quite language-specific, but useful if you are not using a QWERTY layout:
85Many layouts make certain characters, such as Grave or Tilde, available only as [dead keys](https://en.wikipedia.org/wiki/Dead_key), so you must add a space immediately after it in the string you want to send, to prevent it from potentially combining with the next character. 79
86Certain other layouts have no Sendstring header as they do not use a Latin-derived alphabet (for example Greek and Russian), and thus there is no way to input most of the ASCII character set. These are marked above with a `*`. 80|Layout |Keycodes Header |Sendstring LUT Header |
81|-------------------|------------------------|----------------------------|
82|Colemak |`keymap_colemak.h` |`sendstring_colemak.h` |
83|Dvorak |`keymap_dvorak.h` |`sendstring_dvorak.h` |
84|Dvorak (French) |`keymap_dvorak_fr.h` |`sendstring_dvorak_fr.h` |
85|Dvorak (Programmer)|`keymap_dvp.h` |`sendstring_dvp.h` |
86|Norman |`keymap_norman.h` |`sendstring_norman.h` |
87|Plover |`keymap_plover.h` | |
88|Plover (Dvorak) |`keymap_plover_dvorak.h`| |
89|Steno |`keymap_steno.h` | |
90|Workman |`keymap_workman.h` |`sendstring_workman.h` |
91|Workman (ZXCVM) |`keymap_workman_zxcvm.h`|`sendstring_workman_zxcvm.h`|
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-04 09:18:05 +0000