blessed-xterm

Blessed-XTerm
=============

XTerm Widget for Blessed Curses Environment

Abstract
--------

This is an XTerm emulating terminal widget for the awesome
Blessed Curses environment of
Node.js. It allows the execution of interactive terminal programs in a
Blessed Box-derived widget while providing a full-featured and fully
compatible emulated XTerm rendering environment to those programs.

Blessed XTerm is actually a more modern variant of the Terminal widget
as shipped with the Blessed Curses environment. The difference to the
regular Terminal widget is: (1) the Blessed XTerm widget uses the
newer and more portable node-pty
module, instead of the ancient pty.js
module, for Pseudo TTY management, (2) it uses the newer and more
sophisticated XTerm.js module, instead of the
ancient Term.js module, for XTerm
emulation, (3) it provides full scrollback buffer support and (4) it
supports starting and stopping multiple commands while the widget is
active.

To see Blessed XTerm in action, check out stmux,
the utility for which Blessed XTerm originally was developed for.

Example
-------

!Blessed XTerm Sample usage

Installation
------------

``
$ npm install blessed blessed-xterm
`

NOTICE: The node-pty dependency module is a Node.js module with
a native C/C++ component. For this a C/C++ compiler environment is
required during npm install. For macOS, ensure you have Apple XCode
and its Command-Line Tools installed (you can find them in XCode
under menu Xcode / Preferences / Downloads). For Windows,
you need Microsoft's Visual C/C++ Build Tools installed (you can
conveniently install them with npm install --global --production
windows-build-tools from an elevated shell).

Usage
-----

The Blessed XTerm widget supports all configuration options of
Blessed Box,
Blessed Element,
Blessed Node and
Node.js EventEmitter,
plus the following ones:

- shell (default: process.env.SHELL || "sh"):

The shell to execute.
- args (default: []):

The arguments for the shell to execute.
- env (default: process.env):

The environment variables for the shell to execute.
- cwd (default: process.cwd()):

The current working directory for the shell to execute.
- cursorType (default: block):

The type of cursor. Either block, underline or line.
- scrollback (default: 1000):

The amount of lines for scrolling back.
- controlKey (default: C-w):

The control key to enter the scrolling mode.
- ignoreKeys (default: []):

The keys to ignore.
- mousePassthrough (default: false):

The mouse events are captured and passed-through to
the XTerm emulation as mouse key sequences.
- style.scrolling.border.fg (default: red):

The color of the border during scrolling mode.

The Blessed XTerm widget supports all methods of
Blessed Box,
Blessed Element,
Blessed Node and
Node.js EventEmitter,
plus the following ones:

- enableInput(enable: Boolean): Void:

Enable or disable the input handling.
- injectInput(input: String): Void:

Inject input into the terminal as it was typed by the user.
The input is actually sent to the executed program.
- write(output: String): Void:

Write output to the terminal as it was output by the executed program.
The output is just displayed.
- getScrollHeight(): Number:

Get the actual height in lines of the scrolling area.
- getScroll(): Number:

Get the current scroll index in lines.
- setScroll(index: Number): Void:

Scroll the content to an absolute index in lines (same as scrollTo).
- scrollTo(index: Number): Void:

Scroll the content to an absolute index in lines (same as setScroll).
- getScrollPerc(): Number:

Get the current scroll index in percentage (0-100).
- setScrollPerc(percent: Number): Void:

Set the current scroll index in percentage (0-100).
- scroll(offset: Number): Void:

Scroll the content by a relative offset of lines.
- resetScroll(): Void:

Reset the scrolling by scrolling to the bottom of the scroll buffer.
- spawn (shell: String, args: String[], cwd?: String, env?: Object): Void:

Spawn/run a command, optionally first terminating a currently running one.
- terminate(): Void:

Terminate a currently running/spawned program.
- kill(): Void:

Tear down the widget.

The Blessed XTerm widget supports all events of
Blessed Box,
Blessed Element,
Blessed Node and
Node.js EventEmitter,
plus the following ones:

- title (title: String):

The program output a sequence to update the terminal with title.
- beep ():

The program output a sequence to beep the terminal.
- scrolling-start ():

The scrolling mode was started.
- scrolling-end ():

The scrolling mode was ended.
- scroll ():

The content was scrolled.
- exit (code: Number):

The spawned program terminated with code.
Usually used in combination with the Blessed XTerm spawn() method.
- update ():

The rendering engine just updated the widget content.
Usually used in combination with the Blessed Element screenshot()` method.

License
-------

Copyright (c) 2017-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.