Input

Prompt Style

In most terminal emulators, the prompt style appears before the cursor. This is from the backing shell (e.g bash, zsh, fish) that prints it in the terminal.

For example:

My First Terminal

user@host:~ $ ▊

Or even

My First Terminal

┌[user@host]
└$ ▊

In the same way, you can organize the flow of input with a prompt style just before the cursor.

Suppose the state of our app defines the username and hostname like so

const state = { 
    username: 'root', 
    hostname: 'web' 
};

Create a function to write our prompt style to the terminal, let it be ask().

function ask() {
    term.write(`┌[${state.username}@${state.hostname}]\n`);
    term.write('└$ ');
}

Pause & Resume

Using term.pause() will pause or deactivate the terminal from recieving user input whereas term.resume() will do the opposite.

When invoked, term.pause() will trigger the pause event whereas term.resume() will trigger the resume event.

Note

In both cases, input is affected but not the output. You can still do write operations even when the input is deactivated.

Example: Pause input for five (5) seconds and resume thereafter while listening for events.

const term = new XTerminal();

term.mount('#app');

// capture `pause` event
term.on("pause", () => term.writeln("pausing..."));

// capture `resume` event
term.on("resume", () => term.writeln("resuming..."));

term.pause(); // triggers the `pause` event

setTimeout(() => {
    term.resume();  // triggers the `resume` event
}, 5000);

In the five seconds, any keypress won't do anything but we can observe to write operations in order of the events.

---

Suppose that you want to do an async operation, it is a good practice to pause the terminal for input and resume later when the operation is done.

Whenever the input is recieved, you can pause the terminal and handle the async operation first.

term.on("data", async input => {
    term.pause();
    // ...
    // do async task
    // ...
    term.resume();
});

Everytime you write the prompt style, you may want to be able to capture the next command input from the user. In this case, you can use the term.resume() method.

function ask() {
    term.write(`┌[${state.username}@${state.hostname}]\n`);
    term.write('└$ ');
    term.resume(); 
}

Focus & Blur

You can programmatically focus the terminal input, toggling the keyboard in case of mobile devices, using the term.focus() method on the terminal instance.

Focus the input everytime you ask for input using:

function ask() {
    term.writeln(`┌[${state.username}@${state.hostname}]`);
    term.write('└$ ');
    term.resume();
    term.focus(); 
}

In the same way, you might want to blur the terminal for some reason, say after entering data and pressing the Enter key. You can achieve that using the data event and the term.blur() method.

term.on('data', () => {
    term.blur();
});

Set & Clear

Use term.setInput() to simulate user input by modifying the value of the input buffer. This is useful in many scenarios, one of which is to preset some input in the terminal a user can use/modify/execute (so that they don't have to type it themselves).

Here is an example:

term.setInput("help")

My First Terminal

user@host:~ $ help▊

Given that we can now change the input buffer, term.clearInput() allows for clearing the input buffer, for instance, when you want to discard any user input or contents of the input buffer.

term.clearInput()

results into

My First Terminal

user@host:~ $ ▊

A complete example to illustrate both methods in action: the input is set to help and cleared after 2 seconds

term.setInput("help")

setTimeout(() => {
    term.clearInput()
}, 2000)

Next Step

Learn about the history stack that stores all inputs