217 lines
8.2 KiB
Go
217 lines
8.2 KiB
Go
/*
|
|
Package tview implements rich widgets for terminal based user interfaces. The
|
|
widgets provided with this package are useful for data exploration and data
|
|
entry.
|
|
|
|
# Widgets
|
|
|
|
The package implements the following widgets:
|
|
|
|
- [TextView]: A scrollable window that display multi-colored text. Text may
|
|
also be highlighted.
|
|
- [TextArea]: An editable multi-line text area.
|
|
- [Table]: A scrollable display of tabular data. Table cells, rows, or columns
|
|
may also be highlighted.
|
|
- [TreeView]: A scrollable display for hierarchical data. Tree nodes can be
|
|
highlighted, collapsed, expanded, and more.
|
|
- [List]: A navigable text list with optional keyboard shortcuts.
|
|
- [InputField]: One-line input fields to enter text.
|
|
- [DropDown]: Drop-down selection fields.
|
|
- [Checkbox]: Selectable checkbox for boolean values.
|
|
- [Image]: Displays images.
|
|
- [Button]: Buttons which get activated when the user selects them.
|
|
- [Form]: Forms composed of input fields, drop down selections, checkboxes,
|
|
and buttons.
|
|
- [Modal]: A centered window with a text message and one or more buttons.
|
|
- [Grid]: A grid based layout manager.
|
|
- [Flex]: A Flexbox based layout manager.
|
|
- [Pages]: A page based layout manager.
|
|
|
|
The package also provides Application which is used to poll the event queue and
|
|
draw widgets on screen.
|
|
|
|
# Hello World
|
|
|
|
The following is a very basic example showing a box with the title "Hello,
|
|
world!":
|
|
|
|
package main
|
|
|
|
import (
|
|
"github.com/rivo/tview"
|
|
)
|
|
|
|
func main() {
|
|
box := tview.NewBox().SetBorder(true).SetTitle("Hello, world!")
|
|
if err := tview.NewApplication().SetRoot(box, true).Run(); err != nil {
|
|
panic(err)
|
|
}
|
|
}
|
|
|
|
First, we create a box primitive with a border and a title. Then we create an
|
|
application, set the box as its root primitive, and run the event loop. The
|
|
application exits when the application's [Application.Stop] function is called
|
|
or when Ctrl-C is pressed.
|
|
|
|
# More Demos
|
|
|
|
You will find more demos in the "demos" subdirectory. It also contains a
|
|
presentation (written using tview) which gives an overview of the different
|
|
widgets and how they can be used.
|
|
|
|
# Styles, Colors, and Hyperlinks
|
|
|
|
Throughout this package, styles are specified using the [tcell.Style] type.
|
|
Styles specify colors with the [tcell.Color] type. Functions such as
|
|
[tcell.GetColor], [tcell.NewHexColor], and [tcell.NewRGBColor] can be used to
|
|
create colors from W3C color names or RGB values. The [tcell.Style] type also
|
|
allows you to specify text attributes such as "bold" or "underline" or a URL
|
|
which some terminals use to display hyperlinks.
|
|
|
|
Almost all strings which are displayed may contain style tags. A style tag's
|
|
content is always wrapped in square brackets. In its simplest form, a style tag
|
|
specifies the foreground color of the text. Colors in these tags are W3C color
|
|
names or six hexadecimal digits following a hash tag. Examples:
|
|
|
|
This is a [red]warning[white]!
|
|
The sky is [#8080ff]blue[#ffffff].
|
|
|
|
A style tag changes the style of the characters following that style tag. There
|
|
is no style stack and no nesting of style tags.
|
|
|
|
Style tags are used in almost everything from box titles, list text, form item
|
|
labels, to table cells. In a [TextView], this functionality has to be switched
|
|
on explicitly. See the [TextView] documentation for more information.
|
|
|
|
A style tag's full format looks like this:
|
|
|
|
[<foreground>:<background>:<attribute flags>:<url>]
|
|
|
|
Each of the four fields can be left blank and trailing fields can be omitted.
|
|
(Empty square brackets "[]", however, are not considered style tags.) Fields
|
|
that are not specified will be left unchanged. A field with just a dash ("-")
|
|
means "reset to default".
|
|
|
|
You can specify the following flags to turn on certain attributes (some flags
|
|
may not be supported by your terminal):
|
|
|
|
l: blink
|
|
b: bold
|
|
i: italic
|
|
d: dim
|
|
r: reverse (switch foreground and background color)
|
|
u: underline
|
|
s: strike-through
|
|
|
|
Use uppercase letters to turn off the corresponding attribute, for example,
|
|
"B" to turn off bold. Uppercase letters have no effect if the attribute was not
|
|
previously set.
|
|
|
|
Setting a URL allows you to turn a piece of text into a hyperlink in some
|
|
terminals. Specify a dash ("-") to specify the end of the hyperlink. Hyperlinks
|
|
must only contain single-byte characters (e.g. ASCII) and they may not contain
|
|
bracket characters ("[" or "]").
|
|
|
|
Examples:
|
|
|
|
[yellow]Yellow text
|
|
[yellow:red]Yellow text on red background
|
|
[:red]Red background, text color unchanged
|
|
[yellow::u]Yellow text underlined
|
|
[::bl]Bold, blinking text
|
|
[::-]Colors unchanged, flags reset
|
|
[-]Reset foreground color
|
|
[::i]Italic and [::I]not italic
|
|
Click [:::https://example.com]here[:::-] for example.com.
|
|
Send an email to [:::mailto:her@example.com]her/[:::mail:him@example.com]him/[:::mail:them@example.com]them[:::-].
|
|
[-:-:-:-]Reset everything
|
|
[:]No effect
|
|
[]Not a valid style tag, will print square brackets as they are
|
|
|
|
In the rare event that you want to display a string such as "[red]" or
|
|
"[#00ff1a]" without applying its effect, you need to put an opening square
|
|
bracket before the closing square bracket. Note that the text inside the
|
|
brackets will be matched less strictly than region or colors tags. I.e. any
|
|
character that may be used in color or region tags will be recognized. Examples:
|
|
|
|
[red[] will be output as [red]
|
|
["123"[] will be output as ["123"]
|
|
[#6aff00[[] will be output as [#6aff00[]
|
|
[a#"[[[] will be output as [a#"[[]
|
|
[] will be output as [] (see style tags above)
|
|
[[] will be output as [[] (not an escaped tag)
|
|
|
|
You can use the Escape() function to insert brackets automatically where needed.
|
|
|
|
# Styles
|
|
|
|
When primitives are instantiated, they are initialized with colors taken from
|
|
the global [Styles] variable. You may change this variable to adapt the look and
|
|
feel of the primitives to your preferred style.
|
|
|
|
Note that most terminals will not report information about their color theme.
|
|
This package therefore does not support using the terminal's color theme. The
|
|
default style is a dark theme and you must change the [Styles] variable to
|
|
switch to a light (or other) theme.
|
|
|
|
# Unicode Support
|
|
|
|
This package supports all unicode characters supported by your terminal.
|
|
|
|
# Concurrency
|
|
|
|
Many functions in this package are not thread-safe. For many applications, this
|
|
is not an issue: If your code makes changes in response to key events, the
|
|
corresponding callback function will execute in the main goroutine and thus will
|
|
not cause any race conditions. (Exceptions to this are documented.)
|
|
|
|
If you access your primitives from other goroutines, however, you will need to
|
|
synchronize execution. The easiest way to do this is to call
|
|
[Application.QueueUpdate] or [Application.QueueUpdateDraw] (see the function
|
|
documentation for details):
|
|
|
|
go func() {
|
|
app.QueueUpdateDraw(func() {
|
|
table.SetCellSimple(0, 0, "Foo bar")
|
|
})
|
|
}()
|
|
|
|
One exception to this is the io.Writer interface implemented by [TextView]. You
|
|
can safely write to a [TextView] from any goroutine. See the [TextView]
|
|
documentation for details.
|
|
|
|
You can also call [Application.Draw] from any goroutine without having to wrap
|
|
it in [Application.QueueUpdate]. And, as mentioned above, key event callbacks
|
|
are executed in the main goroutine and thus should not use
|
|
[Application.QueueUpdate] as that may lead to deadlocks. It is also not
|
|
necessary to call [Application.Draw] from such callbacks as it will be called
|
|
automatically.
|
|
|
|
# Type Hierarchy
|
|
|
|
All widgets listed above contain the [Box] type. All of [Box]'s functions are
|
|
therefore available for all widgets, too. Please note that if you are using the
|
|
functions of [Box] on a subclass, they will return a *Box, not the subclass.
|
|
This is a Golang limitation. So while tview supports method chaining in many
|
|
places, these chains must be broken when using [Box]'s functions. Example:
|
|
|
|
// This will cause "textArea" to be an empty Box.
|
|
textArea := tview.NewTextArea().
|
|
SetMaxLength(256).
|
|
SetPlaceholder("Enter text here").
|
|
SetBorder(true)
|
|
|
|
You will need to call [Box.SetBorder] separately:
|
|
|
|
textArea := tview.NewTextArea().
|
|
SetMaxLength(256).
|
|
SetPlaceholder("Enter text here")
|
|
texArea.SetBorder(true)
|
|
|
|
All widgets also implement the [Primitive] interface.
|
|
|
|
The tview package's rendering is based on version 2 of
|
|
https://github.com/gdamore/tcell. It uses types and constants from that package
|
|
(e.g. colors, styles, and keyboard values).
|
|
*/
|
|
package tview
|