mirror of
https://github.com/gdamore/tcell.git
synced 2025-04-24 13:48:51 +08:00
Convert to asciidoctor, add more support details, incl. Tidelift.
This commit is contained in:
Garrett D'Amore
parent
8e3efba094
commit
483884f06f
270
README.adoc
Normal file
270
README.adoc
Normal file
@ -0,0 +1,270 @@
|
|||||||
|
= tcell
|
||||||
|
|
||||||
|
|
||||||
|
image:https://img.shields.io/travis/gdamore/tcell.svg?label=linux[Linux Status,link="https://travis-ci.org/gdamore/tcell"]
|
||||||
|
image:https://img.shields.io/appveyor/ci/gdamore/tcell.svg?label=windows[Windows Status,link="https://ci.appveyor.com/project/gdamore/tcell"]
|
||||||
|
image:https://img.shields.io/badge/license-APACHE2-blue.svg[Apache License,link="https://github.com/gdamore/tcell/blob/master/LICENSE"]
|
||||||
|
image:https://img.shields.io/badge/gitter-join-brightgreen.svg[Gitter,link="https://gitter.im/gdamore/tcell"]
|
||||||
|
image:https://img.shields.io/badge/godoc-reference-blue.svg[GoDoc,link="https://godoc.org/github.com/gdamore/tcell"]
|
||||||
|
image:http://goreportcard.com/badge/gdamore/tcell[Go Report Card,link="http://goreportcard.com/report/gdamore/tcell"]
|
||||||
|
image:https://codecov.io/gh/gdamore/tcell/branch/master/graph/badge.svg[codecov,link="https://codecov.io/gh/gdamore/tcell"]
|
||||||
|
image:https://tidelift.com/badges/github/gdamore/tcell?style=flat[Dependencies]
|
||||||
|
|
||||||
|
[cols="2",grid="none"]
|
||||||
|
|===
|
||||||
|
|_Tcell_ is a _Go_ package that provides a cell based view for text terminals, like _xterm_.
|
||||||
|
It was inspired by _termbox_, but includes many additional improvements.
|
||||||
|
a|[.right]
|
||||||
|
image::logos/tcell.png[float="right"]
|
||||||
|
|===
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
* https://github.com/gdamore/proxima5[proxima5] - space shooter (https://youtu.be/jNxKTCmY_bQ[video])
|
||||||
|
* https://github.com/gdamore/govisor[govisor] - service management UI (http://2.bp.blogspot.com/--OsvnfzSNow/Vf7aqMw3zXI/AAAAAAAAARo/uOMtOvw4Sbg/s1600/Screen%2BShot%2B2015-09-20%2Bat%2B9.08.41%2BAM.png[screenshot])
|
||||||
|
* mouse demo - included mouse test (http://2.bp.blogspot.com/-fWvW5opT0es/VhIdItdKqJI/AAAAAAAAATE/7Ojc0L1SpB0/s1600/Screen%2BShot%2B2015-10-04%2Bat%2B11.47.13%2BPM.png[screenshot])
|
||||||
|
* https://github.com/gdamore/gomatrix[gomatrix] - converted from Termbox
|
||||||
|
* https://github.com/zyedidia/micro/[micro] - lightweight text editor with syntax-highlighting and themes
|
||||||
|
* https://github.com/viktomas/godu[godu] - simple golang utility helping to discover large files/folders.
|
||||||
|
* https://github.com/rivo/tview[tview] - rich interactive widgets for terminal UIs
|
||||||
|
* https://github.com/marcusolsson/tui-go[tui-go] - UI library for terminal apps
|
||||||
|
* https://github.com/rgm3/gomandelbrot[gomandelbrot] - Mandelbrot!
|
||||||
|
* https://github.com/senorprogrammer/wtf[WTF]- Personal information dashboard for your terminal
|
||||||
|
* https://github.com/browsh-org/browsh[browsh] - A fully-modern text-based browser, rendering to TTY and browsers (https://www.youtube.com/watch?v=HZq86XfBoRo[video])
|
||||||
|
* https://github.com/sachaos/go-life[go-life] - Conway's Game of Life.
|
||||||
|
|
||||||
|
## Pure Go Terminfo Database
|
||||||
|
|
||||||
|
_Tcell_ 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.
|
||||||
|
|
||||||
|
The database is also flexible & extensible, and can modified by either running
|
||||||
|
a program to build the entire database, or an entry for just a single terminal.
|
||||||
|
|
||||||
|
## More Portable
|
||||||
|
|
||||||
|
_Tcell_ is portable to a wide variety of systems.
|
||||||
|
_Tcell_ is believed
|
||||||
|
to work with all of the systems officially supported by golang with
|
||||||
|
the exception of nacl (which lacks any kind of a terminal interface).
|
||||||
|
(Plan9 is not supported by _Tcell_, but it is experimental status only
|
||||||
|
in golang.) For all of these systems *except Solaris/illumos*, _Tcell_
|
||||||
|
is pure Go, with no need for CGO.
|
||||||
|
|
||||||
|
## No Async IO
|
||||||
|
|
||||||
|
_Tcell_ is able to operate without requiring `SIGIO` signals (unlike _termbox_),
|
||||||
|
or asynchronous I/O, and can instead use standard Go file
|
||||||
|
objects and Go routines.
|
||||||
|
This means it should be safe, especially for
|
||||||
|
use with programs that use exec, or otherwise need to manipulate the
|
||||||
|
tty streams.
|
||||||
|
This model is also much closer to idiomatic Go, leading
|
||||||
|
to fewer surprises.
|
||||||
|
|
||||||
|
## Rich Unicode & non-Unicode support
|
||||||
|
|
||||||
|
_Tcell_ includes enhanced support for Unicode, including wide characters and
|
||||||
|
combining characters, provided your terminal can support them.
|
||||||
|
Note that
|
||||||
|
Windows terminals generally don't support the full Unicode repertoire.
|
||||||
|
|
||||||
|
It will also convert to and from Unicode locales, so that the program
|
||||||
|
can work with UTF-8 internally, and get reasonable output in other locales.
|
||||||
|
_Tcell_ tries hard to convert to native characters on both input and output, and
|
||||||
|
on output _Tcell_ even makes use of the alternate character set to facilitate
|
||||||
|
drawing certain characters.
|
||||||
|
|
||||||
|
## More Function Keys
|
||||||
|
|
||||||
|
_Tcell_ also has richer support for a larger number of special keys that some terminals can send.
|
||||||
|
|
||||||
|
## Better Color Handling
|
||||||
|
|
||||||
|
_Tcell_ 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, _Tcell_ supports 16 colors, bold, dim, and reverse,
|
||||||
|
instead of just termbox's 8 colors with reverse. (Note that there is some
|
||||||
|
conflation with bold/dim and colors.)
|
||||||
|
|
||||||
|
_Tcell_ maps 16 colors down to 8, for terminals that need it.
|
||||||
|
(The upper 8 colors are just brighter versions of the lower 8.)
|
||||||
|
|
||||||
|
## Better Mouse Support
|
||||||
|
|
||||||
|
_Tcell_ supports enhanced mouse tracking mode, so your application can receive
|
||||||
|
regular mouse motion events, and wheel events, if your terminal supports it.
|
||||||
|
|
||||||
|
## _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
|
||||||
|
|
||||||
|
Internally Tcell uses UTF-8, just like Go.
|
||||||
|
However, Tcell understands how to
|
||||||
|
convert to and from other character sets, using the capabilities of
|
||||||
|
the `golang.org/x/text/encoding packages`.
|
||||||
|
Your application must supply
|
||||||
|
them, as the full set of the most common ones bloats the program by about 2MB.
|
||||||
|
If you're lazy, and want them all anyway, see the `encoding` sub-directory.
|
||||||
|
|
||||||
|
## Wide & Combining Characters
|
||||||
|
|
||||||
|
The `SetContent()` API takes a primary rune, and an optional list of combining runes.
|
||||||
|
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 wide character
|
||||||
|
is displayed, and the other character is not; do not depend on that behavior.)
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Colors
|
||||||
|
|
||||||
|
_Tcell_ assumes 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.
|
||||||
|
|
||||||
|
## 24-bit Color
|
||||||
|
|
||||||
|
_Tcell_ _supports true color_! (That is, if your terminal can support it,
|
||||||
|
_Tcell_ can accurately display 24-bit color.)
|
||||||
|
|
||||||
|
To use 24-bit color, you need to use a terminal that supports it. Modern
|
||||||
|
xterm and similar teminal emulators can support this. As terminfo lacks any
|
||||||
|
way to describe this capability, we fabricate the capability for
|
||||||
|
terminals with names ending in `*-truecolor`. The stock distribution ships
|
||||||
|
with a database that defines `xterm-truecolor`.
|
||||||
|
To try it out, set your
|
||||||
|
`TERM` variable to `xterm-truecolor`.
|
||||||
|
|
||||||
|
When using TrueColor, programs will display the colors that the programmer
|
||||||
|
intended, overriding any "`themes`" you may have set in your terminal
|
||||||
|
emulator. (For some cases, accurate color fidelity is more important
|
||||||
|
than respecting themes. For other cases, such as typical text apps that
|
||||||
|
only use a few colors, its more desirable to respect the themes that
|
||||||
|
the user has established.)
|
||||||
|
|
||||||
|
If you find this undesirable, you can either use a `TERM` variable
|
||||||
|
that lacks the `TRUECOLOR` setting, or set `TCELL_TRUECOLOR=disable` in your
|
||||||
|
environment.
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
Reasonable attempts have been made to minimize sending data to terminals,
|
||||||
|
avoiding repeated sequences or drawing the same cell on refresh updates.
|
||||||
|
|
||||||
|
## Terminfo
|
||||||
|
|
||||||
|
(Not relevent for Windows users.)
|
||||||
|
|
||||||
|
The Terminfo implementation operates with two forms of database. The first
|
||||||
|
is the built-in go database, 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 in the form of JSON files, that contain the same information,
|
||||||
|
which can be located either by the `$TCELLDB` environment file, `$HOME/.tcelldb`,
|
||||||
|
or is located in the Go source directory as `database.json`.
|
||||||
|
|
||||||
|
These files (both the Go and the JSON files) 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 infocmp(1) program on
|
||||||
|
the system to collect the necessary information.
|
||||||
|
|
||||||
|
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 wheel buttons on various terminals are known to work, but the support
|
||||||
|
in terminal emulators, as well as support for various buttons and
|
||||||
|
live mouse tracking, varies widely. Modern _xterm_, macOS _Terminal_, and _iTerm_ all work well.
|
||||||
|
|
||||||
|
## Testablity
|
||||||
|
|
||||||
|
There is a `SimulationScreen`, that can be used to simulate a real screen
|
||||||
|
for automated testing. The supplied tests do this. The simulation contains
|
||||||
|
event delivery, screen resizing support, and capabilities to inject events
|
||||||
|
and examine "`physical`" screen contents.
|
||||||
|
|
||||||
|
## Platforms
|
||||||
|
|
||||||
|
### POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
|
||||||
|
|
||||||
|
For mainstream systems with a suitably well defined system call interface
|
||||||
|
to tty settings, everything works using pure Go.
|
||||||
|
|
||||||
|
For the remainder (right now means only Solaris/illumos) we use POSIX function
|
||||||
|
calls to manage termios, which implies that CGO is required on those platforms.
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
|
||||||
|
Windows console mode applications are supported. Unfortunately _mintty_
|
||||||
|
and other _cygwin_ style applications are not supported.
|
||||||
|
|
||||||
|
Modern console applications like ConEmu, as well as the Windows 10
|
||||||
|
console itself, support all the good features (resize, mouse tracking, etc.)
|
||||||
|
|
||||||
|
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! Really, if you're
|
||||||
|
using a Windows application, you should use the native Windows console or a
|
||||||
|
fully compatible console implementation.
|
||||||
|
|
||||||
|
### Plan9 and Native Client (Nacl)
|
||||||
|
|
||||||
|
The nacl and plan9 platforms won't work, but compilation stubs are supplied
|
||||||
|
for folks that want to include parts of this in software targetting those
|
||||||
|
platforms. The Simulation screen works, but as Tcell doesn't know how to
|
||||||
|
allocate a real screen object on those platforms, `NewScreen()` will fail.
|
||||||
|
|
||||||
|
If anyone has wisdom about how to improve support for either of these,
|
||||||
|
please let me know. PRs are especially welcome.
|
||||||
|
|
||||||
|
### Commercial Support
|
||||||
|
|
||||||
|
_Tcell_ is absolutely free, but if you want to obtain commercial, professional support, there are options.
|
||||||
|
|
||||||
|
[cols="2",align="center"]
|
||||||
|
|===
|
||||||
|
^.^|
|
||||||
|
image:logos/tidelift.png[100,100]
|
||||||
|
a|
|
||||||
|
https://tidelift.com/[Tidelift] subscriptions include support for _Tcell_, as well as many other open source packages.
|
||||||
|
|
||||||
|
^.^|
|
||||||
|
image:logos/staysail.png[100,100]
|
||||||
|
a|
|
||||||
|
mailto:info@staysail.tech[Staysail Systems, Inc.] offers direct support, and custom development around _Tcell_ on an hourly basis.
|
||||||
|
|
||||||
|
^.^|
|
||||||
|
image:logos/patreon.png[100,100]
|
||||||
|
a|I also welcome donations at https://www.patron.com/gedamore/[Patreon], if you just want to make a contribution.
|
||||||
|
|===
|
||||||
256
README.md
256
README.md
@ -1,256 +0,0 @@
|
|||||||
## tcell <img src=tcell.png align=right>
|
|
||||||
|
|
||||||
[](https://travis-ci.org/gdamore/tcell)
|
|
||||||
[](https://ci.appveyor.com/project/gdamore/tcell)
|
|
||||||
[](https://github.com/gdamore/tcell/blob/master/LICENSE)
|
|
||||||
[](https://gitter.im/gdamore/tcell)
|
|
||||||
[](https://godoc.org/github.com/gdamore/tcell)
|
|
||||||
[](http://goreportcard.com/report/gdamore/tcell)
|
|
||||||
[](https://codecov.io/gh/gdamore/tcell)
|
|
||||||
|
|
||||||
|
|
||||||
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. It also adds substantial functionality beyond termbox.
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
* [proxima5](https://github.com/gdamore/proxima5) - space shooter ([video](https://youtu.be/jNxKTCmY_bQ))
|
|
||||||
* [govisor](https://github.com/gdamore/govisor) - service management UI ([screenshot](http://2.bp.blogspot.com/--OsvnfzSNow/Vf7aqMw3zXI/AAAAAAAAARo/uOMtOvw4Sbg/s1600/Screen%2BShot%2B2015-09-20%2Bat%2B9.08.41%2BAM.png))
|
|
||||||
* mouse demo - [screenshot](http://2.bp.blogspot.com/-fWvW5opT0es/VhIdItdKqJI/AAAAAAAAATE/7Ojc0L1SpB0/s1600/Screen%2BShot%2B2015-10-04%2Bat%2B11.47.13%2BPM.png) - included mouse test
|
|
||||||
* [gomatrix](https://github.com/gdamore/gomatrix) - converted from Termbox
|
|
||||||
* [micro](https://github.com/zyedidia/micro/) - lightweight text editor with syntax-highlighting and themes
|
|
||||||
* [godu](https://github.com/viktomas/godu) - simple golang utility helping to discover large files/folders.
|
|
||||||
* [tview](https://github.com/rivo/tview) - rich interactive widgets for terminal UIs
|
|
||||||
* [tui-go](https://github.com/marcusolsson/tui-go) - UI library for terminal apps
|
|
||||||
* [gomandelbrot](https://github.com/rgm3/gomandelbrot) - Mandelbrot!
|
|
||||||
* [WTF](https://github.com/senorprogrammer/wtf)- Personal information dashboard for your terminal
|
|
||||||
* [browsh](https://github.com/browsh-org/browsh) - A fully-modern text-based browser, rendering to TTY and browsers ([video](https://www.youtube.com/watch?v=HZq86XfBoRo))
|
|
||||||
* [go-life](https://github.com/sachaos/go-life) - Conway's Game of Life.
|
|
||||||
|
|
||||||
## Pure Go Terminfo Database
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
The database is also flexible & extensible, and can modified by either running
|
|
||||||
a program to build the entire database, or an entry for just a single terminal.
|
|
||||||
|
|
||||||
## More Portable
|
|
||||||
|
|
||||||
Tcell is portable to a wider variety of systems. Tcell is believed
|
|
||||||
to work with all of the systems officially supported by golang with
|
|
||||||
the exception of nacl (which lacks any kind of a terminal interface).
|
|
||||||
(Plan9 is not supported by Tcell, but it is experimental status only
|
|
||||||
in golang.) For all of these systems *except Solaris/illumos*, Tcell
|
|
||||||
is pure Go, with no need for CGO.
|
|
||||||
|
|
||||||
## No Async IO
|
|
||||||
|
|
||||||
Tcell is able to operate without requiring SIGIO signals (unlike Termbox),
|
|
||||||
or asynchronous I/O, and can instead use standard Go file
|
|
||||||
objects and Go routines. This means it should be safe, especially for
|
|
||||||
use with programs that use exec, or otherwise need to manipulate the
|
|
||||||
tty streams. This model is also much closer to idiomatic Go, leading
|
|
||||||
to fewer surprises.
|
|
||||||
|
|
||||||
## Richer Unicode & non-Unicode support
|
|
||||||
|
|
||||||
Tcell includes enhanced support for Unicode, including wide characters and
|
|
||||||
combining characters, provided your terminal can support them. Note that
|
|
||||||
Windows terminals generally don't support the full Unicode repertoire.
|
|
||||||
|
|
||||||
It will also convert to and from Unicode locales, so that the program
|
|
||||||
can work with UTF-8 internally, and get reasonable output in other locales.
|
|
||||||
We try hard to convert to native characters on both input and output, and
|
|
||||||
on output Tcell even makes use of the alternate character set to facilitate
|
|
||||||
drawing certain characters.
|
|
||||||
|
|
||||||
## More Function Keys
|
|
||||||
|
|
||||||
It also has richer support for a larger number of special keys that some
|
|
||||||
terminals can send.
|
|
||||||
|
|
||||||
## Better Color Handling
|
|
||||||
|
|
||||||
Tcell 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, Tcell supports 16 colors, bold, dim, and reverse,
|
|
||||||
instead of just termbox's 8 colors with reverse. (Note that there is some
|
|
||||||
conflation with bold/dim and colors.)
|
|
||||||
|
|
||||||
Tcell maps 16 colors down to 8, for terminals that need it. (The upper
|
|
||||||
8 colors are just brighter versions of the lower 8.)
|
|
||||||
|
|
||||||
## Better Mouse Support
|
|
||||||
|
|
||||||
Tcell supports enhanced mouse tracking mode, so your application can receive
|
|
||||||
regular mouse motion events, and wheel events, if your terminal supports it.
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
Internally Tcell uses UTF-8, just like Go. However, Tcell understands how to
|
|
||||||
convert to and from other character sets, using the capabilities of
|
|
||||||
the golang.org/x/text/encoding packages. Your application must supply
|
|
||||||
them, as the full set of the most common ones bloats the program by about
|
|
||||||
2MB. If you're lazy, and want them all anyway, see the encoding
|
|
||||||
sub-directory.
|
|
||||||
|
|
||||||
## Wide & Combining Characters
|
|
||||||
|
|
||||||
The SetContent() API takes a primary rune, and an optional list of combining
|
|
||||||
runes. 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 wide character
|
|
||||||
is displayed, and the other character is not; do not depend on that behavior.)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Colors
|
|
||||||
|
|
||||||
Tcell assumes 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.
|
|
||||||
|
|
||||||
## 24-bit Color
|
|
||||||
|
|
||||||
Tcell _supports true color_! (That is, if your terminal can support it,
|
|
||||||
Tcell can accurately display 24-bit color.)
|
|
||||||
|
|
||||||
To use 24-bit color, you need to use a terminal that supports it. Modern
|
|
||||||
xterm and similar teminal emulators can support this. As terminfo lacks any
|
|
||||||
way to describe this capability, we fabricate the capability for
|
|
||||||
terminals with names ending in *-truecolor. The stock distribution ships
|
|
||||||
with a database that defines xterm-truecolor. To try it out, set your
|
|
||||||
TERM variable to xterm-truecolor.
|
|
||||||
|
|
||||||
When using TrueColor, programs will display the colors that the programmer
|
|
||||||
intended, overriding any "themes" you may have set in your terminal
|
|
||||||
emulator. (For some cases, accurate color fidelity is more important
|
|
||||||
than respecting themes. For other cases, such as typical text apps that
|
|
||||||
only use a few colors, its more desirable to respect the themes that
|
|
||||||
the user has established.)
|
|
||||||
|
|
||||||
If you find this undesirable, you can either use a TERM variable
|
|
||||||
that lacks the TRUECOLOR setting, or set TCELL_TRUECOLOR=disable in your
|
|
||||||
environment.
|
|
||||||
|
|
||||||
## Performance
|
|
||||||
|
|
||||||
Reasonable attempts have been made to minimize sending data to terminals,
|
|
||||||
avoiding repeated sequences or drawing the same cell on refresh updates.
|
|
||||||
|
|
||||||
## Terminfo
|
|
||||||
|
|
||||||
(Not relevent for Windows users.)
|
|
||||||
|
|
||||||
The Terminfo implementation operates with two forms of database. The first
|
|
||||||
is the built-in go database, 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 in the form of JSON files, that contain the same information,
|
|
||||||
which can be located either by the $TCELLDB environment file, $HOME/.tcelldb,
|
|
||||||
or is located in the Go source directory as database.json.
|
|
||||||
|
|
||||||
These files (both the Go and the JSON files) 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 infocmp(1) program on
|
|
||||||
the system to collect the necessary information.
|
|
||||||
|
|
||||||
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 wheel buttons on various terminals are known to work, but the support
|
|
||||||
in terminal emulators, as well as support for various buttons and
|
|
||||||
live mouse tracking, varies widely. As a particular datum, MacOS X Terminal
|
|
||||||
does not support Mouse events at all (as of MacOS 10.10, aka Yosemite.) The
|
|
||||||
excellent iTerm application is fully supported, as is vanilla XTerm.
|
|
||||||
|
|
||||||
Mouse tracking with live tracking also varies widely. Current XTerm
|
|
||||||
implementations, as well as current Screen and iTerm2, and Windows
|
|
||||||
consoles, all support this quite nicely. On other platforms you might
|
|
||||||
find that only mouse click and release events are reported, with
|
|
||||||
no intervening motion events. It really depends on your terminal.
|
|
||||||
|
|
||||||
## Testablity
|
|
||||||
|
|
||||||
There is a SimulationScreen, that can be used to simulate a real screen
|
|
||||||
for automated testing. The supplied tests do this. The simulation contains
|
|
||||||
event delivery, screen resizing support, and capabilities to inject events
|
|
||||||
and examine "physical" screen contents.
|
|
||||||
|
|
||||||
## Platforms
|
|
||||||
|
|
||||||
### POSIX (Linux, FreeBSD, MacOS, Solaris, etc.)
|
|
||||||
|
|
||||||
For mainstream systems with a suitably well defined system call interface
|
|
||||||
to tty settings, everything works using pure Go.
|
|
||||||
|
|
||||||
For the remainder (right now means only Solaris/illumos) we use POSIX function
|
|
||||||
calls to manage termios, which implies that CGO is required on those platforms.
|
|
||||||
|
|
||||||
### Windows
|
|
||||||
|
|
||||||
Windows console mode applications are supported. Unfortunately mintty
|
|
||||||
and other cygwin style applications are not supported.
|
|
||||||
|
|
||||||
Modern console applications like ConEmu, as well as the Windows 10
|
|
||||||
console itself, support all the good features (resize, mouse tracking, etc.)
|
|
||||||
|
|
||||||
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! Really, if you're
|
|
||||||
using a Windows application, you should use the native Windows console or a
|
|
||||||
fully compatible console implementation.
|
|
||||||
|
|
||||||
### Plan9 and Native Client (Nacl)
|
|
||||||
|
|
||||||
The nacl and plan9 platforms won't work, but compilation stubs are supplied
|
|
||||||
for folks that want to include parts of this in software targetting those
|
|
||||||
platforms. The Simulation screen works, but as Tcell doesn't know how to
|
|
||||||
allocate a real screen object on those platforms, NewScreen() will fail.
|
|
||||||
|
|
||||||
If anyone has wisdom about how to improve support for either of these,
|
|
||||||
please let me know. PRs are especially welcome.
|
|
||||||
|
|
||||||
### Commercial Support
|
|
||||||
|
|
||||||
This software is absolutely free, but if you want to obtain commercial
|
|
||||||
support (giving prioritized access to the developer, etc. on an hourly
|
|
||||||
rate), please drop a line to info@staysail.tech
|
|
||||||
|
|
||||||
I also welcome donations at Patreon, if you just want to feel good about
|
|
||||||
defraying development costs: https://www.patreon.com/gedamore
|
|
||||||
BIN
logos/patreon.png
Normal file
BIN
logos/patreon.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.9 KiB |
BIN
logos/staysail.png
Normal file
BIN
logos/staysail.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
|
Before Width: | Height: | Size: 5.2 KiB After Width: | Height: | Size: 5.2 KiB |
BIN
logos/tidelift.png
Normal file
BIN
logos/tidelift.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.3 KiB |
93
tcell.svg
93
tcell.svg
@ -1,93 +0,0 @@
|
|||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<svg
|
|
||||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
|
||||||
xmlns:cc="http://creativecommons.org/ns#"
|
|
||||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
|
||||||
xmlns:svg="http://www.w3.org/2000/svg"
|
|
||||||
xmlns="http://www.w3.org/2000/svg"
|
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
||||||
id="svg8"
|
|
||||||
version="1.1"
|
|
||||||
viewBox="0 0 210 297"
|
|
||||||
height="297mm"
|
|
||||||
width="210mm">
|
|
||||||
<defs
|
|
||||||
id="defs2">
|
|
||||||
<linearGradient
|
|
||||||
id="linearGradient2680">
|
|
||||||
<stop
|
|
||||||
id="stop2676"
|
|
||||||
offset="0"
|
|
||||||
style="stop-color:#ababab;stop-opacity:1;" />
|
|
||||||
<stop
|
|
||||||
id="stop2678"
|
|
||||||
offset="1"
|
|
||||||
style="stop-color:#ababab;stop-opacity:0;" />
|
|
||||||
</linearGradient>
|
|
||||||
<marker
|
|
||||||
style="overflow:visible"
|
|
||||||
id="Arrow1Lstart"
|
|
||||||
refX="0.0"
|
|
||||||
refY="0.0"
|
|
||||||
orient="auto">
|
|
||||||
<path
|
|
||||||
transform="scale(0.8) translate(12.5,0)"
|
|
||||||
style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt"
|
|
||||||
d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
|
|
||||||
id="path848" />
|
|
||||||
</marker>
|
|
||||||
<radialGradient
|
|
||||||
gradientUnits="userSpaceOnUse"
|
|
||||||
gradientTransform="matrix(1,0,0,0.28804762,0,94.764912)"
|
|
||||||
r="19.622099"
|
|
||||||
fy="133.10568"
|
|
||||||
fx="111.58373"
|
|
||||||
cy="133.10568"
|
|
||||||
cx="111.58373"
|
|
||||||
id="radialGradient2684"
|
|
||||||
xlink:href="#linearGradient2680" />
|
|
||||||
</defs>
|
|
||||||
<metadata
|
|
||||||
id="metadata5">
|
|
||||||
<rdf:RDF>
|
|
||||||
<cc:Work
|
|
||||||
rdf:about="">
|
|
||||||
<dc:format>image/svg+xml</dc:format>
|
|
||||||
<dc:type
|
|
||||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
|
||||||
<dc:title></dc:title>
|
|
||||||
</cc:Work>
|
|
||||||
</rdf:RDF>
|
|
||||||
</metadata>
|
|
||||||
<g
|
|
||||||
id="layer1">
|
|
||||||
<rect
|
|
||||||
y="99.44445"
|
|
||||||
x="31.750006"
|
|
||||||
height="86.430557"
|
|
||||||
width="129.64584"
|
|
||||||
id="rect1130"
|
|
||||||
style="opacity:1;fill:#5d6c53;fill-opacity:1;stroke:#244f24;stroke-width:10;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
|
|
||||||
<text
|
|
||||||
transform="scale(0.99941234,1.000588)"
|
|
||||||
id="text1128"
|
|
||||||
y="160.47581"
|
|
||||||
x="44.689861"
|
|
||||||
style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:46.0962944px;line-height:1.25;font-family:'Glass TTY VT220';-inkscape-font-specification:'Glass TTY VT220, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#5ef86d;fill-opacity:1;stroke:#59ff32;stroke-width:0.80994618;stroke-opacity:0.94520545;"
|
|
||||||
xml:space="preserve"><tspan
|
|
||||||
style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:46.0962944px;font-family:'Glass TTY VT220';-inkscape-font-specification:'Glass TTY VT220, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#5ef86d;fill-opacity:1;stroke:#59ff32;stroke-width:0.80994618;stroke-opacity:0.94520545;"
|
|
||||||
y="160.47581"
|
|
||||||
x="44.689861"
|
|
||||||
id="tspan1126">tcell</tspan></text>
|
|
||||||
<flowRoot
|
|
||||||
style="fill:black;fill-opacity:1;stroke:none;font-family:sans-serif;font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;letter-spacing:0px;word-spacing:0px"
|
|
||||||
id="flowRoot1132"
|
|
||||||
xml:space="preserve"><flowRegion
|
|
||||||
id="flowRegion1134"><rect
|
|
||||||
y="432.51968"
|
|
||||||
x="290"
|
|
||||||
height="160"
|
|
||||||
width="330"
|
|
||||||
id="rect1136" /></flowRegion><flowPara
|
|
||||||
id="flowPara1138"></flowPara></flowRoot> </g>
|
|
||||||
</svg>
|
|
||||||
|
Before Width: | Height: | Size: 3.7 KiB |
Loading…
x
Reference in New Issue
Block a user