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