Class: AnsiTerm

AnsiTerm(params)

The AnsiTerm class represents an ANSI terminal emulator. It provides methods to handle terminal operations, keyboard events, and rendering of characters with various attributes such as bold, italic, underline, and colors. The constructor accepts a set of key-value pairs to configure various characteristics of the terminal.

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

Configuration parameters or the ID of the div element to create the terminal in.

Properties
Name Type Attributes Default Description
nLines number <optional>
24

Number of lines in the terminal.

nColumns number <optional>
80

Number of columns in the terminal.

historySize number <optional>
1000

Size of the history buffer.

fontSize number <optional>
15

Font size for the terminal text.

font string <optional>
"monospace"

Font family for the terminal text.

statusFont string <optional>
"monospace"

Font family for the status bar text.

containerId string <optional>
""

ID of the container element to create the terminal in.

canvasId string <optional>
""

ID of the canvas element to use for the terminal.

url string <optional>
""

URL for the terminal's data source.

channelType string <optional>
""

Type of channel for communication.

httpSessionHintParam string <optional>
"session"

Name of an additional parameter to (try to) connect to a particular session.

httpSessionHint string <optional>
""

Value od the additional parameter to (try to) connect to a particular session. If empty, generates a new one internally.

httpSource string <optional>
""

Source for the terminal's data.

httpSize string <optional>
""

Configuration URL for the terminal.

httpDest string <optional>
""

Destination URL for sending terminal data.

immediateRefresh number <optional>
100

Immediate refresh interval in milliseconds.

fastRefresh number <optional>
500

Fast refresh interval in milliseconds.

slowRefresh number <optional>
2000

Slow refresh interval in milliseconds.

wsEndpoint string <optional>
""

WebSocket endpoint for the terminal.

wsDataTag string <optional>
""

WebSocket data tag for the terminal.

wsSizeTag string <optional>
""

WebSocket size tag for the terminal.

wsSizeData string <optional>
""

WebSocket size data for the terminal.

foreground string <optional>
"rgb(255,255,255)"

Default foreground color.

background string <optional>
"rgb(0,0,0)"

Default background color.

statusForegroundOk string <optional>
"rgb(0,255,0)"

Status bar foreground color for OK status.

statusBackgroundOk string <optional>
"rgb(0,128,0)"

Status bar background color for OK status.

statusForegroundKo string <optional>
"rgb(255,0,0)"

Status bar foreground color for KO status.

statusBackgroundKo string <optional>
"rgb(128,0,0)"

Status bar background color for KO status.

titleBackground string <optional>
"rgb(0,0,128)"

Title bar background color.

titleForeground string <optional>
"rgb(255,255,255)"

Title bar foreground color.

keyboardBackground string <optional>
"rgb(0,0,128)"

Soft keyboard background color.

keyboardForeground string <optional>
"rgb(255,255,255)"

Soft keyboard foreground color.

selectionBackground string <optional>
"rgb(255,255,0)"

Selection background color.

selectionForeground string <optional>
"rgb(0,0,0)"

Selection foreground color.

blinkIsBold boolean <optional>
true

Whether blinking text should be bold.

blinkPeriod number <optional>
500

Blink period in milliseconds.

timeout number <optional>
1000

Timeout for state machine in milliseconds.

titleText string <optional>
""

Default title text.

cursorUpdateStyle string <optional>
"smart"

Cursor update style ("lazy", "precise", "smart").

hasTitleBar boolean <optional>
true

Whether the terminal has a title bar.

hasStatusBar boolean <optional>
true

Whether the terminal has a status bar.

hasSoftKeyboard boolean <optional>
false

Whether the terminal has a soft keyboard.

hasSoftFKeys boolean <optional>
false

Whether the terminal has soft function keys.

Source:

Classes

AnsiTerm

Methods

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:

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:

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:

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