Keyboard — Blessed 1.17.7 documentation

# Keyboard

The built-in function `input()` (or `raw_input()`) is pretty good for a basic game:

    name = input("What is your name? ")
    if sum(map(ord, name)) % 2:
        print(f"{name}?! What a beautiful name!")
    else:
        print(f"How interesting, {name} you say?")

But it has drawbacks – it’s no good for interactive apps! This function will not return until the return key is pressed, so we can’t do any exciting animations, and we can’t understand or detect arrow keys and others required to make awesome, interactive apps and games!

Blessed fixes this issue with a context manager, `cbreak()`, and a single function for all keyboard input, `inkey()`.

## inkey()

Let’s just dive right into a rich “event loop”, that awaits a keypress for 3 seconds and tells us what key we pressed.

    print(f"{term.home}{term.black_on_skyblue}{term.clear}")
    print("press 'q' to quit.")
    with term.cbreak():
        val = ''
        while val.lower() != 'q':
            val = term.inkey(timeout=3)
            if not val:
               print("It sure is quiet in here ...")
            elif val.is_sequence:
               print("got sequence: {0}.".format((str(val), val.name, val.code)))
            elif val:
               print("got {0}.".format(val))
        print(f'bye!{term.normal}')

`cbreak()` enters a special mode that ensures `os.read()` on an input stream will return as soon as input is available, as explained in cbreak(3). This mode is combined with `inkey()` to decode multibyte sequences, such as `\0x1bOA`, into a unicode-derived `Keystroke` instance.

The `Keystroke` returned by `inkey()` is unicode – it may be printed, joined with, or compared to any other unicode strings. It also has these special attributes:

- `is_sequence` (bool): Whether it is an “application” key.

- `code` (int): The keycode, for equality testing.

- `name` (str): a human-readable name of any “application” key.

## Keycodes

When the `is_sequence` property tests True, the value of `code` represents a unique application key of the keyboard.

`code` may then be compared with attributes of `Terminal`, which are duplicated from those found in curses(3), or those constants in `curses` beginning with phrase KEY_, as follows:

All Terminal class attribute Keyboard codes, by name
Name | Value | Example Sequence(s)
--- | --- | ---
KEY_BACKSPACE | 263 | ‘\x08’, ‘\x7f’
KEY_BEGIN | 354 |
KEY_BTAB | 353 |
KEY_C1 | 351 |
KEY_C3 | 352 |
KEY_CANCEL | 355 |
KEY_CATAB | 342 |
KEY_CENTER | 350 |
KEY_CLEAR | 333 |
KEY_CLOSE | 356 |
KEY_COMMAND | 357 |
KEY_COPY | 358 |
KEY_CREATE | 359 |
KEY_CTAB | 341 |
KEY_DELETE | 330 | ‘\x1b[3~’
KEY_DL | 328 |
KEY_DOWN | 258 | ‘\x1b[B’, ‘\x1b[OB’
KEY_EIC | 332 |
KEY_END | 360 | ‘\x1b[F’, ‘\x1b[K’, ‘\x1b[8~’, ‘\x1b[OF’
KEY_ENTER | 343 | ‘\n’, ‘\r’, ‘\x1bOM’
KEY_EOL | 335 |
KEY_EOS | 334 |
KEY_ESCAPE | 361 | ‘\x1b’
KEY_F0 | 264 |
KEY_F1 | 265 | ‘\x1bOP’
KEY_F10 | 274 |
KEY_F11 | 275 |
KEY_F12 | 276 |
KEY_F13 | 277 |
KEY_F14 | 278 |
KEY_F15 | 279 |
KEY_F16 | 280 |
KEY_F17 | 281 |
KEY_F18 | 282 |
KEY_F19 | 283 |
KEY_F2 | 266 | ‘\x1bOQ’
KEY_F20 | 284 |
KEY_F21 | 285 |
KEY_F22 | 286 |
KEY_F23 | 287 |
KEY_F3 | 267 | ‘\x1bOR’
KEY_F4 | 268 | ‘\x1bOS’
KEY_F5 | 269 |
KEY_F6 | 270 |
KEY_F7 | 271 |
KEY_F8 | 272 |
KEY_F9 | 273 |
KEY_FIND | 362 | ‘\x1b[1~’
KEY_HELP | 363 |
KEY_HOME | 262 | ‘\x1b[H’, ‘\x1b[7~’, ‘\x1b[OH’
KEY_IL | 329 |
KEY_INSERT | 331 | ‘\x1b[2~’
KEY_KP_0 | 520 | ‘\x1bOp’
KEY_KP_1 | 521 | ‘\x1bOq’
KEY_KP_2 | 522 | ‘\x1bOr’
KEY_KP_3 | 523 | ‘\x1bOs’
KEY_KP_4 | 524 | ‘\x1bOt’
KEY_KP_5 | 525 | ‘\x1bOu’
KEY_KP_6 | 526 | ‘\x1bOv’
KEY_KP_7 | 527 | ‘\x1bOw’
KEY_KP_8 | 528 | ‘\x1bOx’
KEY_KP_9 | 529 | ‘\x1bOy’
KEY_KP_ADD | 514 | ‘\x1bOk’
KEY_KP_DECIMAL | 517 | ‘\x1bOn’
KEY_KP_DIVIDE | 518 | ‘\x1bOo’
KEY_KP_EQUAL | 519 | ‘\x1bOX’
KEY_KP_MULTIPLY | 513 | ‘\x1bOj’
KEY_KP_SEPARATOR | 515 | ‘\x1bOl’
KEY_KP_SUBTRACT | 516 | ‘\x1bOm’
KEY_LEFT | 260 | ‘\x1b[D’, ‘\x1b[OD’
KEY_LL | 347 |
KEY_MARK | 364 |
KEY_MAX | 511 |
KEY_MESSAGE | 365 |
KEY_MIN | 257 |
KEY_MOUSE | 409 |
KEY_MOVE | 366 |
KEY_NEXT | 367 |
KEY_OPEN | 368 |
KEY_OPTIONS | 369 |
KEY_PGDOWN | 338 | ‘\x1b[U’, ‘\x1b[6~’
KEY_PGUP | 339 | ‘\x1b[V’, ‘\x1b[5~’
KEY_PREVIOUS | 370 |
KEY_PRINT | 346 |
KEY_REDO | 371 |
KEY_REFERENCE | 372 |
KEY_REFRESH | 373 |
KEY_REPLACE | 374 |
KEY_RESET | 345 |
KEY_RESIZE | 410 |
KEY_RESTART | 375 |
KEY_RESUME | 376 |
KEY_RIGHT | 261 | ‘\x1b[C’, ‘\x1b[OC’
KEY_SAVE | 377 |
KEY_SBEG | 378 |
KEY_SCANCEL | 379 |
KEY_SCOMMAND | 380 |
KEY_SCOPY | 381 |
KEY_SCREATE | 382 |
KEY_SDC | 383 |
KEY_SDL | 384 |
KEY_SDOWN | 336 |
KEY_SELECT | 385 | ‘\x1b[4~’
KEY_SEND | 386 |
KEY_SEOL | 387 |
KEY_SEXIT | 388 |
KEY_SFIND | 389 |
KEY_SHELP | 390 |
KEY_SHOME | 391 |
KEY_SIC | 392 |
KEY_SLEFT | 393 |
KEY_SMESSAGE | 394 |
KEY_SMOVE | 395 |
KEY_SNEXT | 396 |
KEY_SOPTIONS | 397 |
KEY_SPREVIOUS | 398 |
KEY_SPRINT | 399 |
KEY_SREDO | 400 |
KEY_SREPLACE | 401 |
KEY_SRESET | 344 |
KEY_SRIGHT | 402 |
KEY_SRSUME | 403 |
KEY_SSAVE | 404 |
KEY_SSUSPEND | 405 |
KEY_STAB | 340 |
KEY_SUNDO | 406 |
KEY_SUP | 337 |
KEY_SUSPEND | 407 |
KEY_TAB | 512 | ‘\t’
KEY_UNDO | 408 |
KEY_UP | 259 | ‘\x1b[A’, ‘\x1b[OA’
KEY_UP_LEFT | 348 |
KEY_UP_RIGHT | 349 |

All such keystrokes can be decoded by blessed, there is a demonstration program, keymatrix.py that tests how many of them you can find !

## delete

Typically, backspace is `^H` (8, or 0x08) and delete is ^? (127, or 0x7f).

On some systems however, the key for backspace is actually labeled and transmitted as “delete”, though its function in the operating system behaves just as backspace. Blessed usually returns “backspace” in most situations.

It is highly recommend to accept both `KEY_DELETE` and `KEY_BACKSPACE` as having the same meaning except when implementing full screen editors, and provide a choice to enable the delete mode by configuration.

## Alt/meta

Programs with GNU readline, like bash, have Alt combinators, such as ALT+u to uppercase the word after cursor. This is achieved by the configuration option altSendsEscape or metaSendsEscape in xterm.

The default for most terminals, however, is for this key to be bound by the operating system, or, used for inserting international keys, (where the combination ALT+u, a is used to insert the character `ä`).

It is therefore a recommendation to avoid alt or meta keys entirely in applications.

And instead prefer the ctrl-key combinations, maybe along with `raw()`, to avoid instructing users to custom-configure their terminal emulators to communicate Alt sequences.

If you still wish to optionall decode them, ALT+z becomes Escape + z (or, in raw form `\x1bz`). This is detected by blessings as two keystrokes, `KEY_ESCAPE` and `'z'`. Blessings currently provides no further assistance in detecting these key combinations.