termdraw
v2.0.0
Published
Terminal drawing library
Downloads
4
Readme
termdraw
About
termdraw
is a library for creating TUI (terminal user interface) applications.
Installation
npm install termdraw
new Draw(opts)
The Draw
object is your portal to the terminal: through it, you can you learn
the terminal's dimensions, the user's keypresses, and redraw the cells when
needed. The Draw
object keeps track of the current state of each cell on the
screen for your program, and rewrites only the changed parts when you inform it
what you want the screen to look like.
Draw
will also emit the following events when the underlying
ANSITerm
fires them:
"resize"
, indicating that the terminal has been resized."keypress"
, indicating that a normal key has been typed"control"
, indicating that a control character (i.e.,^C
or^J
) has been typed."special"
, indicating that a special key (i.e.F1
or the left arrow key) has been typed.
See the node-ansiterm documentation for more details on these events.
Draw#close()
Restore the terminal to its state from before initializing Draw
. The consuming
application should make sure to call this before exiting, so that the users can
return to a normal terminal state.
Draw#bell()
Ring the terminal bell.
Draw#height()
Fetch the number of terminal rows.
Draw#width()
Fetch the number of terminal columns.
Draw#redraw(screen, refresh)
Redraw the terminal to match screen
. Normally Draw
uses its knowledge about
the expected cell states to efficiently redraw the terminal, but messages
written to stdout
or stderr
(by misbehaving libraries or child processes)
may cause display issues. In this case, the optional boolean refresh
can be
passed to force a full redraw of the screen. Some applications may wish to bind
this behaviour to ^L
.
Draw#pause(screen, action)
Tear down the current TUI state, and call the function action(cb)
. The
action
function can then do whatever activity it needs to perform (e.g., run
a shell). Once finished, it should call cb
, which will take care of redrawing
screen
, and reenabling the Draw
instance.
Draw#suspend(screen)
Suspend the current process, and, once it resumes, do a full redraw of screen
.
Some applications may wish to find this behaviour to ^Z
.
new Region(opts)
A Region
represents a grid of cells and their configured states.
Region#height()
Fetch the number of rows contained within this Region
.
Region#width()
Fetch the number of columns contained within this Region
.
Region#resize(w, h)
Resizes this Region
to be w
columns wide, and h
rows tall. Once the region
has been resized, the "resize"
event will be emitted, allowing an opportunity
to write into newly introduced cells (after growing) or to account for truncated
cells (after shrinking).
If the size hasn't changed at all, then nothing is done and the "resize"
event
is not fired.
Region#clear()
Reset all of the cells within this Region
to their default, empty state.
Region#get_cell(x, y)
Gets the Cell
offset horizontally by x
and vertically by y
within
this Region
. If the offset lies outside of the Region
, then this
method returns null.
Region#get_cursor()
Draw#redraw()
uses this method to determine where to place the terminal
cursor after it has finished updating the terminal. If the cursor should be
drawn, then this method returns an object containing "x"
and "y"
. If this
method returns null
, then a cursor will not be drawn within the Region
.
Region#chr(x, y, ch, format)
Updates the cell at (x, y) to contain the character ch
. The optional
format
argument specifies how the cell should be formatted.
This method returns how many columns the written character will occupy within
the Region
. For many characters, this will just be 1
. When writing wide
characters though (e.g. CJK characters and emoji), this will be 2
. When
writing to coordinates outside of the Region
, this will return 0
.
Region#str(x, y, str, format)
Writes the characters in str
horizontally start at position (x, y). format
specifies attributes for each of the cells that the characters are written to.
This method returns how many columns the string will occupy within the Region
.
Region#vstr(x, y, str, format)
Writes the characters in str
vertically start at position (x, y). format
specifies attributes for each of the cells that the characters are written to.
This method returns how many rows the string occupies within the Region
.
Controls
Several basic extensions of Region
are available.
new Box(opts)
The Box
class draws a border with an optional title around a child Region
.
Available options are:
"child"
, optionally specify the Region to be contained in the box"title"
, the title to show inside the top border
Box#set_child(region)
Change the child Region
of this box.
Box#set_title(title)
Set a new title for this box.
new ContentBox(opts)
Creates a Region
that will try to display as much of a given string as it
can, with no wrapping. This can be useful when you wish to display a static
string on the screen, but don't want to write any resizing logic to display
more of the string when space becomes available. Available options are:
"content"
, the content to display in this region"format"
, how to format the content
ContentBox#set_content(content)
Updates the content displayed in this region.
ContentBox#set_format(content)
Updates the formatting of the content displayed in this region.
new FillBox(options)
Creates a Region
full of cells all displaying the same character. Available options are:
"character"
, the character to display (defaults to" "
)"format"
, optional formatting to apply to the cells
FillBox#set_character(character)
Sets a new character to display.
FillBox#set_format(format)
Applies a new format to all of the cells.
new LogBox()
The LogBox
class allows you to display and scroll through a series of lines.
LogBox#add(line)
Adds a new line to the box.
LogBox#moveto(pos)
Given one of "top"
or "bottom"
, scroll to the top or bottom of the log
respectively.
LogBox#offset(n)
Scrolls the view n
lines down (when positive) or up (when negative).
new HLayout(opts)
/ new VLayout(opts)
The HLayout
and VLayout
classes allows you to stack multiple Region
objects alongside each other. Available options are:
"border"
, will draw a border around each contained region"bold"
, will draw a bolder border"children"
, an initial collection of children for this layout; available options are:"child"
, the childRegion
to display"label"
, a title forLayout
to draw in the top border."weight"
, how many rows thisRegion
should be allocated proportional to the others."fixed"
, indicates that thisRegion
should be given a fixed, maximum height or width (forHLayout
andVLayout
respectively). Takes precedence over any specified"weight"
.
*Layout#set_children(children)
Given an array of children
configurations (specified the same way as the
constructor's "children"
option), replace all of the current child regions.
*Layout#push(child, [opts])
Add a new child Region
to the end of this Layout
. Possible options are the
same as those for "children"
.
*Layout#unshift(child, [opts])
Add a new child Region
to the beginning of this Layout
. Possible options
are the same as those for "children"
.
*Layout#pop()
Remove the last child Region
.
*Layout#shift()
Remove the first child Region
.
*Layout#splice(start[, deleteCount[, [child1[, child2[, ...]]]]])
This method behaves like Array#splice()
, allowing consumers to remove
children, and possibly replace them with new ones.
Examples
- examples/loading.js: This example shows how to create a simple, animated splash screen.
- examples/menu.js: This example shows how to create a program with an interactive menu.
- examples/scrolling.js: This example shows how to use the
LogBox
. - examples/textbox.js: This example shows how to create a simple box for entering text.
- examples/commander.js: This example shows how to create an mc-like application.
- examples/unicode.js: This example demonstrates the behaviour of multi-column and multi-byte characters.
License
ISC