summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorRyan <fauxpark@gmail.com>2022-11-01 08:15:12 +1100
committerGitHub <noreply@github.com>2022-10-31 21:15:12 +0000
commit5974d989fe72f6c576901a065bee4487a58c351d (patch)
treea88a796ec2c0a11d4d554325fa92e53d9fbb82c2 /docs
parent743524df32ef265fdc3999518cdaba45cd4abf22 (diff)
Normalise Unicode keycodes (#18898)
* `UC_MOD`/`UC_RMOD` -> `UC_NEXT`/`UC_PREV`

* `UNICODE_MODE_*` -> `QK_UNICODE_MODE_*`

* `UC_MAC` -> `UNICODE_MODE_MACOS`

* `UC_LNX` -> `UNICODE_MODE_LINUX`

* `UC_WIN` -> `UNICODE_MODE_WINDOWS`

* `UC_BSD` -> `UNICODE_MODE_BSD`

* `UC_WINC` -> `UNICODE_MODE_WINCOMPOSE`

* `UC_EMACS` -> `UNICODE_MODE_EMACS`

* `UC__COUNT` -> `UNICODE_MODE_COUNT`

* `UC_M_MA` -> `UC_MAC`

* `UC_M_LN` -> `UC_LINX`

* `UC_M_WI` -> `UC_WIN`

* `UC_M_BS` -> `UC_BSD`

* `UC_M_WC` -> `UC_WINC`

* `UC_M_EM` -> `UC_EMAC`

* Docs

* Update quantum/unicode/unicode.h
Diffstat (limited to 'docs')
-rw-r--r--docs/feature_unicode.md44
-rw-r--r--docs/keycodes.md25
2 files changed, 35 insertions, 34 deletions
diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md
index 0b06cae6c2..a93e9ad2ba 100644
--- a/docs/feature_unicode.md
+++ b/docs/feature_unicode.md
@@ -112,28 +112,28 @@ Unicode input in QMK works by inputting a sequence of characters to the OS, sort
 
 The following input modes are available:
 
-* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0x10FFFF` (all possible code points).
+* **`UNICODE_MODE_MACOS`**: macOS built-in Unicode hex input. Supports code points up to `0x10FFFF` (all possible code points).
 
   To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
   By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with a different keycode.
 
   !> Using the _Unicode Hex Input_ input source may disable some Option-based shortcuts, such as Option+Left and Option+Right.
 
-* **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
+* **`UNICODE_MODE_LINUX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
 
   Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
   By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with a different keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
 
   Users who wish support in non-GTK apps without IBus may need to resort to a more indirect method, such as creating a custom keyboard layout ([more on this method](#custom-linux-layout)).
 
-* **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
+* **`UNICODE_MODE_WINDOWS`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
 
   To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
-  This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead.
+  This mode is not recommended because of reliability and compatibility issues; use the `UNICODE_MODE_WINCOMPOSE` mode instead.
 
-* **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
+* **`UNICODE_MODE_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
 
-* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points).
+* **`UNICODE_MODE_WINCOMPOSE`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points).
 
   To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. This mode works reliably under all version of Windows supported by the app.
   By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with a different keycode.
@@ -144,15 +144,15 @@ The following input modes are available:
 To set your desired input mode, add the following define to your `config.h`:
 
 ```c
-#define UNICODE_SELECTED_MODES UC_LNX
+#define UNICODE_SELECTED_MODES UNICODE_MODE_LINUX
 ```
 
-This example sets the board's default input mode to `UC_LNX`. You can replace this with `UC_MAC`, `UC_WINC`, or any of the other modes listed [above](#input-modes). The board will automatically use the selected mode on startup, unless you manually switch to another mode (see [below](#keycodes)).
+This example sets the board's default input mode to `UNICODE_MODE_LINUX`. You can replace this with `UNICODE_MODE_MACOS`, `UNICODE_MODE_WINCOMPOSE`, or any of the other modes listed [above](#input-modes). The board will automatically use the selected mode on startup, unless you manually switch to another mode (see [below](#keycodes)).
 
-You can also select multiple input modes, which allows you to easily cycle through them using the `UC_MOD`/`UC_RMOD` keycodes.
+You can also select multiple input modes, which allows you to easily cycle through them using the `UC_NEXT`/`UC_PREV` keycodes.
 
 ```c
-#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WINC
+#define UNICODE_SELECTED_MODES UNICODE_MODE_MACOS, UNICODE_MODE_LINUX, UNICODE_MODE_WINCOMPOSE
 ```
 
 Note that the values are separated by commas. The board will remember the last used input mode and will continue using it on next power-up. You can disable this and force it to always start with the first mode in the list by adding `#define UNICODE_CYCLE_PERSIST false` to your `config.h`.
@@ -161,18 +161,18 @@ Note that the values are separated by commas. The board will remember the last u
 
 You can switch the input mode at any time by using the following keycodes. Adding these to your keymap allows you to quickly switch to a specific input mode, including modes not listed in `UNICODE_SELECTED_MODES`.
 
-|Keycode               |Alias    |Input Mode  |Description                                                                  |
-|----------------------|---------|------------|-----------------------------------------------------------------------------|
-|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|Cycle through selected modes, reverse direction when Shift is held           |
-|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|Cycle through selected modes in reverse, forward direction when Shift is held|
-|`UNICODE_MODE_MAC`    |`UC_M_MA`|`UC_MAC`    |Switch to macOS input                                                        |
-|`UNICODE_MODE_LNX`    |`UC_M_LN`|`UC_LNX`    |Switch to Linux input                                                        |
-|`UNICODE_MODE_WIN`    |`UC_M_WI`|`UC_WIN`    |Switch to Windows input                                                      |
-|`UNICODE_MODE_BSD`    |`UC_M_BS`|`UC_BSD`    |Switch to BSD input _(not implemented)_                                      |
-|`UNICODE_MODE_WINC`   |`UC_M_WC`|`UC_WINC`   |Switch to Windows input using WinCompose                                     |
-|`UNICODE_MODE_EMACS`  |`UC_M_EM`|`UC_EMACS`  |Switch to emacs (`C-x-8 RET`)                                               |
-
-You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`).
+|Keycode                     |Alias    |Input Mode               |Description                                                                  |
+|----------------------------|---------|-------------------------|-----------------------------------------------------------------------------|
+|`QK_UNICODE_MODE_NEXT`      |`UC_NEXT`|Next in list             |Cycle through selected modes, reverse direction when Shift is held           |
+|`QK_UNICODE_MODE_PREVIOUS`  |`UC_PREV`|Prev in list             |Cycle through selected modes in reverse, forward direction when Shift is held|
+|`QK_UNICODE_MODE_MACOS`     |`UC_MAC` |`UNICODE_MODE_MACOS`     |Switch to macOS input                                                        |
+|`QK_UNICODE_MODE_LINUX`     |`UC_LINX`|`UNICODE_MODE_LINUX`     |Switch to Linux input                                                        |
+|`QK_UNICODE_MODE_WINDOWS`   |`UC_WIN` |`UNICODE_MODE_WINDOWS`   |Switch to Windows input                                                      |
+|`QK_UNICODE_MODE_BSD`       |`UC_BSD` |`UNICODE_MODE_BSD`       |Switch to BSD input _(not implemented)_                                      |
+|`QK_UNICODE_MODE_WINCOMPOSE`|`UC_WINC`|`UNICODE_MODE_WINCOMPOSE`|Switch to Windows input using WinCompose                                     |
+|`QK_UNICODE_MODE_EMACS`     |`UC_EMAC`|`UNICODE_MODE_EMACS`     |Switch to emacs (`C-x-8 RET`)                                                |
+
+You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UNICODE_MODE_LINUX`).
 
 ?> Using `UNICODE_SELECTED_MODES` is preferable to calling `set_unicode_input_mode()` in `matrix_init_user()` or similar functions, since it's better integrated into the Unicode system and has the added benefit of avoiding unnecessary writes to EEPROM.
 
diff --git a/docs/keycodes.md b/docs/keycodes.md
index 1aea603ede..f701193a45 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -839,15 +839,16 @@ See also: [Swap Hands](feature_swap_hands.md)
 
 See also: [Unicode Support](feature_unicode.md)
 
-|Key                   |Aliases  |Description                                                     |
-|----------------------|---------|----------------------------------------------------------------|
-|`UC(c)`               |         |Send Unicode code point `c`, up to `0x7FFF`                     |
-|`X(i)`                |         |Send Unicode code point at index `i` in `unicode_map`           |
-|`XP(i, j)`            |         |Send Unicode code point at index `i`, or `j` if Shift/Caps is on|
-|`UNICODE_MODE_FORWARD`|`UC_MOD` |Cycle through selected input modes                              |
-|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Cycle through selected input modes in reverse                   |
-|`UNICODE_MODE_MAC`    |`UC_M_MA`|Switch to macOS input                                           |
-|`UNICODE_MODE_LNX`    |`UC_M_LN`|Switch to Linux input                                           |
-|`UNICODE_MODE_WIN`    |`UC_M_WI`|Switch to Windows input                                         |
-|`UNICODE_MODE_BSD`    |`UC_M_BS`|Switch to BSD input (not implemented)                           |
-|`UNICODE_MODE_WINC`   |`UC_M_WC`|Switch to Windows input using WinCompose                        |
+|Key                         |Aliases  |Description                                                     |
+|----------------------------|---------|----------------------------------------------------------------|
+|`UC(c)`                     |         |Send Unicode code point `c`, up to `0x7FFF`                     |
+|`X(i)`                      |         |Send Unicode code point at index `i` in `unicode_map`           |
+|`XP(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`)                                   |