ui

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2023 License: ISC Imports: 6 Imported by: 7

Documentation

Overview

Package ui defines common UI utilities for gruid: menu/table widget, pager, text input, label, text drawing facilities and replay functionality.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Alignment 

type Alignment int16

Alignment represents left, center or right text alignment. It is used to draw text with a given alignment within a grid. 

const (
	AlignCenter Alignment = iota
	AlignLeft
	AlignRight
)

Those constants represent the possible text alignment options. The default alignment is AlignCenter.

type Box 

type Box struct {
	Style       gruid.Style // box style
	Title       StyledText  // optional top text
	Footer      StyledText  // optional bottom text
	AlignTitle  Alignment   // title alignment
	AlignFooter Alignment   // footer alignment
}

Box contains information to draw a rectangle using box characters, with an optional title.

func (Box) Draw 

func (b Box) Draw(gd gruid.Grid) gruid.Grid

Draw draws a rectangular box in a grid, taking the whole grid. It does not draw anything in the interior region. It returns the grid slice that was drawn, which usually is the whole grid, except if the grid was too small to draw a box.

type Label 

type Label struct {
	Content     StyledText // label's styled text content
	Box         *Box       // draw optional box around the label
	AdjustWidth bool       // reduce the width of the label if possible
}

Label represents a bunch of text in a grid. It may be boxed and provided with a title.

func NewLabel 

func NewLabel(content StyledText) *Label

NewLabel returns a new label with given styled text and AdjustWidth set to true.

func (*Label) Draw 

func (lb *Label) Draw(gd gruid.Grid) gruid.Grid

Draw draws the label into the given grid. It returns the grid slice that was drawn.

func (*Label) SetText 

func (lb *Label) SetText(text string)

SetText updates the text for the label's content, using the same styling. 

type Menu struct {
	// contains filtered or unexported fields
}

Menu is a widget that displays a list of entries to the user. It allows to move the active entry, as well as invoke a particular entry.

Menu implements gruid.Model, but is not suitable for use as main model of an application.

func NewMenu 

func NewMenu(cfg MenuConfig) *Menu

NewMenu returns a menu with a given configuration. 

func (m *Menu) Action() MenuAction

Action returns the last action performed in the menu. 

func (m *Menu) Active() int

Active return the index of the currently active entry. 

func (m *Menu) ActiveBounds() gruid.Range

ActiveBounds return the bounds of the the currently active entry grid slice. 

func (m *Menu) Bounds() gruid.Range

Bounds return the bounds of the the currently viewable menu entries (including box if any). 

func (m *Menu) Draw() gruid.Grid

Draw implements gruid.Model.Draw. It returns the grid slice that was drawn. 

func (m *Menu) SetActive(i int)

SetActive updates the active entry among entries. It may be used to launch the menu at a specific default starting index. 

func (m *Menu) SetBox(b *Box)

SetBox updates the menu surrounding box. 

func (m *Menu) SetEntries(entries []MenuEntry)

SetEntries updates the list of menu entries. 

func (m *Menu) Update(msg gruid.Msg) gruid.Effect

Update implements gruid.Model.Update and updates the menu state in response to user input messages. It considers mouse message coordinates to be absolute in its grid. 

type MenuAction int

MenuAction represents an user action with the menu. 

const (
	// MenuPass reports that the menu state did not change (for example a
	// mouse motion outside the menu, or within a same entry line).
	MenuPass MenuAction = iota

	// MenuMove reports that the user moved the active entry. This happens
	// by default when using the arrow keys or a mouse motion.
	MenuMove

	// MenuInvoke reports that the user clicked or pressed enter to invoke
	// an already active entry, or used a shortcut key to both activate and
	// invoke a specific entry.
	MenuInvoke

	// MenuQuit reports that the user requested to quit the menu, either by
	// clicking outside the menu, or by using a key shortcut.
	MenuQuit
)

These constants represent the available actions in a menu. 

type MenuConfig struct {
	Grid    gruid.Grid  // grid slice where the menu is drawn
	Entries []MenuEntry // menu entries
	Keys    MenuKeys    // optional custom key bindings
	Box     *Box        // draw optional box around the menu
	Style   MenuStyle
}

MenuConfig contains configuration options for creating a menu. 

type MenuEntry struct {
	// Text is the styled text displayed on the entry line.
	Text StyledText

	// Disabled means that the entry is not invokable. It may represent a
	// header or an unavailable choice, for example.
	Disabled bool

	// Keys contains entry shortcuts, if any, and only for activable
	// entries. Other menu key bindings take precedence over those.
	Keys []gruid.Key
}

MenuEntry represents an entry in the menu. By default they behave much like a button and can be activated and invoked. 

type MenuKeys struct {
	Up       []gruid.Key // move up active entry (default: ArrowUp, k)
	Down     []gruid.Key // move down active entry (default: ArrowDown, j)
	Left     []gruid.Key // move left active entry (default: ArrowLeft, h)
	Right    []gruid.Key // move right active entry (default: ArrowRight, l)
	PageDown []gruid.Key // go one page down (default: PageDown)
	PageUp   []gruid.Key // go one page up (default: PageUp)
	Invoke   []gruid.Key // invoke selection (default: Enter)
	Quit     []gruid.Key // requist menu quit (default: Escape, q, Q)
}

MenuKeys contains key bindings configuration for the menu. One step movement keys skip disabled entries. 

type MenuStyle struct {
	Layout  gruid.Point // menu layout in (columns, lines); 0 means any
	Active  gruid.Style // specific styling for active entry (no change if default)
	PageNum gruid.Style // page num display style (for boxed menu)
}

MenuStyle describes styling options for a menu.

type Pager 

type Pager struct {
	// contains filtered or unexported fields
}

Pager represents a pager widget for viewing a long list of lines.

Pager implements gruid.Model and can be used as main model of an application.

func NewPager 

func NewPager(cfg PagerConfig) *Pager

NewPager returns a new pager with given configuration options.

func (*Pager) Action 

func (pg *Pager) Action() PagerAction

Action returns the last action performed with the pager.

func (*Pager) Draw 

func (pg *Pager) Draw() gruid.Grid

Draw implements gruid.Model.Draw for Pager. It returns the grid slice that was drawn, or the whole grid if it is used as main model.

func (*Pager) SetBox 

func (pg *Pager) SetBox(b *Box)

SetBox updates the pager surrounding box.

func (*Pager) SetCursor 

func (pg *Pager) SetCursor(p gruid.Point)

SetCursor updates the pager's position to the given (X, Y) point, where X is the indentation level, and Y the line number of the upper-most line of the view.

func (*Pager) SetLines 

func (pg *Pager) SetLines(lines []StyledText)

SetLines updates the pager text lines.

func (*Pager) Update 

func (pg *Pager) Update(msg gruid.Msg) gruid.Effect

Update implements gruid.Model.Update for Pager. It considers mouse message coordinates to be absolute in its grid. If a gruid.MsgInit is passed to Update, the pager will behave as if it is the main model of an application, and send a gruid.Quit() command on PagerQuit action.

func (*Pager) View 

func (pg *Pager) View() gruid.Range

View returns a range (Min, Max) such that the currently displayed lines are the lines whose index is between Min.Y and Max.Y, and the displayed text columns are the ones between Min.X and Max.X.

type PagerAction 

type PagerAction int

PagerAction represents an user action with the pager. 

const (
	// PagerPass reports that the pager state did not change (for example a
	// mouse motion outside the menu, or within a same entry line).
	PagerPass PagerAction = iota

	// PagerMove reports a scrolling movement.
	PagerMove

	// PagerQuit reports that the user clicked outside the menu, or pressed
	// Esc, Space or X.
	PagerQuit
)

type PagerConfig 

type PagerConfig struct {
	Grid  gruid.Grid   // grid slice where the viewable content is drawn
	Lines []StyledText // content lines to be read
	Box   *Box         // draw optional box around the  label
	Keys  PagerKeys    // optional custom key bindings for the pager
	Style PagerStyle
}

PagerConfig describes configuration options for creating a pager.

type PagerKeys 

type PagerKeys struct {
	Down         []gruid.Key // go one line down (default: ArrowDown, j)
	Up           []gruid.Key // go one line up (default: ArrowUp, k)
	Left         []gruid.Key // go left (default: ArrowLeft, h)
	Right        []gruid.Key // go right (default: ArrowRight, l)
	Start        []gruid.Key // go to start of line (default: 0, ^)
	PageDown     []gruid.Key // go one page down (default: PageDown, f)
	PageUp       []gruid.Key // go one page up (default: PageUp, b)
	HalfPageDown []gruid.Key // go half page down (default: Enter, d)
	HalfPageUp   []gruid.Key // go half page up (default: Backspace, u)
	Top          []gruid.Key // go to the top (default: Home, g)
	Bottom       []gruid.Key // go to the bottom (default: End, G)
	Quit         []gruid.Key // quit pager (default: Escape, q, Q)
}

PagerKeys contains key bindings configuration for the pager.

type PagerStyle 

type PagerStyle struct {
	LineNum gruid.Style // line num display style (for boxed pager)
}

PagerStyle describes styling options for a Pager.

type Replay 

type Replay struct {
	// contains filtered or unexported fields
}

Replay represents an application's session with the given recorded frames.

Replay implements gruid.Model and can be used as main model of an application.

func NewReplay 

func NewReplay(cfg ReplayConfig) *Replay

NewReplay returns a new Replay with a given configuration.

func (*Replay) Draw 

func (rep *Replay) Draw() gruid.Grid

Draw implements gruid.Model.Draw for Replay.

func (*Replay) Seek 

func (rep *Replay) Seek(d time.Duration)

Seek moves replay forward/backward by the given duration.

func (*Replay) SetFrame 

func (rep *Replay) SetFrame(n int)

SetFrame sets the current frame number to be displayed.

func (*Replay) Update 

func (rep *Replay) Update(msg gruid.Msg) gruid.Effect

Update implements gruid.Model.Update for Replay. It considers mouse message coordinates to be absolute in its grid. If a gruid.MsgInit is passed to Update, the replay will behave as if it is the main model of an application, and send a gruid.Quit() command on a quit request.

type ReplayConfig 

type ReplayConfig struct {
	Grid         gruid.Grid          // grid to use for drawing
	FrameDecoder *gruid.FrameDecoder // frame decoder
	Keys         ReplayKeys          // optional custom key bindings
}

ReplayConfig contains replay configuration.

type ReplayKeys 

type ReplayKeys struct {
	Quit      []gruid.Key // quit replay (default: q, Q, esc)
	Pause     []gruid.Key // pause replay (default: p, P, space)
	SpeedMore []gruid.Key // increase replay speed (default: +, })
	SpeedLess []gruid.Key // decrease replay speed (default: -, {)
	FrameNext []gruid.Key // go to next frame (default: arrow right, l)
	FramePrev []gruid.Key // go to previous frame (default: arrow left, h)
	Forward   []gruid.Key // go 1 minute forward (default: arrow down, j)
	Backward  []gruid.Key // go 1 minute backward (default: arrow up, k)
	Help      []gruid.Key // key bindings help (default: ?)
}

ReplayKeys contains key bindings configuration for the replay.

type StyledText 

type StyledText struct {
	// contains filtered or unexported fields
}

StyledText is a simple text formatter and styler. The zero value can be used, but you may prefer using Text and Textf.

func NewStyledText 

func NewStyledText(text string, st gruid.Style) StyledText

NewStyledText returns a new styled text with the given text and style. It is a shorthand for StyledText{}.With.

func Text 

func Text(text string) StyledText

Text is a shorthand for StyledText{}.WithText and creates a new styled text with the given text and the default style.

func Textf 

func Textf(format string, a ...interface{}) StyledText

Textf returns a new styled text with the given formatted text, and default style.

func (StyledText) Draw 

func (stt StyledText) Draw(gd gruid.Grid) gruid.Grid

Draw displays the styled text in a given grid. It returns the smallest grid slice containing the drawn part. Note that the grid is not cleared with spaces beforehand by this function, not even the returned one, you should use the styled text with a label for this.

func (StyledText) Format 

func (stt StyledText) Format(width int) StyledText

Format formats the text so that lines longer than a certain width get wrapped at word boundaries, if possible. It preserves spaces at the beginning of a line.

func (StyledText) Iter 

func (stt StyledText) Iter(fn func(gruid.Point, gruid.Cell)) gruid.Point

Iter iterates a function for all couples positions and cells representing the styled text, and returns the minimum (w, h) size in cells which can fit the text.

func (StyledText) Markups 

func (stt StyledText) Markups() map[rune]gruid.Style

Markups returns a copy of the markups currently defined for the styled text.

func (StyledText) Size 

func (stt StyledText) Size() gruid.Point

Size returns the minimum (w, h) size in cells which can fit the text.

func (StyledText) Style 

func (stt StyledText) Style() gruid.Style

Style returns the text default style.

func (StyledText) Text 

func (stt StyledText) Text() string

Text returns the current styled text as a string.

func (StyledText) With 

func (stt StyledText) With(text string, style gruid.Style) StyledText

With returns a derived styled text with new next and style.

func (StyledText) WithMarkup 

func (stt StyledText) WithMarkup(r rune, style gruid.Style) StyledText

WithMarkup returns a derived styled text with a new markup @r available for a given style. Markup starts by a @ sign, and is followed then by a rune indicating the particular style. Default style is marked by @N.

This simple markup is inspired from github/gdamore/tcell, but with somewhat different defaults: unless at least one non-default markup is registered, markup commands processing is not activated, and @ is treated as any other character.

func (StyledText) WithMarkups 

func (stt StyledText) WithMarkups(markups map[rune]gruid.Style) StyledText

WithMarkups is the same as WithMarkup but passing a whole map of rune-style associations.

func (StyledText) WithStyle 

func (stt StyledText) WithStyle(style gruid.Style) StyledText

WithStyle returns a derived styled text with a updated default style.

func (StyledText) WithText 

func (stt StyledText) WithText(text string) StyledText

WithText returns a derived styled text with updated text.

func (StyledText) WithTextf 

func (stt StyledText) WithTextf(format string, a ...interface{}) StyledText

WithTextf returns a derived styled text with updated formatted text.

type TextInput 

type TextInput struct {
	// contains filtered or unexported fields
}

TextInput represents a line entry with text supplied from the user that can be validated. It offers only basic editing shortcuts.

TextInput implements gruid.Model, but is not suitable for use as main model of an application.

func NewTextInput 

func NewTextInput(cfg TextInputConfig) *TextInput

NewTextInput returns a new text input with given configuration options.

func (*TextInput) Action 

func (ti *TextInput) Action() TextInputAction

Action returns the action performed with the TextInput in the last call to Update.

func (*TextInput) Content 

func (ti *TextInput) Content() string

Content returns the current content of the text input.

func (*TextInput) Draw 

func (ti *TextInput) Draw() gruid.Grid

Draw implements gruid.Model.Draw for TextInput.

func (*TextInput) SetBox 

func (ti *TextInput) SetBox(b *Box)

SetBox updates the text input surrounding box.

func (*TextInput) SetCursor 

func (ti *TextInput) SetCursor(i int)

SetCursor updates the position of the cursor.

func (*TextInput) Update 

func (ti *TextInput) Update(msg gruid.Msg) gruid.Effect

Update implements gruid.Model.Update for TextInput. It considers mouse message coordinates to be absolute in its grid.

type TextInputAction 

type TextInputAction int

TextInputAction represents last user action with the text input. 

const (
	TextInputPass   TextInputAction = iota // no change in state
	TextInputChange                        // changed content or moved cursor
	TextInputInvoke                        // invoke/accept content
	TextInputQuit                          // quit/cancel text input
)

These constants represent possible actions raising from interaction with the text input.

type TextInputConfig 

type TextInputConfig struct {
	Grid   gruid.Grid    // grid slice where the text input is drawn
	Text   StyledText    // styled text with initial text input content
	Prompt StyledText    // optional prompt text
	Box    *Box          // draw optional box around the text input
	Keys   TextInputKeys // optional custom key bindings for the text input
	Style  TextInputStyle
}

TextInputConfig describes configuration options for creating a text input.

type TextInputKeys 

type TextInputKeys struct {
	Quit []gruid.Key // quit text input (default: Escape, Tab)
}

TextInputKeys contains key bindings configuration for the text input.

type TextInputStyle 

type TextInputStyle struct {
	Cursor gruid.Style // cursor style
}

TextInputStyle describes styling options for a TextInput.

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.