list

package
v0.0.0-...-f106031 Latest Latest
Warning

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

Go to latest
Published: Dec 22, 2021 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package list provides a feature-rich Bubble Tea component for browsing a general purpose list of items. It features optional filtering, pagination, help, status messages, and a spinner to indicate activity.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DefaultDelegate

type DefaultDelegate struct {
	ShowDescription bool
	Styles          DefaultItemStyles
	UpdateFunc      func(tea.Msg, *Model) tea.Cmd
	ShortHelpFunc   func() []key.Binding
	FullHelpFunc    func() [][]key.Binding
	// contains filtered or unexported fields
}

DefaultDelegate is a standard delegate designed to work in lists. It's styled by DefaultItemStyles, which can be customized as you like.

The description line can be hidden by setting Description to false, which renders the list as single-line-items. The spacing between items can be set with the SetSpacing method.

Setting UpdateFunc is optional. If it's set it will be called when the ItemDelegate called, which is called when the list's Update function is invoked.

Settings ShortHelpFunc and FullHelpFunc is optional. They can can be set to include items in the list's default short and full help menus.

func NewDefaultDelegate

func NewDefaultDelegate() DefaultDelegate

NewDefaultDelegate creates a new delegate with default styles.

func (DefaultDelegate) FullHelp

func (d DefaultDelegate) FullHelp() [][]key.Binding

FullHelp returns the delegate's full help.

func (DefaultDelegate) Height

func (d DefaultDelegate) Height() int

Height returns the delegate's preferred height.

func (DefaultDelegate) Render

func (d DefaultDelegate) Render(w io.Writer, m Model, index int, item Item)

Render prints an item.

func (*DefaultDelegate) SetSpacing

func (d *DefaultDelegate) SetSpacing(i int)

SetSpacing set the delegate's spacing.

func (DefaultDelegate) ShortHelp

func (d DefaultDelegate) ShortHelp() []key.Binding

ShortHelp returns the delegate's short help.

func (DefaultDelegate) Spacing

func (d DefaultDelegate) Spacing() int

Spacing returns the delegate's spacing.

func (DefaultDelegate) Update

func (d DefaultDelegate) Update(msg tea.Msg, m *Model) tea.Cmd

Update checks whether the delegate's UpdateFunc is set and calls it.

type DefaultItem

type DefaultItem interface {
	Item
	Title() string
	Description() string
}

DefaultItem describes an items designed to work with DefaultDelegate.

type DefaultItemStyles

type DefaultItemStyles struct {
	// The Normal state.
	NormalTitle lipgloss.Style
	NormalDesc  lipgloss.Style

	// The selected item state.
	SelectedTitle lipgloss.Style
	SelectedDesc  lipgloss.Style

	// The dimmed state, for when the filter input is initially activated.
	DimmedTitle lipgloss.Style
	DimmedDesc  lipgloss.Style

	// Charcters matching the current filter, if any.
	FilterMatch lipgloss.Style
}

DefaultItemStyles defines styling for a default list item. See DefaultItemView for when these come into play.

func NewDefaultItemStyles

func NewDefaultItemStyles() (s DefaultItemStyles)

NewDefaultItemStyles returns style definitions for a default item. See DefaultItemView for when these come into play.

type FilterMatchesMessage

type FilterMatchesMessage []filteredItem

type FilterState

type FilterState int

FilterState describes the current filtering state on the model.

const (
	Unfiltered    FilterState = iota // no filter set
	Filtering                        // user is actively setting a filter
	FilterApplied                    // a filter is applied and user is not editing filter
)

Possible filter states.

func (FilterState) String

func (f FilterState) String() string

String returns a human-readable string of the current filter state.

type Item

type Item interface {
	// Filter value is the value we use when filtering against this item when
	// we're filtering the list.
	FilterValue() string
}

Item is an item that appears in the list.

type ItemDelegate

type ItemDelegate interface {
	// Render renders the item's view.
	Render(w io.Writer, m Model, index int, item Item)

	// Height is the height of the list item.
	Height() int

	// Spacing is the size of the horizontal gap between list items in cells.
	Spacing() int

	// Update is the update loop for items. All messages in the list's update
	// loop will pass through here except when the user is setting a filter.
	// Use this method to perform item-level updates appropriate to this
	// delegate.
	Update(msg tea.Msg, m *Model) tea.Cmd
}

ItemDelegate encapsulates the general functionality for all list items. The benefit to separating this logic from the item itself is that you can change the functionality of items without changing the actual items themselves.

Note that if the delegate also implements help.KeyMap delegate-related help items will be added to the help view.

type KeyMap

type KeyMap struct {
	// Keybindings used when browsing the list.
	CursorUp        key.Binding
	CursorDown      key.Binding
	NextPage        key.Binding
	PrevPage        key.Binding
	GoToStart       key.Binding
	GoToEnd         key.Binding
	Filter          key.Binding
	ClearFilter     key.Binding
	DeleteSelection key.Binding

	// Keybindings used when setting a filter.
	CancelWhileFiltering key.Binding
	AcceptWhileFiltering key.Binding

	// Help toggle keybindings.
	ShowFullHelp  key.Binding
	CloseFullHelp key.Binding

	// The quit keybinding. This won't be caught when filtering.
	Quit key.Binding

	// The quit-no-matter-what keybinding. This will be caught when filtering.
	ForceQuit key.Binding
}

KeyMap defines keybindings. It satisfies to the help.KeyMap interface, which is used to render the menu menu.

func DefaultKeyMap

func DefaultKeyMap() KeyMap

DefaultKeyMap returns a default set of keybindings.

type Model

type Model struct {
	Title  string
	Styles Styles

	// Key mappings for navigating the list.
	KeyMap KeyMap

	// Additional key mappings for the short and full help views. This allows
	// you to add additional key mappings to the help menu without
	// re-implementing the help component. Of course, you can also disable the
	// list's help component and implement a new one if you need more
	// flexibility.
	AdditionalShortHelpKeys func() []key.Binding
	AdditionalFullHelpKeys  func() []key.Binding

	Paginator paginator.Model

	Help        help.Model
	FilterInput textinput.Model

	// How long status messages should stay visible. By default this is
	// 1 second.
	StatusMessageLifetime time.Duration
	// contains filtered or unexported fields
}

Model contains the state of this component.

func NewModel

func NewModel(items []Item, delegate ItemDelegate, width, height int) Model

NewModel returns a new model with sensible defaults.

func (Model) Cursor

func (m Model) Cursor() int

Cursor returns the index of the cursor on the current page.

func (*Model) CursorDown

func (m *Model) CursorDown()

CursorDown moves the cursor down. This can also advance the state to the next page.

func (*Model) CursorUp

func (m *Model) CursorUp()

CursorUp moves the cursor up. This can also move the state to the previous page.

func (*Model) DisableQuitKeybindings

func (m *Model) DisableQuitKeybindings()

Helper for disabling the keybindings used for quitting, incase you want to handle this elsewhere in your application.

func (Model) FilterState

func (m Model) FilterState() FilterState

FilterState returns the current filter state.

func (Model) FilterValue

func (m Model) FilterValue() string

FilterValue returns the current value of the filter.

func (Model) FilteringEnabled

func (m Model) FilteringEnabled() bool

FilteringEnabled returns whether or not filtering is enabled.

func (Model) FullHelp

func (m Model) FullHelp() [][]key.Binding

FullHelp returns bindings to show the full help view. It's part of the help.KeyMap interface.

func (Model) Height

func (m Model) Height() int

Height returns the current height setting.

func (Model) Index

func (m Model) Index() int

Index returns the index of the currently selected item as it appears in the entire slice of items.

func (*Model) InsertItem

func (m *Model) InsertItem(index int, item Item) tea.Cmd

Insert an item at the given index. This returns a command.

func (Model) Items

func (m Model) Items() []Item

Items returns the items in the list.

func (Model) MatchesForItem

func (m Model) MatchesForItem(index int) []int

MatchesForItem returns rune positions matched by the current filter, if any. Use this to style runes matched by the active filter.

See DefaultItemView for a usage example.

func (*Model) NewStatusMessage

func (m *Model) NewStatusMessage(s string) tea.Cmd

NewStatusMessage sets a new status message, which will show for a limited amount of time. Note that this also returns a command.

func (Model) NextPage

func (m Model) NextPage()

NextPage moves to the next page, if available.

func (Model) PrevPage

func (m Model) PrevPage()

PrevPage moves to the previous page, if available.

func (*Model) RemoveItem

func (m *Model) RemoveItem(index int)

RemoveItem removes an item at the given index. If the index is out of bounds this will be a no-op. O(n) complexity, which probably won't matter in the case of a TUI.

func (*Model) ResetFilter

func (m *Model) ResetFilter()

ResetFilter resets the current filtering state.

func (*Model) ResetSelected

func (m *Model) ResetSelected()

ResetSelected resets the selected item to the first item in the first page of the list.

func (*Model) Select

func (m *Model) Select(index int)

Select selects the given index of the list and goes to its respective page.

func (Model) SelectedItem

func (m Model) SelectedItem() Item

SelectedItems returns the current selected item in the list.

func (*Model) SetDelegate

func (m *Model) SetDelegate(d ItemDelegate)

Set the item delegate.

func (*Model) SetFilteringEnabled

func (m *Model) SetFilteringEnabled(v bool)

SetFilteringEnabled enables or disables filtering. Note that this is different from ShowFilter, which merely hides or shows the input view.

func (*Model) SetHeight

func (m *Model) SetHeight(v int)

SetHeight sets the height of this component.

func (*Model) SetItem

func (m *Model) SetItem(index int, item Item) tea.Cmd

Replace an item at the given index. This returns a command.

func (*Model) SetItems

func (m *Model) SetItems(i []Item) tea.Cmd

Set the items available in the list. This returns a command.

func (*Model) SetShowFilter

func (m *Model) SetShowFilter(v bool)

SetShowFilter shows or hides the filer bar. Note that this does not disable filtering, it simply hides the built-in filter view. This allows you to use the FilterInput to render the filtering UI differently without having to re-implement filtering from scratch.

To disable filtering entirely use EnableFiltering.

func (*Model) SetShowHelp

func (m *Model) SetShowHelp(v bool)

SetShowHelp shows or hides the help view.

func (*Model) SetShowPagination

func (m *Model) SetShowPagination(v bool)

ShowingPagination hides or shoes the paginator. Note that pagination will still be active, it simply won't be displayed.

func (*Model) SetShowStatusBar

func (m *Model) SetShowStatusBar(v bool)

SetShowStatusBar shows or hides the view that displays metadata about the list, such as item counts.

func (*Model) SetShowTitle

func (m *Model) SetShowTitle(v bool)

SetShowTitle shows or hides the title bar.

func (*Model) SetSize

func (m *Model) SetSize(width, height int)

SetSize sets the width and height of this component.

func (*Model) SetSpinner

func (m *Model) SetSpinner(spinner spinner.Spinner)

SetSpinner allows to set the spinner style.

func (*Model) SetWidth

func (m *Model) SetWidth(v int)

SetWidth sets the width of this component.

func (Model) SettingFilter

func (m Model) SettingFilter() bool

SettingFilter returns whether or not the user is currently editing the filter value. It's purely a convenience method for the following:

m.FilterState() == Filtering

It's included here because it's a common thing to check for when implementing this component.

func (Model) ShortHelp

func (m Model) ShortHelp() []key.Binding

ShortHelp returns bindings to show in the abbreviated help view. It's part of the help.KeyMap interface.

func (Model) ShowFilter

func (m Model) ShowFilter() bool

ShowFilter returns whether or not the filter is set to be rendered. Note that this is separate from FilteringEnabled, so filtering can be hidden yet still invoked. This allows you to render filtering differently without having to re-implement it from scratch.

func (Model) ShowHelp

func (m Model) ShowHelp() bool

ShowHelp returns whether or not the help is set to be rendered.

func (*Model) ShowPagination

func (m *Model) ShowPagination() bool

ShowPagination returns whether the pagination is visible.

func (Model) ShowStatusBar

func (m Model) ShowStatusBar() bool

ShowStatusBar returns whether or not the status bar is set to be rendered.

func (Model) ShowTitle

func (m Model) ShowTitle() bool

ShowTitle returns whether or not the title bar is set to be rendered.

func (*Model) StartSpinner

func (m *Model) StartSpinner() tea.Cmd

StartSpinner starts the spinner. Note that this returns a command.

func (*Model) StopSpinner

func (m *Model) StopSpinner()

StopSpinner stops the spinner.

func (*Model) ToggleSpinner

func (m *Model) ToggleSpinner() tea.Cmd

Toggle the spinner. Note that this also returns a command.

func (Model) Update

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

Update is the Bubble Tea update loop.

func (Model) View

func (m Model) View() string

View renders the component.

func (Model) VisibleItems

func (m Model) VisibleItems() []Item

VisibleItems returns the total items available to be shown.

func (Model) Width

func (m Model) Width() int

Width returns the current width setting.

type Styles

type Styles struct {
	TitleBar     lipgloss.Style
	Title        lipgloss.Style
	Spinner      lipgloss.Style
	FilterPrompt lipgloss.Style
	FilterCursor lipgloss.Style

	// Default styling for matched characters in a filter. This can be
	// overridden by delegates.
	DefaultFilterCharacterMatch lipgloss.Style

	StatusBar             lipgloss.Style
	StatusEmpty           lipgloss.Style
	StatusBarActiveFilter lipgloss.Style
	StatusBarFilterCount  lipgloss.Style

	NoItems lipgloss.Style

	PaginationStyle lipgloss.Style
	HelpStyle       lipgloss.Style

	// Styled characters.
	ActivePaginationDot   lipgloss.Style
	InactivePaginationDot lipgloss.Style
	ArabicPagination      lipgloss.Style
	DividerDot            lipgloss.Style
}

Styles contains style definitions for this list component. By default, these values are generated by DefaultStyles.

func DefaultStyles

func DefaultStyles() (s Styles)

DefaultStyles returns a set of default style definitions for this list component.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL