package tk

import "src.elv.sh/pkg/cli/tk"

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

Package Files

codearea.go codearea_render.go colview.go combobox.go empty.go label.go listbox.go listbox_state.go listbox_window.go scrollbar.go textview.go widget.go

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 Widget.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 Widget.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 Widget.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 Widget.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 Widget.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 Widget.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 Widget.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 Widget.Select.

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 errors it has
    // found when highlighting. If this function is not given, the Widget does
    // not highlight the code nor show any errors.
    Highlighter func(code string) (ui.Text, []error)
    // 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 this function is not given, the Widget does not
    // expand any abbreviations.
    Abbreviations          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
}

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) 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) 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  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 New, 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
    First    int
    Height   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 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 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
    Handler
}

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

Package tk imports 10 packages (graph) and is imported by 3 packages. Updated now.

.
Tools for package owners.