From 260932a7ea24bb5fb1632b37b020b5ebe32df187 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 16 Oct 2020 00:05:26 -0700 Subject: [PATCH] Update documentation for V2. --- CHANGESv2.adoc | 27 +++++++++----- README.adoc | 98 ++++++++++++++++++++------------------------------ 2 files changed, 57 insertions(+), 68 deletions(-) diff --git a/CHANGESv2.adoc b/CHANGESv2.adoc index 0862fe2..65d1548 100644 --- a/CHANGESv2.adoc +++ b/CHANGESv2.adoc @@ -4,13 +4,16 @@ A number of changes were made to _Tcell_ for version two, and some of these are breaking. === Import Path + The import path for tcell has changed to `github.com/gdamore/tcell/v2` to reflect a new major version. === Style Is Not Numeric + The type `Style` has changed to a structure, to allow us to add additional data such as flags for color setting, more attribute bits, and so forth. -Applications that relied on being a number will need to be updated to use the accessor methods. +Applications that relied on this being a number will need to be updated to use the accessor methods. === Mouse Event Changes + The middle mouse button was reported as button 2 on Linux, but as button 3 on Windows, and the right mouse button was reported the reverse way. _Tcell_ now always reports the right mouse button as button 2, and the middle button as button 3. @@ -21,15 +24,16 @@ Usually the left button will be considered the Primary, and the right will be th Applications may need to adjust their handling of mouse buttons 2 and 3 accordingly. === Terminals Removed + A number of terminals have been removed. -These are mostly ancient definitions unlikey to be used by anyone, such as `adm3a`. +These are mostly ancient definitions unlikely to be used by anyone, such as `adm3a`. === High Number Function Keys Historically terminfo reported function keys with modifiers set as a different -function key altogether. For example, Shift-F1 was reported as F13 on xterm. +function key altogether. For example, Shift-F1 was reported as F13 on XTerm. _Tcell_ now prefers to report these using the base key (such as F1) with modifiers added. -This works on xterm and VTE based emulators, but some emulators may not support this. +This works on XTerm and VTE based emulators, but some emulators may not support this. The new behavior more closely aligns with behavior on Windows platforms. == New Features in _Tcell_ v2 @@ -49,8 +53,7 @@ use that palette entry as is; this should avoid some inconsistency and undesirab overriding of colors where colors would override settings made in the terminal. When true fidelity to RGB values is needed, the new `TrueColor()` API can be used -to create a color that is precisely the direct color, which bypasses the palette -altogether. +to create a direct color, which bypasses the palette altogether. === Automatic TrueColor Detection @@ -59,7 +62,7 @@ _Tcell_ will automatically assume the terminal supports 24-bit color. === ColorReset -A new color value, `ColorReset` can be used on the foreground or the background +A new color value, `ColorReset` can be used on the foreground or background to reset the color the default used by the terminal. === tmux Support @@ -68,4 +71,12 @@ _Tcell_ now has improved support for tmux, when the `$TERM` variable is set to " === Strikethrough Support -_Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API. \ No newline at end of file +_Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API. + +=== Bracketed Paste Support + +_Tcell_ provides the long requested capability to discriminate paste event by using the +bracketed-paste capability present in some terminals. This is automatically available on +terminals that support XTerm style mouse handling, but applications must opt-in to this +by using the new `EnablePaste()` function. A new `EventPaste` type of event will be +delivered when starting and finishing a paste operation. \ No newline at end of file diff --git a/README.adoc b/README.adoc index 9d775cb..97dfcd5 100644 --- a/README.adoc +++ b/README.adoc @@ -11,15 +11,14 @@ image:https://codecov.io/gh/gdamore/tcell/branch/master/graph/badge.svg[codecov, [cols="2",grid="none"] |=== -|_Tcell_ is a _Go_ package that provides a cell based view for text terminals, like _xterm_. +|_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"] |=== -NOTE: Work has begun on version 2.0 of _Tcell_. There are breaking changes (and more coming.) -Version 1.x is available using the import `github.com/gdamore/tcell`. -The new work in progress is available using master and `github.com/gdamore/tcell/v2`. +NOTE: This is version 2 of _Tcell_. There are breaking changes relative to version 1. +Version 1.x remains available using the import `github.com/gdamore/tcell`. == Examples @@ -60,12 +59,9 @@ 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.) _Tcell_ is pure Go, without any need for CGO. +_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. == No Async IO @@ -143,9 +139,8 @@ 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. +Older terminal applications (especially on systems like Windows 8) lack support +for advanced Unicode, and thus may not fare well. == Colors @@ -153,16 +148,16 @@ _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. +if you have a color terminal that only has `setf` and `setb`, please submit +a ticket; 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 +To use 24-bit color, you need to use a terminal with support. Modern +XTerm and similar terminal 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`. @@ -189,27 +184,18 @@ avoiding repeated sequences or drawing the same cell on refresh updates. (Not relevant 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 Terminfo implementation operates with a built-in database. +This should satisfy most users. However, it can also (on systems +with ncurses installed), dynamically parse the output from `infocmp` +for terminals it does not already know about. -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!) +See the `terminfo/` directory for more information about generating +new entries for the built-in database. _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 +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 since the early 1970s. == Mouse Support @@ -226,7 +212,12 @@ 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 +== Bracketed Paste + +Terminals that appear to support the XTerm mouse model also can support +bracketed paste, for applications that opt-in. See `EnablePaste()` for details. + +== Testability There is a `SimulationScreen`, that can be used to simulate a real screen for automated testing. The supplied tests do this. The simulation contains @@ -237,34 +228,26 @@ and examine "`physical`" screen contents. === 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. +Everything works using pure Go on mainstream platforms. Some more esoteric +platforms (e.g. AIX) may need to be added. Pull requests are welcome! === Windows Windows console mode applications are supported. Unfortunately _mintty_ -and other _cygwin_ style applications are not supported. +and other _cygwin_ style applications are not supported, and are +unlikely to be supportable due to limitations in their design. -Modern console applications like ConEmu, as well as the Windows 10 -console itself, support all the good features (resize, mouse tracking, etc.) +Modern console applications like ConEmu and the Windows 10 terminal, +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, WASM, and others -=== 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 +These platforms won't work, but compilation stubs are supplied +for folks that want to include parts of this in software for 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, +If anyone has wisdom about how to improve support for these, please let me know. PRs are especially welcome. === Commercial Support @@ -282,8 +265,3 @@ https://tidelift.com/[Tidelift] subscriptions include support for _Tcell_, as we 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.patreon.com/gedamore/[Patreon], if you just want to make a contribution. -|===