doc.go (8698B)
1 /* 2 Package tview implements rich widgets for terminal based user interfaces. The 3 widgets provided with this package are useful for data exploration and data 4 entry. 5 6 # Widgets 7 8 The package implements the following widgets: 9 10 - [TextView]: A scrollable window that display multi-colored text. Text may 11 also be highlighted. 12 - [TextArea]: An editable multi-line text area. 13 - [Table]: A scrollable display of tabular data. Table cells, rows, or columns 14 may also be highlighted. 15 - [TreeView]: A scrollable display for hierarchical data. Tree nodes can be 16 highlighted, collapsed, expanded, and more. 17 - [List]: A navigable text list with optional keyboard shortcuts. 18 - [InputField]: One-line input fields to enter text. 19 - [DropDown]: Drop-down selection fields. 20 - [Checkbox]: Selectable checkbox for boolean values. 21 - [Image]: Displays images. 22 - [Button]: Buttons which get activated when the user selects them. 23 - [Form]: Forms composed of input fields, drop down selections, checkboxes, 24 and buttons. 25 - [Modal]: A centered window with a text message and one or more buttons. 26 - [Grid]: A grid based layout manager. 27 - [Flex]: A Flexbox based layout manager. 28 - [Pages]: A page based layout manager. 29 30 The package also provides Application which is used to poll the event queue and 31 draw widgets on screen. 32 33 # Hello World 34 35 The following is a very basic example showing a box with the title "Hello, 36 world!": 37 38 package main 39 40 import ( 41 "github.com/rivo/tview" 42 ) 43 44 func main() { 45 box := tview.NewBox().SetBorder(true).SetTitle("Hello, world!") 46 if err := tview.NewApplication().SetRoot(box, true).Run(); err != nil { 47 panic(err) 48 } 49 } 50 51 First, we create a box primitive with a border and a title. Then we create an 52 application, set the box as its root primitive, and run the event loop. The 53 application exits when the application's [Application.Stop] function is called 54 or when Ctrl-C is pressed. 55 56 # More Demos 57 58 You will find more demos in the "demos" subdirectory. It also contains a 59 presentation (written using tview) which gives an overview of the different 60 widgets and how they can be used. 61 62 # Styles, Colors, and Hyperlinks 63 64 Throughout this package, styles are specified using the [tcell.Style] type. 65 Styles specify colors with the [tcell.Color] type. Functions such as 66 [tcell.GetColor], [tcell.NewHexColor], and [tcell.NewRGBColor] can be used to 67 create colors from W3C color names or RGB values. The [tcell.Style] type also 68 allows you to specify text attributes such as "bold" or "italic" or a URL 69 which some terminals use to display hyperlinks. 70 71 Almost all strings which are displayed may contain style tags. A style tag's 72 content is always wrapped in square brackets. In its simplest form, a style tag 73 specifies the foreground color of the text. Colors in these tags are W3C color 74 names or six hexadecimal digits following a hash tag. Examples: 75 76 This is a [red]warning[white]! 77 The sky is [#8080ff]blue[#ffffff]. 78 79 A style tag changes the style of the characters following that style tag. There 80 is no style stack and no nesting of style tags. 81 82 Style tags are used in almost everything from box titles, list text, form item 83 labels, to table cells. In a [TextView], this functionality has to be switched 84 on explicitly. See the [TextView] documentation for more information. 85 86 A style tag's full format looks like this: 87 88 [<foreground>:<background>:<attribute flags>:<url>] 89 90 Each of the four fields can be left blank and trailing fields can be omitted. 91 (Empty square brackets "[]", however, are not considered style tags.) Fields 92 that are not specified will be left unchanged. A field with just a dash ("-") 93 means "reset to default". 94 95 You can specify the following flags to turn on certain attributes (some flags 96 may not be supported by your terminal): 97 98 l: blink 99 b: bold 100 i: italic 101 d: dim 102 r: reverse (switch foreground and background color) 103 u: underline 104 s: strike-through 105 106 Use uppercase letters to turn off the corresponding attribute, for example, 107 "B" to turn off bold. Uppercase letters have no effect if the attribute was not 108 previously set. 109 110 Setting a URL allows you to turn a piece of text into a hyperlink in some 111 terminals. Specify a dash ("-") to specify the end of the hyperlink. Hyperlinks 112 must only contain single-byte characters (e.g. ASCII) and they may not contain 113 bracket characters ("[" or "]"). 114 115 Examples: 116 117 [yellow]Yellow text 118 [yellow:red]Yellow text on red background 119 [:red]Red background, text color unchanged 120 [yellow::u]Yellow text underlined 121 [::bl]Bold, blinking text 122 [::-]Colors unchanged, flags reset 123 [-]Reset foreground color 124 [::i]Italic and [::I]not italic 125 Click [:::https://example.com]here[:::-] for example.com. 126 Send an email to [:::mailto:her@example.com]her/[:::mail:him@example.com]him/[:::mail:them@example.com]them[:::-]. 127 [-:-:-:-]Reset everything 128 [:]No effect 129 []Not a valid style tag, will print square brackets as they are 130 131 In the rare event that you want to display a string such as "[red]" or 132 "[#00ff1a]" without applying its effect, you need to put an opening square 133 bracket before the closing square bracket. Note that the text inside the 134 brackets will be matched less strictly than region or colors tags. I.e. any 135 character that may be used in color or region tags will be recognized. Examples: 136 137 [red[] will be output as [red] 138 ["123"[] will be output as ["123"] 139 [#6aff00[[] will be output as [#6aff00[] 140 [a#"[[[] will be output as [a#"[[] 141 [] will be output as [] (see style tags above) 142 [[] will be output as [[] (not an escaped tag) 143 144 You can use the Escape() function to insert brackets automatically where needed. 145 146 # Styles 147 148 When primitives are instantiated, they are initialized with colors taken from 149 the global [Styles] variable. You may change this variable to adapt the look and 150 feel of the primitives to your preferred style. 151 152 Note that most terminals will not report information about their color theme. 153 This package therefore does not support using the terminal's color theme. The 154 default style is a dark theme and you must change the [Styles] variable to 155 switch to a light (or other) theme. 156 157 # Unicode Support 158 159 This package supports all unicode characters supported by your terminal. 160 161 # Mouse Support 162 163 If your terminal supports mouse events, you can enable mouse support for your 164 application by calling [Application.EnableMouse]. Note that this may interfere 165 with your terminal's default mouse behavior. Mouse support is disabled by 166 default. 167 168 # Concurrency 169 170 Many functions in this package are not thread-safe. For many applications, this 171 is not an issue: If your code makes changes in response to key events, the 172 corresponding callback function will execute in the main goroutine and thus will 173 not cause any race conditions. (Exceptions to this are documented.) 174 175 If you access your primitives from other goroutines, however, you will need to 176 synchronize execution. The easiest way to do this is to call 177 [Application.QueueUpdate] or [Application.QueueUpdateDraw] (see the function 178 documentation for details): 179 180 go func() { 181 app.QueueUpdateDraw(func() { 182 table.SetCellSimple(0, 0, "Foo bar") 183 }) 184 }() 185 186 One exception to this is the io.Writer interface implemented by [TextView]. You 187 can safely write to a [TextView] from any goroutine. See the [TextView] 188 documentation for details. 189 190 You can also call [Application.Draw] from any goroutine without having to wrap 191 it in [Application.QueueUpdate]. And, as mentioned above, key event callbacks 192 are executed in the main goroutine and thus should not use 193 [Application.QueueUpdate] as that may lead to deadlocks. It is also not 194 necessary to call [Application.Draw] from such callbacks as it will be called 195 automatically. 196 197 # Type Hierarchy 198 199 All widgets listed above contain the [Box] type. All of [Box]'s functions are 200 therefore available for all widgets, too. Please note that if you are using the 201 functions of [Box] on a subclass, they will return a *Box, not the subclass. 202 This is a Golang limitation. So while tview supports method chaining in many 203 places, these chains must be broken when using [Box]'s functions. Example: 204 205 // This will cause "textArea" to be an empty Box. 206 textArea := tview.NewTextArea(). 207 SetMaxLength(256). 208 SetPlaceholder("Enter text here"). 209 SetBorder(true) 210 211 You will need to call [Box.SetBorder] separately: 212 213 textArea := tview.NewTextArea(). 214 SetMaxLength(256). 215 SetPlaceholder("Enter text here") 216 texArea.SetBorder(true) 217 218 All widgets also implement the [Primitive] interface. 219 220 The tview package's rendering is based on version 2 of 221 https://github.com/gdamore/tcell. It uses types and constants from that package 222 (e.g. colors, styles, and keyboard values). 223 */ 224 package tview