2022-04-24 01:31:32 +08:00
< img src = "logos/tcell.png" style = "float: right" / >
2018-10-24 21:25:47 +08:00
2022-04-24 01:31:32 +08:00
# Tcell
2021-07-18 02:04:43 +08:00
_Tcell_ is a _Go_ package that provides a cell based view for text terminals, like _XTerm_ .
2018-10-24 21:25:47 +08:00
It was inspired by _termbox_ , but includes many additional improvements.
2021-07-18 02:04:43 +08:00
2022-08-20 23:50:19 +08:00
[](https://stand-with-ukraine.pp.ua)
2023-01-01 01:12:50 +08:00
[](https://github.com/gdamore/tcell/actions/workflows/linux.yml)
[](https://github.com/gdamore/tcell/actions/workflows/windows.yml)
2021-07-18 03:03:52 +08:00
[](https://github.com/gdamore/tcell/blob/master/LICENSE)
[](https://pkg.go.dev/github.com/gdamore/tcell/v2)
[](https://discord.gg/urTTxDN)
[](https://codecov.io/gh/gdamore/tcell)
2022-09-01 02:43:45 +08:00
[](https://goreportcard.com/report/github.com/gdamore/tcell/v2)
2018-10-24 21:25:47 +08:00
2022-08-20 23:51:58 +08:00
Please see [here ](UKRAINE.md ) for an important message for the people of Russia.
2023-01-01 01:12:50 +08:00
NOTE: This is version 2 of _Tcell_ . There are breaking changes relative to version 1.
2020-10-16 15:05:26 +08:00
Version 1.x remains available using the import `github.com/gdamore/tcell` .
2020-08-26 07:20:58 +08:00
2021-07-18 02:11:35 +08:00
## Tutorial
A brief, and still somewhat rough, [tutorial ](TUTORIAL.md ) is available.
2021-10-27 13:46:39 +08:00
2021-07-18 02:04:43 +08:00
## Examples
2023-01-01 01:12:50 +08:00
- [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 - included mouse test ([screenshot](http://2.bp.blogspot.com/-fWvW5opT0es/VhIdItdKqJI/AAAAAAAAATE/7Ojc0L1SpB0/s1600/Screen%2BShot%2B2015-10-04%2Bat%2B11.47.13%2BPM.png))
- [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 ) - utility to discover large files/folders
- [tview ](https://github.com/rivo/tview/ ) - rich interactive widgets
- [cview ](https://code.rocketnine.space/tslocum/cview ) - user interface toolkit (fork of _tview_ )
2024-08-23 03:13:53 +08:00
- [awesome gocui ](https://github.com/awesome-gocui/gocui ) - Go Console User Interface
2023-01-01 01:12:50 +08:00
- [gomandelbrot ](https://github.com/rgm3/gomandelbrot ) - Mandelbrot!
- [WTF ](https://github.com/senorprogrammer/wtf ) - personal information dashboard
- [browsh ](https://github.com/browsh-org/browsh ) - modern web browser ([video](https://www.youtube.com/watch?v=HZq86XfBoRo))
- [go-life ](https://github.com/sachaos/go-life ) - Conway's Game of Life
- [gowid ](https://github.com/gcla/gowid ) - compositional widgets for terminal UIs, inspired by _urwid_
- [termshark ](https://termshark.io ) - interface for _tshark_ , inspired by Wireshark, built on _gowid_
- [go-tetris ](https://github.com/MichaelS11/go-tetris ) - Go Tetris with AI option
- [fzf ](https://github.com/junegunn/fzf ) - command-line fuzzy finder
- [ascii-fluid ](https://github.com/esimov/ascii-fluid ) - fluid simulation controlled by webcam
- [cbind ](https://code.rocketnine.space/tslocum/cbind ) - key event encoding, decoding and handling
- [tpong ](https://github.com/spinzed/tpong ) - old-school Pong
- [aerc ](https://git.sr.ht/~sircmpwn/aerc ) - email client
- [tblogs ](https://github.com/ezeoleaf/tblogs ) - development blogs reader
- [spinc ](https://github.com/lallassu/spinc ) - _irssi_ inspired chat application for Cisco Spark/WebEx
- [gorss ](https://github.com/lallassu/gorss ) - RSS/Atom feed reader
- [memoryalike ](https://github.com/Bios-Marcel/memoryalike ) - memorization game
- [lf ](https://github.com/gokcehan/lf ) - file manager
- [goful ](https://github.com/anmitsu/goful ) - CUI file manager
- [gokeybr ](https://github.com/bunyk/gokeybr ) - deliberately practice your typing
- [gonano ](https://github.com/jbaramidze/gonano ) - editor, mimics _nano_
- [uchess ](https://github.com/tmountain/uchess ) - UCI chess client
- [min ](https://github.com/a-h/min ) - Gemini browser
- [ov ](https://github.com/noborus/ov ) - file pager
- [tmux-wormhole ](https://github.com/gcla/tmux-wormhole ) - _tmux_ plugin to transfer files
- [gruid-tcell ](https://github.com/anaseto/gruid-tcell ) - driver for the grid based UI and game framework
- [aretext ](https://github.com/aretext/aretext ) - minimalist text editor with _vim_ key bindings
- [sync ](https://github.com/kyprifog/sync ) - GitHub repo synchronization tool
- [statusbar ](https://github.com/kyprifog/statusbar ) - statusbar motivation tool for tracking periodic tasks/goals
- [todo ](https://github.com/kyprifog/todo ) - simple todo app
- [gosnakego ](https://github.com/liweiyi88/gosnakego ) - a snake game
- [gbb ](https://github.com/sdemingo/gbb ) - A classical bulletin board app for tildes or public unix servers
2023-03-25 20:28:59 +08:00
- [lil ](https://github.com/andrievsky/lil ) - A simple and flexible interface for any service by implementing only list and get operations
2023-10-27 18:53:49 +08:00
- [hero.go ](https://github.com/barisbll/hero.go ) - 2d monster shooter ([video](https://user-images.githubusercontent.com/40062673/277157369-240d7606-b471-4aa1-8c54-4379a513122b.mp4))
2024-03-04 05:36:36 +08:00
- [go-tetris ](https://github.com/aaronriekenberg/go-tetris ) - simple tetris game for native terminal and WASM using github actions+pages
2024-06-25 15:05:18 +08:00
- [oddshub ](https://github.com/dos-2/oddshub ) - A TUI designed for analyzing sports betting odds
2021-07-18 02:04:43 +08:00
## Pure Go Terminfo Database
2018-10-24 21:25:47 +08:00
_Tcell_ includes a full parser and expander for terminfo capability strings,
2023-01-01 01:12:50 +08:00
so that it can avoid hard coding escape strings for formatting. It also favors
2018-10-24 21:25:47 +08:00
portability, and includes support for all POSIX systems.
2021-07-18 02:04:43 +08:00
The database is also flexible & extensible, and can be modified by either running
2018-10-24 21:25:47 +08:00
a program to build the entire database, or an entry for just a single terminal.
2021-07-18 02:04:43 +08:00
## More Portable
2018-10-24 21:25:47 +08:00
2020-10-16 15:05:26 +08:00
_Tcell_ is portable to a wide variety of systems, and is pure Go, without
any need for CGO.
_Tcell_ is believed to work with mainstream systems officially supported by golang.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## No Async IO
2018-10-24 21:25:47 +08:00
_Tcell_ is able to operate without requiring `SIGIO` signals (unlike _termbox_ ),
2021-07-18 02:04:43 +08:00
or asynchronous I/O, and can instead use standard Go file objects and Go routines.
2018-10-24 21:25:47 +08:00
This means it should be safe, especially for
2021-07-18 02:04:43 +08:00
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.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## Rich Unicode & non-Unicode support
2018-10-24 21:25:47 +08:00
_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.
2021-07-18 02:04:43 +08:00
_Tcell_ tries hard to convert to native characters on both input and output.
On output _Tcell_ even makes use of the alternate character set to facilitate
2018-10-24 21:25:47 +08:00
drawing certain characters.
2021-07-18 02:04:43 +08:00
## More Function Keys
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
_Tcell_ also has richer support for a larger number of special keys that some
terminals can send.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## Better Color Handling
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
_Tcell_ will respect your terminal's color space as specified within your terminfo entries.
For example attempts to emit color sequences on VT100 terminals
2018-10-24 21:25:47 +08:00
won't result in unintended consequences.
2020-08-26 06:26:09 +08:00
In legacy Windows mode, _Tcell_ supports 16 colors, bold, dim, and reverse,
2023-01-01 01:12:50 +08:00
instead of just termbox's 8 colors with reverse. (Note that there is some
2018-10-24 21:25:47 +08:00
conflation with bold/dim and colors.)
2020-08-26 06:26:09 +08:00
Modern Windows 10 can benefit from much richer colors however.
2018-10-24 21:25:47 +08:00
_Tcell_ maps 16 colors down to 8, for terminals that need it.
(The upper 8 colors are just brighter versions of the lower 8.)
2021-07-18 02:04:43 +08:00
## Better Mouse Support
2018-10-24 21:25:47 +08:00
_Tcell_ supports enhanced mouse tracking mode, so your application can receive
regular mouse motion events, and wheel events, if your terminal supports it.
2020-08-26 06:26:09 +08:00
(Note: The Windows 10 Terminal application suffers from a flaw in this regard,
2023-01-01 01:12:50 +08:00
and does not support mouse interaction. The stock Windows 10 console host
2020-08-26 06:26:09 +08:00
fired up with cmd.exe or PowerShell works fine however.)
2021-07-18 02:04:43 +08:00
## _Termbox_ Compatibility
2018-10-24 21:25:47 +08:00
A compatibility layer for _termbox_ is provided in the `compat` directory.
2020-08-26 06:26:09 +08:00
To use it, try importing `github.com/gdamore/tcell/termbox` instead.
Most _termbox-go_ programs will probably work without further modification.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## Working With Unicode
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
Internally _Tcell_ uses UTF-8, just like Go.
However, _Tcell_ understands how to
2018-10-24 21:25:47 +08:00
convert to and from other character sets, using the capabilities of
2024-03-05 23:46:57 +08:00
the `golang.org/x/text/encoding` packages.
2018-10-24 21:25:47 +08:00
Your application must supply
2021-07-18 02:04:43 +08:00
them, as the full set of the most common ones bloats the program by about 2 MB.
2018-10-24 21:25:47 +08:00
If you're lazy, and want them all anyway, see the `encoding` sub-directory.
2021-07-18 02:04:43 +08:00
## Wide & Combining Characters
2018-10-24 21:25:47 +08:00
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,
2021-07-18 02:04:43 +08:00
then the library will skip output from the following cell. Care must be
2018-10-24 21:25:47 +08:00
taken in the application to avoid explicitly attempting to set content in the
2023-01-01 01:12:50 +08:00
next cell, otherwise the results are undefined. (Normally the wide character
2018-10-24 21:25:47 +08:00
is displayed, and the other character is not; do not depend on that behavior.)
2020-10-16 15:05:26 +08:00
Older terminal applications (especially on systems like Windows 8) lack support
for advanced Unicode, and thus may not fare well.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## Colors
2018-10-24 21:25:47 +08:00
_Tcell_ assumes the ANSI/XTerm color model, including the 256 color map that
2023-01-01 01:12:50 +08:00
XTerm uses when it supports 256 colors. The terminfo guidance will be
honored, with respect to the number of colors supported. Also, only
2018-10-24 21:25:47 +08:00
terminals which expose ANSI style `setaf` and `setab` will support color;
2020-10-16 15:05:26 +08:00
if you have a color terminal that only has `setf` and `setb` , please submit
2021-07-18 02:04:43 +08:00
a ticket.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## 24-bit Color
2018-10-24 21:25:47 +08:00
2023-01-01 01:12:50 +08:00
_Tcell_ _supports 24-bit color!_ (That is, if your terminal can support it.)
2018-10-24 21:25:47 +08:00
2020-10-30 08:30:17 +08:00
NOTE: Technically the approach of using 24-bit RGB values for color is more
2021-07-18 02:04:43 +08:00
accurately described as "direct color", but most people use the term "true color".
We follow the (inaccurate) common convention.
2020-10-30 08:30:17 +08:00
There are a few ways you can enable (or disable) true color.
2023-01-01 01:12:50 +08:00
- For many terminals, we can detect it automatically if your terminal
includes the `RGB` or `Tc` capabilities (or rather it did when the database
was updated.)
2020-10-30 08:30:17 +08:00
2023-01-01 01:12:50 +08:00
- You can force this one by setting the `COLORTERM` environment variable to
`24-bit` , `truecolor` or `24bit` . This is the same method used
by most other terminal applications that support 24-bit color.
2020-10-30 08:30:17 +08:00
2023-01-01 01:12:50 +08:00
- If you set your `TERM` environment variable to a value with the suffix `-truecolor`
then 24-bit color compatible with XTerm and ECMA-48 will be assumed.
(This feature is deprecated.
It is recommended to use one of other methods listed above.)
2020-10-30 08:30:17 +08:00
2023-01-01 01:12:50 +08:00
- You can disable 24-bit color by setting `TCELL_TRUECOLOR=disable` in your
environment.
2018-10-24 21:25:47 +08:00
When using TrueColor, programs will display the colors that the programmer
intended, overriding any "`themes`" you may have set in your terminal
2023-01-01 01:12:50 +08:00
emulator. (For some cases, accurate color fidelity is more important
than respecting themes. For other cases, such as typical text apps that
2018-10-24 21:25:47 +08:00
only use a few colors, its more desirable to respect the themes that
the user has established.)
2021-07-18 02:04:43 +08:00
## Performance
2018-10-24 21:25:47 +08:00
Reasonable attempts have been made to minimize sending data to terminals,
avoiding repeated sequences or drawing the same cell on refresh updates.
2021-07-18 02:04:43 +08:00
## Terminfo
2018-10-24 21:25:47 +08:00
2020-08-26 07:20:58 +08:00
(Not relevant for Windows users.)
2018-10-24 21:25:47 +08:00
2020-10-16 15:05:26 +08:00
The Terminfo implementation operates with a built-in database.
2023-01-01 01:12:50 +08:00
This should satisfy most users. However, it can also (on systems
2020-10-16 15:05:26 +08:00
with ncurses installed), dynamically parse the output from `infocmp`
for terminals it does not already know about.
2018-10-24 21:25:47 +08:00
2020-10-16 15:05:26 +08:00
See the `terminfo/` directory for more information about generating
new entries for the built-in database.
2018-10-24 21:25:47 +08:00
_Tcell_ requires that the terminal support the `cup` mode of cursor addressing.
2020-10-16 15:05:26 +08:00
Ancient terminals without the ability to position the cursor directly
are not supported.
This is unlikely to be a problem; such terminals have not been mass-produced
2018-10-24 21:25:47 +08:00
since the early 1970s.
2021-07-18 02:04:43 +08:00
## Mouse Support
2018-10-24 21:25:47 +08:00
Mouse support is detected via the `kmous` terminfo variable, however,
enablement/disablement and decoding mouse events is done using hard coded
2023-01-01 01:12:50 +08:00
sequences based on the XTerm X11 model. All popular
terminals with mouse tracking support this model. (Full terminfo support
2018-10-24 21:25:47 +08:00
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
2021-07-18 02:04:43 +08:00
live mouse tracking, varies widely.
Modern _xterm_ , macOS _Terminal_ , and _iTerm_ all work well.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
## Bracketed Paste
2020-10-16 15:05:26 +08:00
Terminals that appear to support the XTerm mouse model also can support
2023-01-01 01:12:50 +08:00
bracketed paste, for applications that opt-in. See `EnablePaste()` for details.
2020-10-16 15:05:26 +08:00
2021-07-18 02:04:43 +08:00
## Testability
2018-10-24 21:25:47 +08:00
There is a `SimulationScreen` , that can be used to simulate a real screen
2023-01-01 01:12:50 +08:00
for automated testing. The supplied tests do this. The simulation contains
2018-10-24 21:25:47 +08:00
event delivery, screen resizing support, and capabilities to inject events
and examine "`physical`" screen contents.
2021-07-18 02:04:43 +08:00
## Platforms
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
### POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
2018-10-24 21:25:47 +08:00
2023-01-01 01:12:50 +08:00
Everything works using pure Go on mainstream platforms. Some more esoteric
platforms (e.g., AIX) may need to be added. Pull requests are welcome!
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
### Windows
2018-10-24 21:25:47 +08:00
2021-01-25 05:50:22 +08:00
Windows console mode applications are supported.
2018-10-24 21:25:47 +08:00
2020-10-16 15:05:26 +08:00
Modern console applications like ConEmu and the Windows 10 terminal,
support all the good features (resize, mouse tracking, etc.)
2018-10-24 21:25:47 +08:00
2023-01-03 09:29:40 +08:00
### WASM
2023-01-10 09:04:06 +08:00
WASM is supported, but needs additional setup detailed in [README-wasm ](README-wasm.md ).
2023-01-03 09:29:40 +08:00
### Plan9 and others
2018-10-24 21:25:47 +08:00
2020-10-16 15:05:26 +08:00
These platforms won't work, but compilation stubs are supplied
for folks that want to include parts of this in software for those
2023-01-01 01:12:50 +08:00
platforms. The Simulation screen works, but as _Tcell_ doesn't know how to
2018-10-24 21:25:47 +08:00
allocate a real screen object on those platforms, `NewScreen()` will fail.
2020-10-16 15:05:26 +08:00
If anyone has wisdom about how to improve support for these,
2023-01-01 01:12:50 +08:00
please let me know. PRs are especially welcome.
2018-10-24 21:25:47 +08:00
2021-07-18 02:04:43 +08:00
### Commercial Support
2018-10-24 21:25:47 +08:00
_Tcell_ is absolutely free, but if you want to obtain commercial, professional support, there are options.
2023-01-01 01:12:50 +08:00
- [TideLift ](https://tidelift.com/ ) subscriptions include support for _Tcell_ , as well as many other open source packages.
2024-03-05 23:46:57 +08:00
- [Staysail Systems Inc. ](mailto:info@staysail.tech ) offers direct support, and custom development around _Tcell_ on an hourly basis.
