Documentation
¶
Overview ¶
Package terminu draws and drives a terminal UI the way terminu design (tdp) says, on top of Bubble Tea v1.
Index ¶
- Constants
- Variables
- func Center(s string, w int) string
- func Clipboard(text string)
- func Composite(base, top []string, x, y, width int) []string
- func Cut(s string, from, to int) string
- func DidNotFitText(path, copy string, misfits ...Misfit) string
- func Dim(line string) string
- func DimLines(lines []string) []string
- func EmptyState(w, h int, fact, hint string) []string
- func EnvName(app, name string) string
- func Escape(s string) string
- func Filter(items []string, typed string) []int
- func Fit(s string, w int) string
- func FitLeft(s string, w int) string
- func HexText(c Color) string
- func IconWidth() int
- func KeepAside(path string) (string, error)
- func KeyName(msg tea.KeyMsg) string
- func LoadingFrame() string
- func MarkLabel(key, label string) string
- func Matches(text, typed string) bool
- func Pad(s string, w int) string
- func Pad2(lines []string, w, h int) []string
- func PadLeft(s string, w int) string
- func PowerlineWidth() int
- func Reading(lines ...string) []string
- func Repeat(s string, n int) string
- func SetIconWidth(icon, powerline int)
- func StripStyles(s string) string
- func Syntax(lang string, lines []string) []string
- func Truncate(s string, w int) string
- func TruncateLeft(s string, w int) string
- func TruncateMiddle(s string, w int) string
- func Upper(text string) string
- func Width(s string) int
- func Wrap(s string, w int) []string
- type Action
- type App
- func (a *App) AddScreen(s *Screen) *Screen
- func (a *App) CannotReadAgain(v *Viewer, message ...string) tea.Cmd
- func (a *App) Checks(c Checks) tea.Cmd
- func (a *App) CloseAll() tea.Cmd
- func (a *App) ClosePopup(b PopupBody) tea.Cmd
- func (a *App) CloseTop(n int) tea.Cmd
- func (a *App) CompareAction(p *Panel, l *List, c Compare) Action
- func (a *App) Confirm(ask Ask, accept func() tea.Cmd) tea.Cmd
- func (a *App) Covered() bool
- func (a *App) DidNotFit(path, copy string, misfits ...Misfit) tea.Cmd
- func (a *App) Elevate(e Elevate) tea.Cmd
- func (a *App) Error(title string, message ...string) tea.Cmd
- func (a *App) ErrorAbout(title, subject string, message ...string) tea.Cmd
- func (a *App) Find(f *Finder) tea.Cmd
- func (a *App) Focus(p *Panel) tea.Cmd
- func (a *App) Form(f *Form) tea.Cmd
- func (a *App) Frame() []string
- func (a *App) Init() tea.Cmd
- func (a *App) LoadChecks(c *Checks) tea.Cmd
- func (a *App) LoadSelect(s *Select) tea.Cmd
- func (a *App) Log(kind ToastKind, text string)
- func (a *App) Menu(title string, sections ...MenuSection) tea.Cmd
- func (a *App) MenuAbout(title, subject string, sections ...MenuSection) tea.Cmd
- func (a *App) MoveAside(path string, err error, fresh func() tea.Cmd) tea.Cmd
- func (a *App) MoveAsideRecord(path string, err error, reread func() tea.Cmd) tea.Cmd
- func (a *App) NoLongerUsed(paths ...string)
- func (a *App) Notify(notices ...Notice) tea.Cmd
- func (a *App) Number(in NumberInput) tea.Cmd
- func (a *App) Open(in Input) tea.Cmd
- func (a *App) OpenDiff(p *Panel, item DiffItem) tea.Cmd
- func (a *App) OpenTerminal(t *Terminal) tea.Cmd
- func (a *App) Password(in PasswordInput) tea.Cmd
- func (a *App) PickColor(c ColorPicker) tea.Cmd
- func (a *App) PickDate(d DatePicker) tea.Cmd
- func (a *App) PickFile(p FilePicker) tea.Cmd
- func (a *App) PlaySplash(s Splash) tea.Cmd
- func (a *App) Popup(p Popup) tea.Cmd
- func (a *App) ReadAgain(v *Viewer, lines []string) tea.Cmd
- func (a *App) Reorder(r Reorder) tea.Cmd
- func (a *App) Report(v *Viewer) tea.Cmd
- func (a *App) Run() error
- func (a *App) RunAction(key string) tea.Cmd
- func (a *App) Screen() *Screen
- func (a *App) Select(s Select) tea.Cmd
- func (a *App) SelectionGone(p *Panel, kind ToastKind, title string, message ...string) tea.Cmd
- func (a *App) ShowScreen(s *Screen) tea.Cmd
- func (a *App) Size() (w, h int)
- func (a *App) Text(in TextInput) tea.Cmd
- func (a *App) Textarea(t Textarea) tea.Cmd
- func (a *App) Tick(d time.Duration, fn func(time.Time) tea.Msg) tea.Cmd
- func (a *App) Toast(kind ToastKind, text ...string) tea.Cmd
- func (a *App) Update(msg tea.Msg) (tea.Model, tea.Cmd)
- func (a *App) View() string
- func (a *App) Viewer(v *Viewer) tea.Cmd
- type Ask
- type Body
- type Capsule
- type Checks
- type Color
- type ColorPicker
- type Column
- type Compare
- type CoreKey
- type Corner
- type DatePicker
- type DiffItem
- type DiffMark
- type Elevate
- type ElevateError
- type ElevateTool
- type Failure
- type Field
- type FilePicker
- type FilePreview
- type Finder
- type FinderItem
- type Form
- type FormButton
- type FormField
- type FormResult
- type FrameStatus
- type Input
- type KeyHint
- type KeyRow
- type KeySection
- type List
- func (l *List) Actions() []Action
- func (l *List) ClearFilter()
- func (l *List) ClearMarks()
- func (l *List) Current() (Row, bool)
- func (l *List) Draw(w, h int, focused bool) []string
- func (l *List) Drop()
- func (l *List) Empty() bool
- func (l *List) Filtering() bool
- func (l *List) Focus()
- func (l *List) HasItem() bool
- func (l *List) Hold() bool
- func (l *List) Holding() bool
- func (l *List) Key(key string, msg tea.KeyMsg) (bool, tea.Cmd)
- func (l *List) Marked() []string
- func (l *List) MoveHeld(down bool)
- func (l *List) MoveKeys() []KeyRow
- func (l *List) OpenFilter()
- func (l *List) Rows() []Row
- func (l *List) Scroll() string
- func (l *List) Select(id string) bool
- func (l *List) SetMarked(ids []string)
- func (l *List) SetRows(rows []Row)
- func (l *List) SortBy(keys ...SortKey)
- func (l *List) Sorting() []SortKey
- func (l *List) ToggleMark()
- func (l *List) Typing() bool
- func (l *List) Uncover(rows int)
- type MenuSection
- type Misfit
- type Mode
- type ModeKey
- type Notice
- type NumberInput
- type Pager
- func (t *Pager) Append(lines ...string)
- func (t *Pager) Draw(w, h int, focused bool) []string
- func (t *Pager) Empty() bool
- func (t *Pager) HasItem() bool
- func (t *Pager) Key(key string, _ tea.KeyMsg) (bool, tea.Cmd)
- func (t *Pager) Lines() []string
- func (t *Pager) MoveKeys() []KeyRow
- func (t *Pager) ReadAgain(lines []string)
- func (t *Pager) Scroll() string
- func (t *Pager) SetDiff(anchor, other string)
- func (t *Pager) SetDiffItems(items []DiffItem)
- func (t *Pager) SetLines(lines []string)
- type Panel
- type PasswordInput
- type Popup
- type PopupActions
- type PopupBody
- type PreviewFS
- type PreviewFile
- type ProbeResult
- type RGB
- type Rect
- type Reorder
- type Row
- type Scope
- type Screen
- type SearchStatus
- type Select
- type Selection
- type Slider
- type SortKey
- type Span
- type Splash
- type StatusKind
- type Style
- type Terminal
- func (t *Terminal) Draw(w, h int, focused bool) []string
- func (t *Terminal) Empty() bool
- func (t *Terminal) Enter()
- func (t *Terminal) Exited() bool
- func (t *Terminal) HasItem() bool
- func (t *Terminal) Hide(a *App) tea.Cmd
- func (t *Terminal) Inside() bool
- func (t *Terminal) Key(string, tea.KeyMsg) (bool, tea.Cmd)
- func (t *Terminal) Mode() string
- func (t *Terminal) MoveKeys() []KeyRow
- func (t *Terminal) Running() bool
- func (t *Terminal) Scroll() string
- func (t *Terminal) Spoke() bool
- func (t *Terminal) Start() tea.Cmd
- func (t *Terminal) Stop()
- type TerminalKey
- type TextInput
- type TextMatch
- type Textarea
- type ToastKind
- type Values
- func (v *Values) Actions() []Action
- func (v *Values) Current() *Field
- func (v *Values) Draw(w, h int, focused bool) []string
- func (v *Values) Empty() bool
- func (v *Values) EnterHint() string
- func (v *Values) HasItem() bool
- func (v *Values) Key(key string, _ tea.KeyMsg) (bool, tea.Cmd)
- func (v *Values) MoveKeys() []KeyRow
- func (v *Values) Scroll() string
- func (v *Values) Uncover(rows int)
- type Viewer
- type ViewerKey
- type ViewerSearch
Constants ¶
const ( FamilyIconWidth = "TERMINU__ICON_WIDTH" FamilyPowerlineWidth = "TERMINU__POWERLINE_WIDTH" )
The variables a family app sets for what runs in its PTY (tdp E2, E5).
const ( RemoteIconWidth = "LC_TERMINU_ICON_WIDTH" RemotePowerlineWidth = "LC_TERMINU_POWERLINE_WIDTH" )
The variables an app with ssh sends to the remote end when it connects, for the family app that runs there: OpenSSH passes on only LANG and LC_* (tdp E2, E5). Sending them is that app's; Probe reads them.
Variables ¶
var ( Base = Hex("#1e1e2e") // text on blocks Mantle = Hex("#181825") // an unselected capsule part and the joins of a chain; dimmed, it is Crust #11111b Blue = Hex("#89b4fa") // focus: frames, keys you can press now, the screen chips Surface2 = Hex("#585b70") // not usable: unfocused frames, disabled rows Lavender = Hex("#b4befe") // being edited, the user's footprint Sapphire = Hex("#74c7ec") // the last layer colour Green = Hex("#a6e3a1") // in effect: the chosen value, live sessions, progress Yellow = Hex("#f9e2af") // a mode Peach = Hex("#fab387") // a warning Red = Hex("#f38ba8") // an error Overlay0 = Hex("#6c7086") // quiet text: descriptions, hint words, separators Text = Hex("#cdd6f4") // ordinary text Subtext1 = Hex("#bac2de") // the panel cursor block Surface1 = Hex("#45475a") // an unfocused button )
The family colours, catppuccin-mocha (tdp color). Each meaning has one colour (Principle P4); the comment is what tdp uses it for.
var ErrEmpty = errors.New("can't be empty")
ErrEmpty is a ready "may not be empty" check. The input names the value before it: "Name can't be empty" (tdp input).
Functions ¶
func Clipboard ¶ added in v0.2.0
func Clipboard(text string)
Clipboard puts text on the terminal's clipboard (OSC 52), as a viewer's selection mode copies by default (tdp note). It is sent with the next frame.
func Composite ¶
Composite lays the lines of top over base, top's first cell at column x and row y. Whatever falls off the screen is cut; it never panics, however big top is (tdp E5). base is changed in place and returned; every line keeps base's width.
func Cut ¶
Cut keeps the cells [from, to) of one line. Escape sequences are kept so the styles stay right, and the result ends with a style reset. A wide character cut in half becomes spaces, so the result is always exactly as wide as the part of [from, to) the line covers.
func DidNotFitText ¶ added in v1.2.16
DidNotFitText is DidNotFit's sentence, for an app with no screen to write to stderr, where it does not mix with what it prints (tdp E3): "3 values in config.yaml did not fit: defaults used, yours kept in config.yaml.bak"; "2 entries in hosts.yaml did not fit: taken out, yours kept in hosts.yaml.bak"; with both, "3 values and 2 entries in config.yaml did not fit: defaults used and entries taken out, yours kept in config.yaml.bak". It is "" with no misfits or no copy.
func Dim ¶
Dim redraws one drawn line dimmed: every foreground and background colour in its SGR sequences fades toward #0c0c13, always written as 24-bit, and text with no colour of its own gets dim(Text). Bold, reverse, cursor movement and the text itself are left as they are.
func EmptyState ¶
EmptyState draws an empty panel's two sentences, the fact and the hint naming keys, both in Overlay0 (tdp screen); keys written as [A] in the hint stay as they are.
func EnvName ¶
EnvName is the name of an environment variable app reads, tdp E2: EnvName("filu", "icon width") is "FILU__ICON_WIDTH".
func Escape ¶ added in v0.4.0
Escape is text as a name or a short text is drawn (components, control characters): each control character (C0, DEL, C1), Tab, \n and ESC too, by its name in Red (\t, \n, \x1b, as a pasted one in an input), nothing read as a style or a line break, nothing dropped. The lib draws every name and short text an app gives it this way; an app drawing text from outside itself (on a Canvas, in a popup of its own) uses it too.
func Filter ¶
Filter returns the indexes of the items that match typed, in their order: a filter never reorders.
func IconWidth ¶
func IconWidth() int
IconWidth is how many cells a Nerd Font icon takes on this terminal.
func KeepAside ¶ added in v1.2.16
KeepAside copies path to <name>.bak, or the first of .bak.1, .bak.2… that is free, never over another, keeping its mode, and returns the copy's path (tdp E3, a value that does not fit): the app then writes path again with its defaults for the values that did not fit and without the entries that did not. It needs no App, for a start with no screen too.
When the copy cannot be made (a folder that cannot be written, a full disk) its error says so as the Error toast does, "config.yaml.bak could not be made: permission denied; config.yaml left as it was", wrapping why: the app does not write path again, uses the defaults for this run only, and says the error (an Error toast, or stderr with no screen); the next start finds the values again (tdp E3).
func KeyName ¶
KeyName is the name of the key in msg as tdp writes it (tdp M5): the keycap name in upper camel case (Enter, Esc, Tab, Space, Backspace, Delete, Home, End, PgUp, PgDn), arrows as ↑ ↓ ← →, a letter as typed (q, A), modifiers joined with "-" and Ctrl's letter in upper case (Ctrl-C, Alt-t, Shift-Tab, Alt-Esc). A paste has no name: it is "".
func LoadingFrame ¶ added in v0.2.0
func LoadingFrame() string
LoadingFrame is the loading icon as it is now, for a row of the app's own that is loading (a transfer in a work list): the same icon, turning with the lib's. App.Spinning keeps it turning (tdp popup).
func MarkLabel ¶
MarkLabel writes a hotkey into its label the way tdp M5 says. A letter that is in the label, in either case, goes in place of the first one, written as the key is pressed ("[r]ename", "[n]ew", "D[e]lete", "Ex[P]ort": Shift-P); one that is not goes in front ("[x] Reset"). A modifier key goes in place of the letter it ends with the same way ("[Alt-t]erm"), several letters in place at the start ("[go]to"), a digit, a core key or a symbol always in front ("[3] Favorites", "[Enter] Edit", "[/] Search"). The label keeps its own case. A label that already shows its key, and a row with no key, are left as they are.
func Matches ¶
Matches reports whether text matches what was typed in a filter (tdp finder.7): every space-separated word must appear in text as typed, in one piece, ignoring case; the words may come in any order. Nothing typed matches everything.
func PowerlineWidth ¶
func PowerlineWidth() int
PowerlineWidth is how many cells a powerline symbol takes on this terminal.
func Reading ¶ added in v0.4.0
Reading is lines of reading content (a log, a program's output) as a terminal draws them, the way the lib's viewer and Pager draw theirs (components, control characters): a line with \n in it is two rows, a \r inside a line leaves its last state, the \r of a CRLF goes, colour codes colour, a tab is input_tab_width spaces, any other control character or escape sequence is its name in Red. For a body of the app's own that shows what is read (a container's log behind a prefix, folded): each string it gives back is one row's text, to fold or cut as the app does; Width, Truncate and Cut measure it right.
func SetIconWidth ¶
func SetIconWidth(icon, powerline int)
SetIconWidth sets how many cells a Nerd Font icon takes, and a powerline symbol. Probe sets them; tests and apps that already know may set them.
func Syntax ¶ added in v1.1.8
Syntax is lines in syntax colours, as the lib colours a text file in its file preview and in a viewer (tdp file-picker.3, note.2): chroma's catppuccin-mocha, its colours, bold, italic and underline but never its background, with the gaps chroma leaves filled the family's one way. An app that draws a file in a body of its own colours it with this, so that the file looks the same there as in the preview.
lang is what Viewer.Lang takes: a lexer's name or alias ("toml"), a file name or path ("Cargo.toml"), or a content type ("application/json"). A path also tells a name more than one format has by its directory: a config in .ssh is SSH's, one in .git is git's, a hosts in /etc is the hosts file and one elsewhere is not. A language it cannot tell leaves the lines plain, in Text. The lines are plain text, read together (a string may go on to the next line), and each gives one line back; a tab or a \r stays as it is, for the caller to draw.
Importing the lib puts its lexers in chroma's global registry in place of chroma's own, so an app that calls chroma itself gets the gaps filled too.
func Truncate ¶
Truncate fits one line in w cells, cutting from the end and adding "…" when it had to cut. The result may be narrower than w when a wide character would straddle the cut.
func TruncateLeft ¶
TruncateLeft fits one line in w cells, cutting from the front and putting "…" first: for paths and for a value whose end matters.
func TruncateMiddle ¶ added in v0.2.0
TruncateMiddle fits one line in w cells, cutting from the middle and putting "…" there: for a value whose two ends both matter, a pod's name with its deployment in front and what tells it apart at the end ("demo-app…66-gm72n"). The end keeps the extra cell of an odd split. The result may be narrower than w when a wide character would straddle a cut.
func Upper ¶
Upper writes text in upper case for a capsule, a title, a header or a section title (components, "Uppercase"), leaving the letters in a hotkey marker as they are: "[m]anage" becomes "[m]ANAGE".
func Width ¶
Width is how many cells s takes on the screen: its widest line, escape sequences ignored.
func Wrap ¶
Wrap breaks plain text into lines of at most w cells (components, wrapping): at spaces and on either side of a wide character; inside a word only when it is longer than a line, cut by cells, a wide character never cut in half. Line breaks in s are kept. The text is only shown, so the space it breaks at is not drawn (the textarea and the viewer use foldAt).
Types ¶
type Action ¶
type Action struct {
// Key is the hotkey as KeyName writes it ("r", "D", "Alt-t", "go",
// "Enter", "/"); "" for none. It may not take a core key or a movement
// letter (tdp K1, K12); "Enter" is the panel's Enter action.
Key string
// Label is the action's name ("Rename"); the hotkey marker is added
// where tdp M5 puts it.
Label string
// Desc is one line: what it does to what.
Desc string
Scope Scope
// Hint is the word after the key in the panel's bottom-border hint
// ("logs" for Enter:logs); "" keeps the action out of the hint.
Hint string
// Ask, when set, asks first (tdp F6): every time.
Ask *Ask
// AskFor, when set, is asked when the action runs, after Hidden and
// Disabled, for the question it asks then (the name of the item under the
// cursor); nil asks nothing (a step that turns out to need no asking). It
// wins over Ask. Run from a menu, the confirm opens over the menu, so Esc
// on it goes back to the menu (tdp T1).
AskFor func() *Ask
// Hidden reports that its object does not exist now: the row is not
// shown at all (tdp M6).
Hidden func() bool
// Disabled reports that it cannot run now: the row is shown in the
// disabled colour, the cursor skips it and its hotkey does nothing.
Disabled func() bool
// Run from a menu, an action that opens a popup keeps the menu under it,
// to come back to (tdp T1, F4); one that opens nothing has done the
// menu's work, and the menu closes. A confirm before it is only a door:
// Esc on it goes back to the menu, and once it is accepted what the action
// does decides.
//
// Clear makes what it opens clear the menu, and the popups under it, as
// it opens (tdp T1: the item is gone, a shell, another screen, a drill-down).
Clear bool
// Stay keeps the menu it runs from open even when it opens nothing.
Stay bool
// Detail marks a row whose Enter opens its full text over the menu (a
// worklist, tdp F1): the menu stays and its hint is Enter:detail
// (tdp menu).
Detail bool
// EnterHint is the word after Enter in a menu's hint while the cursor is
// on this row ("cancel" on a work list's transfer, which asks first with
// the row's full text); "" is run, or detail with Detail
// (tdp menu.5).
EnterHint string
// Live, when set, gives the row's label and description each time the
// menu is drawn: a work list's progress and state change while it is open
// (tdp menu). The row keeps the width it had when the menu
// opened.
Live func() (label, desc string)
// ToDetails, on a panel's "Enter" action only, says whether Enter on the
// item under the cursor also sends the focus to the panel's Details: the
// one place Enter changes panels, whether and on which items being the
// app's call (tdp K3). Going in moves the focus, so it does not go in the
// App Log (tdp note.7).
ToDetails func() bool
// Do runs it.
Do func() tea.Cmd
// contains filtered or unexported fields
}
Action is something the user can do. One registration gives the Space menu row, the global operation popup row, the key reference row, the hotkey and the hint, so they cannot drift apart (tdp M3).
type App ¶
type App struct {
// Name is the app's name, for its environment variables (tdp E2).
Name string
// Quit is the quit flow (tdp K9): nil leaves at once, an Ask confirms
// first. A second Ctrl-C during the flow always leaves. With a popup open
// it always asks first: Quit <app>? when nil.
Quit *Ask
// QuitDesc is the Quit row's description in the global operation popup.
QuitDesc string
// QuitFlow, when set, is the quit flow itself, in place of Quit (Rules
// K9: the app's): q and Ctrl-C run it, a menu of the app's own to choose
// how to leave, say. While the popup it opens is open, a second Ctrl-C
// leaves at once, as in any quit flow.
//
// With a popup open the lib runs it first and only then decides whether
// to stop it (tdp K9): when it opens nothing, the command it returns
// waits for Enter on Quit <app>?, and Esc drops it. So what cannot be
// undone (closing a session, stopping a task) goes in that command, not
// in QuitFlow itself.
QuitFlow func() tea.Cmd
// Global are the global operations besides switching screens and
// quitting (Principle P3); their hotkeys work on panels too (tdp M4).
Global []Action
// Status is the statusbar for w cells (tdp screen); nil for none. It
// is spans, in the app's colours (Overlay0 words, a Lavender value...):
// a value from outside (a path) has its control characters drawn by
// name (components, control characters). Cut at w.
Status func(w int) []Span
// Canvas, when set, is a screen the app draws itself, whole: a full-screen
// lock screen. The lib draws it instead of its screens, chips and footer,
// h lines of w cells, and puts its popups and toasts over it, so confirm,
// toast and every kind of input work there as anywhere (tdp E8).
Canvas func(w, h int) []string
// CanvasKey gets every key on the Canvas while no popup is open and
// reports whether it took it. Of what it leaves only Ctrl-C does
// something, the quit flow (tdp K9: App.Quit decides); no Space menu,
// no ?, no q: the screen is the app's.
CanvasKey func(key string, msg tea.KeyMsg) (bool, tea.Cmd)
// HideSecretsInPreview is the user's setting hide_secrets_in_preview,
// read from the app's settings file (tdp E3): a file preview shows only
// the first line of a private key, and nothing of a file only its owner
// may read (tdp file-picker).
HideSecretsInPreview bool
// InputTabWidth is the user's setting input_tab_width: how many spaces
// Tab puts in a textarea, and the spaces a tab in any text is drawn as;
// 4 when unset (tdp textarea, tdp E3).
InputTabWidth int
// ToastLines caps how many lines a toast has, the last one kept ending in
// "…"; 0 for no cap (tdp toast.2: the app's choice).
ToastLines int
// Spinning reports that a loading icon of the app's own is on the screen
// (LoadingFrame in a row), so the lib keeps drawing it turning.
Spinning func() bool
// Progress is a long job's progress, 0 to 1, for the bar under the
// screen chips; ok false when there is none.
Progress func() (frac float64, ok bool)
// ShiftTab makes Shift-Tab go to the previous panel (tdp K2: the app's
// choice).
ShiftTab bool
// OnMsg gets the messages the lib does not handle itself.
OnMsg func(tea.Msg) tea.Cmd
// OnResize runs when the terminal changes size, after the lib has laid
// the screen out again: the place to change what depends on the width
// (which columns a list shows; tdp L1).
OnResize func(w, h int) tea.Cmd
// ForceNarrow draws every screen narrow (for showing the narrow layout).
ForceNarrow bool
// Start runs when the program starts.
Start func() tea.Cmd
// Splash is the family's easter egg, opened with V on a panel (Rules S).
// Every app has one: Run refuses an app without it.
Splash Splash
// MinWidth and MinHeight are the app's least size (tdp L1): 60 × 32 when
// unset, the most they may be. On a smaller terminal only the app's name,
// "needs a terminal of at least W×H" and "Press [Ctrl-C] twice to quit"
// are drawn, in the middle; every key is ignored, the PTY's too, but
// Ctrl-C pressed twice, which leaves. What the app was showing comes back
// as the terminal grows.
MinWidth, MinHeight int
// CoreKeys are core keys of the app's own (tdp K1): each means the same
// on every panel and popup, but on a typing row, in a PTY and in a mode;
// no hotkey may take one.
CoreKeys []CoreKey
// contains filtered or unexported fields
}
App is the whole terminal UI: screens of panels, the popups over them, the footer. It is a Bubble Tea model.
func (*App) AddScreen ¶
AddScreen adds a screen. It panics when a panel registers a key that is not the app's to take (tdp K1, K12), or has a list with both Marks and Flags (tdp panel.7): that is a mistake in the program.
func (*App) CannotReadAgain ¶ added in v1.2.14
CannotReadAgain is for v when its source cannot be read any more (a file deleted; tdp note.9): v leaves the selection mode and keeps what it shows, and message, the app's words, says why (tdp panel.15): an Error toast; with the selection mode's Space menu or key reference open, an error popup over them instead, CANNOT READ: <Subject>, message and "The selection is gone", whose Enter and Esc close it and them, back to the viewer (tdp note-100). With no message it gives no toast: a read the app repeats on its own that fails the same way again (the same words) shows and records nothing, a different failure toasting again (tdp note.7). On a viewer not on the screen it says nothing.
func (*App) CloseAll ¶ added in v0.2.0
CloseAll closes every popup, the lib's and the app's, each playing its own closing at the same time (tdp F2), as when what was done ends the whole stack (tdp T1; a long session started from a viewer). A confirm or an input closed this way is cancelled (OnCancel).
func (*App) ClosePopup ¶ added in v0.1.9
ClosePopup closes the popup b is the inside of, and every popup over it.
func (*App) CloseTop ¶ added in v0.2.0
CloseTop closes the n popups on top, the lowest of them animating, as the last step of a flow ends the steps under it (tdp T1); a step that has been answered is not cancelled.
func (*App) CompareAction ¶ added in v0.4.7
CompareAction is l's Compare item action, for p's Actions: on a row c can compare it enters the compare mode (tdp K11), that row the anchor (List.Anchor). In the mode j|k, u|d and gg|G move; c.Key or Enter compares the row under the cursor with the anchor, off on the anchor, on a row c cannot compare and on a row that holds many against one that does not (tdp M6); the same text on both sides is an Info toast, not a popup. Two rows that hold many go in to the list of the items that differ, as OpenDiff does, the panel staying in the mode: its keys work there, on the item under the cursor, and Esc goes back up a level, the last back to the mode with the anchor kept. Esc leaves it, the anchor gone; Tab and the digits wait; an anchor no longer in the list ends it with a Warning toast, the lists gone into closed. The rows need their IDs. The mode does not go in the App Log; its toasts do, as every toast (tdp note.7).
func (*App) Confirm ¶
Confirm asks ask; accept runs when the user answers Enter. The popup under it stays (tdp T1, a short confirm).
func (*App) Covered ¶ added in v1.2.3
Covered reports whether something is over the screen: a popup (a menu, an input, a dialog, a confirm, the key reference, the App Log, a terminal popup, a popup of the app's own), one that is closing until it is gone, or the splash. A toast is not a popup (tdp F1) and does not count. An app whose screen moves on by itself (a game's clock) asks it on each tick and holds still while the user cannot see the screen.
func (*App) DidNotFit ¶ added in v1.2.16
DidNotFit says what KeepAside and the app's writing path again did (tdp E3): one Warning toast naming the file and the copy, as DidNotFitText words it, and a WARN in the App Log for each misfit: `config.yaml: color "#zzzzzz" did not fit; using "#89b4fa"`, or `hosts.yaml: entry 3 (name "") did not fit; taken out`. With copy "" (the copy could not be made) it only logs the misfits: the app gives KeepAside's error in an Error toast. When the start has more to say, the app gives MisfitNotice to Notify with the rest instead.
func (*App) Elevate ¶ added in v0.6.4
Elevate runs e's command with raised privileges (tdp terminal.7).
func (*App) Error ¶
Error opens an error popup over the top popup (tdp note): an action failed. Each string of message is a row of its own, folded when too long, as Toast's (components, control characters).
func (*App) ErrorAbout ¶ added in v0.2.0
ErrorAbout is Error naming what failed: subject goes after ": " in the title, kept as it is, RENAME FAILED: notes.md (tdp note).
func (*App) Focus ¶ added in v0.2.0
Focus moves the focus to p, on whichever screen it is, switching to that screen. The app does it where the user expects the focus to move: after what they pressed, never on something that happened in the background (a load done, a job ended; tdp K3). A panel on no screen is left alone.
func (*App) Form ¶
Form opens a form. It panics on a field with more than five options: those go in a select or a checkbox popup (tdp form); on a form with both Submit and SubmitLong; and on a button with not one of Submit, SubmitLong, Run and Open: mistakes in the program.
func (*App) LoadChecks ¶ added in v0.2.0
LoadChecks opens a checkbox popup whose options are still coming, as LoadSelect does: keep the pointer and append to Options (and Checked) while Loading is true.
func (*App) LoadSelect ¶ added in v0.2.0
LoadSelect opens a select whose options are still coming: keep the pointer and append to Options while Loading is true. Meanwhile the title has the loading icon and the popup is as wide as it can be, its width not known when it opens (tdp F7).
func (*App) Log ¶ added in v0.4.0
Log writes to the App Log: in kind's level (Info INFO, Success OK, Warning WARN, Error ERR), at the App's time. Every toast and error popup is logged by itself, and so is a switch of screens the user runs ("Switched to Pods"). The app logs the operations of its own the user runs and their results: every item, panel and global operation (tdp P3), from a menu, a hotkey or Enter, one that only looks too (opening a viewer); not moving the cursor or the focus, Enter into a list's details included (tdp K3), nor the panel filter or compare mode, nor one cancelled with Esc at its confirm, form or input popup (it was not done), and what is done in a popup only as the result of the operation it belongs to (tdp note.7). It also logs what it does in the background (moving its files, defaults it made at the start, the details of what it could not reach). Each entry starts with a capital letter as a toast does (tdp toast.2). It may be called from any goroutine; the screen shows it with the next frame.
func (*App) Menu ¶
func (a *App) Menu(title string, sections ...MenuSection) tea.Cmd
Menu opens a menu of sections (tdp M8); running a row closes the menu and everything under it.
func (*App) MenuAbout ¶ added in v0.2.0
func (a *App) MenuAbout(title, subject string, sections ...MenuSection) tea.Cmd
MenuAbout is Menu for one thing: subject goes after ": " in the title, kept as it is, OPEN WITH: notes.md (components, upper case).
func (*App) MoveAside ¶ added in v0.4.0
MoveAside asks what to do with a file of the app's own it cannot read (tdp E3, when it cannot be read): its settings, its state or its data, whatever the reason (a bad format, a broken file, no permission). The confirm, MOVE ASIDE, names the path and why:
- Enter (move) renames the file to <name>.bak (.bak.1, .bak.2… when that is taken: never over another), logs it and runs fresh, where the app goes on as on its first start (its defaults for settings, empty state or data): a file its first start makes is made again, one it does not waits for the first save. The lib makes nothing in its place.
- Esc (quit) leaves the app: Run returns the path and the reason, for main to write to stderr as it does any error of Run.
A cache that cannot be read is not asked about: throw it away and build it again. Something outside the app that cannot be reached (a cluster, the network) is not the app's own: the app goes on and says so where it shows it (tdp panel.15). Data kept one record per file uses MoveAsideRecord.
func (*App) MoveAsideRecord ¶ added in v0.4.2
MoveAsideRecord is MoveAside for data kept one record per file (a mark per file): Enter only renames the record that cannot be read to <name>.bak, making nothing new in its place, and runs reread, where the app reads the rest as usual (tdp E3, when it cannot be read). The question is "Move it to <name>.bak and go on without it?"; Esc leaves the app as MoveAside's.
func (*App) NoLongerUsed ¶ added in v0.4.4
NoLongerUsed notes each file of the app's own that a newer version no longer uses and that is still there (settings, state or data): an INFO in the App Log naming its path, "No longer used: <path>; delete it if you don't need it". The file is not deleted and there is no toast: what to do with it is the user's. Call it at every start; the App Log starts empty (tdp E3, files no longer used).
func (*App) Notify ¶ added in v1.2.17
Notify shows notices as one toast, a row each in the order given, its kind the strongest: Error, then Warning, else the first row's (tdp E3, several at one start). In the App Log each row is an entry of its own at its own kind, a misfit's WARNs right after its row. A notice with no Text has no row; with no rows there is no toast.
func (*App) Number ¶
func (a *App) Number(in NumberInput) tea.Cmd
Number opens a number input popup.
func (*App) OpenDiff ¶ added in v1.2.18
OpenDiff opens item as Enter does on it in a list of the items that differ (tdp note.8, panel.9), for an action of the app's own showing two versions of one item (a file in a commit against the commit before it, a file being edited against its last commit) or going into what changed in one (a commit against the one before it):
- with Text, its comparison, titled DIFF — <Anchor> ↔ <Other>, or the Info toast "No differences between <Anchor> and <Other>" when the two are the same;
- with Items, the list of the items that differ in it, in p in place of p's body as panel.10 goes into an item, its location row <Anchor> ↔ <Other> in place of p's own, or that toast when there is none. Each item is its mark in its colour, then its name. j|k, u|d and gg|G move, Enter opens the item under the cursor the same way (off on one with neither Text nor Items), Esc goes back up a level, the cursor on the item it came out of, the last back to p, its cursor where it was; the Space menu and ? have the list's keys, not p's actions, and Tab and the digits go to the other panels as ever, the list kept. A filter on p is cleared before going in, as Esc clears it (tdp panel.14).
A comparison opens on UNIFIED; SPLIT is off narrower than 96 columns. An error from Text or Items is an error popup. Mark is not used. p is out of a mode: a compare mode goes in so itself (CompareAction).
func (*App) OpenTerminal ¶
OpenTerminal opens a terminal popup with t in it, starting it if it has not started (tdp terminal).
func (*App) Password ¶
func (a *App) Password(in PasswordInput) tea.Cmd
Password opens a password input popup.
func (*App) PickColor ¶
func (a *App) PickColor(c ColorPicker) tea.Cmd
PickColor opens a color picker.
func (*App) PickDate ¶
func (a *App) PickDate(d DatePicker) tea.Cmd
PickDate opens a date (or date and time) picker.
func (*App) PlaySplash ¶ added in v0.2.0
PlaySplash plays s over the whole screen now, from its first frame, as V does with the app's own (Rules S): a splash the app shows of its own accord, a mark being designed, say. Any key closes it.
func (*App) Popup ¶ added in v0.1.9
Popup opens p over what is on top. It panics when p.Body is nil or not comparable: that is a mistake in the program.
func (*App) ReadAgain ¶ added in v1.2.14
ReadAgain puts lines in the open viewer v in place of what it shows, its source read again (a file it watches; tdp note.9). Whether and when to read again are the app's; it is as if v had just been opened on the new lines, keeping only this:
- Where the view was; at the new end when the end was in sight (never in the selection mode), or when the lines are fewer than fill it.
- The line numbers' column, which only widens while v is open.
- The lib's search, found again in the new lines: the first hit at or after the current one is current, the first of all when none is (as n wraps), and the view does not move for it. With none left it is a search that finds nothing: an Info toast, the hits and the status gone. An app's own search (Keys taking /, n or N) is the app's to find again.
- The selection mode's positions, not its text, a position being its line and that line's column: both still there, nothing changes and the copy is of the new text. Where the selection started gone, the selection goes, back to the mode's first layer as one Esc; the cursor's place gone, the mode is left, as Esc to the end; each said in a Warning toast that names Subject (Title without one). With the selection mode's Space menu or key reference open, it is said in a note over them instead, drawn as an error popup in Peach with the Warning toast's glyph, READ AGAIN: <Subject>; Enter and Esc close it and them, back to the viewer (tdp note-99).
Otherwise an open Space menu or key reference stays as it is. It returns the toasts. On a viewer not on the screen it only puts the lines in.
func (*App) Report ¶ added in v1.2.16
Report opens v as a success report too long for a toast that the user needs to read whole (tdp toast.2, note.1, note.3): a read-only viewer titled with what was done, its lines the whole report, in its layer's colour. It came up by itself, so Enter closes it as well as Esc (not in the selection mode, where Enter does nothing); the hint and ? say Enter|Esc. The report goes in the App Log as a Success, "<Title>: <its lines>". Whether a report is short enough for a Success toast is the app's to tell.
func (*App) Run ¶
Run asks the terminal how wide an icon is and what its colours are, then runs the app in the alternate screen. When the user leaves on MoveAside's Esc it returns the path that cannot be read and why, for main to write to stderr (tdp E3).
Closing the terminal (SIGHUP) ends it as leaving does, returning nil, so what main does after Run (saving) still runs. The programs in the app's Terminals are hung up first, as a closed terminal window does, so nothing after Run waits on them for ever. The terminal is gone by then: nothing written to it shows.
func (*App) RunAction ¶ added in v1.2.7
RunAction runs the action key runs on the focused panel out of a mode, as choosing it in a menu does: a key of a popup of the app's own runs one of the app's actions with it (tdp popup.8). It is found as the key is out of a mode (tdp M4): the focused panel's item operations, then its panel operations ("Enter" is its Enter action), then the global ones; q is the quit flow (tdp K9). One that asks opens its confirm over the popup; a disabled or hidden one does nothing, as a key with none does. Done with nothing new open, every popup closes, the one that called too (tdp T1).
func (b *settings) Key(key string, _ tea.KeyMsg) (bool, tea.Cmd) {
if key == "n" { // the panel's [n]ew game
return true, b.app.RunAction("n")
}
...
With the focused panel in a mode, the mode is left as the action runs: after the Enter of its confirm, still in it if the confirm is cancelled. It is left as LeaveMode leaves it, every layer, the mode's Space menu and ? with it, and its OnExit is not run: what OnExit would do (a pause), the app does before calling; and when leaving would lose what the user made and keeps (tdp K11), the app asks before calling. Quitting leaves no mode first.
func (*App) SelectionGone ¶ added in v1.2.15
SelectionGone says that content read again took away the selection of the mode p is in, an app's own selection mode on its own reader (tdp note.9). With that mode's Space menu or key reference open, it is a note over them, drawn as an error popup in kind's colour, Warning in Peach with the Warning toast's glyph, Error in Red, titled title, message its rows; Enter and Esc close it and them, back to the screen (tdp note-99, note-100). With neither open it is a toast of kind with message. Call it before leaving the mode or going back a layer: leaving it then keeps them open under the note, to close with it. Kind is Warning or Error.
func (*App) ShowScreen ¶ added in v0.2.0
ShowScreen switches to s, as its chip's key does (tdp K3: when the user expects it).
func (*App) Tick ¶ added in v0.3.0
Tick is tea.Tick on the App's clock. A timer of the app's own made with it (a debounce, a message that goes after a while) waits, under a test that drives the App, until the test moves the time on (tdptest); one made with tea.Tick runs on the real clock there too.
func (*App) Toast ¶
Toast shows a short message from the bottom (tdp toast); a second one replaces the first and starts its time again. Each string of text is a row of its own, folded when too long: the app's own text has no line break in it, so a \n on the screen is from outside, drawn by its name (components, control characters). Each row starts with a capital letter, a name or a path keeping its own case (kbu.yaml saved): the lib draws the words as they are, not telling a name from a word (tdp toast.2).
type Ask ¶
type Ask struct {
Title string // the action's name, after the shield glyph: "Delete"
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Question string // the last line: "Delete web-a8k2?"
Verb string // Enter:<verb> in the hint: "delete"
Details []string // what to read before answering, above the question
Warn []int // which lines of Details are warnings (Peach)
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
Ask is a confirm popup (tdp confirm): Enter accepts, Esc cancels.
type Body ¶
type Body interface {
// Draw returns h lines of exactly w cells: the inside of the frame.
Draw(w, h int, focused bool) []string
// Key handles a key the panel did not take; it reports whether it did
// something with it. Movement keys arrive here.
Key(key string, msg tea.KeyMsg) (bool, tea.Cmd)
// HasItem reports whether the cursor is on an item, so that item
// operations apply (tdp M2).
HasItem() bool
// Scroll is the scroll position for the bottom border after the last
// Draw ("3 of 40", "1-20 of 120"), "" when everything fits.
Scroll() string
// MoveKeys are the movement keys that work here, for the key
// reference's move section (tdp K6).
MoveKeys() []KeyRow
}
Body is what is inside a panel's frame. The lib has List, Values, Pager, FilePreview and Terminal; an app that draws its own content implements Body itself. A body with an Empty() bool method that reports true has the panel's LoadingText or Fail in its middle instead, whatever the kind of panel (tdp panel.15); the lib's all have it, and a panel with no Body is empty too. A body that learns only as it draws that it has nothing to show (laid out to the panel's width, as a diagram) has a Failure() *Failure method: the panel asks it after each Draw, and one it reports is drawn as Fail in the same frame, the body taken as empty; the panel's own LoadingText and Fail come first. A body with an Uncover(rows int) method is told before each Draw how many rows at the bottom of its inside the inspect toast covers, 0 for none (tdp toast.4): it scrolls so that the item under its cursor shows above them, as List and Values do.
type Checks ¶
type Checks struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Options []string
Checked []bool
// Cursor is the option the cursor starts on, scrolled into sight; the
// app decides (tdp checkbox). 0, the first, by default.
Cursor int
// Surface2, the tick too, but the cursor stops on it and Space flips it
// like any other; what it means is the app's (tdp checkbox).
Unavailable func(i int) bool
// Loading, for a checkbox popup opened with LoadChecks, is true while
// Options are still coming; Checked may be shorter than Options.
Loading bool
// Done gets the new set. It is not called when nothing changed.
Done func([]bool) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func([]bool) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
Checks picks several values (tdp checkbox.2 popup): Space checks a row on screen only, Enter writes the whole set back.
type Color ¶
Color is a colour or no colour (the terminal's own).
func LayerColor ¶
LayerColor is the colour of the popup at layer k, the bottom one being 1; layer 4 and up are Sapphire. A toast is always layer 1.
type ColorPicker ¶
type ColorPicker struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Value is the colour now; one not Set is no colour yet (the theme's
// own): old shows none and no swatch, new starts from #000000, and Choose
// always counts as a change (tdp color-picker).
Value Color
// Done gets the new colour. It is not called when it did not change.
Done func(Color) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(Color) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
ColorPicker picks a colour (tdp color-picker): old and new side by side, the red, green and blue channels each chosen from a select.
type Column ¶
type Column struct {
// Title is the column's header. A list of one column whose Title is ""
// has no header.
Title string
// Number marks a number column: right-aligned and sorted by value (9
// before 10). Text columns are left-aligned and sorted as text.
Number bool
// Flex did let the column give up room first when the panel is narrow. It
// does nothing since tdp v0.8.0: mark a long column Shrink.
Flex bool
// Shrink marks a column of long values (a name, a URL, a line of text):
// the shrinkable columns share the width the others leave, cut each its
// own way when too long, down to MinWidth (12 cells when unset). The
// other columns, short values (a state, a number, a date), keep the width
// of their widest value (tdp panel).
Shrink bool
MinWidth int
// Drop is when the column is taken away, whole and its header with it,
// when the columns do not fit even with the shrinkable ones at their
// MinWidth: 1 first, then 2 and on; 0 never (the name). As the panel
// grows they come back in order, and the shrinkable ones grow back
// (tdp panel).
Drop int
// Path cuts the column's values from the front ("…/.ssh/id_ed25519").
Path bool
// Middle cuts the column's values in the middle, for a value whose two
// ends both matter ("demo-app…66-gm72n").
Middle bool
// Line marks a column of lines of text, for reading (a line of source
// code, of a log): a Tab in it is drawn as input_tab_width spaces, its
// layout; any other control character is still its name in Red
// (components, control characters).
Line bool
}
Column is one column of a List (tdp panel.5).
type Compare ¶ added in v0.4.7
type Compare struct {
// Key is the compare key (the app's choice, kbu's C): on a row it enters
// the mode with that row as the anchor; in the mode it compares, as
// Enter does.
Key string
// Can reports a row that can be compared: text, shown as text, or one
// that holds many (Many). A row it says no to has no Compare action,
// and in the mode the compare keys are off on it (tdp M2, M6). Nil:
// every row.
Can func(Row) bool
// Name is the row as the title names it; its first cell when nil.
Name func(Row) string
// Text is the row's text, compared line by line.
Text func(Row) (string, error)
// Split does nothing.
//
// Deprecated: every comparison opens on UNIFIED and the tab chosen is
// not kept (tdp note.8). The field stays so that code setting it still
// builds; a later minor version takes it away.
Split *bool
// Many reports a row that holds many (a directory, a namespace, a
// commit). Two such rows are not compared as text: the mode goes in to
// the list of the items that differ between them, which Items gives, as
// OpenDiff goes in (tdp panel.9), the location row <anchor> ↔ <the
// other> as Name names them. A row that holds many and one that does
// not are not compared: the compare keys are off (tdp M6). Nil: no row
// holds many.
Many func(Row) bool
// Items gives the items that differ between two rows Many says yes to,
// the anchor first, in the order they are listed, the ones the same on
// both sides left out (DiffItem).
Items func(anchor, other Row) ([]DiffItem, error)
}
Compare is what a list's compare mode needs from the app (tdp panel.9; tdp note.8): the key, which rows can be compared and their text. The lib does the rest.
type DatePicker ¶
type DatePicker struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Value is the value now; zero for none.
Value time.Time
// Time adds the hour and the minute (five minutes a step).
Time bool
// Min and Max limit the dates; zero for no limit.
Min, Max time.Time
// SundayFirst starts a week on Sunday instead of Monday.
SundayFirst bool
// Done gets the new value. It is not called when it did not change.
Done func(time.Time) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(time.Time) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
DatePicker picks a date, or a date and a time (tdp datetime-picker).
type DiffItem ¶ added in v1.2.18
type DiffItem struct {
// Mark is how the item differs. OpenDiff does not use it.
Mark DiffMark
// Name is the item as the list shows it after its mark, named as the
// app names it (a path, internal/ui/ui.go); one the app knows was
// renamed or moved is DiffChanged, named "<old> → <new>".
Name string
// Anchor and Other name the item's two sides as the app names them, so
// that they say where, the older one the anchor (ui.go @ 1a2b3c4,
// ui.go @ 5d6e7f8): its comparison is titled DIFF — <Anchor> ↔ <Other>,
// the same however it is reached, and the list it goes into has
// <Anchor> ↔ <Other> for its location row, in place of the panel's own
// (tdp panel.9).
Anchor, Other string
// Text gives the item's text on each side, "" on a side it is not on:
// opening it opens its comparison, UNIFIED and SPLIT (tdp note.8).
Text func() (anchor, other string, err error)
// Items, for an item that holds many itself, gives the items that
// differ in it: opening it goes in to them, as Compare.Items.
Items func() ([]DiffItem, error)
}
DiffItem is an item that differs between two things that hold many (two directories, two namespaces, a commit and the one before it), or one item's two versions (tdp panel.9, note.8). The app names it and its two sides and gives what is in them; the lib draws the rest.
type DiffMark ¶ added in v1.2.18
type DiffMark byte
DiffMark is how an item differs, the anchor being the base (tdp panel.9): drawn before its name, in its colour.
type Elevate ¶ added in v0.6.4
type Elevate struct {
Tool ElevateTool
// Command is what runs with raised privileges: the program and its
// arguments ("cp", temp, "/etc/hosts").
Command []string
// Verb is what Enter on the password does, for the hint ("write"); run
// when unset.
Verb string
// Subject is what it acts on ("/etc/hosts"), after the tool's name in
// the title of doas's terminal popup.
Subject string
// Done gets how it ended: nil when the command ran and succeeded, an
// *ElevateError when it or the tool failed, for the app's error popup
// (tdp F5). Once the password is taken the command runs to its end, and
// Done comes even when the popup was closed meanwhile.
Done func(err error) tea.Cmd
// OnCancel runs when the user cancels before the command runs: Esc on
// the password popup, or leaving doas's terminal popup.
OnCancel func() tea.Cmd
}
Elevate is a command to run with raised privileges, such as a copy over /etc/hosts (tdp terminal.7). The app gives the command and the lib does the rest: it runs at once when no password is needed (sudo -n); otherwise sudo's password is asked for in a password popup, PASSWORD, the unlock look, and handed to sudo on its standard input and nowhere else. It goes in no file, not in the App Log, not on the screen and is sent nowhere; nothing gives it to the app. A wrong one keeps the popup open, the dots cleared and Wrong password on its error row; Esc cancels, and the command does not run. Doas asks for it itself, in a terminal popup that closes when it ends. On Windows the app raises privileges itself (gsudo, or the sudo Windows has, the system asking with UAC).
type ElevateError ¶ added in v0.6.4
ElevateError is a command run with raised privileges that failed, or the tool that did: Lines are what it printed, blank lines left out, and Err is how it ended.
func (*ElevateError) Error ¶ added in v0.6.4
func (e *ElevateError) Error() string
Error is the first line it printed, or how it ended when it printed none.
func (*ElevateError) Unwrap ¶ added in v0.6.4
func (e *ElevateError) Unwrap() error
type ElevateTool ¶ added in v0.6.4
type ElevateTool int
ElevateTool is a tool that raises privileges, the app's to choose by platform (tdp terminal.7).
const ( // Sudo reads the password on its standard input: the lib asks for it in // a password popup and hands it over. Sudo ElevateTool = iota // Doas cannot: it runs in a terminal popup and asks there itself. Doas )
type Failure ¶
type Failure struct {
Fact, Hint string
}
Failure is what a panel shows when its content could not be had (tdp panel.15): a fact in Red and a hint naming a key.
type Field ¶
type Field struct {
Label string
// Value is the value as shown (tdp input.10);
// Empty is what an empty value means, shown in grey ("not set").
// A control character in it, ESC too, is drawn by its name (Escape).
Value func() string
// Styled, when set, is how the value is shown in colours of the app's own
// (a swatch, ColorSpans; a state in Green): each piece's text drawn as
// Value's is. Value stays what the value is.
Styled func() []Span
Empty string
// Path cuts a value too long from the front: "…/.ssh/id_ed25519".
Path bool
// Options make the field a radio drawn in place, at most five (more is a
// mistake in the program: the panel panics as it draws): Selected is the
// chosen one. With Multi it is a group of checkboxes: Checked says which.
// They are for a fixed set the app defines: options that are the user's own
// data, their number changing with use (profiles), always go in a select
// or a checkbox popup (Edit), however many there are now (tdp radio.1,
// checkbox.1).
Options []string
Selected int
Multi bool
Checked []bool
// OptionUnavailable reports a checkbox option that is not available:
// drawn in Surface2, the tick too, but stopped on and flipped like any
// other (tdp checkbox).
Disabled func() bool
// Err marks the field's value as wrong, or as naming an entry of the
// user's own data that is not there, shown as written (tdp E3): its label
// turns Red.
Err func() bool
// Edit is what Enter does on a field that is not drawn in place: open its
// input popup.
Edit func() tea.Cmd
// OnChange runs when a radio or checkbox changes in place; it takes
// effect at once (there is no submit).
OnChange func() tea.Cmd
// Desc, when set, says what the row means, for the "what each row is"
// section first in the panel's key reference: the label is a word or
// two (tdp panel, note). Whether a panel has the
// section is the app's: it has it when a field has a Desc.
Desc string
// Group is the title of the group the field is in (tdp panel.12), drawn
// as a List's groups are (Row.Group), the title in Overlay0: a group's
// fields stay together, the groups in the order they first appear; the
// fields are drawn two cells further in, under a title the cursor
// skips. With groups, every field is in one: a field that fits no
// group goes in a group of its own ("Other").
Group string
}
Field is one value of a Values panel (tdp panel.12).
type FilePicker ¶
type FilePicker struct {
// Title is the field's name: the title writes the directory after it
// ("IDENTITY FILE · ~/.ssh").
Title, Glyph string
// Root is the directory the list opens in: a start, not a boundary.
Root string
// Value is the file now, if any: the cursor starts on it, in Green.
Value string
// Dirs picks a directory (tdp file-picker.7
// directory). Open it at the directory now (Root = Value): the cursor
// starts on ".", in Green.
Dirs bool
// Icon is a row's icon and its colour, the app's choice (a file type's
// colour); a folder or a file glyph in Text when unset.
Icon func(path string, dir bool) (string, Color)
// Done gets the chosen file (or directory). It is not called when it did
// not change.
Done func(path string) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(path string) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
FilePicker picks a file (tdp file-picker): a finder over a directory, Enter going into a directory or choosing a file. With Dirs it picks a directory instead: only directories are listed, and Enter on the first row, ". (this directory)", chooses the one listed.
type FilePreview ¶ added in v0.2.0
type FilePreview struct {
Path string
// Line is a text file's line to start near: a search's hit.
Line int
// FS is where it reads: the local disk when nil.
FS PreviewFS
// Icon is a tree entry's icon and its colour, as a FilePicker's.
Icon func(path string, dir bool) (string, Color)
// Info puts TYPE, SIZE, MODIFIED and MODE under the preview, after a
// separator.
Info bool
// EmptyFact and EmptyHint are what it says with no Path.
EmptyFact, EmptyHint string
// contains filtered or unexported fields
}
FilePreview is a panel's body that shows a file or a directory as a file-picker's preview does: a tree, a text file in colour with line numbers, an image, a PDF, hex; with Info, its four facts under it (tdp file-picker). As a details panel it follows its list's cursor: set Path in the list's OnMove (tdp panel.13). It takes no keys and does not scroll, as a preview does not.
func (*FilePreview) Draw ¶ added in v0.2.0
func (p *FilePreview) Draw(w, h int, _ bool) []string
Draw draws the preview in w × h, one cell from the frame on either side.
func (*FilePreview) Empty ¶ added in v0.2.0
func (p *FilePreview) Empty() bool
Empty reports whether there is nothing to show, for the panel's loading and failure.
func (*FilePreview) HasItem ¶ added in v0.2.0
func (p *FilePreview) HasItem() bool
HasItem is false: a preview has no item of its own.
func (*FilePreview) MoveKeys ¶ added in v0.2.0
func (p *FilePreview) MoveKeys() []KeyRow
MoveKeys are none.
func (*FilePreview) Scroll ¶ added in v0.2.0
func (p *FilePreview) Scroll() string
Scroll is "": a preview does not scroll.
type Finder ¶
type Finder struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Verb is what Enter on the list does, for the hint ("open").
Verb string
Items []FinderItem
Loading bool
// Preview is the row under the cursor: a title (its name, or where it
// is) and the lines to show.
Preview func(FinderItem) (title string, lines []string)
// Files says the items are files and directories, their IDs the paths:
// the preview shows them as a file-picker does, with their facts under
// it (tdp file-picker), instead of Preview.
Files bool
// FS is where Files reads the paths: the local disk when nil.
FS PreviewFS
// Search, when set, is a search the app runs itself (a search tool, a
// remote host), answering a batch at a time: it gets the typed words each
// time they change and puts what it finds in Items as it comes, Loading
// meanwhile; the list is then Items as they are, not filtered again. It
// must not wait for the search: typing goes on while it runs
// (tdp finder).
Search func(typed string) tea.Cmd
Done func(FinderItem) tea.Cmd
}
Finder is a list with a search that goes somewhere (tdp finder): type to narrow the list, Enter on a row to go there, the row under the cursor previewed beside it. Keep the pointer: rows may keep arriving — append to Items while Loading is true.
type FinderItem ¶
type FinderItem struct {
ID string // the app's own key for it
Text string // shown, and matched unless Match is set
// Match, when set, is what the typed words are matched against instead
// of Text: the item's other content, a file's text (tdp finder.7:
// what is matched is the app's choice).
Match string
// Icon, when set, goes before the text in IconColor (a file's type).
Icon string
IconColor Color
// Line, with Files, is a text file's line a search found: the preview
// starts near it.
Line int
}
FinderItem is one row of a Finder.
type Form ¶
type Form struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Name is the form in the discard question: "Discard changes to New host?"
Name string
Fields []*FormField
// Button is the main submit button's text: what the form does ("Save").
// ButtonSubject is the name it acts on, kept as it is after the verb on
// the button and in the hint: "Overwrite KBU.svg", "Enter:overwrite
// KBU.svg" (tdp form.13).
Button, ButtonSubject string
// Buttons are the action area's other buttons, row by row from the top,
// each row on the right. The main submit goes at the end of the last
// row, the bottom right; an empty last row puts it on a row of its own.
Buttons [][]*FormButton
// Focus, when set, is the field the form opens on.
Focus *FormField
// Submit does what the form is for once every Check passes. An error
// opens an error popup over the form, which stays; otherwise the form
// closes and the command runs.
Submit func() (tea.Cmd, error)
// SubmitLong is a Submit that takes long ("Connect"), in its place: it
// runs off the update loop, the loading icon after the title and Enter
// on its button doing nothing until it ends. ctx ends when the form
// closes first; what it returns then is dropped (tdp form).
SubmitLong func(ctx context.Context) (tea.Cmd, error)
// OnCancel runs when it closes without being submitted: Esc, its discard
// confirm, or the popup it is over closing it, as an Ask's and an input's
// do (tdp F6).
OnCancel func() tea.Cmd
}
Form is several values filled in and submitted together (tdp form): Enter on a field opens its input popup, options are chosen on the form, the button submits.
type FormButton ¶ added in v0.1.7
type FormButton struct {
// Label is what it does ("Overwrite"); Subject the name it acts on, kept
// as it is, as the form's ButtonSubject.
Label, Subject string
// Submit makes it another submit ("Save As"): it checks the whole form
// as the main one does, and the form closes once it is done. SubmitLong
// is one that takes long, as the form's.
Submit func() (tea.Cmd, error)
SubmitLong func(ctx context.Context) (tea.Cmd, error)
// Run makes it an action that keeps the form open ("Test"). It checks
// Needs first, the fields it needs (their Check); then it runs off the
// update loop, the loading icon after the title and Enter on it doing
// nothing until it ends. ctx ends when the form closes first; its result
// is then dropped, Apply too.
Needs []*FormField
Run func(ctx context.Context) FormResult
// Open makes it an action that opens a popup over the form, on the update
// loop, the form staying under it: a terminal popup (OpenTerminal) that
// copies a key to the host, say. Back, when set, runs as the popup it
// opened closes and the form is on top again: where the app reads what
// was done there into the fields; true counts as a change to the form.
Open func() tea.Cmd
Back func() (changed bool)
}
FormButton is a button of a form's action area besides the main submit (tdp form): another submit, or an action that keeps the form open. It has one of Submit, SubmitLong, Run and Open.
type FormField ¶
type FormField struct {
Label string
// Stacked puts the label on a row of its own and the value under it, as
// wide as the inside: for long values (a URL, a path, a command).
Stacked bool
// Value is the value as shown (tdp input.10);
// Empty is what an empty value means, in grey ("not set").
Value func() string
// Styled, when set, is how the value is shown in colours of the app's
// own (a swatch, ColorSpans): each piece's text drawn as Value's is
// (Escape). Value stays what the value is.
Styled func() []Span
Empty string
// Path cuts a value too long from the front: "…/.ssh/id_ed25519".
Path bool
// Edit makes the input popup Enter opens, when it opens: it starts from
// the value then.
Edit func() Input
// Options make the field a radio drawn on the form, at most five
// (Selected is the chosen one); with Multi, a group of checkboxes
// (Checked says which). They are for a fixed set the app defines:
// options that are the user's own data, their number changing with use
// (profiles), always go in a select or a checkbox popup (Edit), however
// many there are now (tdp radio.1, checkbox.1).
Options []string
Selected int
Multi bool
Checked []bool
// OptionDisabled reports an option that cannot be chosen now: drawn in
// the disabled colour and skipped (tdp form).
OptionDisabled func(i int) bool
// OptionUnavailable reports a checkbox option that is not available:
// drawn in Surface2, the tick too, but stopped on and flipped like any
// other (tdp checkbox).
Disabled func() bool
// Check is the whole form's rule for this field (required, depends on
// another field, a name taken), run when the form is submitted: what is
// wrong, or "".
Check func() string
}
FormField is one field of a Form (tdp form).
type FormResult ¶ added in v0.1.7
type FormResult struct {
Toast string
Info bool
Lines []string
Err error
// Apply, when set, runs on the update loop as it ends, before the result
// shows: where the action writes a value into a field, which then counts
// as changed.
Apply func()
}
FormResult is what came of a form's action (tdp form): Err opens an error popup, the focus on the button so that Enter tries again; else Lines open a note to read; else Toast says it in one sentence, a Success toast, or Info when Info is set: which one a thing done is, is the app's (tdp toast).
type FrameStatus ¶ added in v1.2.13
type FrameStatus struct {
Glyph, Text string
Corner Corner
// Kind is how what it tells is going: StatusFine draws it in the
// frame's colour, as the scroll position (Yellow in a mode); when it has
// gone wrong, StatusWarning and StatusError draw it in Peach and Red,
// dimmed on a panel without the focus, a streaming one too (tdp T2).
Kind StatusKind
}
FrameStatus is one lasting status of a panel's own on its frame (tdp panel.1), such as a file the panel watches and when it was last read: a glyph and a short text (U+F04E6 17:43:42), in the corner the app chooses. Whether a panel has one, what it says and where are the app's; the lib draws it while Glyph or Text is not "", and keeping to a glyph and a short text is the app's. In its corner it goes on the inner side of what is there, a space either side and a line segment between: top left after the capsule chain and the loading icon, top right left of the mode name, bottom left after the hint, bottom right left of a search's status and the scroll position; alone in its corner, a segment from it. On a border too narrow it is the first thing to go, whole, before the hint's pairs, and it comes back when there is room. The app sets and clears it as what it tells changes, from the update loop (a timer of its own made with App.Tick, its message in OnMsg; an action's Do), as any other field of the panel; popups have none.
type Input ¶
type Input interface {
// contains filtered or unexported methods
}
Input is an input popup to open on its own (App.Open) or from a form's field: TextInput, PasswordInput, NumberInput, Select, Checks, and the rest.
type KeyHint ¶
type KeyHint struct {
Key, Desc string
}
KeyHint is one "key:what" pair of a hint or the footer (tdp M5).
type KeySection ¶
KeySection is a titled section of a key reference ("terminal").
type List ¶
type List struct {
Columns []Column
// Marks keeps a column for marks in front of every row (Principle P3,
// batches of marked items).
Marks bool
// Draggable keeps that column too, for the swap glyph of the row held in
// a Drag mode (tdp panel): Hold, MoveHeld, Drop.
Draggable bool
// Flags keeps that column in a list that cannot be marked for the rows'
// flags (Row.Flag), one a row (tdp panel.7). A list that can be marked
// keeps it for the tick: Marks and Flags together is a mistake, and
// AddScreen panics.
Flags bool
// Anchor is the ID of a row a mode keeps picked while the cursor moves
// on (a Compare mode's first pick, tdp K11): drawn whole in Yellow,
// the mode's, with Base text, not bold and no arrow, as a selected range
// (tdp color, note). The cursor on it wins. "" is none.
Anchor string
// Filterable lets / open a panel filter on the list.
Filterable bool
// EmptyFact and EmptyHint are what an empty list says (tdp screen.8);
// keys in the hint written in brackets.
EmptyFact, EmptyHint string
// Location, when set, is the list's location row: where the user is (a
// directory, a remote path, the level drilled into), in Lavender on the
// panel's first row, cut from the front. It is only shown: the cursor
// does not stop on it and the scroll position does not count it
// (tdp panel.10). Whether a list has one is the app's. In a panel the
// panel draws it, as Panel.Location: it stays over Loading and Fail and
// dims with the focus, a streaming panel's too.
Location string
// LocationGlyph, when set, starts the location row: one glyph for the
// kind of place, one space after it, in the row's colour, dimming with
// it. A row too long is cut in Location only: the glyph stays and the
// … comes right after it (tdp panel.10). Whether there is one, and
// which, is the app's; it goes with this Location.
LocationGlyph string
// OnMove runs when the cursor comes to another row, by a key or not, the
// first time included: before the frame is drawn, so a details panel
// shows that row in the same frame (tdp panel.13). It does not
// run while no row is under the cursor.
OnMove func(Row) tea.Cmd
// Points, when set, is the panel on the screen a row stands for, nil for
// none (tdp panel.1; whether a list has one
// is the app's). While the list has the focus, the panel its cursor's row
// stands for is pointed at: its frame Lavender, still thin and square, not
// focused, its content dimmed as any panel without the focus. A panel not
// on the screen is not pointed at.
Points func(Row) *Panel
// contains filtered or unexported fields
}
List is a panel body with one item per row: a header, a cursor, marks, a panel filter (tdp panel).
func (*List) Actions ¶
Actions are the list's own panel operations: the filter. Filtering only changes what is in view, so it does not go in the App Log (tdp note.7).
func (*List) Draw ¶
Draw draws the list in w × h: the location row, the filter's typing row, the header, the rows.
func (*List) Drop ¶ added in v0.1.6
func (l *List) Drop()
Drop puts the held row down where it is; its own mark shows again.
func (*List) Focus ¶
func (l *List) Focus()
Focus is called when the panel gets the focus: a list with a filter set goes straight back to its typing row.
func (*List) Hold ¶ added in v0.1.6
Hold picks up the row under the cursor in the panel's Drag mode (tdp panel): it is drawn as the cursor in the mode's colour, Yellow, with the swap glyph in its mark column, until Drop. It reports whether there was a row. The Drag mode and its keys are the app's (Panel.EnterMode).
func (*List) MoveHeld ¶ added in v0.1.6
MoveHeld swaps the held row with the next or the previous row shown, the cursor going with it. Past the ends it wraps: the last moved down goes to the top and the others move down one (tdp K12). It moves the rows themselves: a sorted list shows no move, so the app leaves the sort first.
func (*List) MoveKeys ¶
MoveKeys are the list's movement keys; none when nothing is shown, nothing to move to (tdp M6).
func (*List) OpenFilter ¶
func (l *List) OpenFilter()
OpenFilter puts a typing row at the top of the list, or goes back to it to type on (tdp panel.14).
func (*List) Select ¶
Select puts the cursor on the row with this ID, the next frame scrolling it into sight, and reports whether it is shown. After the app adds an item (New, Copy, Import), it selects it (tdp K3); a row the panel filter hides is not shown, so the app clears the filter first if it wants it seen.
func (*List) SetMarked ¶ added in v0.2.0
SetMarked marks the rows with these IDs and unmarks the others, the rows the panel filter hides too.
func (*List) SetRows ¶
SetRows replaces the list's rows, keeping the cursor on the same row when it is still there.
func (*List) SortBy ¶
SortBy sorts the list by keys, first key first: numbers by value, text as text (tdp panel). nil keeps the rows' order. Rows the keys cannot tell apart go by their IDs, so the same rows come out in the same order however they were set: a list must keep one order every time it is opened or fetched again, and data with no order of its own (a kubeconfig's contexts) is sorted by name.
func (*List) ToggleMark ¶
func (l *List) ToggleMark()
ToggleMark marks or unmarks the row under the cursor.
type MenuSection ¶
MenuSection is a group of a menu's rows under a title. A menu of one group needs none; in a menu of more, every group has one, the first too (Rules M8).
type Misfit ¶ added in v1.2.16
type Misfit struct{ Key, Was, Now string }
Misfit is a value or an entry of a file of the app's own that did not fit (tdp E3). Key names it: a value's key ("color"), or which entry it is with what it had (`entry 3 (name "")`). Was is what the file had for a value; Now is what is used now, "" for an entry taken out (a value whose default is empty says so in words: "none").
type Mode ¶
type Mode struct {
Name string // shown at the right of the top border: one word
// Keys are the mode's own keys: the only ones that work besides the
// core keys of K11. They are listed in its key reference and the footer.
// Space is one of them only where the user put an action on it (ModeKey).
Keys []ModeKey
// Exit is the verb Esc does in the footer ("cancel" for Esc:cancel).
Exit string
// NoLeaveRow keeps the row leaving the mode ([Esc] and Exit) out of its
// Space menu, as a key's NoMenu does (tdp K11); Esc leaves as ever. A
// menu that would list nothing lists it all the same: it has a row.
NoLeaveRow bool
// Pause suspends Tab and the digits in the mode; pressing them then says
// to leave the mode first.
Pause bool
// OnExit runs when Esc leaves the mode, to go back to the state before it.
// Leaving a mode of the app's own, it may open one popup saying where
// things are left (paused: go on?), the mode left by then; Esc on it
// closes it, still outside the mode, and going back in is the popup's
// own action, EnterMode (tdp K11).
OnExit func() tea.Cmd
// Inspect is the inspect toast of the item under the cursor in the mode,
// as Panel.Inspect: while the panel is in the mode it is asked instead of
// the panel's, an inner layer's before an outer one's.
Inspect func() []string
}
Mode is a temporary state of a panel in which some keys mean something of their own and Esc leaves (tdp K11).
type ModeKey ¶
type ModeKey struct {
// Key is how it is written in the footer and the key reference ("j|k");
// Keys are the keys it takes, Key itself when empty. The lib adds none:
// the arrow keys and PgUp|PgDn go in Keys as tdp K12 has them (j|k
// takes j, k, ↓, ↑; u|d takes u, d, PgUp, PgDn), Key writing the letters.
// A movement key with nothing to move in the mode may do the mode's own
// action, its arrow key the same (in a mode where nothing moves up, one
// ModeKey taking k and ↑: tdp K12). A key the user sets (tdp K11) is the
// app's to put in Key and Keys while the mode is on, and what is shown
// follows them; one already in use in the mode is the app's to refuse,
// with a Warning naming what has it. In a mode of the app's own, Enter
// and the movement keys may be set too: a moved movement key is still
// one (NoFooter), the letter it left may take another action, and the
// arrow key stays in the Keys it had, the mode's default (moving left
// set to a takes a and ←); the key reference then writes it after Key
// (a|←), the footer and the Space menu Key alone. The user may put one
// of the mode's actions on Space as well, never the app by default (tdp
// K11): a ModeKey with a Do taking Space. Space then does it, nothing
// while it is disabled, and the mode has no Space menu; the footer writes
// it first, where Space:menu was (Space:drop ?:help), NoFooter or not,
// and ? lists it among the mode's keys, no longer among the core keys.
// The keys only that menu listed go in the footer then (NoFooter off);
// refusing Space when it is taken, the Warning saying what Space does
// now, and keeping Space for the menu in a mode of tdp's (Drag, Compare)
// are the app's. A ModeKey taking Space with no Do is the core key as
// ever, Space opening the menu. An arrow key with its letter in the
// same Keys is that letter, not written (tdp K12). g alone
// is a key of the mode where none of its keys is a pair starting with g
// (gg); with one, g waits for the key after it. A core key a mode of the
// app's own writes in the footer among its keys (q:quit, tdp screen.2)
// is a ModeKey with no Do: the key does what it does in any mode, its
// row in the Space menu too, and ? lists it once, among the core keys.
Key string
Keys []string
Desc string
NoFooter bool
// NoMenu keeps it out of the mode's Space menu: what a mode of the app's
// own lists there is the app's (tdp K11). It stays in ? and the footer.
NoMenu bool
// Ref, when set, is what the mode's key reference writes for it, one row
// or more in its place, instead of Key, Desc and the arrow keys written
// after Key; drawn disabled with it. The footer and the Space menu stay
// as they are. A pair (one way each half) whose one half the user set to
// another key, its arrow key still doing that half, is two rows there
// (rotate left set to Enter: Enter|PgDn rotate left, k rotate right; tdp
// M5, K11). Without Ref the arrow key goes after the pair (Enter|k|PgDn):
// listed, but not as tdp M5 writes it.
Ref []KeyRow
// Do runs it, with the key pressed. A row of the mode's Space menu closes
// the menu before Do runs, so a popup Do opens goes back to the mode when
// it is cancelled or closed, not to the menu (tdp K11).
Do func(key string) tea.Cmd
// Disabled reports that it cannot be pressed now: in the disabled colour
// in the footer and the key reference, pressing it does nothing (tdp M6).
Disabled func() bool
// In the mode's Space menu (tdp menu.4): Item puts
// it under ITEM OPERATION, a key acting on the item under the cursor or
// the range selected; the others go under the mode's name, a NoFooter one
// (a movement key) only shown. Label names its row, its hotkey marked
// (Compare: [C]ompare), Desc capitalised when empty; MenuDesc describes it.
Item bool
Label string
MenuDesc string
// contains filtered or unexported fields
}
ModeKey is one of a mode's keys.
type Notice ¶ added in v1.2.17
Notice is one row of the toast a start gives, with its own kind (tdp E3, several at one start): a location moved, values that did not fit (MisfitNotice), a copy that could not be made (KeepAside's error), a value naming an entry that is not there. Notify shows them as one toast; with no screen, each Text that is not "" is a line of its own on stderr.
func MisfitNotice ¶ added in v1.2.17
MisfitNotice is DidNotFit's row, a Warning in DidNotFitText's words, carrying a WARN for each misfit that Notify logs right after it. With copy "" its Text is "": no row, the WARNs still logged.
type NumberInput ¶
type NumberInput struct {
Title, Glyph, Prompt, Verb string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Name is the value's name in its errors ("Port must be 1-65535"); left
// unset, the title names it.
Name string
Old string
// Suggest is a value the app proposes when there is no Old, as on a
// TextInput.
Suggest string
Min, Max float64
Negative bool // "-" may be typed
Decimal bool // "." may be typed
// Optional lets the value be empty: an empty one is not checked against
// the range and is written back empty; what it means the form or panel
// says in grey (tdp number). Otherwise empty is an error.
Optional bool
// Unit is what the number counts, the whole word ("seconds"), in grey on
// a row of its own under the value (tdp number).
Unit string
Check func(string) error
Done func(string) tea.Cmd
// Stay keeps it open under what Done opens: a step of a flow (current
// PIN, new PIN, confirm PIN), each step a popup of its own, Esc on the
// next one coming back here (tdp F1, F4). The app ends the flow with
// CloseTop when its last step is done (tdp T1).
Stay bool
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(string) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
// Unchanged, when set, runs when Enter takes the value it opened with, so
// nothing is written back and Done is not called: a step of a flow ends
// the flow (CloseTop), a page waiting for an answer gets the value it
// offered (tdp K3, F6).
Unchanged func() tea.Cmd
}
NumberInput is a number (tdp number).
type Pager ¶
type Pager struct {
Follow bool
// EmptyFact and EmptyHint are what it says with no lines.
EmptyFact, EmptyHint string
// contains filtered or unexported fields
}
Pager is a panel body that shows lines with no cursor: a preview, a log. When Follow is set, new lines keep it at the bottom as long as it was there; scrolled up, it stays where it is. A Pager that takes lines while it is open (Append, ReadAgain) sets Follow (tdp note.9). Its lines are reading content, drawn as a terminal draws them (components, control characters): \n starts another line, a \r in one leaves its last state, SGR colours it, a tab is spaces, any other control character is its name in Red.
func (*Pager) HasItem ¶
HasItem is false: a text has no items (tdp K3: Enter works on the whole panel).
func (*Pager) MoveKeys ¶
MoveKeys are the scrolling keys; none when every line fits, nothing to scroll (tdp M6).
func (*Pager) ReadAgain ¶ added in v1.2.14
ReadAgain puts lines in place of the Pager's, its source read again (a file it watches; tdp note.9): with Follow, at the new end when the end was in sight; otherwise where it was, at the new end when the lines are fewer than fill it. SetLines is new content, the view going nowhere.
func (*Pager) SetDiff ¶
SetDiff shows a difference as UNIFIED does (tdp note.8 "In a panel"): anchor's text against other's, only the parts that differ with 3 lines around, an Overlay0 line between them as wide as the panel, both line numbers in Overlay0, - in Red and + in Green; never a tool's own output. The same text on both sides shows the empty state (EmptyFact). Lines are cut at the panel's edge, as every Pager line is; the comparison folds them. The view stays where it was, as with SetLines; SetLines, Append and ReadAgain go back to plain lines. Enter is the panel's own action, App.OpenDiff opening the comparison of the same two (tdp note.8).
func (*Pager) SetDiffItems ¶
SetDiffItems shows the items that differ in what holds many (tdp note.8 "In a panel": a folder that is new, a commit), never their bare names: each item's mark in its colour in the mark column, then its name, a long one cut from the front, as the list App.OpenDiff goes into draws them (tdp panel.9; a new folder's items all DiffAdded, + in Green). None is the empty state (EmptyFact). The view stays where it was, as with SetLines; SetLines, Append and ReadAgain go back to plain lines. Enter is the panel's own action, App.OpenDiff with Items giving the same items going into that list in the panel.
type Panel ¶
type Panel struct {
// Label is the panel's name after its [N]. With tabs it is the first
// tab's name: a panel has no other name (tdp panel.4).
Label string
// Name, when set, is the name of the one thing the panel shows, kept as it
// is after the label, upper case, and ": " ([2] PODS: nginx-7d4f); with no
// Label it is the whole label ([1] prod-web-01). The Space menu and the
// key reference write it so too (components, upper case).
Name string
// Tabs are the panel's other tabs, after the label's own. Tab is the
// current one, 0 being the label's; h/l switch tabs and call OnTab.
Tabs []string
Tab int
OnTab func(tab int) tea.Cmd
Body Body
// Location, when set, is the location row of a panel with no list, a
// reader (a file, a web page): where the user is, on the panel's first
// row above its body, drawn as List.Location (tdp panel.10) and kept
// there whatever the body shows, its empty state, Loading or Fail
// included; it dims with the focus, on a Stream panel too. A list's
// List.Location is drawn here the same way; with both set, this one is
// the row. Whether a panel has one is the app's.
Location string
// LocationGlyph is the glyph that starts Location's row, drawn as
// List.LocationGlyph; a list's own goes with the list's Location.
LocationGlyph string
// SearchStatus is the status of the app's own / search in the panel
// (a panel with no cursor searching its text, a mode's search), drawn
// on the bottom border left of the scroll position while its Count is
// not 0 (tdp note.3, panel.1). The app sets it as the hits change and
// clears it with them (Esc).
SearchStatus SearchStatus
// FrameStatus is the panel's own lasting status on its frame, a glyph
// and a short text in the corner the app chooses (tdp panel.1); the zero
// value is none.
FrameStatus FrameStatus
// Actions are the panel's item and panel operations; a "Enter" key is
// what Enter does here (tdp K3).
Actions []Action
// Details is the panel that shows the item under this panel's cursor
// (tdp panel.13): the "Enter" action may send the
// focus there (Action.ToDetails).
Details *Panel
// Stream marks streaming content, which is not dimmed when unfocused
// (tdp T2): what a running program or a connection keeps sending.
// Content read again from a source that changed (a watched file, a log
// file among them) is not streaming and dims (tdp T2, note.9).
Stream bool
// Loading puts the loading icon after the capsule chain; LoadingText is
// what an empty panel says meanwhile ("loading pods…", tdp panel.15).
Loading bool
LoadingText string
// Fail, when set and the panel has nothing to show, is shown in its middle.
// A failure known only while the body draws is the body's Failure()
// (Body).
Fail *Failure
// OnEsc is the app's "one level up" for Esc on this panel (tdp K4); it
// reports whether there was one.
OnEsc func() tea.Cmd
// HintPressableOnly leaves what cannot run now out of the bottom-border
// hint (tdp M6: the app's choice); otherwise it is listed in the
// disabled colour, as in the Space menu and ?.
HintPressableOnly bool
// OtherKeys are sections of its ? about another surface that has no key
// reference of its own (tdp M6: a PTY, a grid), after the panel's own.
OtherKeys []KeySection
// Inspect, when set, is what the item under the panel's cursor has to show
// in an inspect toast (tdp toast.4), nil for an item with nothing: each
// string a row of its own, as Toast's. The lib asks it after every message
// while the panel has the focus and shows the toast, with no timer and no
// key of its own, every key going through it; it goes when the cursor
// leaves the item, and an ordinary toast replaces it until that one is
// gone. Which items have one and what it says are the app's.
Inspect func() []string
// contains filtered or unexported fields
}
Panel is a region of a screen with its own cursor and content (Principle "Panel"). It is numbered by its place in its screen, from [1].
func (*Panel) EnterLayer ¶ added in v1.1.1
EnterLayer goes a layer further into the mode the panel is in, to m (tdp K11): its name follows the mode's after ">" (Visual>select), its keys and Exit are the ones that work, and Esc leaves m alone, running its OnExit, back to the layer it was in. Out of a mode it is EnterMode.
func (*Panel) LeaveDiff ¶ added in v1.2.18
func (p *Panel) LeaveDiff()
LeaveDiff leaves every list of the items that differ the panel went into (App.OpenDiff, tdp panel.9), back to its own rows as they are now, the cursor where the app left it: for an action of the app's own that shows something in the panel (Enter on a branch putting its commit under the cursor of the panel that went into a commit), as if Esc were pressed until it is back. It does nothing when there is none. A mode the panel is in stays: a compare mode goes back to picking, its anchor kept.
func (*Panel) LeaveMode ¶
func (p *Panel) LeaveMode()
LeaveMode leaves the whole mode, every layer, without running an OnExit: a mode of the app's own ending by its own key or on its own (a game over). The mode's Space menu and ? close with it, and what is open over them (tdp K11); a popup the app opens then is over the panel.
type PasswordInput ¶
type PasswordInput struct {
Title, Glyph, Prompt, Verb string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Name is the value's name in its errors when the title is not
// ("Password" on a "Log in"); left unset, the title names it.
Name string
// Set says a password exists now: eight grey dots stand for it.
Set bool
// Unlock is the unlock look: one ● per character, a cell apart, centred
// (a PIN), and no prompt row: the title says what to type (UNLOCK,
// CURRENT PIN); otherwise one • per character from the left.
Unlock bool
MaxLen int
Check func(string) error
// PausedUntil, when set, is asked when the popup opens and after each
// Enter: until the time it gives, the popup takes no value, the error row
// counting down each second ("try again in 27 s") and every key but Esc
// swallowed (a PIN wrong too many times; tdp
// popup.7).
PausedUntil func() time.Time
// Done gets the new password; "" with clear true when it was removed.
Done func(value string, clear bool) tea.Cmd
// Stay keeps it open under what Done opens: a step of a flow (current
// PIN, new PIN, confirm PIN), each step a popup of its own, Esc on the
// next one coming back here (tdp F1, F4). The app ends the flow with
// CloseTop when its last step is done (tdp T1).
Stay bool
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(value string, clear bool) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
// Unchanged, when set, runs when Enter takes the value it opened with, so
// nothing is written back and Done is not called: a step of a flow ends
// the flow (CloseTop), a page waiting for an answer gets the value it
// offered (tdp K3, F6).
Unchanged func() tea.Cmd
}
PasswordInput is a masked input (tdp password).
type Popup ¶ added in v0.1.9
type Popup struct {
// Title is what the popup is for, upper case on the frame; Subject is
// the one thing it acts on, kept as it is after ": " ("DRAW: kamonu";
// tdp popup.1). Glyph goes before the title.
Title, Glyph, Subject string
Body PopupBody
// Actions, when set, says it has values to submit: it then works as a
// form (tdp popup.8, form). The action area goes under the content;
// Tab and Shift-Tab go between the two, back to where the focus was;
// on the buttons the keys are the lib's. A body with Check keeps an
// error row. Esc asks first once the body has Changed. q does nothing,
// Ctrl-C is the quit flow (tdp K9).
Actions *PopupActions
}
Popup is a popup of the app's own, for what none of the seven kinds holds (a grid to draw on; tdp F1, popup.8). The app draws what is inside the frame and handles its keys; the lib draws the frame with the title and the hint in the layer colour, dims what is under it, opens and closes it with the animation (tdp F2, F8), and puts its own popups over it: a confirm, an input, an error popup, the key reference.
type PopupActions ¶ added in v0.5.0
type PopupActions struct {
// Button is the main submit's text ("Save"), at the bottom right;
// ButtonSubject the name it acts on. Buttons are the others, row by row
// from the top. A button's Needs has no fields to name here: a Run button
// checks nothing.
Button, ButtonSubject string
Buttons [][]*FormButton
// Submit and SubmitLong do what it is for once the body's Check passes;
// it then closes. With neither, the main button only closes it.
Submit func() (tea.Cmd, error)
SubmitLong func(ctx context.Context) (tea.Cmd, error)
// OnCancel runs when it closes without being submitted.
OnCancel func() tea.Cmd
// Name is what the discard question names: "Discard changes to
// kamonu?"; the popup's Subject, else its Title, when unset.
Name string
// Content names the content in a button's hint, where Tab goes back
// to: "grid" in "Tab:grid"; "content" when unset (tdp form.13).
Content string
// ErrorSubject, when set, is the name the error popup of a failing
// button puts after ": " in its title ("SAVE FAILED: kamonu"), the
// buttons keeping their own text; unset, a button's own subject goes
// there, as on a form (tdp note.6, popup.1).
ErrorSubject string
}
PopupActions is the action area of a popup of the app's own with values to submit; each field works as a Form's of the same name (tdp form.7).
type PopupBody ¶ added in v0.1.9
type PopupBody interface {
// Size is the inside on a sw × sh screen: w cells from frame line to
// frame line, h rows between the blank rows above and below. It is asked
// when the popup opens and when the terminal changes size; the lib makes
// it wide enough for the title and the hint, and no bigger than the
// screen allows (tdp F7).
Size(sw, sh int) (w, h int)
// Draw returns h lines of w cells; layer is the popup's colour. The cell
// at either end is the blank margin, which only a full-row cursor covers
// (tdp popup).
Draw(w, h int, layer Color) []string
// Key handles a key while the popup is on top and reports whether it
// did. The lib does the keys it leaves: Esc closes the popup, ? opens its
// key reference, q starts the quit flow (tdp K1). Ctrl-C never comes
// here: it is always the quit flow (tdp K9). Space comes here too: on a
// cell with several values it goes to the next one (tdp K5).
//
// With Actions, only the keys on the content come here, and not Tab,
// Shift-Tab, Esc or q: those are the lib's, as on a form.
Key(key string, msg tea.KeyMsg) (bool, tea.Cmd)
// Hint is the hint on the bottom frame line now (tdp M5). With Actions,
// only the content's own keys: the lib adds Tab:actions and Esc:cancel,
// and writes the hint on the buttons.
Hint() []KeyHint
// Keys is its key reference: only its own keys, Esc among them (tdp K6).
// With Actions, only the content's: the lib adds the buttons', Tab and
// Esc.
Keys() []KeySection
}
PopupBody is the inside of a popup of the app's own. It must be comparable, a pointer most often: ClosePopup finds the popup by it.
A body may also have QuitNote() string: what quitting now would lose ("Changes to kamonu are not saved."), "" for nothing. The quit flow's confirm puts it last, in Peach, and asks first even when App.Quit is nil (tdp K9: the quit flow is the app's).
A body that scrolls may also have Scroll() string: its scroll position ("3 of 40", "1-20 of 120"), "" when everything fits. The lib draws it on the right of the bottom frame line in the layer colour and, when the popup opens, makes it wide enough for it and the whole hint (tdp popup.6).
A body with Actions may also have:
- Changed() bool: something was changed, to be lost by Esc; once it says so, Esc asks first (tdp form.15).
- Check() string: what is wrong with the values, "" for nothing. It runs at each submit; what it says goes in the error row and stays until the next check, the focus back on the content (tdp popup.7). This error row takes no focus, as in an input popup. The error row is the app's to decide (tdp popup.8): one that wants another, one the focus stops at say, leaves Check out and draws its own as the last rows of its content.
- Focus(on bool): called before each Draw, whether the focus is on the content (true) or on a button (false): draw where the focus is only while it is there (tdp L5).
type PreviewFS ¶ added in v0.2.0
type PreviewFS interface {
Open(name string) (PreviewFile, error)
Stat(name string) (fs.FileInfo, error)
// Lstat does not follow a link, ReadLink says where one points: a link's
// TYPE is "link → <target>".
Lstat(name string) (fs.FileInfo, error)
ReadLink(name string) (string, error)
ReadDir(name string) ([]fs.FileInfo, error)
}
PreviewFS is where a file preview reads: the local disk when nil, or a file system the app gives, such as a remote host's over SFTP, so its files get the same preview, tree and facts (tdp file-picker.3). Paths are the app's own, slash-separated as SFTP's are.
type PreviewFile ¶ added in v0.2.0
PreviewFile is an open file of a PreviewFS: read from its start, or at an offset (a PDF, a zip).
type ProbeResult ¶
type ProbeResult struct {
IconCells int // cells a Nerd Font icon takes
PowerlineCells int // cells a powerline symbol takes
// IconFrom and PowerlineFrom say where each came from: the variable's
// name, "probe", or "default".
IconFrom, PowerlineFrom string
Palette int // how many of the 16 colours the terminal reported (OSC 4)
}
ProbeResult is what Probe found out about the terminal.
func Probe ¶
func Probe(app string) ProbeResult
Probe finds out, before Bubble Tea takes the terminal, how many cells an icon and a powerline symbol take (tdp E5) and the terminal's 16 colours (tdp color.4). Each width comes from the app's variable (<APP>__ICON_WIDTH, <APP>__POWERLINE_WIDTH), then the family's (TERMINU__ICON_WIDTH, TERMINU__POWERLINE_WIDTH), then the one brought over ssh (LC_TERMINU_ICON_WIDTH, LC_TERMINU_POWERLINE_WIDTH), then asking the terminal where the cursor ended up after printing one (CPR, unix only). The palette is asked for with OSC 4 at the same time; colours the terminal does not report stay xterm's. Probe sets the lib's widths and palette and reports what it found.
type Reorder ¶ added in v0.1.6
type Reorder struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Options []string
// Done gets the new order: the options' indexes as they now stand
// ([2 0 1]: the third first). It is not called when the order did not
// change.
Done func(order []int) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(order []int) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
Reorder puts a set of items in an order by hand (tdp reorder): the panel's Drag mode in a popup. D picks up the item under the cursor, j|k move it, Enter drops it; Enter with nothing held writes the order back.
type Row ¶
type Row struct {
ID string // what marks are kept by; the row's place when empty
// Cells are the row's text, one per column: a control character in one,
// ESC too, is drawn by its name (Escape; tdp panel). The filter and
// sorting go by them.
Cells []string
// Styled, when set for a cell, is how it is drawn in colours of the app's
// own: each piece's text drawn as a cell's is. The cell's text stays in
// Cells.
Styled [][]Span
// Sort, when set, are the values sorted by instead of the cells (an age
// shown as "3d" sorted by seconds).
Sort []string
// SortGroup keeps rows apart when the list is sorted: the lower group
// first, sorting only within each (a file manager's directories before its
// files); no title is drawn between them (tdp panel). The rows of one
// group keep their order when the list is not sorted.
SortGroup int
// Group is the title of the group the row is in (tdp panel.11).
// A group's rows stay together, the groups in the order they first
// appear, sorted within; the rows are drawn two cells further in, under
// a title the cursor skips. A group with no row shown has no title.
// With groups, every row is in one: a row that fits no group goes in a
// group of its own ("Other").
Group string
// Flag is drawn in the mark column of a list with Flags: one sign, its
// glyph and colour the app's (locku's Green ● before the active
// profile); none leaves the column blank (tdp panel.7).
Flag Span
// CursorColor, when set, is the cursor block's colour while the cursor
// is on the row, the arrow on its right too, its text Base bold as ever:
// the colour the row's content has of its own (a ranking's places), and
// never another (tdp color.2). Unset it is Subtext1, as it is again while
// the panel is in a mode, the mode's Yellow marking what it marks.
CursorColor Color
}
Row is one item of a List.
type Screen ¶
type Screen struct {
// Name is the screen's chip and its row in the global operation popup
// ("Panels"); Key is its global hotkey ("P"). Desc is that row's
// description.
Name, Key, Desc string
Panels []*Panel
// Layout places the panels in the panel area, one Rect each; nil puts
// them side by side in equal widths. How a screen is laid out is the
// app's (tdp L1).
Layout func(w, h int) []Rect
// NarrowBelow is the width under which only the focused panel is drawn,
// across the whole width (tdp screen.5); at most 60, where every panel
// is side by side (tdp L1).
NarrowBelow int
// contains filtered or unexported fields
}
Screen is a set of panels shown together (Principle "Screen"). A screen's panels are numbered from [1] by their order (tdp K1).
type SearchStatus ¶ added in v1.2.1
SearchStatus is a / search's status, which the lib draws on the bottom border left of the scroll position while Count is not 0 (tdp note.3): "/", Text, then the current hit of how many, "/goroutine 2 of 5", in the scroll position's colour; a Text too long is cut at its end with …, the numbers kept. Current counts from 0, as Viewer.Current does.
type Select ¶
type Select struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Options []string
// Keys, when set, are the options' hotkeys (tdp M5); "" for none.
Keys []string
// Selected is the value now; -1 for none.
Selected int
// Loading, for a select opened with LoadSelect, is true while Options
// are still coming.
Loading bool
// Done gets the chosen option. It is not called when the value did not
// change.
Done func(int) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(int) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
Select picks one value from a list (tdp select).
type Selection ¶
type Selection struct {
Key string // "v"
Name string // the mode's name on the frame: "Visual"
CopyKey string // "y" when unset
// Copy takes the text copied. Unset, it goes on the terminal's
// clipboard and a Success toast says so (tdp note).
Copy func(text string) tea.Cmd
}
Selection is a viewer's selection mode: Key brings the cursor out at the start of the first line in sight, Key again starts the selection where it is, the cursor moves through the text (h|j|k|l, w|b|e, 0|$), CopyKey hands the selected text to Copy and leaves; Esc leaves.
type Slider ¶
type Slider struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Bottom, Top float64
// Step is the distance between two numbers: (Top − Bottom) / 10 when 0.
Step float64
Value float64
// Done gets the new number. It is not called when it did not change.
Done func(float64) tea.Cmd
}
Slider is a number in a range, shown as a track (tdp slider). It has no keys of its own: Enter opens a select of the numbers from Bottom to Top, Step apart.
type Span ¶ added in v0.4.0
Span is a piece of text in a style of the app's own, for the places an app colours text it gives the lib (a list's cell, a value, the statusbar): the text is drawn as any name or short text, a control character in it by its name (Escape); the style is the app's.
func ColorSpans ¶ added in v0.4.0
ColorSpans is a colour as a value on a form or a panel shows it, for Styled: a small swatch and its hex (tdp color-picker).
type Splash ¶
Splash draws frame n (from 0) of the family's easter egg in w × h cells (Rules S). done reports that the reveal is over; the last frame then stays until a key. NewSplash makes the one tdp S5 describes.
func NewSplash ¶
NewSplash is the family's splash (tdp S5): the mark in icon, the app's docs/icon.svg, cell for cell, and under it the app's name (its command's), its version as `<app> version` prints it and a one-line intro, then the family's author and the hint. The text is designed with the mark: a name, version or intro wider than the mark (50 columns) is an error.
icon is read as S5 describes it: a 250 × 250 viewBox of 10 × 10 rects, the U frame in #205090 and the letters in #f2b753 within rows 3–21. The letters are revealed one at a time: each XML comment starts the next one, so the svg lists them in the order of the app's name with a comment before each (`<!-- K -->`). Without comments all the gold is one letter.
type StatusKind ¶ added in v1.2.13
type StatusKind int
StatusKind is how what a FrameStatus tells is going (tdp panel.1).
const ( StatusFine StatusKind = iota // in the frame's colour StatusWarning // worth noticing: Peach StatusError // gone wrong: Red )
type Style ¶
type Style struct {
Fg, Bg Color
Bold bool
Italic bool // syntax colours have it where catppuccin-mocha does (tdp file-picker.3)
Underline bool
}
Style is what a piece of text is drawn with. The zero Style draws the text as it is.
type Terminal ¶
type Terminal struct {
// Title is what runs, in capitals ("SHELL", "ALTERM"); Subject what it
// runs on, as it is ("myhost"): the popup's title reads "ALTERM: myhost".
Title, Subject string
// Command is the program and its arguments: the user's shell ($SHELL)
// when empty.
Command []string
Dir string
// Env is added to the app's environment. TERMINU__ICON_WIDTH and
// TERMINU__POWERLINE_WIDTH are always set to the app's own (tdp E5).
Env []string
// Ends makes the exit key end the program ("Alt-Esc:exit"); otherwise
// leaving keeps it running ("Alt-Esc:leave").
Ends bool
// Keys are the app's own keys in the PTY, shown after the exit key.
Keys []TerminalKey
// Interactive marks a terminal the user types commands of their own in
// (a shell, an ssh session, kubectl exec), not one the app opens to run
// one program for one thing ($EDITOR, sudo asking for a password). It
// has the two modes of tdp terminal, which every other PTY
// leaves to its program, PgUp too:
// - History, on PgUp: j|k, u|d, gg|G, PgUp|PgDn scroll back through
// what went off the top, Esc goes back to the live screen, any other
// key leaves the mode and goes to the program. While the program
// fills the whole screen (vim, less, htop: the alternate screen),
// PgUp is the program's and the hint leaves PgUp:history out.
// - The selection, on Alt-v (the family's v, with Alt to get out of
// the program): the screen holds still, what the program prints
// meanwhile waiting; the cursor starts at the first line in sight
// and goes up into the history too; v starts selecting, y copies,
// Esc leaves. Copy takes the text; unset, it goes on the terminal's
// clipboard with a Success toast.
Interactive bool
// AllKeys, while set, hands every key to the program but the exit key
// and the app's own Keys (the one that takes them back): the user gave
// them all away (sshu's locked cell, a family app running inside). The
// selection is the program's then and PgUp|PgDn go to it, the innermost
// PTY scrolling its own history (tdp terminal).
AllKeys bool
// ExitKey is the key that takes the focus out (tdp K10), Alt-Esc when
// unset; the app may change it while the program runs, and the hint and
// the footer show it as it is. Alt-Esc always asks first; another asks
// when ExitAsks.
ExitKey string
ExitAsks bool
// Copy takes what the selection copies (Interactive); unset, it goes on
// the terminal's clipboard with a Success toast.
Copy func(text string) tea.Cmd
// NotReady, while it reports true, keeps the ordinary keys from the
// program (it is still connecting); Ctrl-C and the exit key still work.
NotReady func() bool
// OnExit runs when the program ends.
OnExit func(err error) tea.Cmd
// OnLeave runs when the exit key is accepted (asked first or not), once
// the focus is out and, with Ends, the program told to stop: where the
// focus goes now is the app's (tdp K10), such as back to the list row
// of the session left. The app's own keys that call Hide do not run it.
OnLeave func() tea.Cmd
// OnFirstOutput runs when the program first prints something after
// Start: an ssh that has connected, to end the panel's loading and
// NotReady (tdp K10, F7).
OnFirstOutput func() tea.Cmd
// contains filtered or unexported fields
}
Terminal is a program running in a PTY (tdp terminal): a shell, an editor, a remote session. Put it in a panel as the panel's Body, or open it in a terminal popup (App.OpenTerminal). While the focus is in it every key goes to the program, but the exit key and the app's own keys (tdp K10).
func (*Terminal) Empty ¶ added in v0.2.1
Empty reports nothing on the screen yet: the program not started, or started and silent so far. The panel's LoadingText or Fail shows in its middle meanwhile (tdp panel.15). A Start that failed has its error there.
func (*Terminal) Enter ¶
func (t *Terminal) Enter()
Enter puts the focus in a terminal in a panel: keys go to the program until the exit key.
func (*Terminal) Hide ¶
Hide takes the focus out and leaves the program running: its popup closes, a terminal in a panel lets the panel's keys work again. For an app's own exit key, such as one that hides a terminal popup.
func (*Terminal) Key ¶
Key does nothing: while the focus is in the terminal the app sends it every key; outside it the panel's own keys apply.
func (*Terminal) Spoke ¶ added in v0.2.0
Spoke reports whether the program has printed anything since Start.
type TerminalKey ¶
type TerminalKey struct {
// Key is how it is written in the footer and the hint ("Alt-←|→|↑|↓");
// Keys are the keys it takes, Key itself when empty, as a ModeKey's
// (tdp M5).
Key string
Keys []string
Desc string
Do func() tea.Cmd
// DoKey, when set, runs instead of Do, with the key pressed.
DoKey func(key string) tea.Cmd
}
TerminalKey is one of the app's own keys in a PTY (tdp K10).
type TextInput ¶
type TextInput struct {
Title string // what the popup is for, in its title ("Rename")
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
Glyph string // its title glyph: the app's choice
// Prompt is one line saying what to type ("New name for assets").
Prompt string
// Verb is what Enter does, for the hint ("rename").
Verb string
// Name is the value's name in its errors when the title says what the
// popup does rather than what the value is called: "Name can't have
// control characters" on a "Save as" (tdp input). Left
// unset, the title names it.
Name string
// Old is the value now: offered in grey from the cursor on, Tab takes it
// (tdp input.5).
Old string
// Suggest, when there is no Old, is a value the app proposes for a new
// thing ("assets.zip"), offered in grey as Old is; Enter with nothing
// touched takes it, checked and written back as any value
// (tdp input.6).
Suggest string
// MaxLen, when set, is the most characters the value can have; the
// popup's width is then known when it opens.
MaxLen int
// Check is the value's own rules: an error is written on the error row
// and the value is not written back.
Check func(string) error
// Search marks a value that is only searched for, never used: control
// characters in it are drawn, not held back on Enter, as on a finder's
// typing row (tdp input.8).
Search bool
// Done gets the new value. It is not called when the value did not change.
Done func(string) tea.Cmd
// Stay keeps it open under what Done opens: a step of a flow (current
// PIN, new PIN, confirm PIN), each step a popup of its own, Esc on the
// next one coming back here (tdp F1, F4). The app ends the flow with
// CloseTop when its last step is done (tdp T1).
Stay bool
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(string) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
// Unchanged, when set, runs when Enter takes the value it opened with, so
// nothing is written back and Done is not called: a step of a flow ends
// the flow (CloseTop), a page waiting for an answer gets the value it
// offered (tdp K3, F6).
Unchanged func() tea.Cmd
}
TextInput is a one-line text input popup (tdp text): a prompt, the value, an error row.
type TextMatch ¶ added in v0.2.0
type TextMatch struct{ Line, From, To int }
TextMatch is a stretch of a viewer's line: its characters From to To, To not in, counted as the selection mode's cursor counts them.
type Textarea ¶
type Textarea struct {
Title, Glyph string
// Subject is the one thing it acts on, kept as it is after ": " in the
// title: "EDIT: filu" (tdp popup).
Subject string
// Name is the text's name in its errors when the title is not ("Notes"
// on an "Edit"); left unset, the title names it (tdp input).
Name string
Old string
// Check, when set, judges a changed text on Enter: an error keeps it
// open and is written in the error row, as on a one-line input (tdp K3).
Check func(string) error
// Done gets the new text. It is not called when it did not change.
Done func(string) tea.Cmd
// Commit, when set, writes a changed value back when Enter takes it, on
// the update loop, before Done: an error keeps the popup open with the
// value in it and opens an error popup over it, "RENAME FAILED"
// (tdp popup.7, F4).
Commit func(string) error
// OnCancel runs when it closes with no answer: Esc, or the popup it is
// over closing it, so whoever waits for the answer (a web page's prompt,
// ssh's askpass) hears it was cancelled (tdp F6).
OnCancel func() tea.Cmd
}
Textarea is multi-line text (tdp textarea): it opens writing, with the value there and the cursor at its end; Esc moves to the moving state, where Enter saves.
type ToastKind ¶
type ToastKind int
ToastKind is what a toast says (tdp toast): which one goes with the meaning of its colour.
type Values ¶
type Values struct {
Fields []*Field
// Header, when set, is the table header over the labels and the values.
// A panel with groups (a field with a Group) draws none: each group's
// title says what its rows are (tdp panel.12).
Header [2]string
// OnMove runs when the cursor comes to another place, by a key or not,
// the first time included: the field, and the option in it (-1 for a
// field not drawn in place, -2 for a checkbox group's Select all). It runs before the frame is drawn, so a
// details panel follows in the same frame (tdp panel.13).
OnMove func(f *Field, option int) tea.Cmd
// EmptyFact and EmptyHint are what it says with no fields, in Overlay0, as
// a list does (tdp screen.8).
EmptyFact, EmptyHint string
// contains filtered or unexported fields
}
Values is a panel body with one value per row: a settings screen (tdp panel). It moves like a form; a value takes effect when it is set.
func (*Values) Actions ¶ added in v0.2.0
Actions are the panel's own item operation: what Enter does on the item under the cursor, so the Space menu and ? have it as the hint does (Rules M3, K6); in the disabled colour on a field that cannot be used now (tdp M6).
func (*Values) Draw ¶
Draw draws the fields: labels in upper case in Blue, two cells, the values; in groups, each under its title, two cells further in.
func (*Values) EnterHint ¶
EnterHint is what Enter does on the item under the cursor, for the panel's hint: edit a value, choose a radio option, toggle a checkbox.
func (*Values) MoveKeys ¶
MoveKeys are a one-dimensional list's (tdp K12); none with no fields, nothing to move to (tdp M6).
type Viewer ¶
type Viewer struct {
// Title is what it shows, in capitals ("YAML"); Subject is the thing
// itself, as it is ("pod/nginx"): the title reads "YAML — pod/nginx".
Title, Subject string
Glyph string
Lines []string
Loading bool
// Lang is the language its lines are coloured in, as the file preview
// colours a text file (tdp note): a chroma lexer's name or
// alias ("yaml", "json"), a file name to judge by ("deploy.yaml"), or a
// content type ("application/json"). Unset or not known: plain text, in
// Text (an App Log).
Lang string
// Tabs, when set, follow the title (tdp popup); h/l switch
// them and OnTab fills Lines for the new one.
Tabs []string
Tab int
OnTab func(tab int) tea.Cmd
// Keys are the viewer's own hotkeys, first in its hint.
Keys []ViewerKey
// Select is its selection mode (tdp K11): every viewer has one
// (tdp note). Unset, it is v, Visual, y copying to the
// terminal's clipboard with a Success toast.
Select *Selection
// Deprecated: a viewer always wraps and never cuts a line with "…"
// (tdp note.2); NoWrap does nothing.
NoWrap bool
// NoNumbers leaves out the line numbers, for a table the app lays out
// itself, where they mean nothing (tdp note).
NoNumbers bool
// Hits are what a search found, Search's or one the app runs itself
// (FindText finds them): each underlined in its own colours,
// Hits[Current] drawn as the cursor block, "you are here" (tdp note.2).
// No new colour: Yellow is the selection's. They go when the viewer
// closes (tdp note.3).
Hits []TextMatch
Current int
// Query is the text the Hits are of, drawn with them as the search's
// status on the bottom border, "/", Query, the current hit of how many,
// left of the scroll position (tdp note.3). Search sets it; an app
// running its own search sets it with Hits.
Query string
// Search is the viewer's search (tdp note.3): / asks for the text in an
// input popup, every place it is becomes a hit, the first scrolled into
// sight, and n|N go to the next and the previous, wrapping at the ends;
// with none an Info toast says so. /, n and N are then the search's, not
// Keys'. Every viewer has one (tdp note.3): unset, it is titled Search.
// A viewer whose Keys take /, n or N has none of the lib's: the app runs
// its own search there.
Search *ViewerSearch
// contains filtered or unexported fields
}
Viewer is a note to read (tdp note): a YAML view, a log, a file. Its lines are numbered on the left and a long one folds onto the rows under it. It scrolls, may have keys of its own and a selection mode, and closes with Esc only. Keep the pointer: lines may keep arriving while Loading is true.
func (*Viewer) FindText ¶ added in v0.2.0
FindText is every place q is in the lines, in either case, for the app's search (Hits).
type ViewerSearch ¶ added in v1.1.5
type ViewerSearch struct {
Title, Glyph, Prompt string
}
ViewerSearch is the words of a viewer's search, the app's (tdp note.3): the input popup's title ("Search" when unset), glyph and prompt ("Find in the YAML").
Source Files
¶
- action.go
- app.go
- applog.go
- apppopup.go
- clipboard.go
- clock.go
- color.go
- colorpicker.go
- compare.go
- confirm.go
- corekeys.go
- datetime.go
- didnotfit.go
- editor.go
- elevate.go
- filepicker.go
- filepreview.go
- finder.go
- form.go
- frame.go
- framestatus.go
- hangup.go
- input.go
- keys.go
- list.go
- match.go
- menu.go
- modelabel.go
- modemenu.go
- moveaside.go
- note.go
- output.go
- pager.go
- panel.go
- popup.go
- preview.go
- previewfs.go
- probe.go
- probe_unix.go
- readagain.go
- reorder.go
- selectall.go
- slider.go
- splash.go
- syntax.go
- terminal.go
- terminal_unix.go
- text.go
- textarea.go
- toast.go
- values.go
- viewer.go
- vt.go
- width.go
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
minimal
command
minimal is the smallest terminu app: one list and one action on it.
|
minimal is the smallest terminu app: one list and one action on it. |
|
showcase
command
Command showcase shows every component of terminu design and every way they combine, on fake data laid out like a real app.
|
Command showcase shows every component of terminu design and every way they combine, on fake data laid out like a real app. |
|
internal
|
|
|
testhook
Package testhook is how tdptest reaches into the lib: terminu fills these in when it loads.
|
Package testhook is how tdptest reaches into the lib: terminu fills these in when it loads. |
|
proto
|
|
|
c1
command
Package main is a throwaway prototype that checked one question: does lipgloss v2's layer compositing keep frames straight when a Nerd Font icon advances the cursor two cells (tdp E5)? It is not the lib.
|
Package main is a throwaway prototype that checked one question: does lipgloss v2's layer compositing keep frames straight when a Nerd Font icon advances the cursor two cells (tdp E5)? It is not the lib. |
|
Package tdptest drives a terminu App in a Go test the way a user does — keys, a paste, the terminal changing size, time going by — and checks, after every message, what tdp asks of every screen: each row exactly as wide as the terminal (tdp L4).
|
Package tdptest drives a terminu App in a Go test the way a user does — keys, a paste, the terminal changing size, time going by — and checks, after every message, what tdp asks of every screen: each row exactly as wide as the terminal (tdp L4). |