A curses-like library with a high level terminal interface API for node.js.

Blessed is over 16,000 lines of code and terminal goodness. It's completely
implemented in javascript, and its goal consists of two things:

Reimplement ncurses entirely by parsing and compiling terminfo and termcap,
and exposing a Program object which can output escape sequences compatible
with any terminal.

Implement a widget API which is heavily optimized for terminals.

The blessed renderer makes use of CSR (change-scroll-region), and BCE
(back-color-erase). It draws the screen using the painter's algorithm and is
sped up with smart cursor movements and a screen damage buffer. This means
rendering of your application will be extremely efficient: blessed only draws
the changes (damage) to the screen.

Blessed is arguably as accurate as ncurses, but even more optimized in some
ways. The widget library gives you an API which is reminiscent of the DOM.
Anyone is able to make an awesome terminal application with blessed. There are
terminal widget libraries for other platforms (primarily [python][urwid] and
[perl][curses-ui]), but blessed is possibly the most DOM-like (dare I say the
most user-friendly?).

Blessed has been used to implement other popular libraries and programs.
Examples include: the [slap text editor][slap] and [blessed-contrib][contrib].
The blessed API itself has gone on to inspire [termui][termui] for Go.

The absolute .leftproperty (not option) has been renamed to .aleft.
The .rleft property has been renamed to .left. This should not have much
effect on most applications. This includes all other coordinate properties.

autoPadding is now enabled by default. To revert to the original behavior,
pass autoPadding: false into the screen object. That being said, it would
be wiser to adjust your code to use autoPadding. Non-autoPadding is now
considered deprecated.

This will render a box with line borders containing the text 'Hello world!',
perfectly centered horizontally and vertically.

NOTE: It is recommend you use either smartCSR or fastCSR as a
blessed.screen option. autoPadding is also recommended; it will
automatically offset box content within borders instead of on top of them when
coords are 0. Non-autoPaddingmay be deprecated in the future. See the
API documentation for further explanation of these options.

var blessed =require('blessed');

// Create a screen object.

varscreen= blessed.screen({

autoPadding:true,

smartCSR:true

});

screen.title='my window title';

// Create a box perfectly centered horizontally and vertically.

var box = blessed.box({

top:'center',

left:'center',

width:'50%',

height:'50%',

content:'Hello {bold}world{/bold}!',

tags:true,

border:{

type:'line'

},

style:{

fg:'white',

bg:'magenta',

border:{

fg:'#f0f0f0'

},

hover:{

bg:'green'

}

}

});

// Append our box to the screen.

screen.append(box);

// Add a png icon to the box

var icon = blessed.image({

parent: box,

top:0,

left:0,

type:'overlay',

width:'shrink',

height:'shrink',

file:__dirname+'/my-program-icon.png',

search:false

});

// If our box is clicked, change the content.

box.on('click',function(data){

box.setContent('{center}Some different {red-fg}content{/red-fg}.{/center}');

screen.render();

});

// If box is focused, handle `enter`/`return` and give us some more content.

box.key('enter',function(ch, key){

box.setContent('{right}Even different {black-fg}content{/black-fg}.{/right}\n');

program - The blessed Program to be associated with. Will be
automatically instantiated if none is provided.

smartCSR - Attempt to perform CSR optimization on all possible elements
(not just full-width ones, elements with uniform cells to their sides).
This is known to cause flickering with elements that are not full-width,
however, it is more optimal for terminal rendering.

fastCSR - Do CSR on any element within 20 cols of the screen edge on
either side. Faster than smartCSR, but may cause flickering depending on
what is on each side of the element.

useBCE - Attempt to perform back_color_erase optimizations for terminals
that support it. It will also work with terminals that don't support it, but
only on lines with the default background color. As it stands with the current
implementation, it's uncertain how much terminal performance this adds at the
cost of overhead within node.

resizeTimeout - Amount of time (in ms) to redraw the screen after the
terminal is resized (Default: 300).

tabSize - The width of tabs within an element's content.

autoPadding - Automatically position child elements with border and
padding in mind (NOTE: this is a recommended option. It may become
default in the future).

dump - Dump all output and input to desired file. Can be used together
with log option if set as a boolean.

debug - Debug mode. Enables usage of the debug method. Also creates a
debug console which will display when pressing F12. It will display all log
and debug messages.

ignoreLocked - Array of keys in their full format (e.g. C-c) to ignore
when keys are locked or grabbed. Useful for creating a key that will always
exit no matter whether the keys are locked.

dockBorders - Automatically "dock" borders with other elements instead of
overlapping, depending on position (experimental). For example:
These border-overlapped elements:

┌─────────┌─────────┐

│ box1 │ box2 │

└─────────└─────────┘

Become:

┌─────────┬─────────┐

│ box1 │ box2 │

└─────────┴─────────┘

ignoreDockContrast - Normally, dockable borders will not dock if the
colors or attributes are different. This option will allow them to dock
regardless. It may produce some odd looking multi-colored borders though.

fullUnicode - Allow for rendering of East Asian double-width characters,
utf-16 surrogate pairs, and unicode combining characters. This allows you to
display text above the basic multilingual plane. This is behind an option
because it may affect performance slightly negatively. Without this option
enabled, all double-width, surrogate pair, and combining characters will be
replaced by '??', '?', '' respectively. (NOTE: iTerm2 cannot display
combining characters properly. Blessed simply removes them from an element's
content if iTerm2 is detected).

sendFocus - Send focus events after mouse is enabled.

warnings - Display warnings (such as the output not being a TTY, similar
to ncurses).

forceUnicode - Force blessed to use unicode even if it is not detected
via terminfo, env variables, or windows code page.

padding - Amount of padding on the inside of the element. Can be a number
or an object containing the properties: left, right, top, and bottom.

width, height - Width/height of the element, can be a number, percentage
(0-100%), or keyword (half or shrink). Percentages can also have
offsets (50%+1, 50%-1).

left, right, top, bottom - Offsets of the element relative to its
parent. Can be a number, percentage (0-100%), or keyword (center).
right and bottom do not accept keywords. Percentages can also have
offsets (50%+1, 50%-1).

onScreenEvent(type, handler) - Same asel.on('screen', ...) except this
will automatically keep track of which listeners are bound to the screen
object. For use with removeScreenEvent(), free(), and destroy().

removeScreenEvent(type, handler) - Same asel.removeListener('screen', ...) except this will automatically keep track of which listeners are bound
to the screen object. For use with onScreenEvent(), free(), and
destroy().

free() - Free up the element. Automatically unbind all events that may
have been bound to the screen object. This prevents memory leaks. For use
with onScreenEvent(), removeScreenEvent(), and destroy().

destroy() - Same as the detach() method, except this will automatically
call free() and unbind any screen events to prevent memory leaks. for use
with onScreenEvent(), removeScreenEvent(), and free().

setIndex(z) - Set the z-index of the element (changes rendering order).

setFront() - Put the element in front of its siblings.

setBack() - Put the element in back of its siblings.

setLabel(text/options) - Set the label text for the top-left corner.
Example options: {text:'foo',side:'left'}

removeLabel() - Remove the label completely.

setHover(text/options) - Set a hover text box to follow the cursor.
Similar to the "title" DOM attribute in the browser.
Example options: {text:'foo'}

removeHover() - Remove the hover label completely.

enableMouse() - Enable mouse events for the element (automatically called
when a form of on('mouse') is bound).

enableKeys() - Enable keypress events for the element (automatically
called when a form of on('keypress') is bound).

Methods for dealing with text content, line by line. Useful for writing a
text editor, irc client, etc.

Note: All of these methods deal with pre-aligned, pre-wrapped text. If you use
deleteTop() on a box with a wrapped line at the top, it may remove 3-4 "real"
lines (rows) depending on how long the original line was.

The lines parameter can be a string or an array of strings. The line
parameter must be a string.

setContent(text) - Set the content. Note: When text is input, it will be
stripped of all non-SGR escape codes, tabs will be replaced with 8 spaces,
and tags will be replaced with SGR codes (if enabled).

search - A function that is called when vi mode is enabled and the key
/ is pressed. This function accepts a callback function which should be
called with the search string. The search string is then used to jump to an
item that is found in items.

interactive - Whether the list is interactive and can have items selected
(Default: true).

A box which spins up a pseudo terminal and renders the output. Useful for
writing a terminal multiplexer, or something similar to an mc-like file
manager. Requires term.js and pty.js to be installed. See
example/multiplex.js for an example terminal multiplexer.

Convert any .png file (or .gif, see below) to an ANSI image and display it
as an element. This differs from the OverlayImage element in that it uses
blessed's internal PNG/GIF parser and does not require external dependencies.

The blessed PNG reader supports adam7 deinterlacing, animation (APNG), all
color types, bit depths 1-32, alpha, alpha palettes, and outputs scaled bitmaps
(cellmaps) in blessed for efficient rendering to the screen buffer. It also
uses some code from libcaca/libcucul to add density ASCII characters in order
to give the image more detail in the terminal.

If a corrupt PNG or a non-PNG is passed in, blessed will display error text in
the element.

.gif files are also supported via a javascript implementation (they are
internally converted to bitmaps and fed to the PNG renderer). Any other image
format is support only if the user has imagemagick (convert and identify)
installed.

scale - Scale cellmap down (0-1.0) from its original pixel width/height
(Default: 1.0).

width/height - This differs from other element's width or height in
that only one of them is needed: blessed will maintain the aspect ratio of
the image as it scales down to the proper number of cells. NOTE: PNG/GIF's
are always automatically shrunken to size (based on scale) if a width or
height is not given.

ascii - Add various "density" ASCII characters over the rendering to give
the image more detail, similar to libcaca/libcucul (the library mplayer uses
to display videos in the terminal).

animate - Whether to animate if the image is an APNG/animating GIF. If
false, only display the first frame or IDAT (Default: true).

speed - Set the speed of animation. Slower: 0.0-1.0. Faster: 1-1000.
It cannot go faster than 1 frame per millisecond, so 1000 is the fastest.
(Default: 1.0)

optimization - mem or cpu. If optimizing for memory, animation frames
will be rendered to bitmaps as the animation plays, using less memory.
Optimizing for cpu will precompile all bitmaps beforehand, which may be
faster, but might also OOM the process on large images. (Default: mem).

renderer - A callback which is called right before the children are
iterated over to be rendered. Should return an iterator callback which is
called on each child element: __iterator(el, i)__.

layout - Using the default renderer, it provides two layouts: inline, and
grid. inline is the default and will render akin to inline-block. grid
will create an automatic grid based on element dimensions. The grid cells'
width and height are always determined by the largest children in the layout.

renderer(coords) - A callback which is called right before the children
are iterated over to be rendered. Should return an iterator callback which is
called on each child element: __iterator(el, i)__.

isRendered(el) - Check to see if a previous child element has been
rendered and is visible on screen. This is only useful for checking child
elements that have already been attempted to be rendered! see the example
below.

getLast(i) - Get the last rendered and visible child element based on an
index. This is useful for basing the position of the current child element on
the position of the last child element.

getLastCoords(i) - Get the last rendered and visible child element coords
based on an index. This is useful for basing the position of the current
child element on the position of the last child element. See the example
below.

You must always give Layout a width and height. This is a chicken-and-egg
problem: blessed cannot calculate the width and height dynamically before the
children are positioned.

border and padding are already calculated into the coords object the
renderer receives, so there is no need to account for it in your renderer.

Try to set position for children using el.position. el.position is the most
primitive "to-be-rendered" way to set coordinates. Setting el.left directly
has more dynamic behavior which may interfere with rendering.

Some definitions for coords (otherwise known as el.lpos):

coords.xi - the absolute x coordinate of the left side of a rendered
element. It is absolute: relative to the screen itself.

coords.xl - the absolute x coordinate of the right side of a rendered
element. It is absolute: relative to the screen itself.

coords.yi - the absolute y coordinate of the top side of a rendered
element. It is absolute: relative to the screen itself.

coords.yl - the absolute y coordinate of the bottom side of a rendered
element. It is absolute: relative to the screen itself.

Note again: the coords the renderer receives for the Layout already has
border and padding subtracted, so you do not have to account for these. The
children do not.

Here is an example of how to provide a renderer. Note that this is also the
default renderer if none is provided. This renderer will render each child as
though they were display: inline-block; in CSS, as if there were a
dynamically sized horizontal grid from left to right.

var layout = blessed.layout({

parent:screen,

top:'center',

left:'center',

width:'50%',

height:'50%',

border:'line',

style:{

bg:'red',

border:{

fg:'blue'

}

},

// NOTE: This is already the default renderer if none is provided!

renderer: function(coords){

var self =this;

// The coordinates of the layout element

var width = coords.xl - coords.xi

, height = coords.yl - coords.yi

, xi = coords.xi

, xl = coords.xl

, yi = coords.yi

, yl = coords.yl;

// The current row offset in cells (which row are we on?)

var rowOffset =0;

// The index of the first child in the row

var rowIndex =0;

returnfunctioniterator(el, i){

// Make our children shrinkable. If they don't have a height, for

// example, calculate it for them.

el.shrink =true;

// Find the previous rendered child's coordinates

var last = self.getLastCoords(i);

// If there is no previously rendered element, we are on the first child.

if(!last){

el.position.left=0;

el.position.top=0;

}else{

// Otherwise, figure out where to place this child. We'll start by

// setting it's `left`/`x` coordinate to right after the previous

// rendered element. This child will end up directly to the right of it.

el.position.left= last.xl - xi;

// If our child does not overlap the right side of the Layout, set it's

// `top`/`y` to the current `rowOffset` (the coordinate for the current

Content can also handle SGR escape codes. This means if you got output from a
program, say git log for example, you can feed it directly to an element's
content and the colors will be parsed appropriately.

This means that while {red-fg}foo{/red-fg} produces ^[[31mfoo^[[39m, you
could just feed ^[[31mfoo^[[39m directly to the content.

Colors can be the names of any of the 16 basic terminal colors, along with hex
values (e.g. #ff0000) for 256 color terminals. If 256 or 88 colors is not
supported. Blessed with reduce the color to whatever is available.

Blessed can set the opacity of an element to 50% using style.transparent = true;. While this seems like it normally shouldn't be possible in a terminal,
blessed will use a color blending algorithm to blend the element of the
foremost element with the background behind it. Obviously characters cannot be
blended, but background colors can.

Elements are rendered with the lower elements in the children array being
painted first. In terms of the painter's algorithm, the lowest indicies in the
array are the furthest away, just like in the DOM.

Terminal cursors can be tricky. They all have different custom escape codes to
alter. As an experimental alternative, blessed can draw a cursor for you,
allowing you to have a custom cursor that you control.