Format unicode_common (#13)

vomindoraan · drashna · commit 919c90eab316 · 2018-11-03T10:24:24.000-07:00
* case alignment

* process_record_unicode_common → process_unicode_common

* Move song arrays into function where they're used, align preprocessor directives

* Swap the order of UC_WIN and UC_BSD

* Update Unicode docs

* Reorder Unicode mode stuff to match the order of input mode constants

* Fix capitalization in doc subtitle

* Readd BSD and OSX_RALT songs

* Reword BSD note in docs

* Readd BSD keycode description

* Reword explanation of input on different platforms
diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md
@@ -1,6 +1,6 @@
 # Unicode Support
 
-There are three Unicode keymap definition method available in QMK:
+There are three Unicode keymap definition methods available in QMK:
 
 ## UNICODE_ENABLE
 
@@ -14,15 +14,15 @@ And you may want to have an enum to make reference easier.  So you'd want to add
 
 ```c
 enum unicode_names {
-  BANG, // ‽
-  IRONY, // ⸮
-  SNEK // snke 🐍
+  BANG,
+  IRONY,
+  SNEK,
 };
 
 const uint32_t PROGMEM unicode_map[] = {
-  [BANG]  = 0x0203D, // ‽
-  [IRONY] = 0x02E2E, // ⸮
-  [SNEK]  = 0x1F40D  // snke 🐍
+  [BANG]    = 0x203D,  // ‽
+  [IRONY]   = 0x2E2E,  // ⸮
+  [SNEK]    = 0x1F40D, // 🐍
 }:
 ```
 
@@ -77,18 +77,9 @@ void qk_ucis_symbol_fallback (void) { // falls back to manual unicode entry
 
 ## Input Modes
 
-Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, each OS has different ideas on how Unicode is input. Specifically, each OS has one (or more) key sequences that it requires to input unicode characters.
+Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, the way this is done differs for each platform. Specifically, each platform requires a different combination of keys to trigger Unicode input. Therefore, a corresponding input mode has to be set in QMK.
 
-There are two ways to set the input mode for Unicode, by keycode or by function.  
-
-Keep in mind that both methods write to persistant storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it once, you do not need to set it again unless you need to change it or you've reset the EEPROM settings.
-
-!> There are options for BSD here, but it is not implemented at this time. If you use BSD and want to help in adding support for this, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues)
-
-
-### Functions
-
-You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, and this works the same way as the keycodes below.
+The following input modes are available:
 
 * __UC_OSX__: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
 * __UC_OSX_RALT__: Same as UC_OSX, but sends the Right Alt key for unicode input
@@ -97,21 +88,30 @@ You can also switch the input mode by calling `set_unicode_input_mode(x)` in you
 * __UC_WIN__: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
 * __UC_WINC__: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
 
-### Keycodes
+!> There is an input mode option for BSD, but it's not implemented at this time. If you use BSD and want to help with adding support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
+
+### Switching Input Modes
 
-|Key                       |Aliases  |Input Method  |Description                                        |
-|--------------------------|---------|--------------|---------------------------------------------------|
-|`UNICODE_MODE_OSX`        |`UC_M_OS`|`UC_OSX`      |Sets the input method for MacOS X                  |
-|`UNICODE_MODE_LNX`        |`UC_M_LN`|`UC_LNX`      |Sets the input method for Linux                    |
-|`UNICODE_MODE_BSD`        |`UC_M_BS`|`UC_BSD`      |Sets the input method for BSD (Non-Operational)    |
-|`UNICODE_MODE_WIN`        |`UC_M_WI`|`UC_WIN`      |Sets the input method for Windows                  |
-|`UNICODE_MODE_WINC`       |`UC_M_WC`|`UC_WINC`     |Sets the input method for Windows using WinCompose |
-|`UNICODE_MODE_OSX_RALT`   |`UC_M_OR`|`UC_OSX_RALT` |Sets the input method for MacOS X using RAlt/AltGr |
-### Audio Feedback for Input Mode keycodes
+There are two ways to set the input mode for Unicode: by keycode or by function. Keep in mind that both methods write to persistent storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it once, you don't need to set it again unless you want to change it, or you've reset the EEPROM settings.
+
+You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap.
+
+|Keycode                |Alias    |Input mode   |Description                              |
+|-----------------------|---------|-------------|-----------------------------------------|
+|`UNICODE_MODE_OSX`     |`UC_M_OS`|`UC_OSX`     |Switch to Mac OS X 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_OSX_RALT`|`UC_M_OR`|`UC_OSX_RALT`|Switch to Mac OS X input using Right Alt.|
+
+You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, and this works the same way as the above keycodes.
+
+### Audio Feedback
 
 If you have the [Audio feature](feature_audio.md) enabled on the board, you can set melodies to be played when you press the above keys. That way you can have some audio feedback when switching input modes.
 
-For instance, you can add these to your `config.h` file.
+For instance, you can add these definitions to your `config.h` file:
 
 ```c
 #define UNICODE_SONG_OSX  COIN_SOUND
@@ -122,16 +122,15 @@ For instance, you can add these to your `config.h` file.
 #define UNICODE_SONG_OSX_RALT COIN_SOUND
 ```
 
-### Unicode Input Method Customization
+### Additional Customization
 
-The "start" and "finish" functions for unicode method can be customized locally. A great use for this is to customize the input methods if you don't use the default keys. Or to add visual, or audio feedback when inputting unicode characters.
+The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input.
 
-* `void unicode_input_start(void)` - This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on Mac.
-* `void unicode_input_finish (void)` - his is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
+* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on Mac.
+* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
 
 You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c).
 
-
 ## `send_unicode_hex_string`
 
 To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
diff --git a/quantum/process_keycode/process_unicode_common.c b/quantum/process_keycode/process_unicode_common.c
@@ -21,27 +21,6 @@
 
 unicode_config_t unicode_config;
 static uint8_t saved_mods;
-#ifdef AUDIO_ENABLE
-  #ifdef UNICODE_SONG_OSX
-    float osx_song[][2] = UNICODE_SONG_OSX;
-  #endif
-  #ifdef UNICODE_SONG_LNX
-    float song_lnx[][2] = UNICODE_SONG_LNX;
-  #endif
-  #ifdef UNICODE_SONG_WIN
-    float windows_song[][2] = UNICODE_SONG_WIN;
-  #endif
-  #ifdef UNICODE_SONG_BSD
-    float song_bsd[][2] = UNICODE_SONG_BSD;
-  #endif
-  #ifdef UNICODE_SONG_WINC
-    float win_compose_song[][2] = UNICODE_SONG_WINC;
-  #endif
-  #ifdef UNICODE_SONG_OSX_RALT
-    float osx_ralt_song[][2] = UNICODE_SONG_OSX_RALT;
-  #endif
-#endif
-
 
 void set_unicode_input_mode(uint8_t os_target) {
   unicode_config.input_mode = os_target;
@@ -92,16 +71,16 @@ void unicode_input_start(void) {
 __attribute__((weak))
 void unicode_input_finish(void) {
   switch (unicode_config.input_mode) {
-    case UC_OSX:
-    case UC_WIN:
-      unregister_code(KC_LALT);
-      break;
-    case UC_OSX_RALT:
-      unregister_code(KC_RALT);
-      break;
-    case UC_LNX:
-      tap_code(KC_SPC);
-      break;
+  case UC_OSX:
+  case UC_WIN:
+    unregister_code(KC_LALT);
+    break;
+  case UC_OSX_RALT:
+    unregister_code(KC_RALT);
+    break;
+  case UC_LNX:
+    tap_code(KC_SPC);
+    break;
   }
 
   set_mods(saved_mods); // Reregister previously set mods
@@ -153,52 +132,57 @@ void send_unicode_hex_string(const char *str) {
 bool process_unicode_common(uint16_t keycode, keyrecord_t *record) {
   if (record->event.pressed) {
     switch (keycode) {
-      case UNICODE_MODE_OSX:
+    case UNICODE_MODE_OSX:
       set_unicode_input_mode(UC_OSX);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_OSX)
-          PLAY_SONG(osx_song);
-        #endif
-        break;
-      case UNICODE_MODE_LNX:
-        set_unicode_input_mode(UC_LNX);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_LNX)
-          PLAY_SONG(song_lnx);
-        #endif
-        break;
-      case UNICODE_MODE_WIN:
-        set_unicode_input_mode(UC_WIN);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_WIN)
-          PLAY_SONG(windows_song);
-        #endif
-        break;
-      case UNICODE_MODE_BSD:
-        set_unicode_input_mode(UC_BSD);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_BSD)
-          PLAY_SONG(song_bsd);
-        #endif
-        break;
-      case UNICODE_MODE_WINC:
-        set_unicode_input_mode(UC_WINC);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_WINC)
-          PLAY_SONG(win_compose_song);
-        #endif
-        break;
-      case UNICODE_MODE_OSX_RALT:
-        set_unicode_input_mode(UC_OSX_RALT);
-        #if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_OSX_RALT)
-          PLAY_SONG(osx_ralt_song);
-        #endif
-        break;
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_OSX)
+      static float song_osx[][2] = UNICODE_SONG_OSX;
+      PLAY_SONG(song_osx);
+#endif
+      break;
+    case UNICODE_MODE_LNX:
+      set_unicode_input_mode(UC_LNX);
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_LNX)
+      static float song_lnx[][2] = UNICODE_SONG_LNX;
+      PLAY_SONG(song_lnx);
+#endif
+      break;
+    case UNICODE_MODE_WIN:
+      set_unicode_input_mode(UC_WIN);
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_WIN)
+      static float song_win[][2] = UNICODE_SONG_WIN;
+      PLAY_SONG(song_win);
+#endif
+      break;
+    case UNICODE_MODE_BSD:
+      set_unicode_input_mode(UC_BSD);
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_BSD)
+      static float song_bsd[][2] = UNICODE_SONG_BSD;
+      PLAY_SONG(song_bsd);
+#endif
+      break;
+    case UNICODE_MODE_WINC:
+      set_unicode_input_mode(UC_WINC);
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_WINC)
+      static float song_winc[][2] = UNICODE_SONG_WINC;
+      PLAY_SONG(song_winc);
+#endif
+      break;
+    case UNICODE_MODE_OSX_RALT:
+      set_unicode_input_mode(UC_OSX_RALT);
+#if defined(AUDIO_ENABLE) && defined(UNICODE_SONG_OSX_RALT)
+      static float song_osx_ralt[][2] = UNICODE_SONG_OSX_RALT;
+      PLAY_SONG(song_osx_ralt);
+#endif
+      break;
     }
   }
-  #ifdef UNICODE_ENABLE
-    return process_unicode(keycode, record);
-  #endif
-  #ifdef UCIS_ENABLE
-    return process_ucis(keycode, record);
-  #endif
-  #ifdef UNICODEMAP_ENABLE
-    return process_unicode_map(keycode, record);
-  #endif
+#if   defined(UNICODE_ENABLE)
+  return process_unicode(keycode, record);
+#elif defined(UNICODEMAP_ENABLE)
+  return process_unicode_map(keycode, record);
+#elif defined(UCIS_ENABLE)
+  return process_ucis(keycode, record);
+#else
   return true;
+#endif
 }
diff --git a/quantum/process_keycode/process_unicode_common.h b/quantum/process_keycode/process_unicode_common.h
@@ -19,11 +19,11 @@
 #include "quantum.h"
 
 #if defined(UNICODE_ENABLE) + defined(UNICODEMAP_ENABLE) + defined(UCIS_ENABLE) > 1
-  #error "Cannot enable more than one unicode method (UNICODE, UNICODEMAP, UCIS) at the same time"
+  #error "Cannot enable more than one Unicode method (UNICODE, UNICODEMAP, UCIS) at the same time"
 #endif
 
 #ifndef UNICODE_TYPE_DELAY
-#define UNICODE_TYPE_DELAY 10
+  #define UNICODE_TYPE_DELAY 10
 #endif
 
 typedef union {
diff --git a/quantum/quantum.c b/quantum/quantum.c
@@ -235,7 +235,7 @@ bool process_record_quantum(keyrecord_t *record) {
     process_key_lock(&keycode, record) &&
   #endif
   #if defined(AUDIO_ENABLE) && defined(AUDIO_CLICKY)
-      process_clicky(keycode, record) &&
+    process_clicky(keycode, record) &&
   #endif //AUDIO_CLICKY
     process_record_kb(keycode, record) &&
   #if defined(RGB_MATRIX_ENABLE) && defined(RGB_MATRIX_KEYPRESSES)
@@ -250,13 +250,13 @@ bool process_record_quantum(keyrecord_t *record) {
   #ifdef STENO_ENABLE
     process_steno(keycode, record) &&
   #endif
-  #if ( defined(AUDIO_ENABLE) || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))) && !defined(NO_MUSIC_MODE)
+  #if (defined(AUDIO_ENABLE) || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))) && !defined(NO_MUSIC_MODE)
     process_music(keycode, record) &&
   #endif
   #ifdef TAP_DANCE_ENABLE
     process_tap_dance(keycode, record) &&
   #endif
-  #if (defined(UNICODE_ENABLE) || defined(UNICODEMAP_ENABLE) || defined(UCIS_ENABLE))
+  #if defined(UNICODE_ENABLE) || defined(UNICODEMAP_ENABLE) || defined(UCIS_ENABLE)
     process_unicode_common(keycode, record) &&
   #endif
   #ifdef LEADER_ENABLE
