tk

package
v0.20.1 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2024 License: BSD-2-Clause Imports: 11 Imported by: 0

Documentation

Overview

Package tk is the toolkit for the cli package.

This package defines three basic interfaces - Renderer, Handler and Widget - and numerous implementations of these interfaces.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CategorizeSmallWord 

func CategorizeSmallWord(r rune) int

CategorizeSmallWord determines if the rune is whitespace, alphanum, or something else.

func IsAlnum 

func IsAlnum(r rune) bool

IsAlnum determines if the rune is an alphanumeric character.

func Left 

func Left(s ListBoxState) int

Left moves the selection to the item to the left. It is only meaningful in horizontal layout and suitable as an argument to [ListBox.Select].

func Next 

func Next(s ListBoxState) int

Next moves the selection to the previous item, or does nothing if the last item is currently selected. It is a suitable as an argument to [ListBox.Select].

func NextPage 

func NextPage(s ListBoxState) int

NextPage moves the selection to the item one page after. It is only meaningful in vertical layout and suitable as an argument to [ListBox.Select].

TODO(xiaq): This does not correctly with multi-line items.

func NextWrap 

func NextWrap(s ListBoxState) int

NextWrap moves the selection to the previous item, or to the first item if the last item is currently selected. It is a suitable as an argument to [ListBox.Select].

func Prev 

func Prev(s ListBoxState) int

Prev moves the selection to the previous item, or does nothing if the first item is currently selected. It is a suitable as an argument to [ListBox.Select].

func PrevPage 

func PrevPage(s ListBoxState) int

PrevPage moves the selection to the item one page before. It is only meaningful in vertical layout and suitable as an argument to [ListBox.Select].

TODO(xiaq): This does not correctly with multi-line items.

func PrevWrap 

func PrevWrap(s ListBoxState) int

PrevWrap moves the selection to the previous item, or to the last item if the first item is currently selected. It is a suitable as an argument to [ListBox.Select]. 

func Right(s ListBoxState) int

Right moves the selection to the item to the right. It is only meaningful in horizontal layout and suitable as an argument to [ListBox.Select].

Types

type Bindings 

type Bindings interface {
	Handle(Widget, term.Event) bool
}

Bindings is the interface for key bindings.

type CodeArea 

type CodeArea interface {
	Widget
	// CopyState returns a copy of the state.
	CopyState() CodeAreaState
	// MutateState calls the given the function while locking StateMutex.
	MutateState(f func(*CodeAreaState))
	// Submit triggers the OnSubmit callback.
	Submit()
}

CodeArea is a Widget for displaying and editing code.

func NewCodeArea 

func NewCodeArea(spec CodeAreaSpec) CodeArea

NewCodeArea creates a new CodeArea from the given spec.

type CodeAreaSpec 

type CodeAreaSpec struct {
	// Key bindings.
	Bindings Bindings
	// A function that highlights the given code and returns any tips it has
	// found, such as errors and autofixes. If this function is not given, the
	// Widget does not highlight the code nor show any tips.
	Highlighter func(code string) (ui.Text, []ui.Text)
	// Prompt callback.
	Prompt func() ui.Text
	// Right-prompt callback.
	RPrompt func() ui.Text
	// A function that calls the callback with string pairs for abbreviations
	// and their expansions. If no function is provided the Widget does not
	// expand any abbreviations of the specified type.
	SimpleAbbreviations    func(f func(abbr, full string))
	CommandAbbreviations   func(f func(abbr, full string))
	SmallWordAbbreviations func(f func(abbr, full string))
	// A function that returns whether pasted texts (from bracketed pastes)
	// should be quoted. If this function is not given, the Widget defaults to
	// not quoting pasted texts.
	QuotePaste func() bool
	// A function that is called on the submit event.
	OnSubmit func()

	// State. When used in New, this field specifies the initial state.
	State CodeAreaState
}

CodeAreaSpec specifies the configuration and initial state for CodeArea.

type CodeAreaState 

type CodeAreaState struct {
	Buffer      CodeBuffer
	Pending     PendingCode
	HideRPrompt bool
	HideTips    bool
}

CodeAreaState keeps the mutable state of the CodeArea widget.

func (*CodeAreaState) ApplyPending 

func (s *CodeAreaState) ApplyPending()

ApplyPending applies pending code to the code buffer, and resets pending code.

type CodeBuffer 

type CodeBuffer struct {
	// Content of the buffer.
	Content string
	// Position of the dot (more commonly known as the cursor), as a byte index
	// into Content.
	Dot int
}

CodeBuffer represents the buffer of the CodeArea widget.

func (*CodeBuffer) InsertAtDot 

func (c *CodeBuffer) InsertAtDot(text string)

type ColView 

type ColView interface {
	Widget
	// MutateState mutates the state.
	MutateState(f func(*ColViewState))
	// CopyState returns a copy of the state.
	CopyState() ColViewState
	// Left triggers the OnLeft callback.
	Left()
	// Right triggers the OnRight callback.
	Right()
}

ColView is a Widget that arranges several widgets in a column.

func NewColView 

func NewColView(spec ColViewSpec) ColView

NewColView creates a new ColView from the given spec.

type ColViewSpec 

type ColViewSpec struct {
	// Key bindings.
	Bindings Bindings
	// A function that takes the number of columns and return weights for the
	// widths of the columns. The returned slice must have a size of n. If this
	// function is nil, all the columns will have the same weight.
	Weights func(n int) []int
	// A function called when the Left method of Widget is called, or when Left
	// is pressed and unhandled.
	OnLeft func(w ColView)
	// A function called when the Right method of Widget is called, or when
	// Right is pressed and unhandled.
	OnRight func(w ColView)

	// State. Specifies the initial state when used in New.
	State ColViewState
}

ColViewSpec specifies the configuration and initial state for ColView.

type ColViewState 

type ColViewState struct {
	Columns     []Widget
	FocusColumn int
}

ColViewState keeps the mutable state of the ColView widget.

type ComboBox 

type ComboBox interface {
	Widget
	// Returns the embedded codearea widget.
	CodeArea() CodeArea
	// Returns the embedded listbox widget.
	ListBox() ListBox
	// Forces the filtering to rerun.
	Refilter()
}

ComboBox is a Widget that combines a ListBox and a CodeArea.

func NewComboBox 

func NewComboBox(spec ComboBoxSpec) ComboBox

NewComboBox creates a new ComboBox from the given spec.

type ComboBoxSpec 

type ComboBoxSpec struct {
	CodeArea CodeAreaSpec
	ListBox  ListBoxSpec
	OnFilter func(ComboBox, string)
}

ComboBoxSpec specifies the configuration and initial state for ComboBox.

type DummyBindings 

type DummyBindings struct{}

DummyBindings is a trivial Bindings implementation.

func (DummyBindings) Handle 

func (DummyBindings) Handle(w Widget, event term.Event) bool

Handle always returns false.

type Empty 

type Empty struct{}

Empty is an empty widget.

func (Empty) Handle 

func (Empty) Handle(event term.Event) bool

Handle always returns false.

func (Empty) MaxHeight added in v0.17.0 

func (Empty) MaxHeight(width, height int) int

MaxHeight returns 1, since this widget always occupies one line.

func (Empty) Render 

func (Empty) Render(width, height int) *term.Buffer

Render shows nothing, although the resulting Buffer still occupies one line.

type FuncBindings 

type FuncBindings func(Widget, term.Event) bool

FuncBindings is a function-based Bindings implementation.

func (FuncBindings) Handle 

func (f FuncBindings) Handle(w Widget, event term.Event) bool

Handle handles the event by calling the function.

type HScrollbar 

type HScrollbar struct {
	Total int
	Low   int
	High  int
}

HScrollbar is a Renderer for a horizontal scrollbar.

func (HScrollbar) Render 

func (h HScrollbar) Render(width, height int) *term.Buffer

type Handler 

type Handler interface {
	// Try to handle a terminal event and returns whether the event has been
	// handled.
	Handle(event term.Event) bool
}

Handler wraps the Handle method.

type Items 

type Items interface {
	// Show renders the item at the given zero-based index.
	Show(i int) ui.Text
	// Len returns the number of items.
	Len() int
}

Items is an interface for accessing multiple items.

type Label 

type Label struct {
	Content ui.Text
}

Label is a Renderer that writes out a text.

func (Label) Handle 

func (l Label) Handle(event term.Event) bool

Handle always returns false.

func (Label) MaxHeight added in v0.17.0 

func (l Label) MaxHeight(width, height int) int

MaxHeight returns the maximum height the Label can take when rendering within a bound box.

func (Label) Render 

func (l Label) Render(width, height int) *term.Buffer

Render shows the content. If the given box is too small, the text is cropped.

type ListBox 

type ListBox interface {
	Widget
	// CopyState returns a copy of the state.
	CopyState() ListBoxState
	// Reset resets the state of the widget with the given items and index of
	// the selected item. It triggers the OnSelect callback if the index is
	// valid.
	Reset(it Items, selected int)
	// Select changes the selection by calling f with the current state, and
	// using the return value as the new selection index. It triggers the
	// OnSelect callback if the selected index has changed and is valid.
	Select(f func(ListBoxState) int)
	// Accept accepts the currently selected item.
	Accept()
}

ListBox is a list for displaying and selecting from a list of items.

func NewListBox 

func NewListBox(spec ListBoxSpec) ListBox

NewListBox creates a new ListBox from the given spec.

type ListBoxSpec 

type ListBoxSpec struct {
	// Key bindings.
	Bindings Bindings
	// A placeholder to show when there are no items.
	Placeholder ui.Text
	// A function to call when the selected item has changed.
	OnSelect func(it Items, i int)
	// A function called on the accept event.
	OnAccept func(it Items, i int)
	// Whether the listbox should be rendered in a horizontal layout. Note that
	// in the horizontal layout, items must have only one line.
	Horizontal bool
	// The minimal amount of space to reserve for left and right sides of each
	// entry.
	Padding int
	// If true, the left padding of each item will be styled the same as the
	// first segment of the item, and the right spacing and padding will be
	// styled the same as the last segment of the item.
	ExtendStyle bool

	// State. When used in [NewListBox], this field specifies the initial state.
	State ListBoxState
}

ListBoxSpec specifies the configuration and initial state for ListBox.

type ListBoxState 

type ListBoxState struct {
	Items    Items
	Selected int
	// The first element to show. Used when rendering and adjusted accordingly
	// when the terminal size changes or the user has scrolled.
	First int
	// Height of the listbox, excluding horizontal scrollbar when using the
	// horizontal layout. Stored in the state for commands to move the cursor by
	// page (for vertical layout) or column (for horizontal layout).
	ContentHeight int
}

ListBoxState keeps the mutable state ListBox.

type MapBindings 

type MapBindings map[term.Event]func(Widget)

MapBindings is a map-backed Bindings implementation.

func (MapBindings) Handle 

func (m MapBindings) Handle(w Widget, event term.Event) bool

Handle handles the event by calling the function corresponding to the event in the map. If there is no corresponding function, it returns false.

type MaxHeighter added in v0.17.0 

type MaxHeighter interface {
	// MaxHeight returns the maximum height needed when rendering onto a region
	// of bound width and height. The returned value may be larger than the
	// height argument.
	MaxHeight(width, height int) int
}

MaxHeighter wraps the MaxHeight method.

type PendingCode 

type PendingCode struct {
	// Beginning index of the text area that the pending code replaces, as a
	// byte index into RawState.Code.
	From int
	// End index of the text area that the pending code replaces, as a byte
	// index into RawState.Code.
	To int
	// The content of the pending code.
	Content string
}

PendingCode represents pending code, such as during completion.

type Renderer 

type Renderer interface {
	// Render renders onto a region of bound width and height.
	Render(width, height int) *term.Buffer
}

Renderer wraps the Render method.

type TestItems 

type TestItems struct {
	Prefix string
	Style  ui.Styling
	NItems int
}

TestItems is an implementation of Items useful for testing.

func (TestItems) Len 

func (it TestItems) Len() int

Len returns it.NItems.

func (TestItems) Show 

func (it TestItems) Show(i int) ui.Text

Show returns a plain text consisting of the prefix and i. If the prefix is empty, it defaults to "item ".

type TextView 

type TextView interface {
	Widget
	// ScrollBy scrolls the widget by the given delta. Positive values scroll
	// down, and negative values scroll up.
	ScrollBy(delta int)
	// MutateState mutates the state.
	MutateState(f func(*TextViewState))
	// CopyState returns a copy of the State.
	CopyState() TextViewState
}

TextView is a Widget for displaying text, with support for vertical scrolling.

NOTE: This widget now always crops long lines. In future it should support wrapping and horizontal scrolling.

func NewTextView 

func NewTextView(spec TextViewSpec) TextView

NewTextView builds a TextView from the given spec.

type TextViewSpec 

type TextViewSpec struct {
	// Key bindings.
	Bindings Bindings
	// If true, a vertical scrollbar will be shown when there are more lines
	// that can be displayed, and the widget responds to Up and Down keys.
	Scrollable bool
	// State. Specifies the initial state if used in New.
	State TextViewState
}

TextViewSpec specifies the configuration and initial state for a Widget.

type TextViewState 

type TextViewState struct {
	Lines []string
	First int
}

TextViewState keeps mutable state of TextView.

type VScrollbar 

type VScrollbar struct {
	Total int
	Low   int
	High  int
}

VScrollbar is a Renderer for a vertical scrollbar.

func (VScrollbar) Render 

func (v VScrollbar) Render(width, height int) *term.Buffer

type VScrollbarContainer 

type VScrollbarContainer struct {
	Content   Renderer
	Scrollbar VScrollbar
}

VScrollbarContainer is a Renderer consisting of content and a vertical scrollbar on the right.

func (VScrollbarContainer) Render 

func (v VScrollbarContainer) Render(width, height int) *term.Buffer

type Widget 

type Widget interface {
	Renderer
	MaxHeighter
	Handler
}

Widget is the basic component of UI; it knows how to handle events and how to render itself.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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