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.

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.