tview

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 1, 2018 License: MIT Imports: 9 Imported by: 1

README

Widgets for Terminal GUIs

Based on github.com/gdamore/tcell.

Work in progress.

Documentation

Overview

Package tview implements primitives for terminal based applications. It uses github.com/gdamore/tcell.

Hello World

Here 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. It exits when the application's Stop() function is called or when Ctrl-C is pressed.

If we have a primitive which consumes key presses, we call the application's SetFocus() function to redirect all key presses to that primitive. Most primitives then offer ways to install handlers that allow you to react to any actions performed on them.

No mouse input (yet).

Index

Constants

View Source 
const (
	FlexRow = iota
	FlexColumn
)

Configuration values.

View Source 
const (
	AlignLeft = iota
	AlignCenter
	AlignRight
)

Text alignment within a box.

View Source 
const (
	GraphicsHoriBar             = '\u2500'
	GraphicsVertBar             = '\u2502'
	GraphicsTopLeftCorner       = '\u250c'
	GraphicsTopRightCorner      = '\u2510'
	GraphicsBottomRightCorner   = '\u2518'
	GraphicsBottomLeftCorner    = '\u2514'
	GraphicsDbVertBar           = '\u2550'
	GraphicsDbHorBar            = '\u2551'
	GraphicsDbTopLeftCorner     = '\u2554'
	GraphicsDbTopRightCorner    = '\u2557'
	GraphicsDbBottomRightCorner = '\u255d'
	GraphicsDbBottomLeftCorner  = '\u255a'
	GraphicsRightT              = '\u2524'
	GraphicsLeftT               = '\u251c'
	GraphicsTopT                = '\u252c'
	GraphicsBottomT             = '\u2534'
	GraphicsCross               = '\u253c'
	GraphicsEllipsis            = '\u2026'
)

Semigraphical runes.

Variables

View Source 
var (
	// InputFieldInteger accepts integers.
	InputFieldInteger func(text string, ch rune) bool

	// InputFieldFloat accepts floating-point numbers.
	InputFieldFloat func(text string, ch rune) bool

	// InputFieldMaxLength returns an input field accept handler which accepts
	// input strings up to a given length. Use it like this:
	//
	//   inputField.SetAcceptanceFunc(InputFieldMaxLength(10)) // Accept up to 10 characters.
	InputFieldMaxLength func(maxLength int) func(text string, ch rune) bool
)

Functions

func Print 

func Print(screen tcell.Screen, text string, x, y, maxWidth, align int, color tcell.Color) int

Print prints text onto the screen into the given box at (x,y,maxWidth,1), no exceeding that box. "align" is one of AlignLeft, AlignCenter, or AlignRight. The screen's background color will be maintained.

Returns the number of actual runes printed.

func PrintSimple 

func PrintSimple(screen tcell.Screen, text string, x, y int)

PrintSimple prints white text to the screen at the given position.

func WordWrap 

func WordWrap(text string, width int) (lines []string)

WordWrap splits a text such that each resulting line does not exceed the given width. Possible split points are after commas, dots, dashes, and any whitespace. Whitespace at split points will be dropped.

Text is always split at newline characters ('\n').

Types

type Application 

type Application struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Application represents the top node of an application.

It is not strictly required to use this class as none of the other classes depend on it. However, it provides useful tools to set up an application and plays nicely with all widgets.

func NewApplication 

func NewApplication() *Application

NewApplication creates and returns a new application.

func (*Application) Draw 

func (a *Application) Draw() *Application

Draw refreshes the screen. It calls the Draw() function of the application's root primitive and then syncs the screen buffer.

func (*Application) GetFocus 

func (a *Application) GetFocus() Primitive

GetFocus returns the primitive which has the current focus. If none has it, nil is returned.

func (*Application) ResizeToFullScreen 

func (a *Application) ResizeToFullScreen(p Primitive) *Application

ResizeToFullScreen resizes the given primitive such that it fills the entire screen.

func (*Application) Run 

func (a *Application) Run() error

Run starts the application and thus the event loop. This function returns when Stop() was called.

func (*Application) SetFocus 

func (a *Application) SetFocus(p Primitive) *Application

SetFocus sets the focus on a new primitive. All key events will be redirected to that primitive. Callers must ensure that the primitive will handle key events.

Blur() will be called on the previously focused primitive. Focus() will be called on the new primitive.

func (*Application) SetKeyCapture 

func (a *Application) SetKeyCapture(key tcell.Key, ch rune, handler func(p Primitive) bool) *Application

SetKeyCapture installs a global capture function for the given key. It intercepts all events for the given key and routes them to the handler. The handler receives the Primitive to which the key is originally redirected, the one which has focus, or nil if it was not directed to a Primitive. The handler also returns whether or not the key event is then forwarded to that Primitive.

Special keys (e.g. Escape, Enter, or Ctrl-A) are defined by the "key" argument. The "ch" rune is ignored. Other keys (e.g. "a", "h", or "5") are specified by their rune, with key set to tcell.KeyRune. See also https://godoc.org/github.com/gdamore/tcell#EventKey for more information.

To remove a handler again, provide a nil handler for the same key.

The application itself will exit when Ctrl-C is pressed. You can intercept this with this function as well.

func (*Application) SetRoot 

func (a *Application) SetRoot(root Primitive, autoSize bool) *Application

SetRoot sets the root primitive for this application. This function must be called or nothing will be displayed when the application starts.

It also calls SetFocus() on the primitive.

func (*Application) Stop 

func (a *Application) Stop()

Stop stops the application, causing Run() to return.

type Box 

type Box struct {
	// contains filtered or unexported fields
}

Box implements Primitive with a background and optional elements such as a border and a title. Most subclasses keep their content contained in the box but don't necessarily have to.

func NewBox 

func NewBox() *Box

NewBox returns a Box without a border.

func (*Box) Blur 

func (b *Box) Blur()

Blur is called when this primitive loses focus.

func (*Box) Draw 

func (b *Box) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Box) Focus 

func (b *Box) Focus(delegate func(p Primitive))

Focus is called when this primitive receives focus.

func (*Box) GetFocusable 

func (b *Box) GetFocusable() Focusable

GetFocusable returns the item's Focusable.

func (*Box) GetInnerRect 

func (b *Box) GetInnerRect() (int, int, int, int)

GetInnerRect returns the position of the inner rectangle, without the border and without any padding.

func (*Box) GetRect 

func (b *Box) GetRect() (int, int, int, int)

GetRect returns the current position of the rectangle, x, y, width, and height.

func (*Box) HasFocus 

func (b *Box) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Box) InputHandler 

func (b *Box) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns nil.

func (*Box) SetBackgroundColor 

func (b *Box) SetBackgroundColor(color tcell.Color) *Box

SetBackgroundColor sets the box's background color.

func (*Box) SetBorder 

func (b *Box) SetBorder(show bool) *Box

SetBorder sets the flag indicating whether or not the box should have a border.

func (*Box) SetBorderColor 

func (b *Box) SetBorderColor(color tcell.Color) *Box

SetBorderColor sets the box's border color.

func (*Box) SetBorderPadding 

func (b *Box) SetBorderPadding(top, bottom, left, right int) *Box

SetBorderPadding sets the size of the borders around the box content.

func (*Box) SetRect 

func (b *Box) SetRect(x, y, width, height int)

SetRect sets a new position of the rectangle.

func (*Box) SetTitle 

func (b *Box) SetTitle(title string) *Box

SetTitle sets the box's title.

func (*Box) SetTitleAlign 

func (b *Box) SetTitleAlign(align int) *Box

SetTitleAlign sets the alignment of the title, one of AlignLeft, AlignCenter, or AlignRight.

func (*Box) SetTitleColor 

func (b *Box) SetTitleColor(color tcell.Color) *Box

SetTitleColor sets the box's title color.

type Button 

type Button struct {
	*Box
	// contains filtered or unexported fields
}

Button is labeled box that triggers an action when selected.

func NewButton 

func NewButton(label string) *Button

NewButton returns a new input field.

func (*Button) Draw 

func (b *Button) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Button) GetLabel 

func (b *Button) GetLabel() string

GetLabel returns the button text.

func (*Button) InputHandler 

func (b *Button) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*Button) SetBackgroundColorActivated 

func (b *Button) SetBackgroundColorActivated(color tcell.Color) *Button

SetBackgroundColorActivated sets the background color of the button text when the button is in focus.

func (*Button) SetBlurFunc 

func (b *Button) SetBlurFunc(handler func(key tcell.Key)) *Button

SetBlurFunc sets a handler which is called when the user leaves the button. The callback function is provided with the key that was pressed, which is one of the following:

  • KeyEscape: Leaving the button with no specific direction.
  • KeyTab: Move to the next field.
  • KeyBacktab: Move to the previous field.

func (*Button) SetLabel 

func (b *Button) SetLabel(label string) *Button

SetLabel sets the button text.

func (*Button) SetLabelColor 

func (b *Button) SetLabelColor(color tcell.Color) *Button

SetLabelColor sets the color of the button text.

func (*Button) SetLabelColorActivated 

func (b *Button) SetLabelColorActivated(color tcell.Color) *Button

SetLabelColorActivated sets the color of the button text when the button is in focus.

func (*Button) SetSelectedFunc 

func (b *Button) SetSelectedFunc(handler func()) *Button

SetSelectedFunc sets a handler which is called when the button was selected.

type Checkbox 

type Checkbox struct {
	*Box
	// contains filtered or unexported fields
}

Checkbox is a one-line box (three lines if there is a title) where the user can enter text.

func NewCheckbox 

func NewCheckbox() *Checkbox

NewCheckbox returns a new input field.

func (*Checkbox) Draw 

func (c *Checkbox) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Checkbox) GetLabel 

func (c *Checkbox) GetLabel() string

GetLabel returns the text to be displayed before the input area.

func (*Checkbox) InputHandler 

func (c *Checkbox) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*Checkbox) SetChangedFunc 

func (c *Checkbox) SetChangedFunc(handler func(checked bool)) *Checkbox

SetChangedFunc sets a handler which is called when the checked state of this checkbox was changed by the user. The handler function receives the new state.

func (*Checkbox) SetChecked 

func (c *Checkbox) SetChecked(checked bool) *Checkbox

SetChecked sets the state of the checkbox.

func (*Checkbox) SetDoneFunc 

func (c *Checkbox) SetDoneFunc(handler func(key tcell.Key)) *Checkbox

SetDoneFunc sets a handler which is called when the user is done entering text. The callback function is provided with the key that was pressed, which is one of the following:

  • KeyEscape: Abort text input.
  • KeyTab: Move to the next field.
  • KeyBacktab: Move to the previous field.

func (*Checkbox) SetFieldBackgroundColor 

func (c *Checkbox) SetFieldBackgroundColor(color tcell.Color) *Checkbox

SetFieldBackgroundColor sets the background color of the input area.

func (*Checkbox) SetFieldTextColor 

func (c *Checkbox) SetFieldTextColor(color tcell.Color) *Checkbox

SetFieldTextColor sets the text color of the input area.

func (*Checkbox) SetFinishedFunc 

func (c *Checkbox) SetFinishedFunc(handler func(key tcell.Key)) FormItem

SetFinishedFunc calls SetDoneFunc().

func (*Checkbox) SetFormAttributes 

func (c *Checkbox) SetFormAttributes(label string, labelColor, bgColor, fieldTextColor, fieldBgColor tcell.Color) FormItem

SetFormAttributes sets attributes shared by all form items.

func (*Checkbox) SetLabel 

func (c *Checkbox) SetLabel(label string) *Checkbox

SetLabel sets the text to be displayed before the input area.

func (*Checkbox) SetLabelColor 

func (c *Checkbox) SetLabelColor(color tcell.Color) *Checkbox

SetLabelColor sets the color of the label. 

type DropDown struct {
	*Box
	// contains filtered or unexported fields
}

DropDown is a one-line box (three lines if there is a title) where the user can enter text.

func NewDropDown 

func NewDropDown() *DropDown

NewDropDown returns a new drop-down. 

func (d *DropDown) AddOption(text string, selected func()) *DropDown

AddOption adds a new selectable option to this drop-down. The "selected" callback is called when this option was selected. It may be nil. 

func (d *DropDown) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen. 

func (d *DropDown) Focus(delegate func(p Primitive))

Focus is called by the application when the primitive receives focus. 

func (d *DropDown) GetLabel() string

GetLabel returns the text to be displayed before the input area. 

func (d *DropDown) HasFocus() bool

HasFocus returns whether or not this primitive has focus. 

func (d *DropDown) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive. 

func (d *DropDown) SetCurrentOption(index int) *DropDown

SetCurrentOption sets the index of the currently selected option. 

func (d *DropDown) SetDoneFunc(handler func(key tcell.Key)) *DropDown

SetDoneFunc sets a handler which is called when the user is done selecting options. The callback function is provided with the key that was pressed, which is one of the following:

  • KeyEscape: Abort selection.
  • KeyTab: Move to the next field.
  • KeyBacktab: Move to the previous field.
func (d *DropDown) SetFieldBackgroundColor(color tcell.Color) *DropDown

SetFieldBackgroundColor sets the background color of the options area. 

func (d *DropDown) SetFieldLength(length int) *DropDown

SetFieldLength sets the length of the options area. A value of 0 means extend to as long as the longest option text. 

func (d *DropDown) SetFieldTextColor(color tcell.Color) *DropDown

SetFieldTextColor sets the text color of the options area. 

func (d *DropDown) SetFinishedFunc(handler func(key tcell.Key)) FormItem

SetFinishedFunc calls SetDoneFunc(). 

func (d *DropDown) SetFormAttributes(label string, labelColor, bgColor, fieldTextColor, fieldBgColor tcell.Color) FormItem

SetFormAttributes sets attributes shared by all form items. 

func (d *DropDown) SetLabel(label string) *DropDown

SetLabel sets the text to be displayed before the input area. 

func (d *DropDown) SetLabelColor(color tcell.Color) *DropDown

SetLabelColor sets the color of the label. 

func (d *DropDown) SetOptions(texts []string, selected func(text string, index int)) *DropDown

SetOptions replaces all current options with the ones provided and installs one callback function which is called when one of the options is selected. It will be called with the option's text and its index into the options slice. The "selected" parameter may be nil.

type Flex 

type Flex struct {
	*Box
	// contains filtered or unexported fields
}

Flex is a basic implementation of a flexbox layout.

func NewFlex 

func NewFlex() *Flex

NewFlex returns a new flexbox layout container with the given primitives. The items all have no fixed size. If more control is needed, call AddItem(). The direction argument must be FlexRow or FlexColumn.

func (*Flex) AddItem 

func (f *Flex) AddItem(item Primitive, fixedSize, proportion int, focus bool) *Flex

AddItem adds a new item to the container. The "fixedSize" argument is a width or height that may not be changed by the layout algorithm. A value of 0 means that its size is flexible and may be changed. The "proportion" argument defines the relative size of the item compared to other flexible-size items. For example, items with a proportion of 2 will be twice as large as items with a proportion of 1. Must be at least 1 if fixedSize > 0 (ignored otherwise)

If "focus" is set to true, the item will receive focus when the Flex primitive receives focus. If multiple items have the "focus" flag set to true, the first one will receive focus.

func (*Flex) Draw 

func (f *Flex) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Flex) Focus 

func (f *Flex) Focus(delegate func(p Primitive))

Focus is called when this primitive receives focus.

func (*Flex) HasFocus 

func (f *Flex) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Flex) SetDirection 

func (f *Flex) SetDirection(direction int) *Flex

SetDirection sets the direction in which the contained primitives are distributed. This can be either FlexColumn (default) or FlexRow.

func (*Flex) SetFullScreen 

func (f *Flex) SetFullScreen(fullScreen bool) *Flex

SetFullScreen sets the flag which, when true, causes the flex layout to use the entire screen space instead of whatever size it is currently assigned to.

type Focusable 

type Focusable interface {
	HasFocus() bool
}

Focusable provides a method which determines if a primitive has focus. Composed primitives may be focused based on the focused state of their contained primitives.

type Form 

type Form struct {
	*Box
	// contains filtered or unexported fields
}

Form is a Box which contains multiple input fields, one per row.

func NewForm 

func NewForm() *Form

NewForm returns a new form.

func (*Form) AddButton 

func (f *Form) AddButton(label string, selected func()) *Form

AddButton adds a new button to the form. The "selected" function is called when the user selects this button. It may be nil.

func (*Form) AddCheckbox 

func (f *Form) AddCheckbox(label string, checked bool, changed func(checked bool)) *Form

AddCheckbox adds a checkbox to the form. It has a label, an initial state, and an (optional) callback function which is invoked when the state of the checkbox was changed by the user.

func (*Form) AddDropDown 

func (f *Form) AddDropDown(label string, options []string, initialOption int, selected func(option string, optionIndex int)) *Form

AddDropDown adds a drop-down element to the form. It has a label, options, and an (optional) callback function which is invoked when an option was selected.

func (*Form) AddInputField 

func (f *Form) AddInputField(label, value string, fieldLength int, accept func(textToCheck string, lastChar rune) bool) *Form

AddInputField adds an input field to the form. It has a label, an optional initial value, a field length (a value of 0 extends it as far as possible), and an optional accept function to validate the item's value (set to nil to accept any text).

func (*Form) Draw 

func (f *Form) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Form) Focus 

func (f *Form) Focus(delegate func(p Primitive))

Focus is called by the application when the primitive receives focus.

func (*Form) HasFocus 

func (f *Form) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Form) SetButtonBackgroundColor 

func (f *Form) SetButtonBackgroundColor(color tcell.Color) *Form

SetButtonBackgroundColor sets the background color of the buttons.

func (*Form) SetButtonTextColor 

func (f *Form) SetButtonTextColor(color tcell.Color) *Form

SetButtonTextColor sets the color of the button texts.

func (*Form) SetButtonsAlign 

func (f *Form) SetButtonsAlign(align int) *Form

SetButtonsAlign sets how the buttons align horizontally, one of AlignLeft (the default), AlignCenter, and AlignRight.

func (*Form) SetCancelFunc 

func (f *Form) SetCancelFunc(callback func()) *Form

SetCancelFunc sets a handler which is called when the user hits the Escape key.

func (*Form) SetFieldBackgroundColor 

func (f *Form) SetFieldBackgroundColor(color tcell.Color) *Form

SetFieldBackgroundColor sets the background color of the input areas.

func (*Form) SetFieldTextColor 

func (f *Form) SetFieldTextColor(color tcell.Color) *Form

SetFieldTextColor sets the text color of the input areas.

func (*Form) SetItemPadding 

func (f *Form) SetItemPadding(padding int) *Form

SetItemPadding sets the number of empty rows between form items.

func (*Form) SetLabelColor 

func (f *Form) SetLabelColor(color tcell.Color) *Form

SetLabelColor sets the color of the labels.

type FormItem 

type FormItem interface {
	Primitive

	// GetLabel returns the item's label text.
	GetLabel() string

	// SetFormAttributes sets a number of item attributes at once.
	SetFormAttributes(label string, labelColor, bgColor, fieldTextColor, fieldBgColor tcell.Color) FormItem

	// SetEnteredFunc sets the handler function for when the user finished
	// entering data into the item. The handler may receive events for the
	// Enter key (we're done), the Escape key (cancel input), the Tab key (move to
	// next field), and the Backtab key (move to previous field).
	SetFinishedFunc(handler func(key tcell.Key)) FormItem
}

FormItem is the interface all form items must implement to be able to be included in a form.

type Frame 

type Frame struct {
	*Box
	// contains filtered or unexported fields
}

Frame is a wrapper which adds a border around another primitive. The top area (header) and the bottom area (footer) may also contain text.

func NewFrame 

func NewFrame(primitive Primitive) *Frame

NewFrame returns a new frame around the given primitive. The primitive's size will be changed to fit within this frame.

func (*Frame) AddText 

func (f *Frame) AddText(text string, header bool, align int, color tcell.Color) *Frame

AddText adds text to the frame. Set "header" to true if the text is to appear in the header, above the contained primitive. Set it to false for it to appear in the footer, below the contained primitive. "align" must be one of the Align constants. Rows in the header are printed top to bottom, rows in the footer are printed bottom to top. Note that long text can overlap as different alignments will be placed on the same row.

func (*Frame) Clear 

func (f *Frame) Clear() *Frame

Clear removes all text from the frame.

func (*Frame) Draw 

func (f *Frame) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Frame) Focus 

func (f *Frame) Focus(delegate func(p Primitive))

Focus is called when this primitive receives focus.

func (*Frame) HasFocus 

func (f *Frame) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Frame) SetBorders 

func (f *Frame) SetBorders(top, bottom, header, footer, left, right int) *Frame

SetBorders sets the width of the frame borders as well as "header" and "footer", the vertical space between the header and footer text and the contained primitive (does not apply if there is no text).

type InputField 

type InputField struct {
	*Box
	// contains filtered or unexported fields
}

InputField is a one-line box (three lines if there is a title) where the user can enter text.

func NewInputField 

func NewInputField() *InputField

NewInputField returns a new input field.

func (*InputField) Draw 

func (i *InputField) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*InputField) GetLabel 

func (i *InputField) GetLabel() string

GetLabel returns the text to be displayed before the input area.

func (*InputField) GetText 

func (i *InputField) GetText() string

GetText returns the current text of the input field.

func (*InputField) InputHandler 

func (i *InputField) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*InputField) SetAcceptanceFunc 

func (i *InputField) SetAcceptanceFunc(handler func(textToCheck string, lastChar rune) bool) *InputField

SetAcceptanceFunc sets a handler which may reject the last character that was entered (by returning false).

This package defines a number of variables Prefixed with InputField which may be used for common input (e.g. numbers, maximum text length).

func (*InputField) SetDoneFunc 

func (i *InputField) SetDoneFunc(handler func(key tcell.Key)) *InputField

SetDoneFunc sets a handler which is called when the user is done entering text. The callback function is provided with the key that was pressed, which is one of the following:

  • KeyEnter: Done entering text.
  • KeyEscape: Abort text input.
  • KeyTab: Move to the next field.
  • KeyBacktab: Move to the previous field.

func (*InputField) SetFieldBackgroundColor 

func (i *InputField) SetFieldBackgroundColor(color tcell.Color) *InputField

SetFieldBackgroundColor sets the background color of the input area.

func (*InputField) SetFieldLength 

func (i *InputField) SetFieldLength(length int) *InputField

SetFieldLength sets the length of the input area. A value of 0 means extend as much as possible.

func (*InputField) SetFieldTextColor 

func (i *InputField) SetFieldTextColor(color tcell.Color) *InputField

SetFieldTextColor sets the text color of the input area.

func (*InputField) SetFinishedFunc 

func (i *InputField) SetFinishedFunc(handler func(key tcell.Key)) FormItem

SetFinishedFunc calls SetDoneFunc().

func (*InputField) SetFormAttributes 

func (i *InputField) SetFormAttributes(label string, labelColor, bgColor, fieldTextColor, fieldBgColor tcell.Color) FormItem

SetFormAttributes sets attributes shared by all form items.

func (*InputField) SetLabel 

func (i *InputField) SetLabel(label string) *InputField

SetLabel sets the text to be displayed before the input area.

func (*InputField) SetLabelColor 

func (i *InputField) SetLabelColor(color tcell.Color) *InputField

SetLabelColor sets the color of the label.

func (*InputField) SetText 

func (i *InputField) SetText(text string) *InputField

SetText sets the current text of the input field.

type List 

type List struct {
	*Box
	// contains filtered or unexported fields
}

List displays rows of items, each of which can be selected.

func NewList 

func NewList() *List

NewList returns a new form.

func (*List) AddItem 

func (l *List) AddItem(mainText, secondaryText string, shortcut rune, selected func()) *List

AddItem adds a new item to the list. An item has a main text which will be highlighted when selected. It also has a secondary text which is shown underneath the main text (if it is set to visible) but which may remain empty.

The shortcut is a key binding. If the specified rune is entered, the item is selected immediately. Set to 0 for no binding.

The "selected" callback will be invoked when the user selects the item. You may provide nil if no such item is needed or if all events are handled through the selected callback set with SetSelectedFunc().

func (*List) Clear 

func (l *List) Clear() *List

Clear removes all items from the list.

func (*List) Draw 

func (l *List) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*List) InputHandler 

func (l *List) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*List) SetChangedFunc 

func (l *List) SetChangedFunc(handler func(int, string, string, rune)) *List

SetChangedFunc sets the function which is called when the user navigates to a list item. The function receives the item's index in the list of items (starting with 0), its main text, secondary text, and its shortcut rune.

This function is also called when the first item is added or when SetCurrentItem() is called.

func (*List) SetCurrentItem 

func (l *List) SetCurrentItem(index int) *List

SetCurrentItem sets the currently selected item by its index.

func (*List) SetDoneFunc 

func (l *List) SetDoneFunc(handler func()) *List

SetDoneFunc sets a function which is called when the user presses the Escape key.

func (*List) SetMainTextColor 

func (l *List) SetMainTextColor(color tcell.Color) *List

SetMainTextColor sets the color of the items' main text.

func (*List) SetSecondaryTextColor 

func (l *List) SetSecondaryTextColor(color tcell.Color) *List

SetSecondaryTextColor sets the color of the items' secondary text.

func (*List) SetSelectedBackgroundColor 

func (l *List) SetSelectedBackgroundColor(color tcell.Color) *List

SetSelectedBackgroundColor sets the background color of selected items.

func (*List) SetSelectedFunc 

func (l *List) SetSelectedFunc(handler func(int, string, string, rune)) *List

SetSelectedFunc sets the function which is called when the user selects a list item by pressing Enter on the current selection. The function receives the item's index in the list of items (starting with 0), its main text, secondary text, and its shortcut rune.

func (*List) SetSelectedTextColor 

func (l *List) SetSelectedTextColor(color tcell.Color) *List

SetSelectedTextColor sets the text color of selected items.

func (*List) SetShortcutColor 

func (l *List) SetShortcutColor(color tcell.Color) *List

SetShortcutColor sets the color of the items' shortcut.

func (*List) ShowSecondaryText 

func (l *List) ShowSecondaryText(show bool) *List

ShowSecondaryText determines whether or not to show secondary item texts. 

type Modal struct {
	*Box
	// contains filtered or unexported fields
}

Modal is a centered message window used to inform the user or prompt them for an immediate decision. It needs to have at least one button (added via AddButtons()) or it will never disappear.

func NewModal 

func NewModal() *Modal

NewModal returns a new modal message window.

func (*Modal) AddButtons 

func (m *Modal) AddButtons(labels []string) *Modal

AddButtons adds buttons to the window. There must be at least one button and a "done" handler so the window can be closed again.

func (*Modal) Draw 

func (m *Modal) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Modal) Focus 

func (m *Modal) Focus(delegate func(p Primitive))

Focus is called when this primitive receives focus.

func (*Modal) HasFocus 

func (m *Modal) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Modal) SetDoneFunc 

func (m *Modal) SetDoneFunc(handler func(buttonIndex int, buttonLabel string)) *Modal

SetDoneFunc sets a handler which is called when one of the buttons was pressed. It receives the index of the button as well as its label text. The handler is also called when the user presses the Escape key. The index will then be negative and the label text an emptry string.

func (*Modal) SetText 

func (m *Modal) SetText(text string) *Modal

SetText sets the message text of the window. The text may contain line breaks. Note that words are wrapped, too, based on the final size of the window.

func (*Modal) SetTextColor 

func (m *Modal) SetTextColor(color tcell.Color) *Modal

SetTextColor sets the color of the message text.

type Pages 

type Pages struct {
	*Box
	// contains filtered or unexported fields
}

Pages is a container for other primitives often used as the application's root primitive. It allows to easily switch the visibility of the contained primitives.

func NewPages 

func NewPages() *Pages

NewPages returns a new Pages object.

func (*Pages) AddPage 

func (p *Pages) AddPage(name string, item Primitive, resize, visible bool) *Pages

AddPage adds a new page with the given name and primitive. Leaving the name empty or using the same name for multiple items may cause conflicts in other functions.

Visible pages will be drawn in the order they were added (unless that order was changed in one of the other functions). If "resize" is set to true, the primitive will be set to the size available to the Pages primitive whenever the pages are drawn.

func (*Pages) Draw 

func (p *Pages) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Pages) Focus 

func (p *Pages) Focus(delegate func(p Primitive))

Focus is called by the application when the primitive receives focus.

func (*Pages) HasFocus 

func (p *Pages) HasFocus() bool

HasFocus returns whether or not this primitive has focus.

func (*Pages) HasPage 

func (p *Pages) HasPage(name string) bool

HasPage returns true if a page with the given name exists in this object.

func (*Pages) HidePage 

func (p *Pages) HidePage(name string) *Pages

HidePage sets a page's visibility to "false".

func (*Pages) RemovePage 

func (p *Pages) RemovePage(name string) *Pages

RemovePage removes the page with the given name.

func (*Pages) SendToBack 

func (p *Pages) SendToBack(name string) *Pages

SendToBack changes the order of the pages such that the page with the given name comes first, causing it to be drawn first with the next update (if visible).

func (*Pages) SendToFront 

func (p *Pages) SendToFront(name string) *Pages

SendToFront changes the order of the pages such that the page with the given name comes last, causing it to be drawn last with the next update (if visible).

func (*Pages) SetChangedFunc 

func (p *Pages) SetChangedFunc(handler func()) *Pages

SetChangedFunc sets a handler which is called whenever the visibility or the order of any visible pages changes. This can be used to redraw the pages.

func (*Pages) ShowPage 

func (p *Pages) ShowPage(name string) *Pages

ShowPage sets a page's visibility to "true" (in addition to any other pages which are already visible).

func (*Pages) SwitchToPage 

func (p *Pages) SwitchToPage(name string) *Pages

SwitchToPage sets a page's visibility to "true" and all other pages' visibility to "false".

type Primitive 

type Primitive interface {
	// Draw draws this primitive onto the screen. Implementers can call the
	// screen's ShowCursor() function but should only do so when they have focus.
	// (They will need to keep track of this themselves.)
	Draw(screen tcell.Screen)

	// GetRect returns the current position of the primitive, x, y, width, and
	// height.
	GetRect() (int, int, int, int)

	// SetRect sets a new position of the primitive.
	SetRect(x, y, width, height int)

	// InputHandler returns a handler which receives key events when it has focus.
	// It is called by the Application class.
	//
	// A value of nil may also be returned, in which case this primitive cannot
	// receive focus and will not process any key events.
	//
	// The handler will receive the key event and a function that allows it to
	// set the focus to a different primitive, so that future key events are sent
	// to that primitive.
	//
	// The Application's Draw() function will be called automatically after the
	// handler returns.
	InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

	// Focus is called by the application when the primitive receives focus.
	// Implementers may call delegate() to pass the focus on to another primitive.
	Focus(delegate func(p Primitive))

	// Blur is called by the application when the primitive loses focus.
	Blur()

	// GetFocusable returns the item's Focusable.
	GetFocusable() Focusable
}

Primitive is the top-most interface for all graphical primitives.

type Table 

type Table struct {
	*Box
	// contains filtered or unexported fields
}

Table visualizes two-dimensional data consisting of rows and columns. Each Table cell is defined via SetCell() by the TableCell type. They can be added dynamically to the table and changed any time.

The most compact display of a table is without borders. Each row will then occupy one row on screen and columns are seperated by the rune defined via SetSeparator() (a space character by default).

When borders are turned on (via SetBorders()), each table cell is surrounded by lines. Therefore one table row will require two rows on screen.

Columns will use as much horizontal space as they need. You can constrain their size with the MaxWidth parameter of the TableCell type.

Fixed Columns

You can define fixed rows and rolumns via SetFixed(). They will always stay in their place, even when the table is scrolled. Fixed rows are always the top rows. Fixed columns are always the leftmost columns.

Selections

You can call SetSelectable() to set columns and/or rows to "selectable". If the flag is set only for columns, entire columns can be selected by the user. If it is set only for rows, entire rows can be selected. If both flags are set, individual cells can be selected. The "selected" handler set via SetSelectedFunc() is invoked when the user presses Enter on a selection.

Navigation

If the table extends beyond the available space, it can be navigated with key bindings similar to Vim:

  • h, left arrow: Move left by one column.
  • l, right arrow: Move right by one column.
  • j, down arrow: Move down by one row.
  • k, up arrow: Move up by one row.
  • g, home: Move to the top.
  • G, end: Move to the bottom.
  • Ctrl-F, page down: Move down by one page.
  • Ctrl-B, page up: Move up by one page.

When there is no selection, this affects the entire table (except for fixed rows and columns). When there is a selection, the user moves the selection. The class will attempt to keep the selection from moving out of the screen.

func NewTable 

func NewTable() *Table

NewTable returns a new table.

func (*Table) Clear 

func (t *Table) Clear() *Table

Clear removes all table data.

func (*Table) Draw 

func (t *Table) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*Table) GetCell 

func (t *Table) GetCell(row, column int) *TableCell

GetCell returns the contents of the cell at the specified position. A valid TableCell object is always returns but it will be uninitialized if the cell was not previously set.

func (*Table) GetColumnCount 

func (t *Table) GetColumnCount() int

GetColumnCount returns the (maximum) number of columns in the table.

func (*Table) GetRowCount 

func (t *Table) GetRowCount() int

GetRowCount returns the number of rows in the table.

func (*Table) InputHandler 

func (t *Table) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*Table) ScrollToBeginning 

func (t *Table) ScrollToBeginning() *Table

ScrollToBeginning scrolls the table to the beginning to that the top left corner of the table is shown. Note that this position may be corrected if there is a selection.

func (*Table) ScrollToEnd 

func (t *Table) ScrollToEnd() *Table

ScrollToEnd scrolls the table to the beginning to that the bottom left corner of the table is shown. Adding more rows to the table will cause it to automatically scroll with the new data. Note that this position may be corrected if there is a selection.

func (*Table) Select 

func (t *Table) Select(row, column int) *Table

Select sets the selected cell. Depending on the selection settings specified via SetSelectable(), this may be an entire row or column, or even ignored completely.

func (*Table) SetBorders 

func (t *Table) SetBorders(show bool) *Table

SetBorders sets whether or not each cell in the table is surrounded by a border.

func (*Table) SetBordersColor 

func (t *Table) SetBordersColor(color tcell.Color) *Table

SetBordersColor sets the color of the cell borders.

func (*Table) SetCell 

func (t *Table) SetCell(row, column int, cell *TableCell) *Table

SetCell sets the content of a cell the specified position. It is ok to directly instantiate a TableCell object. If the cell has contain, at least the Text and Color fields should be set.

Note that setting cells in previously unknown rows and columns will automatically extend the internal table representation, e.g. starting with a row of 100,000 will immediately create 100,000 empty rows.

To avoid unnecessary garbage collection, fill columns from left to right.

func (*Table) SetCellSimple 

func (t *Table) SetCellSimple(row, column int, text string) *Table

SetCellSimple calls SetCell() with the given text, left-aligned, in white.

func (*Table) SetDoneFunc 

func (t *Table) SetDoneFunc(handler func(key tcell.Key)) *Table

SetDoneFunc sets a handler which is called whenever the user presses the Escape, Tab, or Backtab key. If nothing is selected, it is also called when user presses the Enter key (because pressing Enter on a selection triggers the "selected" handler set via SetSelectedFunc()).

func (*Table) SetFixed 

func (t *Table) SetFixed(rows, columns int) *Table

SetFixed sets the number of fixed rows and columns which are always visible even when the rest of the cells are scrolled out of view. Rows are always the top-most ones. Columns are always the left-most ones.

func (*Table) SetOffset 

func (t *Table) SetOffset(row, column int) *Table

SetOffset sets how many rows and columns should be skipped when drawing the table. This is useful for large tables that do not fit on the screen. Navigating a selection can change these values.

Fixed rows and columns are never skipped.

func (*Table) SetSelectable 

func (t *Table) SetSelectable(rows, columns bool) *Table

SetSelectable sets the flags which determine what can be selected in a table. There are three selection modi:

  • rows = false, columns = false: Nothing can be selected.
  • rows = true, columns = false: Rows can be selected.
  • rows = false, columns = true: Columns can be selected.
  • rows = true, columns = true: Individual cells can be selected.

func (*Table) SetSelectedFunc 

func (t *Table) SetSelectedFunc(handler func(row, column int)) *Table

SetSelectedFunc sets a handler which is called whenever the user presses the Enter key on a selected cell/row/column. The handler receives the position of the selection and its cell contents. If entire rows are selected, the column index is undefined. Likewise for entire columns.

func (*Table) SetSeparator 

func (t *Table) SetSeparator(separator rune) *Table

SetSeparator sets the character used to fill the space between two neighboring cells. This is a space character ' ' per default but you may want to set it to GraphicsVertBar (or any other rune) if the column separation should be more visible. If cell borders are activated, this is ignored.

Separators have the same color as borders.

type TableCell 

type TableCell struct {
	// The text to be displayed in the table cell.
	Text string

	// The alignment of the cell text. One of AlignLeft (default), AlignCenter,
	// or AlignRight.
	Align int

	// The maximum width of the cell. This is used to give a column a maximum
	// width. Any cell text whose length exceeds this width is cut off. Set to
	// 0 if there is no maximum width.
	MaxWidth int

	// The color of the cell text.
	Color tcell.Color

	// If set to true, this cell cannot be selected.
	NotSelectable bool
	// contains filtered or unexported fields
}

TableCell represents one cell inside a Table.

func (*TableCell) GetLastPosition 

func (c *TableCell) GetLastPosition() (x, y, width int)

GetLastPosition returns the position of the table cell the last time it was drawn on screen. If the cell is not on screen, the return values are undefined.

Because the Table class will attempt to keep selected cells on screen, this function is most useful in response to a "selected" event (see SetSelectedFunc()).

type TextView 

type TextView struct {
	sync.Mutex
	*Box
	// contains filtered or unexported fields
}

TextView is a box which displays text. It implements the io.Writer interface so you can stream text to it. This does not trigger a redraw automatically but if a handler is installed via SetChangedFunc(), you can cause it to be redrawn.

Navigation

If the text view is scrollable (the default), text is kept in a buffer which may be larger than the screen and can be navigated similarly to Vim:

  • h, left arrow: Move left.
  • l, right arrow: Move right.
  • j, down arrow: Move down.
  • k, up arrow: Move up.
  • g, home: Move to the top.
  • G, end: Move to the bottom.
  • Ctrl-F, page down: Move down by one page.
  • Ctrl-B, page up: Move up by one page.

If the text is not scrollable, any text above the top visible line is discarded.

Navigation can be intercepted by installing a callback function via SetCaptureFunc() which receives all keyboard events and decides which ones to forward to the default handler.

Colors

If dynamic colors are enabled via SetDynamicColors(), text color can be changed dynamically by embedding color strings in square brackets. For example, 

This is a [red]warning[white]!

will print the word "warning" in red. The following colors are currently supported: white, yellow, blue, green, red, cyan, magenta.

Regions and Highlights

If regions are enabled via SetRegions(), you can define text regions within the text and assign region IDs to them. Text regions start with region tags. Region tags are square brackets that contain a region ID in double quotes, for example: 

We define a ["rg"]region[""] here.

A text region ends with the next region tag. Tags with no region ID ([""]) don't start new regions. They can therefore be used to mark the end of a region. Region IDs must satisfy the following regular expression: 

[a-zA-Z0-9_,;: \-\.]+

Regions can be highlighted by calling the Highlight() function with one or more region IDs. This can be used to display search results, for example.

The ScrollToHighlight() function can be used to jump to the currently highlighted region once when the text view is drawn the next time.

func NewTextView 

func NewTextView() *TextView

NewTextView returns a new text view.

func (*TextView) Clear 

func (t *TextView) Clear() *TextView

Clear removes all text from the buffer.

func (*TextView) Draw 

func (t *TextView) Draw(screen tcell.Screen)

Draw draws this primitive onto the screen.

func (*TextView) GetHighlights 

func (t *TextView) GetHighlights() (regionIDs []string)

GetHighlights returns the IDs of all currently highlighted regions.

func (*TextView) GetRegionText 

func (t *TextView) GetRegionText(regionID string) string

GetRegionText returns the text of the region with the given ID. If dynamic colors are enabled, color tags are stripped from the text. Newlines are always returned as '\n' runes.

If the region does not exist or if regions are turned off, an empty string is returned.

func (*TextView) Highlight 

func (t *TextView) Highlight(regionIDs ...string) *TextView

Highlight specifies which regions should be highlighted. See class description for details on regions. Empty region strings are ignored.

Text in highlighted regions will be drawn inverted, i.e. with their background and foreground colors swapped.

Calling this function will remove any previous highlights. To remove all highlights, call this function without any arguments.

func (*TextView) InputHandler 

func (t *TextView) InputHandler() func(event *tcell.EventKey, setFocus func(p Primitive))

InputHandler returns the handler for this primitive.

func (*TextView) ScrollToHighlight 

func (t *TextView) ScrollToHighlight() *TextView

ScrollToHighlight will cause the visible area to be scrolled so that the highlighted regions appear in the visible area of the text view. This repositioning happens the next time the text view is drawn. It happens only once so you will need to call this function repeatedly to always keep highlighted regions in view.

Nothing happens if there are no highlighted regions or if the text view is not scrollable.

func (*TextView) SetCaptureFunc 

func (t *TextView) SetCaptureFunc(handler func(event *tcell.EventKey) bool) *TextView

SetCaptureFunc sets a handler which is called whenever a key is pressed. This allows you to override the default key handling of the text view. Returning true will allow the default key handling to go forward after the handler returns. Returning false will disable any default key handling.

func (*TextView) SetChangedFunc 

func (t *TextView) SetChangedFunc(handler func()) *TextView

SetChangedFunc sets a handler function which is called when the text of the text view has changed. This is typically used to cause the application to redraw the screen.

func (*TextView) SetDoneFunc 

func (t *TextView) SetDoneFunc(handler func(key tcell.Key)) *TextView

SetDoneFunc sets a handler which is called when the user presses on the following keys: Escape, Enter, Tab, Backtab. The key is passed to the handler.

func (*TextView) SetDynamicColors 

func (t *TextView) SetDynamicColors(dynamic bool) *TextView

SetDynamicColors sets the flag that allows the text color to be changed dynamically. See class description for details.

func (*TextView) SetRegions 

func (t *TextView) SetRegions(regions bool) *TextView

SetRegions sets the flag that allows to define regions in the text. See class description for details.

func (*TextView) SetScrollable 

func (t *TextView) SetScrollable(scrollable bool) *TextView

SetScrollable sets the flag that decides whether or not the text view is scollable. If true, text is kept in a buffer and can be navigated.

func (*TextView) SetTextColor 

func (t *TextView) SetTextColor(color tcell.Color) *TextView

SetTextColor sets the initial color of the text (which can be changed dynamically by sending color strings in square brackets to the text view if dynamic colors are enabled).

func (*TextView) SetWrap 

func (t *TextView) SetWrap(wrap bool) *TextView

SetWrap sets the flag that, if true, leads to lines that are longer than the available width being wrapped onto the next line. If false, any characters beyond the available width are not displayed.

func (*TextView) Write 

func (t *TextView) Write(p []byte) (n int, err error)

Write lets us implement the io.Writer interface.

Source Files

View all Source files

Directories

Path Synopsis
demos
box
button
checkbox
dropdown
flex
form
frame
inputfield
list
modal
pages
presentation
Navigation
 Navigation
table
textview

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.