mirror of
https://github.com/jesseduffield/lazygit.git
synced 2025-05-12 12:55:47 +02:00
bump gocui
This commit is contained in:
Jesse Duffield
parent
ab0117c416
commit
c8e9d1b4fc
112 changed files with 4773 additions and 4538 deletions
|
|
@ -1,18 +1,18 @@
|
|||
== Breaking Changes in _Tcell_ v2
|
||||
## Breaking Changes in _Tcell_ v2
|
||||
|
||||
A number of changes were made to _Tcell_ for version two, and some of these
|
||||
are breaking.
|
||||
A number of changes were made to _Tcell_ for version two, and some of these are breaking.
|
||||
|
||||
=== Import Path
|
||||
### 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
|
||||
### 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.
|
||||
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 this being a number will need to be updated to use the accessor methods.
|
||||
|
||||
=== Mouse Event Changes
|
||||
### 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.
|
||||
|
|
@ -23,12 +23,12 @@ To help make this clearer, new symbols `ButtonPrimary`, `ButtonSecondary`, and
|
|||
Usually the left button will be considered the Primary, and the right will be the Secondary.)
|
||||
Applications may need to adjust their handling of mouse buttons 2 and 3 accordingly.
|
||||
|
||||
=== Terminals Removed
|
||||
### Terminals Removed
|
||||
|
||||
A number of terminals have been removed.
|
||||
These are mostly ancient definitions unlikely to be used by anyone, such as `adm3a`.
|
||||
|
||||
=== High Number Function Keys
|
||||
### 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.
|
||||
|
|
@ -36,44 +36,44 @@ _Tcell_ now prefers to report these using the base key (such as F1) with modifie
|
|||
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
|
||||
## New Features in _Tcell_ v2
|
||||
|
||||
These features are not breaking, but are introduced in version 2.
|
||||
|
||||
=== Improved Modifier Support
|
||||
### Improved Modifier Support
|
||||
|
||||
For terminals that appear to behave like the venerable XTerm, _tcell_
|
||||
automatically adds modifier reporting for ALT, CTRL, SHIFT, and META keys
|
||||
when the terminal reports them.
|
||||
|
||||
=== Better Support for Palettes (Themes)
|
||||
### Better Support for Palettes (Themes)
|
||||
|
||||
When using a color by its name or palette entry, _Tcell_ now tries to
|
||||
use that palette entry as is; this should avoid some inconsistency and undesirable
|
||||
overriding of colors where colors would override settings made in the terminal.
|
||||
use that palette entry as is; this should avoid some inconsistency and respect
|
||||
terminal themes correctly.
|
||||
|
||||
When true fidelity to RGB values is needed, the new `TrueColor()` API can be used
|
||||
to create a direct color, which bypasses the palette altogether.
|
||||
|
||||
=== Automatic TrueColor Detection
|
||||
### Automatic TrueColor Detection
|
||||
|
||||
For some terminals, if the `Tc` or `RGB` properties are present in terminfo,
|
||||
_Tcell_ will automatically assume the terminal supports 24-bit color.
|
||||
|
||||
=== ColorReset
|
||||
### ColorReset
|
||||
|
||||
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
|
||||
### tmux Support
|
||||
|
||||
_Tcell_ now has improved support for tmux, when the `$TERM` variable is set to "tmux".
|
||||
|
||||
=== Strikethrough Support
|
||||
### Strikethrough Support
|
||||
|
||||
_Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API.
|
||||
|
||||
=== Bracketed Paste Support
|
||||
### 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
|
||||
|
|
@ -1,88 +1,85 @@
|
|||
= 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/godoc-reference-blue.svg[GoDoc,link="https://godoc.org/github.com/gdamore/tcell"]
|
||||
image:https://goreportcard.com/badge/gdamore/tcell[Go Report Card,link="http://goreportcard.com/report/gdamore/tcell"]
|
||||
image:https://img.shields.io/discord/639503822733180969?label=discord[Discord,link="https://discord.gg/urTTxDN"]
|
||||
image:https://codecov.io/gh/gdamore/tcell/branch/master/graph/badge.svg[codecov,link="https://codecov.io/gh/gdamore/tcell"]
|
||||
|
||||
[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"]
|
||||
|===
|
||||
|
||||
[](https://travis-ci.org/gdamore/tcell)
|
||||
[](https://ci.appveyor.com/project/gdamore/tcell)
|
||||
[](https://github.com/gdamore/tcell/blob/master/LICENSE)
|
||||
[](https://pkg.go.dev/github.com/gdamore/tcell/v2)
|
||||
[](http://goreportcard.com/report/gdamore/tcell/v2)
|
||||
[](https://discord.gg/urTTxDN)
|
||||
[](https://codecov.io/gh/gdamore/tcell)
|
||||
|
||||
|
||||
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
|
||||
## Tutorial
|
||||
|
||||
* 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/awesome-gocui/gocui[awesome gocui] - Go Console User Interface
|
||||
* 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.
|
||||
* https://github.com/gcla/gowid[gowid] - compositional widgets for terminal UIs, inspired by urwid
|
||||
* https://termshark.io[termshark] - a terminal UI for tshark, inspired by Wireshark, built on gowid
|
||||
* https://github.com/MichaelS11/go-tetris[go-tetris] - Go Tetris with AI option
|
||||
* https://github.com/junegunn/fzf[fzf] - A command-line fuzzy finder
|
||||
* https://github.com/esimov/ascii-fluid[ascii-fluid] - A terminal based ASCII fluid simulation controlled by webcam
|
||||
* https://gitlab.com/tslocum/cbind[cbind] - Provides key event encoding, decoding and handling
|
||||
* https://github.com/spinzed/tpong[tpong] - The old-school Pong remade in terminal
|
||||
* https://git.sr.ht/~sircmpwn/aerc[aerc] - An email client for your terminal.
|
||||
* https://github.com/ezeoleaf/tblogs[tblogs] - A terminal based development blogs reader
|
||||
* https://github.com/lallassu/spinc[spinc] - An irssi inspired terminal chat application for Cisco Spark/WebEx
|
||||
* https://github.com/lallassu/gorss[gorss] - A RSS/Atom feed reader for your terminal
|
||||
* https://github.com/Bios-Marcel/memoryalike[memoryalike] - A game where you have to memorize runes and hit their respective keys
|
||||
* https://github.com/gokcehan/lf[lf] - Terminal file manager
|
||||
* https://github.com/bunyk/gokeybr[gokeybr] - program that helps to deliberately practice your typing.
|
||||
* https://github.com/jbaramidze/gonano[gonano] - CLI test editor
|
||||
* https://github.com/tmountain/uchess[uchess] - A UCI chess client for your terminal
|
||||
* https://github.com/a-h/min[min] - A Gemini browser
|
||||
* https://github.com/noborus/ov[ov] - Terminal pager
|
||||
* https://github.com/gcla/tmux-wormhole[tmux-wormhole] - A tmux plugin to transfer files with magic wormhole
|
||||
* https://github.com/anaseto/gruid-tcell[gruid-tcell] - A tcell driver for the grid based UI and game framework gruid.
|
||||
* https://github.com/aretext/aretext[aretext] - Minimalist text editor with vim key bindings.
|
||||
A brief, and still somewhat rough, [tutorial](TUTORIAL.md) is available.
|
||||
## Examples
|
||||
|
||||
== Pure Go Terminfo Database
|
||||
* [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_)
|
||||
* [awsome gocui](https://github.com/awesome-gocui/gocui) - Go Console User Interface
|
||||
* [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
|
||||
* [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
|
||||
|
||||
## 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
|
||||
The database is also flexible & extensible, and can be modified by either running
|
||||
a program to build the entire database, or an entry for just a single terminal.
|
||||
|
||||
== More Portable
|
||||
## More Portable
|
||||
|
||||
_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
|
||||
## 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.
|
||||
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.
|
||||
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
|
||||
## Rich Unicode & non-Unicode support
|
||||
|
||||
_Tcell_ includes enhanced support for Unicode, including wide characters and
|
||||
combining characters, provided your terminal can support them.
|
||||
|
|
@ -91,18 +88,19 @@ 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
|
||||
_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
|
||||
drawing certain characters.
|
||||
|
||||
== More Function Keys
|
||||
## More Function Keys
|
||||
|
||||
_Tcell_ also has richer support for a larger number of special keys that some terminals can send.
|
||||
_Tcell_ also has richer support for a larger number of special keys that some
|
||||
terminals can send.
|
||||
|
||||
== Better Color Handling
|
||||
## 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
|
||||
_Tcell_ will respect your terminal's color space as specified within your terminfo entries.
|
||||
For example attempts to emit color sequences on VT100 terminals
|
||||
won't result in unintended consequences.
|
||||
|
||||
In legacy Windows mode, _Tcell_ supports 16 colors, bold, dim, and reverse,
|
||||
|
|
@ -113,7 +111,7 @@ Modern Windows 10 can benefit from much richer colors however.
|
|||
_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
|
||||
## 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.
|
||||
|
|
@ -122,51 +120,50 @@ regular mouse motion events, and wheel events, if your terminal supports it.
|
|||
and does not support mouse interaction. The stock Windows 10 console host
|
||||
fired up with cmd.exe or PowerShell works fine however.)
|
||||
|
||||
== _Termbox_ Compatibility
|
||||
## _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
|
||||
## Working With Unicode
|
||||
|
||||
Internally Tcell uses UTF-8, just like Go.
|
||||
However, Tcell understands how to
|
||||
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.
|
||||
them, as the full set of the most common ones bloats the program by about 2 MB.
|
||||
If you're lazy, and want them all anyway, see the `encoding` sub-directory.
|
||||
|
||||
== Wide & Combining Characters
|
||||
## 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
|
||||
then the library will skip output from the following cell. 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
|
||||
next cell, otherwise the results are undefined. (Normally the wide character
|
||||
is displayed, and the other character is not; do not depend on that behavior.)
|
||||
|
||||
Older terminal applications (especially on systems like Windows 8) lack support
|
||||
for advanced Unicode, and thus may not fare well.
|
||||
|
||||
== Colors
|
||||
## 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 submit
|
||||
a ticket; it wouldn't be hard to add that if there is need.
|
||||
a ticket.
|
||||
|
||||
== 24-bit Color
|
||||
## 24-bit Color
|
||||
|
||||
_Tcell_ _supports true color_! (That is, if your terminal can support it,
|
||||
_Tcell_ can accurately display 24-bit color.)
|
||||
_Tcell_ _supports 24-bit color!_ (That is, if your terminal can support it.)
|
||||
|
||||
NOTE: Technically the approach of using 24-bit RGB values for color is more
|
||||
accurately described as "direct color", but most people use the term "true color",
|
||||
and so we follow the (inaccurate) common convention.
|
||||
accurately described as "direct color", but most people use the term "true color".
|
||||
We follow the (inaccurate) common convention.
|
||||
|
||||
There are a few ways you can enable (or disable) true color.
|
||||
|
||||
|
|
@ -175,15 +172,13 @@ includes the `RGB` or `Tc` capabilities (or rather it did when the database
|
|||
was updated.)
|
||||
|
||||
* You can force this one by setting the `COLORTERM` environment variable to
|
||||
"24-bit", "truecolor" or "24bit". This is the same method used
|
||||
`24-bit`, `truecolor` or `24bit`. This is the same method used
|
||||
by most other terminal applications that support 24-bit color.
|
||||
|
||||
* If you set your `TERM` environment variable to a value with the suffix `-truecolor`
|
||||
then 24-bit color compatible with XTerm will be assumed (and the terminal will
|
||||
otherwise use the same escape sequences as the base terminal definition.)
|
||||
|
||||
NOTE: This feature is for compatibility with older _Tcell_ versions.
|
||||
It is recommended to use one of other methods instead.
|
||||
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.)
|
||||
|
||||
* You can disable 24-bit color by setting `TCELL_TRUECOLOR=disable` in your
|
||||
environment.
|
||||
|
|
@ -195,12 +190,12 @@ 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.)
|
||||
|
||||
== Performance
|
||||
## Performance
|
||||
|
||||
Reasonable attempts have been made to minimize sending data to terminals,
|
||||
avoiding repeated sequences or drawing the same cell on refresh updates.
|
||||
|
||||
== Terminfo
|
||||
## Terminfo
|
||||
|
||||
(Not relevant for Windows users.)
|
||||
|
||||
|
|
@ -218,11 +213,11 @@ 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
|
||||
|
||||
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
|
||||
sequences based on the XTerm X11 model. All popular
|
||||
terminals with mouse tracking support this model. (Full terminfo support
|
||||
is not possible as terminfo sequences are not defined.)
|
||||
|
||||
|
|
@ -230,35 +225,36 @@ 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.
|
||||
live mouse tracking, varies widely.
|
||||
Modern _xterm_, macOS _Terminal_, and _iTerm_ all work well.
|
||||
|
||||
== Bracketed Paste
|
||||
## 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
|
||||
## 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
|
||||
event delivery, screen resizing support, and capabilities to inject events
|
||||
and examine "`physical`" screen contents.
|
||||
|
||||
== Platforms
|
||||
## Platforms
|
||||
|
||||
=== POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
|
||||
### POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
|
||||
|
||||
Everything works using pure Go on mainstream platforms. Some more esoteric
|
||||
platforms (e.g. AIX) may need to be added. Pull requests are welcome!
|
||||
platforms (e.g., AIX) may need to be added. Pull requests are welcome!
|
||||
|
||||
=== Windows
|
||||
### Windows
|
||||
|
||||
Windows console mode applications are supported.
|
||||
|
||||
Modern console applications like ConEmu and the Windows 10 terminal,
|
||||
support all the good features (resize, mouse tracking, etc.)
|
||||
|
||||
=== Plan9, WASM, and others
|
||||
### Plan9, WASM, and others
|
||||
|
||||
These platforms won't work, but compilation stubs are supplied
|
||||
for folks that want to include parts of this in software for those
|
||||
|
|
@ -268,18 +264,9 @@ allocate a real screen object on those platforms, `NewScreen()` will fail.
|
|||
If anyone has wisdom about how to improve support for these,
|
||||
please let me know. PRs are especially welcome.
|
||||
|
||||
=== Commercial Support
|
||||
### 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.
|
||||
* [TideLift](https://tidelift.com/) subscriptions include support for _Tcell_, as well as many other open source packages.
|
||||
* [Staysail Systems Inc.](mailto:info@staysail.tech) offers direct support, and custom development around _Tcell_ on an hourly basis.
|
||||
|
|
@ -1,30 +1,32 @@
|
|||
= tcell tutorial
|
||||
# _Tcell_ Tutorial
|
||||
|
||||
tcell provides a low-level, portable API for building terminal-based programs.
|
||||
A https://en.wikipedia.org/wiki/Terminal_emulator[terminal emulator] is used to
|
||||
interact with such a program.
|
||||
_Tcell_ provides a low-level, portable API for building terminal-based programs.
|
||||
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator)
|
||||
(or a real terminal such as a DEC VT-220) is used to interact with such a program.
|
||||
|
||||
Applications typically initialize a screen and enter an event loop, then
|
||||
finalize the screen before exiting.
|
||||
_Tcell_'s interface is fairly low-level.
|
||||
While it provides a reasonably portable way of dealing with all the usual terminal
|
||||
features, it may be easier to utilize a higher level framework.
|
||||
A number of such frameworks are listed on the _Tcell_ main [README](README.md).
|
||||
|
||||
Application frameworks such as https://github.com/rivo/tview[tview] and
|
||||
https://gitlab.com/tslocum/cview[cview] provide widgets and additional features.
|
||||
This tutorial provides the details of _Tcell_, and is appropriate for developers
|
||||
wishing to create their own application frameworks or needing more direct access
|
||||
to the terminal capabilities.
|
||||
|
||||
== Resize events
|
||||
## Resize events
|
||||
|
||||
Applications receive an event of type `EventResize` when they are first initialized and each time the terminal is resized.
|
||||
The new size is available as `Size`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventResize:
|
||||
w, h := ev.Size()
|
||||
logMessage(fmt.Sprintf("Resized to %dx%d", w, h))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
== Key events
|
||||
## Key events
|
||||
|
||||
When a key is pressed, applications receive an event of type `EventKey`.
|
||||
This event describes the modifier keys pressed (if any) and the pressed key or rune.
|
||||
|
|
@ -33,16 +35,15 @@ When a rune key is pressed, an event with its `Key` set to `KeyRune` is dispatch
|
|||
|
||||
When a non-rune key is pressed, it is available as the `Key` of the event.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventKey:
|
||||
mod, key, ch := ev.Mod(), ev.Key(), ev.Rune()
|
||||
logMessage(fmt.Sprintf("EventKey Modifiers: %d Key: %d Rune: %d", mod, key, ch))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
=== Key event restrictions
|
||||
### Key event restrictions
|
||||
|
||||
Terminal-based programs have less visibility into keyboard activity than graphical applications.
|
||||
|
||||
|
|
@ -53,12 +54,7 @@ Key release events are not available.
|
|||
It is not possible to distinguish runes typed while holding shift and runes typed using caps lock.
|
||||
Capital letters are reported without the Shift modifier.
|
||||
|
||||
=== Key event handling library
|
||||
|
||||
https://gitlab.com/tslocum/cbind[cbind] provides key event encoding and decoding
|
||||
to and from human-readable strings. It also provides keybinding-based input handling.
|
||||
|
||||
== Mouse events
|
||||
## Mouse events
|
||||
|
||||
Applications receive an event of type `EventMouse` when the mouse moves, or a mouse button is pressed or released.
|
||||
Mouse events are only delivered if
|
||||
|
|
@ -66,8 +62,7 @@ Mouse events are only delivered if
|
|||
|
||||
The mouse buttons being pressed (if any) are available as `Buttons`, and the position of the mouse is available as `Position`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventMouse:
|
||||
mod := ev.Modifiers()
|
||||
|
|
@ -75,46 +70,23 @@ case *tcell.EventMouse:
|
|||
x, y := ev.Position()
|
||||
logMessage(fmt.Sprintf("EventMouse Modifiers: %d Buttons: %d Position: %d,%d", mod, btns, x, y))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
=== Mouse buttons
|
||||
### Mouse buttons
|
||||
|
||||
[cols=3*,options=header]
|
||||
|===
|
||||
Identifier | Alias | Description
|
||||
-----------|-----------------|-----------
|
||||
Button1 | ButtonPrimary | Left button
|
||||
Button2 | ButtonSecondary | Right button
|
||||
Button3 | ButtonMiddle | Middle button
|
||||
Button4 | | Side button (thumb/next)
|
||||
Button5 | | Side button (thumb/prev)
|
||||
|
||||
|Identifier
|
||||
|Alias
|
||||
|Description
|
||||
|
||||
|Button1
|
||||
|ButtonPrimary
|
||||
|Left button
|
||||
|
||||
|Button2
|
||||
|ButtonSecondary
|
||||
|Right button
|
||||
|
||||
|Button3
|
||||
|ButtonMiddle
|
||||
|Middle button
|
||||
|
||||
|Button4
|
||||
|
|
||||
|Side button (thumb/next)
|
||||
|
||||
|Button5
|
||||
|
|
||||
|Side button (thumb/prev)
|
||||
|
||||
|===
|
||||
|
||||
== Usage
|
||||
## Usage
|
||||
|
||||
To create a tcell application, first initialize a screen to hold it.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
// Initialize screen
|
||||
```golang
|
||||
s, err := tcell.NewScreen()
|
||||
if err != nil {
|
||||
log.Fatalf("%+v", err)
|
||||
|
|
@ -129,21 +101,19 @@ s.SetStyle(defStyle)
|
|||
|
||||
// Clear screen
|
||||
s.Clear()
|
||||
----
|
||||
```
|
||||
|
||||
Text may be drawn on the screen using `SetContent`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
s.SetContent(0, 0, 'H', nil, defStyle)
|
||||
s.SetContent(1, 0, 'i', nil, defStyle)
|
||||
s.SetContent(2, 0, '!', nil, defStyle)
|
||||
----
|
||||
```
|
||||
|
||||
To draw text more easily, define a render function.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
func drawText(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string) {
|
||||
row := y1
|
||||
col := x1
|
||||
|
|
@ -159,12 +129,11 @@ func drawText(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
Lastly, define an event loop to handle user input and update application state.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
quit := func() {
|
||||
s.Fini()
|
||||
os.Exit(0)
|
||||
|
|
@ -186,14 +155,13 @@ for {
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
== Demo application
|
||||
## Demo application
|
||||
|
||||
The following demonstrates how to initialize a screen, draw text/graphics and handle user input.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
package main
|
||||
|
||||
import (
|
||||
|
|
@ -322,4 +290,4 @@ func main() {
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
20
vendor/github.com/gdamore/tcell/v2/console_win.go
generated
vendored
20
vendor/github.com/gdamore/tcell/v2/console_win.go
generated
vendored
|
|
@ -343,6 +343,26 @@ func (s *cScreen) PostEvent(ev Event) error {
|
|||
}
|
||||
}
|
||||
|
||||
func (s *cScreen) ChannelEvents(ch chan<- Event, quit <-chan struct{}) {
|
||||
defer close(ch)
|
||||
for {
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-s.stopQ:
|
||||
return
|
||||
case ev := <-s.evch:
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-s.stopQ:
|
||||
return
|
||||
case ch <- ev:
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (s *cScreen) PollEvent() Event {
|
||||
select {
|
||||
case <-s.stopQ:
|
||||
|
|
|
|||
11
vendor/github.com/gdamore/tcell/v2/screen.go
generated
vendored
11
vendor/github.com/gdamore/tcell/v2/screen.go
generated
vendored
|
|
@ -78,6 +78,17 @@ type Screen interface {
|
|||
// response to a call to Clear or Flush.
|
||||
Size() (int, int)
|
||||
|
||||
// ChannelEvents is an infinite loop that waits for an event and
|
||||
// channels it into the user provided channel ch. Closing the
|
||||
// quit channel and calling the Fini method are cancellation
|
||||
// signals. When a cancellation signal is received the method
|
||||
// returns after closing ch.
|
||||
//
|
||||
// This method should be used as a goroutine.
|
||||
//
|
||||
// NOTE: PollEvent should not be called while this method is running.
|
||||
ChannelEvents(ch chan<- Event, quit <-chan struct{})
|
||||
|
||||
// PollEvent waits for events to arrive. Main application loops
|
||||
// must spin on this to prevent the application from stalling.
|
||||
// Furthermore, this will return nil if the Screen is finalized.
|
||||
|
|
|
|||
22
vendor/github.com/gdamore/tcell/v2/simulation.go
generated
vendored
22
vendor/github.com/gdamore/tcell/v2/simulation.go
generated
vendored
|
|
@ -351,6 +351,26 @@ func (s *simscreen) Colors() int {
|
|||
return 256
|
||||
}
|
||||
|
||||
func (s *simscreen) ChannelEvents(ch chan<- Event, quit <-chan struct{}) {
|
||||
defer close(ch)
|
||||
for {
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-s.quit:
|
||||
return
|
||||
case ev := <-s.evch:
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-s.quit:
|
||||
return
|
||||
case ch <- ev:
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (s *simscreen) PollEvent() Event {
|
||||
select {
|
||||
case <-s.quit:
|
||||
|
|
@ -531,4 +551,4 @@ func (s *simscreen) Suspend() error {
|
|||
|
||||
func (s *simscreen) Resume() error {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
|
|
|||
22
vendor/github.com/gdamore/tcell/v2/tscreen.go
generated
vendored
22
vendor/github.com/gdamore/tcell/v2/tscreen.go
generated
vendored
|
|
@ -638,7 +638,7 @@ func (t *tScreen) drawCell(x, y int) int {
|
|||
t.TPuts(ti.TGoto(x-1, y))
|
||||
t.TPuts(ti.InsertChar)
|
||||
t.cy = y
|
||||
t.cx = x-1
|
||||
t.cx = x - 1
|
||||
t.cells.SetDirty(x-1, y, true)
|
||||
_ = t.drawCell(x-1, y)
|
||||
t.TPuts(t.ti.TGoto(0, 0))
|
||||
|
|
@ -941,6 +941,26 @@ func (t *tScreen) nColors() int {
|
|||
return t.ti.Colors
|
||||
}
|
||||
|
||||
func (t *tScreen) ChannelEvents(ch chan<- Event, quit <-chan struct{}) {
|
||||
defer close(ch)
|
||||
for {
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-t.quit:
|
||||
return
|
||||
case ev := <-t.evch:
|
||||
select {
|
||||
case <-quit:
|
||||
return
|
||||
case <-t.quit:
|
||||
return
|
||||
case ch <- ev:
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (t *tScreen) PollEvent() Event {
|
||||
select {
|
||||
case <-t.quit:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue