Unicode

With a little help from your OS, practically any Unicode character can be input using your keyboard.

Caveats

There are some limitations to this feature. Because there is no "standard" method of Unicode input across all operating systems, each of them require their own setup process on both the host and in the firmware, which may involve installation of additional software. This also means Unicode input will not "just work" when the keyboard is plugged into another device.

Usage

The core Unicode API can be used purely programmatically. However, there are also additional subsystems which build on top of it and come with keycodes to make things easier. See below for more details.

Add the following to your keymap's rules.mk:

UNICODE_COMMON = yes

Basic Configuration

Add the following to your config.h:

Define	Default	Description
UNICODE_KEY_MAC	KC_LEFT_ALT	The key to hold when beginning a Unicode sequence with the macOS input mode
UNICODE_KEY_LNX	LCTL(LSFT(KC_U))	The key to tap when beginning a Unicode sequence with the Linux input mode
UNICODE_KEY_WINC	KC_RIGHT_ALT	The key to hold when beginning a Unicode sequence with the WinCompose input mode
UNICODE_SELECTED_MODES	-1	A comma separated list of input modes for cycling through
UNICODE_CYCLE_PERSIST	true	Whether to persist the current Unicode input mode to EEPROM
UNICODE_TYPE_DELAY	10	The amount of time to wait, in milliseconds, between Unicode sequence keystrokes

Audio Feedback

If you have the Audio feature enabled on your board, you can configure it to play sounds when the input mode is changed.

Add the following to your config.h:

Define	Default	Description
UNICODE_SONG_MAC	n/a	The song to play when the macOS input mode is selected
UNICODE_SONG_LNX	n/a	The song to play when the Linux input mode is selected
UNICODE_SONG_BSD	n/a	The song to play when the BSD input mode is selected
UNICODE_SONG_WIN	n/a	The song to play when the Windows input mode is selected
UNICODE_SONG_WINC	n/a	The song to play when the WinCompose input mode is selected

Input Subsystems

Each of these subsystems have their own pros and cons in terms of flexibility and ease of use. Choose the one that best fits your needs.

This is the easiest to use, albeit somewhat limited. It supports code points up to U+7FFF, which covers characters for most modern languages (including East Asian), as well as many symbols, but does not include emoji.

To enable Basic Unicode, add the following to your rules.mk:

UNICODE_ENABLE = yes

You can then add UC(c) keycodes to your keymap, where c is the code point of the desired character (in hexadecimal - the U+ prefix will not work). For example, UC(0x40B) will output Ћ, and UC(0x30C4) will output ツ.

Input Modes

Unicode input works by typing a sequence of characters, similar to a macro. However, since this sequence depends on your OS, you will need to prepare both your host machine and QMK to recognise and send the correct Unicode input sequences respectively.

To set the list of enabled input modes, add the UNICODE_SELECTED_MODES define to your keymap's config.h, for example:

#define UNICODE_SELECTED_MODES UNICODE_MODE_LINUX
// or
#define UNICODE_SELECTED_MODES UNICODE_MODE_MACOS, UNICODE_MODE_WINCOMPOSE

These modes can then be cycled through using the UC_NEXT and UC_PREV keycodes. You can also switch to any input mode, even if it is not specified in UNICODE_SELECTED_MODES, using their respective keycodes.

If your keyboard has working EEPROM, it will remember the last used input mode and continue using it on the next power up. This can be disabled by defining UNICODE_CYCLE_PERSIST to false.

Mode Name: UNICODE_MODE_MACOS

macOS has built-in support for Unicode input as its own input source. It supports all possible code points by way of surrogate pairs for code points above U+FFFF.

To enable, go to System Preferences → Keyboard → Input Sources, then add Unicode Hex Input to the list (under Other), and activate it from the input dropdown in the menu bar. Note that this may disable some Option-based shortcuts such as Option+Left and Option+Right.

Keycodes

Key	Aliases	Description
UC(c)		Send Unicode code point c, up to 0x7FFF
UM(i)		Send Unicode code point at index i in unicode_map
UP(i, j)		Send Unicode code point at index i, or j if Shift/Caps is on
QK_UNICODE_MODE_NEXT	UC_NEXT	Cycle through selected input modes
QK_UNICODE_MODE_PREVIOUS	UC_PREV	Cycle through selected input modes in reverse
QK_UNICODE_MODE_MACOS	UC_MAC	Switch to macOS input
QK_UNICODE_MODE_LINUX	UC_LINX	Switch to Linux input
QK_UNICODE_MODE_WINDOWS	UC_WIN	Switch to Windows input
QK_UNICODE_MODE_BSD	UC_BSD	Switch to BSD input (not implemented)
QK_UNICODE_MODE_WINCOMPOSE	UC_WINC	Switch to Windows input using WinCompose
QK_UNICODE_MODE_EMACS	UC_EMAC	Switch to emacs (C-x-8 RET)

API

uint8_t get_unicode_input_mode(void)

Get the current Unicode input mode.

Return Value

The currently active Unicode input mode.

---

void set_unicode_input_mode(uint8_t mode)

Set the Unicode input mode.

Arguments

• uint8_t mode
  The input mode to set.

---

void unicode_input_mode_step(void)

Change to the next Unicode input mode.

---

void unicode_input_mode_step_reverse(void)

Change to the previous Unicode input mode.

---

void unicode_input_mode_set_user(uint8_t input_mode)

User-level callback, invoked when the input mode is changed.

Arguments

• uint8_t input_mode
  The new input mode.

---

void unicode_input_mode_set_kb(uint8_t input_mode)

Keyboard-level callback, invoked when the input mode is changed.

Arguments

• uint8_t input_mode
  The new input mode.

---

void unicode_input_start(void)

Begin the Unicode input sequence. The exact behavior depends on the currently selected input mode:

• macOS: Hold UNICODE_KEY_MAC
• Linux: Tap UNICODE_KEY_LNX
• WinCompose: Tap UNICODE_KEY_WINC, then U
• HexNumpad: Hold Left Alt, then tap Numpad +
• Emacs: Tap Ctrl+X, then 8, then Enter

This function is weakly defined, and can be overridden in user code.

---

void unicode_input_finish(void)

Complete the Unicode input sequence. The exact behavior depends on the currently selected input mode:

• macOS: Release UNICODE_KEY_MAC
• Linux: Tap Space
• WinCompose: Tap Enter
• HexNumpad: Release Left Alt
• Emacs: Tap Enter

This function is weakly defined, and can be overridden in user code.

---

void unicode_input_cancel(void)

Cancel the Unicode input sequence. The exact behavior depends on the currently selected input mode:

• macOS: Release UNICODE_KEY_MAC
• Linux: Tap Escape
• WinCompose: Tap Escape
• HexNumpad: Release Left Alt
• Emacs: Tap Ctrl+G

This function is weakly defined, and can be overridden in user code.

---

void register_unicode(uint32_t code_point)

Input a single Unicode character. A surrogate pair will be sent if required by the input mode.

Arguments

• uint32_t code_point
  The code point of the character to send.

---

void send_unicode_string(const char *str)

Send a string containing Unicode characters.

Arguments

• const char *str
  The string to send.

---

uint8_t unicodemap_index(uint16_t keycode)

Get the index into the unicode_map array for the given keycode, respecting shift state for pair keycodes.

Arguments

• uint16_t keycode
  The Unicode Map keycode to get the index of.

Return Value

An index into the unicode_map array.

---

uint32_t unicodemap_get_code_point(uint8_t index)

Get the code point for the given index in the unicode_map array.

Arguments

• uint8_t index
  The index into the unicode_map array.

Return Value

A Unicode code point value.

---

void register_unicodemap(uint8_t index)

Send the code point for the given index in the unicode_map array.

Arguments

• uint8_t index
  The index into the unicode_map array.

---

void ucis_start(void)

Begin the input sequence.

---

bool ucis_active(void)

Whether UCIS is currently active.

Return Value

true if UCIS is active.

---

uint8_t ucis_count(void)

Get the number of characters in the input sequence buffer.

Return Value

The current input sequence buffer length.

---

bool ucis_add(uint16_t keycode)

Add the given keycode to the input sequence buffer.

Arguments

• uint16_t keycode
  The keycode to add. Must be between KC_A and KC_Z, or KC_1 and KC_0.

Return Value

true if the keycode was added.

---

bool ucis_remove_last(void)

Remove the last character from the input sequence buffer.

Return Value

true if the sequence was not empty.

---

void ucis_finish(void)

Mark the input sequence as complete, and attempt to match.

---

void ucis_cancel(void)

Cancel the input sequence.

---

void register_ucis(void)

Send the code point(s) for the given UCIS index.

Arguments

• uint8_t index
  The index into the UCIS symbol table.