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 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

‘\x1b[1;2B’

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

‘\x1b[1;2D’

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

‘\x1b[1;2C’

KEY_SRSUME

403

KEY_SSAVE

404

KEY_SSUSPEND

405

KEY_STAB

340

KEY_SUNDO

406

KEY_SUP

337

‘\x1b[1;2A’

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.