Merge pull request #116 from michalpokusa/layout-write-delay

KeyboardLayout.write() delay parameter

adafruit_hid/keyboard_layout_base.py

@@ -16,6 +16,7 @@
 except ImportError:
     pass
 
+from time import sleep
 
 __version__ = "0.0.0+auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_HID.git"
@@ -88,10 +89,11 @@ def _write(self, keycode: int, altgr: bool = False) -> None:
         self.keyboard.press(keycode)
         self.keyboard.release_all()
 
-    def write(self, string: str) -> None:
+    def write(self, string: str, delay: float = None) -> None:
         """Type the string by pressing and releasing keys on my keyboard.
 
         :param string: A string of UTF-8 characters to convert to key presses and send.
+        :param float delay: Optional delay in seconds between key presses.
         :raises ValueError: if any of the characters has no keycode
             (such as some control characters).
 
@@ -122,6 +124,9 @@ def write(self, string: str) -> None:
                     )
                 )
 
+            if delay is not None:
+                sleep(delay)
+
     def keycodes(self, char: str) -> Tuple[int, ...]:
         """Return a tuple of keycodes needed to type the given character.
 

docs/api.rst

@@ -9,6 +9,7 @@
 
 .. automodule:: adafruit_hid.keyboard_layout_us
    :members:
+   :inherited-members:
 
 .. automodule:: adafruit_hid.keyboard_layout_base
    :members:

docs/examples.rst

@@ -16,6 +16,19 @@ Send ALT+Tab for swapping windows, and CTRL+K for searching in a browser.
     :caption: examples/hid_keyboard_shortcuts.py
     :linenos:
 
+Keyboard Layout
+---------------
+
+While the ``Keyboard`` class itself provides easy way for sending key shortcuts, for writing more
+complex text you may want to use a ``KeyboardLayout`` and a ``.write()`` method.
+
+It is also possible to adjust the typing speed by specifying ``delay`` between key presses.
+
+.. literalinclude:: ../examples/hid_keyboard_layout.py
+    :caption: examples/hid_keyboard_layout.py
+    :emphasize-lines: 12-13,29,33
+    :linenos:
+
 Simple Gamepad
 ---------------
 

examples/hid_keyboard_layout.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
+# SPDX-License-Identifier: MIT
+
+import time
+import board
+import digitalio
+import usb_hid
+
+from adafruit_hid.keyboard import Keyboard
+from adafruit_hid.keyboard_layout_us import KeyboardLayoutUS
+
+keyboard = Keyboard(usb_hid.devices)
+layout = KeyboardLayoutUS(keyboard)
+
+
+# define buttons. these can be any physical switches/buttons, but the values
+# here work out-of-the-box with a CircuitPlayground Express' A and B buttons.
+slow_write = digitalio.DigitalInOut(board.D4)
+slow_write.direction = digitalio.Direction.INPUT
+slow_write.pull = digitalio.Pull.DOWN
+
+fast_write = digitalio.DigitalInOut(board.D5)
+fast_write.direction = digitalio.Direction.INPUT
+fast_write.pull = digitalio.Pull.DOWN
+
+while True:
+    # Write `Hello World!` slowly
+    if slow_write.value:
+        layout.write("Hello World!", delay=0.2)
+
+    # Write `Hello World!` normally
+    elif fast_write.value:
+        layout.write("Hello World!")
+
+    time.sleep(0.1)