tty-input v0.6.0

tty-input

tty-input is a fast package for handling input (keyboard, mouse and bracketed paste mode) from the terminal, made for interactive, terminal-based applications.

Note: This package has been renamed to tty-events. Please use it instead.

Features

• Full mouse support (VT200 and SGR extended);
• Bracketed paste mode support;
• Focus support (xterm);
• Full UTF-8 support;
• Keys always have objects;
• Easy comparation (key == "Ctrl+s");
• Support for more key combinations (especially in Windows);
• unknownSequence event.

Usage Examples

Keyboard

Here's a simple logger:

if (process.stdin.isTTY)
	process.stdin.setRawMode(true);

const term = new (require("tty-input"));

term.on("keypress", (key)=>{
	if (key == "Ctrl+c") {
		process.exit(0)
	}
	console.log("You pressed %s.", key.toString())
});

Mouse

tty-input supports mouse (VT200 and SGR extended). In order to receive mouse events, the enableMouse() function must be called first.

term.enableMouse();

term.on("mousedown", (ev)=>{
	console.log("You clicked at (%i, %i) with the button no. %i.", ev.x, ev.y, ev.button)
});

Pasting

tty-input supports bracketed paste mode. This feature allows to distinguish between real keystrokes and pasted text from the clipboard. This is useful in applications where ceratin keys trigger some command. In order to receive paste events, the enableBPM() function must be called first.

term.enableBPM();

term.on("paste", (text)=>{
	console.log("You pasted %O.", text)
});

Focus

Focus events allow an applicatioin to stop updating the screen when it's not necessary. In order to receive paste events, the enableFocus() function must be called first.

term.enableFocus();

term.on("focusin", ()=>{
	console.log("The terminal received focus.")
});
term.on("focusout", ()=>{
	console.log("The terminal lost focus.")
});

Important Notes and Limitations

Because of the way terminals work, there are some aspects that might seem unintuitive.

Uppercase VS Shift

An uppercase letter emits an event with the uppercase letter and with the shift property set to false. This is because there is no way to know if Shift was being pressed (an uppercase letter can be produced with Caps Lock). For example: Shift+Alt+A emits Alt+A instead of Alt+Shift+a.

"Twin" Keys

Some key combinations produce the same output to stdin. Here is a list of most (if not all) the key combinations that may not work as expected:

• Ctrl+Shift+letter: Emits Ctrl+[letter] (in lowercase). (The Shift modifier is ignored.)
• Ctrl+M: Emits enter. (Terminals send \r when Ctrl+M is pressed.)
• Ctrl+J: Emits enter. (Terminals send \n when Ctrl+J is pressed.)
• Ctrl+I: Emits tab. (Terminals send \t when Ctrl+I is pressed.)
• Ctrl+H: Emits backspace. (Terminals send \b when Ctrl+H is pressed.)
• Ctrl+[: Emits escape. (Terminals send \x1b when Ctrl+[ is pressed.)
• Shift+F1: Emits f11 in some terminals.
• Shift+F2: Emits f12 in some terminals.

Escape Key

Use of Esc (escape) is discouraged, since terminals send \x1b when Esc is pressed, which is the first byte of escape sequences.

Incompatible Terminals

Also, some features and/or key combinations don't work in some terminal emulators:

• Mouse support isn't available in Windows Console.
• Bracketed paste mode isn't available in Windows Console.
• Ctrl+@ doesn't work in Windows Console and in some keyboard layouts Ctrl+\, Ctrl+], Ctrl+^ and Ctrl+- don't work too.

Documentation

The full documentation is available here.