Add keys for uc mode selection to macros + missing docs

xs5871 · xs5871 · commit 6adb6be0b992 · 2024-05-20T08:45:45.000Z
diff --git a/docs/en/macros.md b/docs/en/macros.md
@@ -0,0 +1,226 @@
+# Macros
+
+Macros are used for sending multiple keystrokes in a single action, and can
+be used for things like Unicode characters (even emojis! 🇨🇦), _Lorem ipsum_
+generators, triggering side effects (think lighting, speakers,
+microcontroller-optimized cryptocurrency miners, whatever).
+
+## Setup
+
+```python
+from kmk.modules.macros import Macros
+
+macros = Macros()
+keyboard.modules.append(macros)
+```
+
+This will enable a new type of keycode: `KC.MACRO()`
+
+## Keycodes
+
+|Key                |Description                               |
+|-------------------|------------------------------------------|
+|`KC.MACRO(macro)`  |Create a key that will play back a macro. |
+|`KC.UC_MODE_IBUS`  |Switch Unicode mode to IBus.              |
+|`KC.UC_MODE_MACOS` |Switch Unicode mode to macOS.             |
+|`KC.UC_MODE_WINC`  |Switch Unicode mode to Windows Compose.   |
+
+## Sending strings
+
+The most basic sequence is an ASCII string. It can be used to send any standard
+English alphabet character, and an assortment of other "standard" keyboard keys
+(return, space, exclamation points, etc.).
+Keep in mind that some characters from shifted keys are i18n dependent.
+
+```python
+WOW = KC.MACRO("Wow, KMK is awesome!")
+
+keyboard.keymap = [<other keycodes>, WOW, <other keycodes>]
+```
+
+## Key sequences
+
+If you need to add modifier keys to your sequence or you need more granular control.
+You can use it to add things like copying/pasting, tabbing between fields, etc.
+
+```python
+from kmk.modules.macros import Press, Release, Tap
+
+PASTE_WITH_COMMENTARY = KC.MACRO(
+    "look at this: ",
+    Press(KC.LCTL),
+    Tap(KC.V),
+    Release(KC.LCTL)
+)
+
+keyboard.keymap = [<other keycodes>, PASTE_WITH_COMMENTARY, <other keycodes>]
+```
+
+The above example will type out "look at this: " and then paste the contents of your
+clipboard.
+
+
+### Sleeping within a sequence
+
+If you need to wait during a sequence, you can use `Delay(ms)` to wait a
+length of time, in milliseconds.
+
+```python
+from kmk.modules.macros import Tap, Delay
+
+COUNTDOWN_TO_PASTE = KC.MACRO(
+    Tap(KC.N3),
+    Tap(KC.ENTER),
+    Delay(1000),
+    Tap(KC.N2),
+    Tap(KC.ENTER),
+    Delay(1000),
+    Tap(KC.N1),
+    Tap(KC.ENTER),
+    Delay(1000),
+    Tap(KC.LCTL(KC.V)),
+)
+
+keyboard.keymap = [<other keycodes>, COUNTDOWN_TO_PASTE, <other keycodes>]
+```
+
+This example will type out the following, waiting one second (1000 ms) between numbers:
+
+    3
+    2
+    1
+
+and then paste the contents of your clipboard.
+
+### Alt Tab with delay
+
+If alt tab isn't working because it requires a delay, adding a delay and triggering
+down and up on ALT manually may fix the issue.
+
+``` python
+from kmk.modules.macros import Delay, Press, Release, Tap
+
+NEXT = KC.MACRO(
+    Press(KC.LALT),
+    Delay(30),
+    Tap(KC.TAB),
+    Delay(30),
+    Release(KC.LALT),
+)
+```
+
+## Unicode
+
+### Unicode Modes
+
+On Linux, Unicode uses `Ctrl-Shift-U`, which is supported by `ibus` and GTK+3.
+`ibus` users will need to add `IBUS_ENABLE_CTRL_SHIFT_U=1` to their environment
+(`~/profile`, `~/.bashrc`, `~/.zshrc`, or through your desktop environment's
+configurator).
+
+On Windows, [WinCompose](https://github.com/samhocevar/wincompose) is required.
+
+- Linux : `UnicodeModeIBus`, the default
+- MacOS: `UnicodeModeMacOS`
+- Windows: `UnicodeModeWinC`
+
+### Unicode Examples
+
+Initialize `Macros` to use `UnicodeModeMac` and make a key to cycle between modes
+at runtime.
+
+```python
+from kmk.keys import Key
+from kmk.modules.macros import Macros, UnicodeModeIBus, UnicodeModeMacOS, UnicodeModeWinC
+
+macros = Macros(unicode_mode=UnicodeModeMacOS)
+keyboard.modules.append(macros)
+
+def switch_um(keyboard):
+    if macros.unicode_mode == UnicodeModeIBus:
+        macros.unicode_mode = UnicodeModeMacOS
+    elif macros.unicode_mode == UnicodeModeMacOS:
+        macros.unicode_mode = UnicodeModeWinC
+    else:
+        macros.Unicode_mode = UnicodeModeIBus
+
+UCCYCLE = Key(code=None, on_press=switch_um)
+
+FLIP = KC.MACRO('(ノಠ痊ಠ)ノ彡┻━┻')
+
+keyboard.keymap = [<other keycodes>, UCCYCLE, FLIP, <other keycodes>]
+```
+
+## Arbitrary Actions
+
+As it happens, macros accept any callable object (even generators) as arguments.
+The `KMKKeyboard` object is passed as argument to that callable.
+
+### Example 1
+
+Change the RGB animation mode to "SWIRL" for five seconds and print an ASCII
+spinner
+
+```python
+# ... boilerplate omitted for brevity.
+
+prev_animation = None
+
+def start_spinning(keyboard):
+    global prev_animation
+    prev_animation = rgb.animation_mode
+    rgb.animation_mode = AnimationModes.SWIRL
+    rgb.effect_init = True
+
+def stop_spinning(keyboard):
+    rgb.animation_mode = prev_animation
+    rgb.effect_init = True
+
+DISCO = KC.MACRO(
+    "disco time!",
+    start_color_wheel,
+    "-",
+    DELAY(1000),
+    KC.BSPC,
+    "\\",
+    DELAY(1000),
+    KC.BSPC,
+    "|",
+    DELAY(1000),
+    KC.BSPC,
+    "/",
+    DELAY(1000),
+    KC.BSPC,
+    "-",
+    DELAY(1000),
+    KC.BSPC,
+    stop_color_wheel,
+    " disco time over.",
+    )
+```
+
+### Example 2
+
+Here's a programmatic version of the earlier countdown-to-paste example, using a
+generator.
+Any return value that is not `None` is interpreted as a delay instruction in
+milliseconds.
+
+```python
+def countdown(count, delay_ms):
+    def generator(keyboard):
+        for n in range(count, 0, -1):
+            KC[n].on_press(keyboard)
+            yield
+            KC[n].on_release(keyboard)
+            yield
+            KC.ENTER.on_press(keyboard)
+            yield
+            KC.ENTER.on_release(keyboard)
+            yield delay_ms
+    return generator
+
+COUNTDOWN_TO_PASTE = KC.MACRO(
+    countdown(3, 1000),
+    Tap(KC.LCTL(KC.V)),
+)
diff --git a/kmk/modules/macros.py b/kmk/modules/macros.py
@@ -1,4 +1,4 @@
-from kmk.keys import KC, make_argumented_key
+from kmk.keys import KC, make_argumented_key, make_key
 from kmk.modules import Module
 from kmk.scheduler import create_task
 from kmk.utils import Debug
@@ -49,7 +49,7 @@ def post(keyboard):
         KC.ENTER.on_release(keyboard)
 
 
-class UnicodeModeMac:
+class UnicodeModeMacOS:
     @staticmethod
     def pre(keyboard):
         KC.LALT.on_press(keyboard)
@@ -135,7 +135,22 @@ def __init__(self, unicode_mode=UnicodeModeIBus, delay=10):
         make_argumented_key(
             validator=MacroMeta,
             names=('MACRO',),
-            on_press=self.macro_pressed,
+            on_press=self.on_press_macro,
+        )
+        make_key(
+            names=('UC_MODE_IBUS',),
+            meta=UnicodeModeIBus,
+            on_press=self.on_press_unicode_mode,
+        )
+        make_key(
+            names=('UC_MODE_MACOS',),
+            meta=UnicodeModeMacOS,
+            on_press=self.on_press_unicode_mode,
+        )
+        make_key(
+            names=('UC_MODE_WINC',),
+            meta=UnicodeModeWinC,
+            on_press=self.on_press_unicode_mode,
         )
 
     def during_bootup(self, keyboard):
@@ -165,7 +180,10 @@ def on_powersave_enable(self, keyboard):
     def on_powersave_disable(self, keyboard):
         return
 
-    def macro_pressed(self, key, keyboard, *args, **kwargs):
+    def on_press_unicode_mode(self, key, keyboard, *args, **kwargs):
+        self.unicode_mode = key.meta
+
+    def on_press_macro(self, key, keyboard, *args, **kwargs):
         self._active = True
 
         _iter = MacroIter(keyboard, key.meta.macro, self.unicode_mode)
diff --git a/tests/test_macros.py b/tests/test_macros.py
@@ -8,7 +8,7 @@
     Release,
     Tap,
     UnicodeModeIBus,
-    UnicodeModeMac,
+    UnicodeModeMacOS,
     UnicodeModeWinC,
 )
 from tests.keyboard_test import KeyboardTest
@@ -31,7 +31,7 @@ def setUp(self):
                     KC.MACRO('🍺!'),
                 ]
             ],
-            debug_enabled=True,
+            debug_enabled=False,
         )
 
     def test_0(self):
@@ -144,7 +144,7 @@ def test_7_ibus_explicit(self):
         )
 
     def test_7_ralt(self):
-        self.macros.unicode_mode = UnicodeModeMac
+        self.macros.unicode_mode = UnicodeModeMacOS
         self.kb.test(
             '',
             [(7, True), (7, False)],
@@ -192,5 +192,33 @@ def test_8_winc(self):
         )
 
 
+class TestUnicodeModeKeys(unittest.TestCase):
+    def setUp(self):
+        self.macros = Macros()
+        self.kb = KeyboardTest(
+            [self.macros],
+            [
+                [
+                    KC.UC_MODE_IBUS,
+                    KC.UC_MODE_MACOS,
+                    KC.UC_MODE_WINC,
+                ]
+            ],
+            debug_enabled=False,
+        )
+
+    def test_ibus(self):
+        self.kb.test('', [(0, True), (0, False)], [{}])
+        self.assertEqual(self.macros.unicode_mode, UnicodeModeIBus)
+
+    def test_mac(self):
+        self.kb.test('', [(1, True), (1, False)], [{}])
+        self.assertEqual(self.macros.unicode_mode, UnicodeModeMacOS)
+
+    def test_winc(self):
+        self.kb.test('', [(2, True), (2, False)], [{}])
+        self.assertEqual(self.macros.unicode_mode, UnicodeModeWinC)
+
+
 if __name__ == '__main__':
     unittest.main()
diff --git a/util/aspell.en.pws b/util/aspell.en.pws
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 354
+personal_ws-1.1 en 355 
 ADNS
 AMS
 ANAVI
@@ -69,6 +69,7 @@ Hanja
 Hankaku
 Henkan
 HoldTap
+IBus
 InternalState
 ItsyBitsy
 JIS
