Source code for keys

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""SDL-style key codes, names, and modifier masks.

Import as ``import keys`` and use ``keys.K_a``, ``keys.KMOD_CTRL``,
``keys.keyname(code)``, ``keys.chord_matches(...)``.
"""

try:
    from micropython import const as _const
except ImportError:

    def _const(x):
        return x


[docs] def keyname(x): """Return the human-readable name for key code ``x``.""" return _keytable.get(x, "Unknown")
[docs] def key(x): """Return the key code whose name is ``x``. Args: x: A name from `keyname` (e.g. ``"Return"``). Returns: int: Matching ``K_*`` code. Raises: ValueError: When ``x`` is not a known key name. """ return list(_keytable.keys())[list(_keytable.values()).index(x)]
[docs] def modname(x): """Return the human-readable name for modifier mask ``x``.""" return _modtable.get(x, "Unknown")
[docs] def mod(x): """Return the modifier mask whose name is ``x``. Args: x: A name from `modname` (e.g. ``"Ctrl"``). Returns: int: Matching ``KMOD_*`` mask. Raises: ValueError: When ``x`` is not a known modifier name. """ return list(_modtable.keys())[list(_modtable.values()).index(x)]
K_UNKNOWN = _const(0) K_BACKSPACE = _const(8) K_TAB = _const(9) K_RETURN = _const(13) K_ESCAPE = _const(27) K_SPACE = _const(32) K_EXCLAIM = _const(33) K_QUOTEDBL = _const(34) K_HASH = _const(35) K_DOLLAR = _const(36) K_PERCENT = _const(37) K_AMPERSAND = _const(38) K_QUOTE = _const(39) K_LEFTPAREN = _const(40) K_RIGHTPAREN = _const(41) K_ASTERISK = _const(42) K_PLUS = _const(43) K_COMMA = _const(44) K_MINUS = _const(45) K_PERIOD = _const(46) K_SLASH = _const(47) K_0 = _const(48) K_1 = _const(49) K_2 = _const(50) K_3 = _const(51) K_4 = _const(52) K_5 = _const(53) K_6 = _const(54) K_7 = _const(55) K_8 = _const(56) K_9 = _const(57) K_COLON = _const(58) K_SEMICOLON = _const(59) K_LESS = _const(60) K_EQUALS = _const(61) K_GREATER = _const(62) K_QUESTION = _const(63) K_AT = _const(64) K_LEFTBRACKET = _const(91) K_BACKSLASH = _const(92) K_RIGHTBRACKET = _const(93) K_CARET = _const(94) K_UNDERSCORE = _const(95) K_BACKQUOTE = _const(96) K_a = _const(97) K_b = _const(98) K_c = _const(99) K_d = _const(100) K_e = _const(101) K_f = _const(102) K_g = _const(103) K_h = _const(104) K_i = _const(105) K_j = _const(106) K_k = _const(107) K_l = _const(108) K_m = _const(109) K_n = _const(110) K_o = _const(111) K_p = _const(112) K_q = _const(113) K_r = _const(114) K_s = _const(115) K_t = _const(116) K_u = _const(117) K_v = _const(118) K_w = _const(119) K_x = _const(120) K_y = _const(121) K_z = _const(122) K_DELETE = _const(127) K_CAPSLOCK = _const(1073741881) K_F1 = _const(1073741882) K_F2 = _const(1073741883) K_F3 = _const(1073741884) K_F4 = _const(1073741885) K_F5 = _const(1073741886) K_F6 = _const(1073741887) K_F7 = _const(1073741888) K_F8 = _const(1073741889) K_F9 = _const(1073741890) K_F10 = _const(1073741891) K_F11 = _const(1073741892) K_F12 = _const(1073741893) K_PRINTSCREEN = _const(1073741894) K_SCROLLLOCK = _const(1073741895) K_PAUSE = _const(1073741896) K_INSERT = _const(1073741897) K_HOME = _const(1073741898) K_PAGEUP = _const(1073741899) K_END = _const(1073741901) K_PAGEDOWN = _const(1073741902) K_RIGHT = _const(1073741903) K_LEFT = _const(1073741904) K_DOWN = _const(1073741905) K_UP = _const(1073741906) K_NUMLOCKCLEAR = _const(1073741907) K_KP_DIVIDE = _const(1073741908) K_KP_MULTIPLY = _const(1073741909) K_KP_MINUS = _const(1073741910) K_KP_PLUS = _const(1073741911) K_KP_ENTER = _const(1073741912) K_KP_1 = _const(1073741913) K_KP_2 = _const(1073741914) K_KP_3 = _const(1073741915) K_KP_4 = _const(1073741916) K_KP_5 = _const(1073741917) K_KP_6 = _const(1073741918) K_KP_7 = _const(1073741919) K_KP_8 = _const(1073741920) K_KP_9 = _const(1073741921) K_KP_0 = _const(1073741922) K_KP_PERIOD = _const(1073741923) K_APPLICATION = _const(1073741925) K_POWER = _const(1073741926) K_KP_EQUALS = _const(1073741927) K_F13 = _const(1073741928) K_F14 = _const(1073741929) K_F15 = _const(1073741930) K_F16 = _const(1073741931) K_F17 = _const(1073741932) K_F18 = _const(1073741933) K_F19 = _const(1073741934) K_F20 = _const(1073741935) K_F21 = _const(1073741936) K_F22 = _const(1073741937) K_F23 = _const(1073741938) K_F24 = _const(1073741939) K_EXECUTE = _const(1073741940) K_HELP = _const(1073741941) K_MENU = _const(1073741942) K_SELECT = _const(1073741943) K_STOP = _const(1073741944) K_AGAIN = _const(1073741945) K_UNDO = _const(1073741946) K_CUT = _const(1073741947) K_COPY = _const(1073741948) K_PASTE = _const(1073741949) K_FIND = _const(1073741950) K_MUTE = _const(1073741951) K_VOLUMEUP = _const(1073741952) K_VOLUMEDOWN = _const(1073741953) K_KP_COMMA = _const(1073741957) K_KP_EQUALSAS400 = _const(1073741958) K_ALTERASE = _const(1073741977) K_SYSREQ = _const(1073741978) K_CANCEL = _const(1073741979) K_CLEAR = _const(1073741980) K_PRIOR = _const(1073741981) K_RETURN2 = _const(1073741982) K_SEPARATOR = _const(1073741983) K_OUT = _const(1073741984) K_OPER = _const(1073741985) K_CLEARAGAIN = _const(1073741986) K_CRSEL = _const(1073741987) K_EXSEL = _const(1073741988) K_KP_00 = _const(1073742000) K_KP_000 = _const(1073742001) K_THOUSANDSSEPARATOR = _const(1073742002) K_DECIMALSEPARATOR = _const(1073742003) K_CURRENCYUNIT = _const(1073742004) K_CURRENCYSUBUNIT = _const(1073742005) K_KP_LEFTPAREN = _const(1073742006) K_KP_RIGHTPAREN = _const(1073742007) K_KP_LEFTBRACE = _const(1073742008) K_KP_RIGHTBRACE = _const(1073742009) K_KP_TAB = _const(1073742010) K_KP_BACKSPACE = _const(1073742011) K_KP_A = _const(1073742012) K_KP_B = _const(1073742013) K_KP_C = _const(1073742014) K_KP_D = _const(1073742015) K_KP_E = _const(1073742016) K_KP_F = _const(1073742017) K_KP_XOR = _const(1073742018) K_KP_POWER = _const(1073742019) K_KP_PERCENT = _const(1073742020) K_KP_LESS = _const(1073742021) K_KP_GREATER = _const(1073742022) K_KP_AMPERSAND = _const(1073742023) K_KP_DBLAMPERSAND = _const(1073742024) K_KP_VERTICALBAR = _const(1073742025) K_KP_DBLVERTICALBAR = _const(1073742026) K_KP_COLON = _const(1073742027) K_KP_HASH = _const(1073742028) K_KP_SPACE = _const(1073742029) K_KP_AT = _const(1073742030) K_KP_EXCLAM = _const(1073742031) K_KP_MEMSTORE = _const(1073742032) K_KP_MEMRECALL = _const(1073742033) K_KP_MEMCLEAR = _const(1073742034) K_KP_MEMADD = _const(1073742035) K_KP_MEMSUBTRACT = _const(1073742036) K_KP_MEMMULTIPLY = _const(1073742037) K_KP_MEMDIVIDE = _const(1073742038) K_KP_PLUSMINUS = _const(1073742039) K_KP_CLEAR = _const(1073742040) K_KP_CLEARENTRY = _const(1073742041) K_KP_BINARY = _const(1073742042) K_KP_OCTAL = _const(1073742043) K_KP_DECIMAL = _const(1073742044) K_KP_HEXADECIMAL = _const(1073742045) K_LCTRL = _const(1073742048) K_LSHIFT = _const(1073742049) K_LALT = _const(1073742050) K_LGUI = _const(1073742051) K_RCTRL = _const(1073742052) K_RSHIFT = _const(1073742053) K_RALT = _const(1073742054) K_RGUI = _const(1073742055) K_MODE = _const(1073742081) K_AUDIONEXT = _const(1073742082) K_AUDIOPREV = _const(1073742083) K_AUDIOSTOP = _const(1073742084) K_AUDIOPLAY = _const(1073742085) K_AUDIOMUTE = _const(1073742086) K_MEDIASELECT = _const(1073742087) K_WWW = _const(1073742088) K_MAIL = _const(1073742089) K_CALCULATOR = _const(1073742090) K_COMPUTER = _const(1073742091) K_AC_SEARCH = _const(1073742092) K_AC_HOME = _const(1073742093) K_AC_BACK = _const(1073742094) K_AC_FORWARD = _const(1073742095) K_AC_STOP = _const(1073742096) K_AC_REFRESH = _const(1073742097) K_AC_BOOKMARKS = _const(1073742098) K_BRIGHTNESSDOWN = _const(1073742099) K_BRIGHTNESSUP = _const(1073742100) K_DISPLAYSWITCH = _const(1073742101) K_KBDILLUMTOGGLE = _const(1073742102) K_KBDILLUMDOWN = _const(1073742103) K_KBDILLUMUP = _const(1073742104) K_EJECT = _const(1073742105) K_SLEEP = _const(1073742106) _keytable = { K_UNKNOWN: "Unknown", K_BACKSPACE: "Backspace", K_TAB: "Tab", K_RETURN: "Return", K_ESCAPE: "Escape", K_SPACE: "Space", K_EXCLAIM: "!", K_QUOTEDBL: '"', K_HASH: "#", K_DOLLAR: "$", K_PERCENT: "%", K_AMPERSAND: "&", K_QUOTE: "'", K_LEFTPAREN: "(", K_RIGHTPAREN: ")", K_ASTERISK: "*", K_PLUS: "+", K_COMMA: ",", K_MINUS: "-", K_PERIOD: ".", K_SLASH: "/", K_0: "0", K_1: "1", K_2: "2", K_3: "3", K_4: "4", K_5: "5", K_6: "6", K_7: "7", K_8: "8", K_9: "9", K_COLON: ":", K_SEMICOLON: ";", K_LESS: "<", K_EQUALS: "=", K_GREATER: ">", K_QUESTION: "?", K_AT: "@", # 65: " A", # 66: " B", # 67: " C", # 68: " D", # 69: " E", # 70: " F", # 71: " G", # 72: " H", # 73: " I", # 74: " J", # 75: " K", # 76: " L", # 77: " M", # 78: " N", # 79: " O", # 80: " P", # 81: " Q", # 82: " R", # 83: " S", # 84: " T", # 85: " U", # 86: " V", # 87: " W", # 88: " X", # 89: " Y", # 90: " Z", K_LEFTBRACKET: "[", K_BACKSLASH: "\\", K_RIGHTBRACKET: "]", K_CARET: "^", K_UNDERSCORE: "_", K_BACKQUOTE: "`", K_a: "A", K_b: "B", K_c: "C", K_d: "D", K_e: "E", K_f: "F", K_g: "G", K_h: "H", K_i: "I", K_j: "J", K_k: "K", K_l: "L", K_m: "M", K_n: "N", K_o: "O", K_p: "P", K_q: "Q", K_r: "R", K_s: "S", K_t: "T", K_u: "U", K_v: "V", K_w: "W", K_x: "X", K_y: "Y", K_z: "Z", # 123: "{", # 124: "|", # 125: "}", # 126: "~", K_DELETE: "Delete", K_CAPSLOCK: "CapsLock", K_F1: "F1", K_F2: "F2", K_F3: "F3", K_F4: "F4", K_F5: "F5", K_F6: "F6", K_F7: "F7", K_F8: "F8", K_F9: "F9", K_F10: "F10", K_F11: "F11", K_F12: "F12", K_PRINTSCREEN: "PrintScreen", K_SCROLLLOCK: "ScrollLock", K_PAUSE: "Pause", K_INSERT: "Insert", K_HOME: "Home", K_PAGEUP: "PageUp", K_END: "End", K_PAGEDOWN: "PageDown", K_RIGHT: "Right", K_LEFT: "Left", K_DOWN: "Down", K_UP: "Up", K_NUMLOCKCLEAR: "Numlock", K_KP_DIVIDE: "Keypad /", K_KP_MULTIPLY: "Keypad *", K_KP_MINUS: "Keypad -", K_KP_PLUS: "Keypad +", K_KP_ENTER: "Keypad Enter", K_KP_1: "Keypad 1", K_KP_2: "Keypad 2", K_KP_3: "Keypad 3", K_KP_4: "Keypad 4", K_KP_5: "Keypad 5", K_KP_6: "Keypad 6", K_KP_7: "Keypad 7", K_KP_8: "Keypad 8", K_KP_9: "Keypad 9", K_KP_0: "Keypad 0", K_KP_PERIOD: "Keypad .", K_APPLICATION: "Application", K_POWER: "Power", K_KP_EQUALS: "Keypad =", K_F13: "F13", K_F14: "F14", K_F15: "F15", K_F16: "F16", K_F17: "F17", K_F18: "F18", K_F19: "F19", K_F20: "F20", K_F21: "F21", K_F22: "F22", K_F23: "F23", K_F24: "F24", K_EXECUTE: "Execute", K_HELP: "Help", K_MENU: "Menu", K_SELECT: "Select", K_STOP: "Stop", K_AGAIN: "Again", K_UNDO: "Undo", K_CUT: "Cut", K_COPY: "Copy", K_PASTE: "Paste", K_FIND: "Find", K_MUTE: "Mute", K_VOLUMEUP: "VolumeUp", K_VOLUMEDOWN: "VolumeDown", K_KP_COMMA: "Keypad ", K_KP_EQUALSAS400: "Keypad = (AS400)", K_ALTERASE: "AltErase", K_SYSREQ: "SysReq", K_CANCEL: "Cancel", K_CLEAR: "Clear", K_PRIOR: "Prior", K_RETURN2: "Return", K_SEPARATOR: "Separator", K_OUT: "Out", K_OPER: "Oper", K_CLEARAGAIN: "Clear / Again", K_CRSEL: "CrSel", K_EXSEL: "ExSel", K_KP_00: "Keypad 00", K_KP_000: "Keypad 000", K_THOUSANDSSEPARATOR: "ThousandsSeparator", K_DECIMALSEPARATOR: "DecimalSeparator", K_CURRENCYUNIT: "CurrencyUnit", K_CURRENCYSUBUNIT: "CurrencySubUnit", K_KP_LEFTPAREN: "Keypad (", K_KP_RIGHTPAREN: "Keypad )", K_KP_LEFTBRACE: "Keypad {", K_KP_RIGHTBRACE: "Keypad }", K_KP_TAB: "Keypad Tab", K_KP_BACKSPACE: "Keypad Backspace", K_KP_A: "Keypad A", K_KP_B: "Keypad B", K_KP_C: "Keypad C", K_KP_D: "Keypad D", K_KP_E: "Keypad E", K_KP_F: "Keypad F", K_KP_XOR: "Keypad XOR", K_KP_POWER: "Keypad ^", K_KP_PERCENT: "Keypad %", K_KP_LESS: "Keypad <", K_KP_GREATER: "Keypad >", K_KP_AMPERSAND: "Keypad &", K_KP_DBLAMPERSAND: "Keypad &&", K_KP_VERTICALBAR: "Keypad |", K_KP_DBLVERTICALBAR: "Keypad ||", K_KP_COLON: "Keypad :", K_KP_HASH: "Keypad #", K_KP_SPACE: "Keypad Space", K_KP_AT: "Keypad @", K_KP_EXCLAM: "Keypad !", K_KP_MEMSTORE: "Keypad MemStore", K_KP_MEMRECALL: "Keypad MemRecall", K_KP_MEMCLEAR: "Keypad MemClear", K_KP_MEMADD: "Keypad MemAdd", K_KP_MEMSUBTRACT: "Keypad MemSubtract", K_KP_MEMMULTIPLY: "Keypad MemMultiply", K_KP_MEMDIVIDE: "Keypad MemDivide", K_KP_PLUSMINUS: "Keypad +/-", K_KP_CLEAR: "Keypad Clear", K_KP_CLEARENTRY: "Keypad ClearEntry", K_KP_BINARY: "Keypad Binary", K_KP_OCTAL: "Keypad Octal", K_KP_DECIMAL: "Keypad Decimal", K_KP_HEXADECIMAL: "Keypad Hexadecimal", K_LCTRL: "Left Ctrl", K_LSHIFT: "Left Shift", K_LALT: "Left Alt", K_LGUI: "Left GUI", K_RCTRL: "Right Ctrl", K_RSHIFT: "Right Shift", K_RALT: "Right Alt", K_RGUI: "Right GUI", K_MODE: "ModeSwitch", K_AUDIONEXT: "AudioNext", K_AUDIOPREV: "AudioPrev", K_AUDIOSTOP: "AudioStop", K_AUDIOPLAY: "AudioPlay", K_AUDIOMUTE: "AudioMute", K_MEDIASELECT: "MediaSelect", K_WWW: "WWW", K_MAIL: "Mail", K_CALCULATOR: "Calculator", K_COMPUTER: "Computer", K_AC_SEARCH: "AC Search", K_AC_HOME: "AC Home", K_AC_BACK: "AC Back", K_AC_FORWARD: "AC Forward", K_AC_STOP: "AC Stop", K_AC_REFRESH: "AC Refresh", K_AC_BOOKMARKS: "AC Bookmarks", K_BRIGHTNESSDOWN: "BrightnessDown", K_BRIGHTNESSUP: "BrightnessUp", K_DISPLAYSWITCH: "DisplaySwitch", K_KBDILLUMTOGGLE: "KBDIllumToggle", K_KBDILLUMDOWN: "KBDIllumDown", K_KBDILLUMUP: "KBDIllumUp", K_EJECT: "Eject", K_SLEEP: "Sleep", } # SDL_Keycode mod values (not complete) KMOD_NONE = _const(0x0000) KMOD_LSHIFT = _const(0x0001) KMOD_RSHIFT = _const(0x0002) KMOD_LCTRL = _const(0x0040) KMOD_RCTRL = _const(0x0080) KMOD_LALT = _const(0x0100) KMOD_RALT = _const(0x0200) KMOD_LGUI = _const(0x0400) KMOD_RGUI = _const(0x0800) KMOD_NUM = _const(0x1000) KMOD_CAPS = _const(0x2000) KMOD_MODE = _const(0x4000) KMOD_CTRL = KMOD_LCTRL | KMOD_RCTRL KMOD_SHIFT = KMOD_LSHIFT | KMOD_RSHIFT KMOD_ALT = KMOD_LALT | KMOD_RALT KMOD_GUI = KMOD_LGUI | KMOD_RGUI _modtable = { KMOD_NONE: "None", KMOD_LSHIFT: "Left Shift", KMOD_RSHIFT: "Right Shift", KMOD_LCTRL: "Left Ctrl", KMOD_RCTRL: "Right Ctrl", KMOD_LALT: "Left Alt", KMOD_RALT: "Right Alt", KMOD_LGUI: "Left GUI", KMOD_RGUI: "Right GUI", KMOD_NUM: "Num Lock", KMOD_CAPS: "Caps Lock", KMOD_MODE: "Mode", KMOD_CTRL: "Ctrl", KMOD_SHIFT: "Shift", KMOD_ALT: "Alt", KMOD_GUI: "GUI", } _MOD_GROUPS = (KMOD_CTRL, KMOD_SHIFT, KMOD_ALT, KMOD_GUI)
[docs] def chord_matches(chord, keycode, mod): """ Return True if ``(keycode, mod)`` satisfies a ``(key, mod_mask)`` chord. Modifier matching is group-aware: a required ``KMOD_CTRL`` is satisfied by either left or right Ctrl. Extra modifiers beyond those required are ignored. Args: chord (tuple | None): A ``(key_code, modifier_mask)`` tuple, or None. keycode (int): The pressed key code. mod (int): The active modifier mask. Returns: bool: Whether the chord is satisfied. """ if not chord: return False chord_key, chord_mod = chord if keycode != chord_key: return False return all(not (chord_mod & group and not mod & group) for group in _MOD_GROUPS)
# --- HID keyboards -------------------------------------------------------- # # The one table from HID keyboard usages to these codes. usbif's USB keyboard # decoder and bledev.hidreport's BLE one both use it, so a key reads the same # whichever way it arrived. SDL's scancodes ARE the HID usages, and every key # without a character has the keycode ``usage | 1 << 30``, so only the # character keys need a table. The ISO "# ~" key (usage 0x32), which SDL # calls '#', stays unmapped. _HID_CHARS = { 0x28: K_RETURN, 0x29: K_ESCAPE, 0x2A: K_BACKSPACE, 0x2B: K_TAB, 0x2C: K_SPACE, 0x2D: K_MINUS, 0x2E: K_EQUALS, 0x2F: K_LEFTBRACKET, 0x30: K_RIGHTBRACKET, 0x31: K_BACKSLASH, 0x33: K_SEMICOLON, 0x34: K_QUOTE, 0x35: K_BACKQUOTE, 0x36: K_COMMA, 0x37: K_PERIOD, 0x38: K_SLASH, 0x4C: K_DELETE, }
[docs] def hid_keycode(usage): """The ``K_*`` code for a HID keyboard-page usage (``0x04`` is 'a'), or None.""" if 0x04 <= usage <= 0x1D: return K_a + usage - 0x04 if 0x1E <= usage <= 0x26: return K_1 + usage - 0x1E if usage == 0x27: return K_0 code = _HID_CHARS.get(usage) if code is not None: return code if usage >= 0x39: code = usage | 0x40000000 if code in _keytable: return code return None
#: The eight modifier bits of a HID keyboard report, in bit order (bit 0 is #: left Ctrl), as ``(KMOD_* mask, K_* code)``. Bit ``i`` is usage ``0xE0 + i``. HID_MODIFIERS = ( (KMOD_LCTRL, K_LCTRL), (KMOD_LSHIFT, K_LSHIFT), (KMOD_LALT, K_LALT), (KMOD_LGUI, K_LGUI), (KMOD_RCTRL, K_RCTRL), (KMOD_RSHIFT, K_RSHIFT), (KMOD_RALT, K_RALT), (KMOD_RGUI, K_RGUI), )
[docs] def hid_modifiers(bits): """The ``KMOD_*`` mask for a HID report's modifier byte.""" mask = KMOD_NONE for i in range(8): if bits & (1 << i): mask |= HID_MODIFIERS[i][0] return mask