diff options
Diffstat (limited to 'vendor/maunium.net/go/tcell/README.adoc')
| -rw-r--r-- | vendor/maunium.net/go/tcell/README.adoc | 270 |
1 files changed, 0 insertions, 270 deletions
diff --git a/vendor/maunium.net/go/tcell/README.adoc b/vendor/maunium.net/go/tcell/README.adoc deleted file mode 100644 index 3b60057..0000000 --- a/vendor/maunium.net/go/tcell/README.adoc +++ /dev/null @@ -1,270 +0,0 @@ -= 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",frame="none", grid="none"] -|=== -^.^| -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. -|=== |