...

Source file src/gitlab.com/tslocum/cview/doc.go

Documentation: gitlab.com/tslocum/cview

     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    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://gitlab.com/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.
   172  
   173  Styles
   174  
   175  When primitives are instantiated, they are initialized with colors taken from
   176  the global Styles variable. You may change this variable to adapt the look and
   177  feel of the primitives to your preferred style.
   178  
   179  Scroll Bars
   180  
   181  Scroll bars are supported by the following widgets: List, Table, TextView and
   182  TreeView. Each widget will display scroll bars automatically when there are
   183  additional items offscreen. See SetScrollBarColor and SetScrollBarVisibility.
   184  
   185  Hello World
   186  
   187  The following is an example application which shows a box titled "Greetings"
   188  containing the text "Hello, world!":
   189  
   190    package main
   191  
   192    import (
   193      "gitlab.com/tslocum/cview"
   194    )
   195  
   196    func main() {
   197      tv := cview.NewTextView()
   198      tv.SetText("Hello, world!").
   199         SetBorder(true).
   200         SetTitle("Greetings")
   201      if err := cview.NewApplication().SetRoot(tv, true).Run(); err != nil {
   202        panic(err)
   203      }
   204    }
   205  
   206  First, we create a TextView with a border and a title. Then we create an
   207  application, set the TextView as its root primitive, and run the event loop.
   208  The application exits when the application's Stop() function is called or when
   209  Ctrl-C is pressed.
   210  
   211  If we have a primitive which consumes key presses, we call the application's
   212  SetFocus() function to redirect all key presses to that primitive. Most
   213  primitives then offer ways to install handlers that allow you to react to any
   214  actions performed on them.
   215  
   216  Demos
   217  
   218  The "demos" subdirectory contains a demo for each widget, as well as a
   219  presentation which gives an overview of the widgets and how they may be used.
   220  */
   221  package cview
   222  

View as plain text