Class: AnsiTerm

AnsiTerm(params)

The AnsiTerm class implements a terminal emulator capable of interpreting ANSI escape sequences and rendering the corresponding output on an HTML5 canvas. It supports features such as cursor movement, text attributes (e.g., bold, italic, underline), color management, scrolling regions, and keyboard input handling.

This class is designed to be highly configurable and extensible, allowing developers to integrate it into web applications requiring terminal-like functionality.

Features:

  • ANSI escape sequence interpretation.
  • Support for 16-color and 256-color palettes.
  • Cursor movement and text attributes (bold, italic, underline, reverse, blink).
  • Scrolling regions and history buffer.
  • Clipboard integration (copy as text, ANSI sequences, or HTML).
  • Mouse-based text selection.
  • Configurable keyboard input handling.
  • Communication with a backend via REST, WebSocket, or custom drivers.

Usage:

To create an instance of AnsiTerm, provide a configuration object or a container ID:

const term = new AnsiTerm({
  nLines: 24,
  nColumns: 80,
  containerId: "terminal-container",
  fontSize: 14,
  font: "monospace",
  background: "black",
  foreground: "white",
});

The terminal can then be used to render text, handle keyboard input, and communicate with a backend server.

Example:

term.write("Hello, World!\n");
term.registerOnTitleChange((title) => {
  console.log("Title changed to:", title);
});
term.sendText("ls -la\n");

Parameters:

  • params (optional): A configuration object or a string representing the container ID. If no parameters are provided, default settings are applied.

Configuration Options:

  • nLines (number): Number of lines in the terminal (default: 25).
  • nColumns (number): Number of columns in the terminal (default: 80).
  • fontSize (number): Font size in pixels (default: 14).
  • font (string): Font family (default: "monospace").
  • background (string): Background color (default: "black").
  • foreground (string): Foreground color (default: "white").
  • containerId (string): ID of the container element for the terminal.
  • driver (object): Custom driver for communication (default: null).
  • channelType (string): Communication channel type ("rest", "websocket", "dummy").
  • historySize (number): Number of lines to keep in the history buffer (default: 1000).

Methods:

  • write(text): Writes a sequence of characters to the terminal.
  • sendText(text): Sends a sequence of characters to the backend.
  • focus(): Sets focus on the terminal to receive keyboard input.
  • close(): Closes the terminal and its communication channel.
  • registerOnTitleChange(callback): Registers a callback for title changes.
  • registerOnStatusChange(callback): Registers a callback for status changes.
  • registerOnFreezeChange(callback): Registers a callback for freeze state changes.
  • clearSelection(): Clears the current text selection.
  • selectAll(): Selects the entire screen.
  • clipboardCopyAsText(): Copies the selection to the clipboard as plain text.
  • clipboardCopyAsAnsiSequence(): Copies the selection to the clipboard as ANSI sequences.
  • clipboardCopyAsHtml(): Copies the selection to the clipboard as HTML.
  • clipboardCopyAsRichText(): Copies the selection to the clipboard as Rich Text.
  • clipboardPaste(): Pastes text from the clipboard into the terminal.
  • toggleFreezeState(): Toggles the freeze state of the terminal.

Events:

  • onTitleChange: Triggered when the terminal title changes.
  • onStatusChange: Triggered when the communication status changes.
  • onFreezeChange: Triggered when the freeze state changes.

Notes:

  • The terminal supports mouse-based text selection and clipboard integration.
  • The AnsiTerm class is designed to be extensible, allowing developers to implement custom drivers and event handlers.

Constructor

new AnsiTerm(params)

Creates an AnsiTerm instance.

If "params" is not specified, the default configuration is applied (80x25, title bar, status bar, soft keyboard, HTTP protocol, "document.body" as parent).

If "params" is a string, it is interpreted as the container ID in which the terminal takes place.

Parameters:
Name Type Description
params *

optional parameters, as a single string or set of key-value pairs.
Source:

Classes

AnsiTerm

Methods

cancelOnAppCursorKeyChange(cb)

This method removes the callback registered by registerOnAppCursorKeyChange.

Parameters:
Name Type Description
cb function

The callback function to remove.
Source:

cancelOnCopy(cb)

This method removes the callback registered by registerOnCopy.

Parameters:
Name Type Description
cb function

The callback function to remove.
Source:

cancelOnFreezeChange(cb)

This method removes the callback registered by registerOnFreezeChange.

Parameters:
Name Type Description
cb function

The callback function to remove.
Source:

cancelOnStatusChange(cb)

This method removes the callback registered by registerOnStatusChange.

Parameters:
Name Type Description
cb function

The callback function to remove.
Source:

cancelOnTitleChange(cb)

This method removes the callback registered by registerOnTitleChange.

Parameters:
Name Type Description
cb function

The callback function to remove.
Source:

clearSelection()

This method clears the selection and returns the focus to the terminal.

Source:

clipboardCopyAsAnsiSequence()

This method copies the selection to the clipboard. The selection is copied as text, possibly containing ANSI sequences to reproduce the character attributes of the on-screen text.

Source:

clipboardCopyAsHtml()

This method copies the selection to the clipboard. The selection is copied as HTML, reproducing the characters of the on-screen text and their attributes.

Source:

clipboardCopyAsRichText()

This method copies the selection to the clipboard. The selection is copied as Rich Text.

NOTE: this method is still under development, and its behavior may change in future releases.

The text is actually stored as HTML, but trailing spaces in lines are discarded. Since the goal of this method is to capture data suited to be pasted into word processors, some adjustments may be useful (e.g., color correction to deal with typical white backgrounds).

Source:

clipboardCopyAsText()

This method copies the selection to the clipboard. The selection is copied as plain text.

Source:

clipboardPaste()

This method implements the clipboard "paste" function.

Source:

close()

This method closes the terminal's communication channel and destroys the terminal.

Source:

focus()

This method sets the focus on the terminal. It is used to make the terminal ready to receive keyboard input.

Source:

getCanvas() → {HTMLCanvasElement}

This method returns the canvas element used by the terminal.

Source:
Returns:

The canvas element.

Type
HTMLCanvasElement

registerOnAppCursorKeyChange(cb)

This method adds a callback that the terminal will invoke each time the application cursor key mode changes, i.e., when the "set application cursor" ANSI sequence is received. The callback receives the new application cursor mode as a parameter. Multiple callbacks may be registered in this way. The callbacks can be removed by calling the cancelOnAppCursorKeyChange method.

Parameters:
Name Type Description
cb function

The callback function to add.
Source:

registerOnCopy(cb)

This method adds a callback that the terminal will invoke each time a some kind of "copy on clipboard" operation is performed. The callback receives the content copied to the clipboard as a string. The callback is called with the second argument set to true if the content is copied as text, and false if it is copied as a blob. Multiple callbacks may be registered in this way. The callbacks can be removed by calling the cancelOnCopy method.

Parameters:
Name Type Description
cb function

The callback function to add.
Source:

registerOnFreezeChange(cb)

This method adds a callback that the terminal will invoke each time one of these events happens:

  • the terminal freezes, i.e., stops updating the screen and accumulates incoming characters instead of showing them. A "freeze" may be generated by entering the mouse selection state or programmatically by calling toggleFreezeState.
  • the terminal is frozen, and new characters are received.
  • the terminal exits the freeze state.

The callback receives two parameters:

  • a boolean parameter, "true" if the terminal is frozen, "false" if not,
  • the number of characters received since the terminal has been frozen.

Multiple callbacks may be registered in this way.

The callbacks can be removed by calling the cancelOnFreezeChange method.

Parameters:
Name Type Description
cb function

The callback function to add.
Source:

registerOnStatusChange(cb)

Adds a callback that the terminal will invoke when the communication state changes. The callback receives a boolean parameter: "true" if the communication is established, "false" if not.

Multiple callbacks may be registered in this way. The callbacks can be removed by calling the cancelOnStatusChange method.

Parameters:
Name Type Description
cb function

The callback function to add.
Source:

registerOnTitleChange(cb)

This method adds a callback that the terminal will invoke each time the title changes, i.e., when the "set title" ANSI sequence is received. The callback receives the new title as a parameter. Multiple callbacks may be registered in this way. The callbacks can be removed by calling the cancelOnTitleChange method.

Parameters:
Name Type Description
cb function

The callback function to add.
Source:

resize(nLines, nColumns)

This method resizes the terminal to the given number of lines and columns. The selection and the viewpoint are cleared, and the cursor is adjusted accordingly. The alternate screen is simply cleared, as it is usually redrawn when the terminal is resized.

Parameters:
Name Type Description
nLines number

The number of lines for the terminal.
nColumns number

The number of columns for the terminal.
Source:

selectAll()

This method selects the entire screen. It implements the "Select all" button function.

Source:

sendKeyByKeyEvent(key)

This method sends the ANSI sequence corresponding to the given keyboard event object to the communication channel used by the terminal.

A key event is an object containing key-related members as produced by a real key event. The object is not required to be a real "event", as only a subset of members is needed:

  • "key",
  • "code",
  • "composed",
  • "ctrlKey",
  • "altKey",
  • "metaKey".

Example: the TAB key is represented by this object:

{ key: 'Tab', code: 'Tab', composed: false, ctrlKey: false, altKey: false, metaKey: false }

Parameters:
Name Type Description
key KeyEventObject

the key event to send
Source:

sendText(text)

This method sends the given sequence of characters to the communication channel used by the terminal.

Parameters:
Name Type Description
text string

the text to send
Source:

setBell(enabled, dration, frequency, decay) → {void}

This method allows you to configure the bell sound parameters for the terminal. The bell sound is played when the terminal receives a BEL character (0x07). You can enable or disable the bell sound, set its duration, frequency, and decay ratio. The default values are:

  • enabled: true
  • duration: 0.5 seconds
  • frequency: 1760 Hz (A6 note)
  • decay: 0.9998 (decay ratio between a sample and the next one, i.e., next/current)
Parameters:
Name Type Description
enabled boolean

Whether the bell sound is enabled.
dration number

The duration of the bell sound in seconds (no changes if undefined).
frequency number

The frequency of the bell sound in Hz (no changes if undefined).
decay number

The decay ratio of the bell sound (no changes if undefined).
Source:
Returns:
Type
void
Example
term.setBell(true, 0.5, 1760, 0.9);

write(text)

This method writes the given sequence of characters. The sequence is processed by the ANSI interpreter, which modifies the screen accordingly.

Parameters:
Name Type Description
text string

The text to write to the terminal.
Source:

(static) getVersion() → {string}

This method retrieves the version string of "xwterm.js".

Source:
Returns:

The version string of this package.

Type
string