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)