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}')
A visual example of interacting with the Terminal.inkey() and cbreak() methods.

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 Keystrok returned by inkey() is unicode – it may be printed, joined with, or compared to any other unicode strings. It also has these provides the 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.