mirror of
https://github.com/gdamore/tcell.git
synced 2025-04-27 13:48:50 +08:00
150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
## tcell
|
|
|
|
[](https://travis-ci.org/gdamore/tcell)
|
|
[](https://ci.appveyor.com/project/gdamore/tcell)
|
|
[](https://github.com/gdamore/tcell/blob/master/LICENSE)
|
|
[](https://github.com/gdamore/tcell/issues)
|
|
[](https://gitter.im/gdamore/tcell)
|
|
[](https://godoc.org/github.com/gdamore/tcell)
|
|
|
|
> _Tcell is a work in progress (Beta).
|
|
> Please use with caution; interfaces may change in before final release._
|
|
|
|
Package tcell provides a cell based view for text terminals, like xterm.
|
|
It was inspired by termbox, but differs from termbox in some important
|
|
ways.
|
|
|
|
First, it includes a full parser and expander for terminfo capability strings,
|
|
so that it can avoid hard coding escape strings for formatting. It also favors
|
|
portability, and includes support for all POSIX systems, at the slight expense
|
|
of needing cgo support for terminal initializations. (This will be corrected
|
|
when Go provides standard support for terminal handling via termio ioctls on
|
|
all POSIX platforms.)
|
|
|
|
Also, this code is able to operate without requiring
|
|
SIGIO signals, or asynchronous I/O, and can instead use standard Go file
|
|
objects and Go routines.
|
|
|
|
It also includes enhanced support for Unicode, include wide characters and
|
|
combining characters. It also has richer support for a larger number of
|
|
special keys that some terminals can send.
|
|
|
|
It will respect your terminal's color space as specified within your terminfo
|
|
entries, so that for example attempts to emit color sequences on VT100 terminals
|
|
won't result in unintended consequences.
|
|
|
|
In Windows mode, we support 16 colors, underline, bold, dim, and reverse,
|
|
instead of just termbox's 8 colors with reverse. (Note that there is some
|
|
conflation with bold/dim and colors.)
|
|
|
|
I started this project originally by submitting patches to the author of
|
|
go-termbox, but due to some fundamental differences of opinion, I thought
|
|
it might be simpler just to start from scratch.
|
|
|
|
## Termbox compatibility
|
|
|
|
A compatibility layer for termbox is provided in the compat
|
|
directory. To use it, try importing "github.com/gdamore/tcell/termbox"
|
|
instead. Most termbox-go programs will probably work without further
|
|
modification.
|
|
|
|
## Working with Unicode
|
|
|
|
This version of the tcells expects that your terminal can support Unicode
|
|
on output. That is, if you submit Unicode sequences to it, it will attempt
|
|
send Unicode to the terminal. This works for modern xterm and other emulators,
|
|
but legacy systems may have poor results. I'm interested to hear reports from
|
|
folks who need support for other character sets.
|
|
|
|
## Wide & Combining Characters
|
|
|
|
The Setcell() API takes a sequence of runes; exactly least one of them should
|
|
be a non-zero width. Combining runes may follow. If any of the runes
|
|
is a wide (East Asian) rune occupying two cells, then the library will skip
|
|
output from the following cell, but care must be taken in the application to
|
|
avoid explicitly attempting to set content in the next cell, otherwise the
|
|
results are undefined. (Normally the wide character will not be displayed.)
|
|
|
|
Experience has shown that the vanilla Windows 8 console application does not
|
|
support any of these characters properly, but at least some options like
|
|
ConEmu do support Wide characters at least. Combining characters are
|
|
disabled for Windows in the release.
|
|
|
|
## Colors
|
|
|
|
We assume the ANSI/XTerm color model, including the 256 color map that
|
|
XTerm uses when it supports 256 colors. The terminfo guidance will be
|
|
honored, with respect to the number of colors supported. Also, only
|
|
terminals which expose ANSI style setaf and setab will support color;
|
|
if you have a color terminal that only has setf and setb, please let me
|
|
know; it wouldn't be hard to add that if there is need.
|
|
|
|
## Performance
|
|
|
|
Reasonable attempts have been made to minimize sending data to terminals,
|
|
avoiding repeated sequences or drawing the same cell on refresh updates.
|
|
|
|
Windows still needs some work here, as it can make numerous system calls
|
|
a bit less efficiently than it could.
|
|
|
|
## Terminfo
|
|
|
|
(Not relevent for Windows users.)
|
|
|
|
The Terminfo implementation operates with two forms of database. The first
|
|
is the database.go file, which contains a number of real database entries
|
|
that are compiled into the program directly. This should minimize calling
|
|
out to database file searches.
|
|
|
|
The second is a JSON file, that contains the same information, which can
|
|
be located either by the $TCELLDB environment file, or is located in the
|
|
Go source directory.
|
|
|
|
These files (both the Go database.go and the database.json) file can be
|
|
generated using the mkinfo.go program. If you need to regnerate the
|
|
entire set for some reason, run the mkdatabase.sh file. The generation
|
|
uses the terminfo routines on the system to populate the data files.
|
|
|
|
The mkinfo.go program can also be used to generate specific database entries
|
|
for named terminals, in case your favorite terminal is missing. (If you
|
|
find that this is the case, please let me know and I'll try to add it!)
|
|
|
|
Tcell requires that the terminal support the 'cup' mode of cursor addressing.
|
|
Terminals without absolute cursor addressability are not supported.
|
|
This is unlikely to be a problem; such terminals have not been mass produced
|
|
since the early 1970s.
|
|
|
|
## Mouse Support
|
|
|
|
Mouse support is detected via the "kmous" terminfo variable, however,
|
|
enablement/disablement and decoding mouse events is done using hard coded
|
|
sequences based on the XTerm X11 model. As of this writing all popular
|
|
terminals with mouse tracking support this model. (Full terminfo support
|
|
is not possible as terminfo sequences are not defined.)
|
|
|
|
On Windows, the mouse works normally.
|
|
|
|
Mouse wheels are unlikely to work, and I have made no effort to support them,
|
|
given the lack of portability across emulation packages.
|
|
|
|
Only button press and release events are reported at this time. In the
|
|
future we can easily add full tracking for Windows, and for "genuine" XTerm,
|
|
but most alternatives don't have support for the full mouse motion events.
|
|
|
|
## Platforms
|
|
|
|
On POSIX systems, a POSIX termios implementation with /dev/tty is required.
|
|
It also requires functional cgo to run. As of this writing, Cgo is available
|
|
on all POSIX Go 1.5 platforms.
|
|
|
|
Windows console mode applications are supported. Unfortunately mintty
|
|
and other cygwin style applications are not supported; modern console
|
|
applications like ConEmu support all the good features (resize, mouse, etc.)
|
|
The Windows version is a bit inefficient in its drawing, as it performs
|
|
a single WriteConsoleOutput call for each on screen cell that is changed,
|
|
but experimentally I wasn't able to notice the inefficiency.
|
|
|
|
I haven't figured out how to cleanly resolve the dichotomy between cygwin
|
|
style termios and the Windows Console API; it seems that perhaps nobody else
|
|
has either. If anyone has suggestions, let me know!
|