auri.ee
keyboard stuff
1# Send String {#send-string}
2
3The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically.
4
5The full ASCII character set is supported, along with all of the keycodes in the Basic Keycode range (as these are the only ones that will actually be sent to the host).
6
7::: tip
8Unicode characters are **not** supported with this API -- see the [Unicode](unicode) feature instead.
9:::
10
11## Usage {#usage}
12
13Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`:
14
15```make
16SEND_STRING_ENABLE = yes
17```
18
19## Basic Configuration {#basic-configuration}
20
21Add the following to your `config.h`:
22
23|Define |Default |Description |
24|-----------------|----------------|------------------------------------------------------------------------------------------------------------|
25|`SENDSTRING_BELL`|*Not defined* |If the [Audio](audio) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.|
26|`BELL_SOUND` |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5. |
27
28## Keycodes {#keycodes}
29
30The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](../keycodes_basic) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`.
31
32|Macro |Description |
33|--------------|-------------------------------------------------------------------|
34|`SS_TAP(x)` |Send a keydown, then keyup, event for the given Send String keycode|
35|`SS_DOWN(x)` |Send a keydown event for the given Send String keycode |
36|`SS_UP(x)` |Send a keyup event for the given Send String keycode |
37|`SS_DELAY(ms)`|Wait for `ms` milliseconds |
38
39The following characters are also mapped to their respective keycodes for convenience:
40
41|Character|Hex |ASCII|Keycode |
42|---------|------|-----|--------------|
43|`\b` |`\x08`|`BS` |`KC_BACKSPACE`|
44|`\e` |`\x09`|`ESC`|`KC_ESCAPE` |
45|`\n` |`\x0A`|`LF` |`KC_ENTER` |
46|`\t` |`\x1B`|`TAB`|`KC_TAB` |
47| |`\x7F`|`DEL`|`KC_DELETE` |
48
49### Language Support {#language-support}
50
51By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](../reference_keymap_extras#sendstring-support).
52
53## Examples {#examples}
54
55### Hello World {#example-hello-world}
56
57A simple custom keycode which types out "Hello, world!" and the Enter key when pressed.
58
59Add the following to your `keymap.c`:
60
61```c
62bool process_record_user(uint16_t keycode, keyrecord_t *record) {
63 switch (keycode) {
64 case SS_HELLO:
65 if (record->event.pressed) {
66 SEND_STRING("Hello, world!\n");
67 }
68 return false;
69 }
70
71 return true;
72}
73```
74
75### Keycode Injection {#example-keycode-injection}
76
77This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two.
78
79```c
80SEND_STRING("{}" SS_TAP(X_LEFT));
81```
82
83This example types Ctrl+A, then Ctrl+C, without releasing Ctrl.
84
85```c
86SEND_STRING(SS_LCTL("ac"));
87```
88
89## API {#api}
90
91### `void send_string(const char *string)` {#api-send-string}
92
93Type out a string of ASCII characters.
94
95This function simply calls `send_string_with_delay(string, 0)`.
96
97#### Arguments {#api-send-string-arguments}
98
99 - `const char *string`
100 The string to type out.
101
102---
103
104### `void send_string_with_delay(const char *string, uint8_t interval)` {#api-send-string-with-delay}
105
106Type out a string of ASCII characters, with a delay between each character.
107
108#### Arguments {#api-send-string-with-delay-arguments}
109
110 - `const char *string`
111 The string to type out.
112 - `uint8_t interval`
113 The amount of time, in milliseconds, to wait before typing the next character.
114
115---
116
117### `void send_string_P(const char *string)` {#api-send-string-p}
118
119Type out a PROGMEM string of ASCII characters.
120
121On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`.
122
123#### Arguments {#api-send-string-p-arguments}
124
125 - `const char *string`
126 The string to type out.
127
128---
129
130### `void send_string_with_delay_P(const char *string, uint8_t interval)` {#api-send-string-with-delay-p}
131
132Type out a PROGMEM string of ASCII characters, with a delay between each character.
133
134On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`.
135
136#### Arguments {#api-send-string-with-delay-p-arguments}
137
138 - `const char *string`
139 The string to type out.
140 - `uint8_t interval`
141 The amount of time, in milliseconds, to wait before typing the next character.
142
143---
144
145### `void send_char(char ascii_code)` {#api-send-char}
146
147Type out an ASCII character.
148
149#### Arguments {#api-send-char-arguments}
150
151 - `char ascii_code`
152 The character to type.
153
154---
155
156### `void send_dword(uint32_t number)` {#api-send-dword}
157
158Type out an eight digit (unsigned 32-bit) hexadecimal value.
159
160The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`.
161
162#### Arguments {#api-send-dword-arguments}
163
164 - `uint32_t number`
165 The value to type, from 0 to 4,294,967,295.
166
167---
168
169### `void send_word(uint16_t number)` {#api-send-word}
170
171Type out a four digit (unsigned 16-bit) hexadecimal value.
172
173The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`.
174
175#### Arguments {#api-send-word-arguments}
176
177 - `uint16_t number`
178 The value to type, from 0 to 65,535.
179
180---
181
182### `void send_byte(uint8_t number)` {#api-send-bytes}
183
184Type out a two digit (8-bit) hexadecimal value.
185
186The format is `[0-9a-f]{2}`, eg. `00` through `ff`.
187
188#### Arguments {#api-send-byte-arguments}
189
190 - `uint8_t number`
191 The value to type, from 0 to 255.
192
193---
194
195### `void send_nibble(uint8_t number)` {#api-send-nibble}
196
197Type out a single hexadecimal digit.
198
199The format is `[0-9a-f]{1}`, eg. `0` through `f`.
200
201#### Arguments {#api-send-nibble-arguments}
202
203 - `uint8_t number`
204 The value to type, from 0 to 15.
205
206---
207
208### `void tap_random_base64(void)` {#api-tap-random-base64}
209
210Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`.
211
212---
213
214### `SEND_STRING(string)` {#api-send-string-macro}
215
216Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`.
217
218On ARM devices, this define evaluates to `send_string_with_delay(string, 0)`.
219
220---
221
222### `SEND_STRING_DELAY(string, interval)` {#api-send-string-delay-macro}
223
224Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`.
225
226On ARM devices, this define evaluates to `send_string_with_delay(string, interval)`.