1 /* 2 Package cview implements rich widgets for terminal based user interfaces. 3 4 See the demos folder and the example application provided with the 5 NewApplication documentation for usage examples. 6 7 # Types 8 9 This package is built on top of tcell, which provides the types necessary to 10 create a terminal-based application (e.g. EventKey). For information on 11 inherited types see the tcell documentation. 12 13 tcell: https://github.com/gdamore/tcell 14 15 # Base Primitive 16 17 Widgets must implement the Primitive interface. All widgets embed the base 18 primitive, Box, and thus inherit its functions. This isn't necessarily 19 required, but it makes more sense than reimplementing Box's functionality in 20 each widget. 21 22 # Widgets 23 24 The following widgets are available: 25 26 Button - Button which is activated when the user selects it. 27 CheckBox - Selectable checkbox for boolean values. 28 DropDown - Drop-down selection field. 29 Flex - A Flexbox based layout manager. 30 Form - Form composed of input fields, drop down selections, checkboxes, and buttons. 31 Grid - A grid based layout manager. 32 InputField - Single-line text entry field. 33 List - A navigable text list with optional keyboard shortcuts. 34 Modal - A centered window with a text message and one or more buttons. 35 Panels - A panel based layout manager. 36 ProgressBar - Indicates the progress of an operation. 37 TabbedPanels - Panels widget with tabbed navigation. 38 Table - A scrollable display of tabular data. Table cells, rows, or columns 39 may also be highlighted. 40 TextView - A scrollable window that displays multi-colored text. Text may 41 also be highlighted. 42 TreeView - A scrollable display for hierarchical data. Tree nodes can be 43 highlighted, collapsed, expanded, and more. 44 Window - A draggable and resizable container. 45 46 Widgets may be used without an application created via NewApplication, allowing 47 them to be integrated into any tcell-based application. 48 49 # Concurrency 50 51 All functions may be called concurrently (they are thread-safe). When called 52 from multiple threads, functions will block until the application or widget 53 becomes available. Function calls may be queued with Application.QueueUpdate to 54 avoid blocking. 55 56 # Unicode Support 57 58 This package supports unicode characters including wide characters. 59 60 # Keyboard Shortcuts 61 62 Widgets use keyboard shortcuts (a.k.a. keybindings) such as arrow keys and 63 H/J/K/L by default. You may replace these defaults by modifying the shortcuts 64 listed in Keys. You may also override keyboard shortcuts globally by setting a 65 handler with Application.SetInputCapture. 66 67 cbind is a library which simplifies the process of adding support for custom 68 keyboard shortcuts to your application. It allows setting handlers for 69 EventKeys. It also translates between EventKeys and human-readable strings such 70 as "Alt+Enter". This makes it possible to store keybindings in a configuration 71 file. 72 73 cbind: https://codeberg.org/tslocum/cbind 74 75 # Bracketed Paste Mode 76 77 Bracketed paste mode is enabled by default. It may be disabled by calling 78 Application.EnableBracketedPaste before Application.Run. The following demo 79 shows how to handle paste events and process pasted text. 80 81 tcell bracketed paste demo: https://github.com/gdamore/tcell/blob/master/_demos/mouse.go 82 83 # Mouse Support 84 85 Mouse support may be enabled by calling Application.EnableMouse before 86 Application.Run. See the example application provided with the 87 Application.EnableMouse documentation. 88 89 Double clicks are treated single clicks by default. Specify a maximum duration 90 between clicks with Application.SetDoubleClickInterval to enable double clicks. 91 A standard duration is provided as StandardDoubleClick. 92 93 Mouse events are passed to: 94 95 - The handler set with SetMouseCapture, which is reserved for use by application 96 developers to permanently intercept mouse events. Return nil to stop 97 propagation. 98 99 - The MouseHandler method of the topmost widget under the mouse. 100 101 # Colors 102 103 Throughout this package, colors are specified using the tcell.Color type. 104 Functions such as tcell.GetColor(), tcell.NewHexColor(), and tcell.NewRGBColor() 105 can be used to create colors from W3C color names or RGB values. 106 107 Almost all strings which are displayed can contain color tags. Color tags are 108 W3C color names or six hexadecimal digits following a hash tag, wrapped in 109 square brackets. Examples: 110 111 This is a [red]warning[white]! 112 The sky is [#8080ff]blue[#ffffff]. 113 114 A color tag changes the color of the characters following that color tag. This 115 applies to almost everything from box titles, list text, form item labels, to 116 table cells. In a TextView, this functionality must be explicitly enabled. See 117 the TextView documentation for more information. 118 119 Color tags may contain not just the foreground (text) color but also the 120 background color and additional flags. In fact, the full definition of a color 121 tag is as follows: 122 123 [<foreground>:<background>:<flags>] 124 125 Each of the three fields can be left blank and trailing fields can be omitted. 126 (Empty square brackets "[]", however, are not considered color tags.) Colors 127 that are not specified will be left unchanged. A field with just a dash ("-") 128 means "reset to default". 129 130 You can specify the following flags (some flags may not be supported by your 131 terminal): 132 133 l: blink 134 b: bold 135 d: dim 136 i: italic 137 r: reverse (switch foreground and background color) 138 u: underline 139 s: strikethrough 140 141 Examples: 142 143 [yellow]Yellow text 144 [yellow:red]Yellow text on red background 145 [:red]Red background, text color unchanged 146 [yellow::u]Yellow text underlined 147 [::bl]Bold, blinking text 148 [::-]Colors unchanged, flags reset 149 [-]Reset foreground color 150 [-:-:-]Reset everything 151 [:]No effect 152 []Not a valid color tag, will print square brackets as they are 153 154 In the rare event that you want to display a string such as "[red]" or 155 "[#00ff1a]" without applying its effect, you need to put an opening square 156 bracket before the closing square bracket. Note that the text inside the 157 brackets will be matched less strictly than region or colors tags. I.e. any 158 character that may be used in color or region tags will be recognized. Examples: 159 160 [red[] will be output as [red] 161 ["123"[] will be output as ["123"] 162 [#6aff00[[] will be output as [#6aff00[] 163 [a#"[[[] will be output as [a#"[[] 164 [] will be output as [] (see color tags above) 165 [[] will be output as [[] (not an escaped tag) 166 167 You can use the Escape() function to insert brackets automatically where needed. 168 169 Setting the background color of a primitive to tcell.ColorDefault will use the 170 default terminal background color. To enable transparency (allowing one or more 171 primitives to display behind a primitive) call SetBackgroundTransparent. The 172 screen is not cleared before drawing the application. Overlaying transparent 173 widgets directly onto the screen may result in artifacts. To resolve this, add 174 a blank, non-transparent Box to the bottom layer of the interface via Panels, 175 or set a handler via SetBeforeDrawFunc which clears the screen. 176 177 # Styles 178 179 When primitives are instantiated, they are initialized with colors taken from 180 the global Styles variable. You may change this variable to adapt the look and 181 feel of the primitives to your preferred style. 182 183 # Scroll Bars 184 185 Scroll bars are supported by the following widgets: List, Table, TextView and 186 TreeView. Each widget will display scroll bars automatically when there are 187 additional items offscreen. See SetScrollBarColor and SetScrollBarVisibility. 188 189 # Hello World 190 191 The following is an example application which shows a box titled "Greetings" 192 containing the text "Hello, world!": 193 194 package main 195 196 import ( 197 "codeberg.org/tslocum/cview" 198 ) 199 200 func main() { 201 tv := cview.NewTextView() 202 tv.SetText("Hello, world!"). 203 SetBorder(true). 204 SetTitle("Greetings") 205 if err := cview.NewApplication().SetRoot(tv, true).Run(); err != nil { 206 panic(err) 207 } 208 } 209 210 First, we create a TextView with a border and a title. Then we create an 211 application, set the TextView as its root primitive, and run the event loop. 212 The application exits when the application's Stop() function is called or when 213 Ctrl-C is pressed. 214 215 If we have a primitive which consumes key presses, we call the application's 216 SetFocus() function to redirect all key presses to that primitive. Most 217 primitives then offer ways to install handlers that allow you to react to any 218 actions performed on them. 219 220 # Demos 221 222 The "demos" subdirectory contains a demo for each widget, as well as a 223 presentation which gives an overview of the widgets and how they may be used. 224 */ 225 package cview 226