canvas

Documentation

Overview

Package canvas implements an abstract 2D area used to plot arbitary runes that can be displayed using the bubbletea framework.

Index

• func CanvasYCoordinate(xAxis int, y int) (r int)
• func CanvasYCoordinates(xAxis int, seq []int) (r []int)
• type Cell
  • func NewCell(r rune) Cell
  • func NewCellWithStyle(r rune, s lipgloss.Style) Cell
• type CellLine
• type Float64Point
  • func CanvasFloat64Point(origin Point, p Float64Point) (r Float64Point)
  • func NewFloat64PointFromPoint(p Point) Float64Point
  • func (p Float64Point) Add(f Float64Point) Float64Point
  • func (p Float64Point) Mul(f Float64Point) Float64Point
  • func (p Float64Point) Sub(f Float64Point) Float64Point
• type KeyMap
  • func DefaultKeyMap() KeyMap
• type Model
  • func New(w, h int, opts ...Option) Model
  • func (m *Model) Blur()
  • func (m *Model) Cell(p Point) (c Cell)
  • func (m *Model) Clear()
  • func (m *Model) Cursor() Point
  • func (m *Model) Fill(c Cell)
  • func (m *Model) FillLine(y int, c Cell)
  • func (m *Model) Focus()
  • func (m *Model) Focused() bool
  • func (m *Model) Height() int
  • func (m Model) Init() tea.Cmd
  • func (m *Model) MoveDown(i int)
  • func (m *Model) MoveLeft(i int)
  • func (m *Model) MoveRight(i int)
  • func (m *Model) MoveUp(i int)
  • func (m *Model) Resize(w, h int)
  • func (m *Model) SetCell(p Point, c Cell) bool
  • func (m *Model) SetCellStyle(p Point, s lipgloss.Style) bool
  • func (m *Model) SetCursor(p Point)
  • func (m *Model) SetLines(lines []string) bool
  • func (m *Model) SetLinesWithStyle(lines []string, s lipgloss.Style) bool
  • func (m *Model) SetRune(p Point, r rune) bool
  • func (m *Model) SetRunes(p Point, l []rune) bool
  • func (m *Model) SetRunesWithStyle(p Point, l []rune, s lipgloss.Style) bool
  • func (m *Model) SetString(p Point, l string) bool
  • func (m *Model) SetStringWithStyle(p Point, l string, s lipgloss.Style) bool
  • func (m *Model) SetStyle(s lipgloss.Style)
  • func (m *Model) SetZoneManager(zm *zone.Manager)
  • func (m *Model) ShiftDown()
  • func (m *Model) ShiftLeft()
  • func (m *Model) ShiftRight()
  • func (m *Model) ShiftUp()
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() (r string)
  • func (m *Model) Width() int
  • func (m *Model) ZoneID() string
  • func (m *Model) ZoneManager() *zone.Manager
• type Option
  • func WithContent(l []string) Option
  • func WithCursor(p Point) Option
  • func WithFocus() Option
  • func WithKeyMap(k KeyMap) Option
  • func WithStyle(s lipgloss.Style) Option
  • func WithUpdateHandler(h UpdateHandler) Option
  • func WithViewHeight(h int) Option
  • func WithViewWidth(w int) Option
  • func WithZoneManager(zm *zone.Manager) Option
• type Point
  • func CanvasPoint(origin Point, p Point) (r Point)
  • func CanvasPointFromFloat64Point(origin Point, f Float64Point) Point
  • func CanvasPoints(origin Point, seq []Point) (r []Point)
  • func NewPointFromFloat64Point(f Float64Point) Point
• type UpdateHandler
  • func DefaultUpdateHandler() UpdateHandler

Functions

func CanvasYCoordinate

func CanvasYCoordinate(xAxis int, y int) (r int)

CanvasYCoordinate returns a Y coordinates in the canvas coordinates system (X,Y is top left) from a Y coordinate in the Cartesian coordinates system (X,Y is bottom left) by passing the graph X axis in the canvas coordinates system.

func CanvasYCoordinates

func CanvasYCoordinates(xAxis int, seq []int) (r []int)

CanvasYCoordinates returns a sequence of Y coordinates in the canvas coordinates system (X,Y is top left) from a given sequence of Y coordinates in the Cartesian coordinates system (X,Y is bottom left) by passing the graph X axis in the canvas coordinates system.

Types

type Cell

type Cell struct {
	Rune  rune
	Style lipgloss.Style
}

Cell contains a rune and lipgloss Style for rendering

func NewCell

func NewCell(r rune) Cell

NewCell returns Cell with given rune and default lipgloss Style.

func NewCellWithStyle

func NewCellWithStyle(r rune, s lipgloss.Style) Cell

NewCellWithStyle returns Cell with given rune and lipgloss Style.

type CellLine

type CellLine []Cell

CellLine is a slice of Cells

type Float64Point

type Float64Point struct {
	X float64
	Y float64
}

Float64Point represents a point in a coordinate system with floating point precision.

func CanvasFloat64Point

func CanvasFloat64Point(origin Point, p Float64Point) (r Float64Point)

CanvasFloat64Point returns a Float64Point in the canvas coordinates system (X,Y is top left) from a given Float64Point in the Cartesian coordinates system (X,Y is bottom left) by passing the graph origin in the canvas coordinates system.

func NewFloat64PointFromPoint

func NewFloat64PointFromPoint(p Point) Float64Point

NewFloat64PointFromPoint returns a new Float64Point from a given Point.

func (Float64Point) Add

func (p Float64Point) Add(f Float64Point) Float64Point

Add returns a Float64Point with both X and Y values added to the X and Y values of the given Float64Point.

func (Float64Point) Mul

func (p Float64Point) Mul(f Float64Point) Float64Point

Mul returns a Float64Point with both X and Y values multiplied by the X and Y values of the given Float64Point.

func (Float64Point) Sub

func (p Float64Point) Sub(f Float64Point) Float64Point

Sub returns a Float64Point with both X and Y values subtracted by the X and Y values of the given Float64Point.

type KeyMap

type KeyMap struct {
	Up     key.Binding
	Down   key.Binding
	Left   key.Binding
	Right  key.Binding
	PgUp   key.Binding
	PgDown key.Binding
}

func DefaultKeyMap

func DefaultKeyMap() KeyMap

DefaultKeyMap returns a default KeyMap for canvas.

type Model

type Model struct {
	Style         lipgloss.Style // default style applied to all cells
	KeyMap        KeyMap         // KeyMap used for keyboard msgs during Update()
	UpdateHandler UpdateHandler  // callback invoked during Update()

	// simulates a viewport width and height
	// to display contents of the canvas
	ViewWidth  int
	ViewHeight int
	// contains filtered or unexported fields
}

Model contains state of a canvas

func New

func New(w, h int, opts ...Option) Model

New returns a canvas Model initialized with given width, height and various options.

func (*Model) Blur

func (m *Model) Blur()

Blur disables Update events processing.

func (*Model) Cell

func (m *Model) Cell(p Point) (c Cell)

Cell returns Cell located at (X,Y) coordinates of canvas. Returns default Cell if coorindates are out of bounds.

func (*Model) Clear

func (m *Model) Clear()

Clear will reset canvas contents.

func (*Model) Cursor

func (m *Model) Cursor() Point

Cursor returns Point containg (X,Y) coordinates pointing to top left of viewport.

func (*Model) Fill

func (m *Model) Fill(c Cell)

Fill sets all content in canvas to Cell.

func (*Model) FillLine

func (m *Model) FillLine(y int, c Cell)

FillLine sets all Cells in a CellLine y away from origin to given Cell.

func (*Model) Focus

func (m *Model) Focus()

Focus enables Update events processing.

func (*Model) Focused

func (m *Model) Focused() bool

Focused returns whether canvas is being focused.

func (*Model) Height

func (m *Model) Height() int

Height returns canvas height.

func (Model) Init

func (m Model) Init() tea.Cmd

Init initializes the canvas.

func (*Model) MoveDown

func (m *Model) MoveDown(i int)

MoveDown moves cursor down if possible.

func (*Model) MoveLeft

func (m *Model) MoveLeft(i int)

MoveLeft moves cursor left if possible.

func (*Model) MoveRight

func (m *Model) MoveRight(i int)

MoveRight moves cursor right if possible.

func (*Model) MoveUp

func (m *Model) MoveUp(i int)

MoveUp moves cursor up if possible.

func (*Model) Resize

func (m *Model) Resize(w, h int)

Resize will resize canvas to new height and width, and resets cursor. Will truncate existing content if canvas size shrinks. Does not change viewport for displaying contents.

func (*Model) SetCell

func (m *Model) SetCell(p Point, c Cell) bool

SetCell sets a Cell using (X,Y) coordinates of canvas.

func (*Model) SetCellStyle

func (m *Model) SetCellStyle(p Point, s lipgloss.Style) bool

SetCellStyle sets Cell.Style using (X,Y) coordinates of canvas.

func (*Model) SetCursor

func (m *Model) SetCursor(p Point)

SetCursor sets (X,Y) coordinates of cursor pointing to top left of viewport. Coordinates will be bounded by canvas if x, y coordinates are out of bound.

func (*Model) SetLines

func (m *Model) SetLines(lines []string) bool

SetLines copies []string into canvas as contents. Each string element represents a line in the canvas starting from top to bottom. Truncates contents if contents are greater than canvas height and width.

func (*Model) SetLinesWithStyle

func (m *Model) SetLinesWithStyle(lines []string, s lipgloss.Style) bool

SetLinesWithStyle copies []string into canvas as contents with style applied to all Cells. Each string element represents a line in the canvas starting from top to bottom. Truncates contents if contents are greater than canvas height and width.

func (*Model) SetRune

func (m *Model) SetRune(p Point, r rune) bool

SetRune sets Cell.Rune using (X,Y) coordinates of canvas.

func (*Model) SetRunes

func (m *Model) SetRunes(p Point, l []rune) bool

SetRunes copies rune values into canvas CellLine starting at coordinates (X, Y). Style will be applied to all Cells. Truncates values execeeding the canvas width.

func (*Model) SetRunesWithStyle

func (m *Model) SetRunesWithStyle(p Point, l []rune, s lipgloss.Style) bool

SetRunesWithStyle copies rune values into canvas CellLine starting at coordinates (X, Y). Style will be applied to all Cells. Truncates values execeeding the canvas width.

func (*Model) SetString

func (m *Model) SetString(p Point, l string) bool

SetString copies string as rune values into canvas CellLine starting at coordinates (X, Y). Truncates values execeeding the canvas width.

func (*Model) SetStringWithStyle

func (m *Model) SetStringWithStyle(p Point, l string, s lipgloss.Style) bool

SetStringWithStyle copies string as rune values into canvas CellLine starting at coordinates (X, Y). Style will be applied to all Cells. Truncates values execeeding the canvas width.

func (*Model) SetStyle

func (m *Model) SetStyle(s lipgloss.Style)

SetStyle applies a lipgloss.Style to all Cells to change visual elements of each rune in the canvas.

func (*Model) SetZoneManager

func (m *Model) SetZoneManager(zm *zone.Manager)

SetZoneManager enables mouse functionality by setting a bubblezone.Manager to the canvas. The bubblezone.Manager can check bubbletea mouse event Msgs passed to the UpdateHandler handler during an Update(). The root bubbletea model must wrap the View() string with bubblezone.Manager.Scan() to enable mouse functionality. To disable mouse functionality after enabling, call SetZoneManager on nil.

func (*Model) ShiftDown

func (m *Model) ShiftDown()

ShiftDown moves all Cells down once. First CellLine will be set to a new CellLine.

func (*Model) ShiftLeft

func (m *Model) ShiftLeft()

ShiftLeft moves all Cells left once. Last cell in each CellLine will be a new default Cell.

func (*Model) ShiftRight

func (m *Model) ShiftRight()

ShiftRight moves all Cells right once. First cell in each CellLine will be a new default Cell.

func (*Model) ShiftUp

func (m *Model) ShiftUp()

ShiftUp moves all Cells up once. Last CellLine will be set to a new CellLine.

func (Model) Update

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

Update processes bubbletea Msg to by invoking UpdateHandler callback if canvas is focused.

func (Model) View

func (m Model) View() (r string)

View returns a string used by the bubbletea framework to display the canvas.

func (*Model) Width

func (m *Model) Width() int

Width returns canvas width.

func (*Model) ZoneID

func (m *Model) ZoneID() string

ZoneID will return canvas zone ID used by zone Manager.

func (*Model) ZoneManager

func (m *Model) ZoneManager() *zone.Manager

ZoneManager will return canvas zone Manager.

type Option

type Option func(*Model)

Option is used to set options when initializing a sparkline. Example:

canvas := New(width, height, WithStyle(someStyle), WithKeyMap(someKeyMap))

func WithContent

func WithContent(l []string) Option

WithContent copies the given []string into the contents of the canvas with default style. Each string will be copied into a row starting from the top of the canvas to bottom. Use option WithStyle() to set canvas style before using WithContent() for styling.

func WithCursor

func WithCursor(p Point) Option

WithCursor sets the cursor starting position for the viewport.

func WithFocus

func WithFocus() Option

WithFocus sets the canvas to be focused.

func WithKeyMap

func WithKeyMap(k KeyMap) Option

WithKeyMap sets the KeyMap used when processing keyboard event messages in Update().

func WithStyle

func WithStyle(s lipgloss.Style) Option

WithStyle sets the default Cell style.

func WithUpdateHandler

func WithUpdateHandler(h UpdateHandler) Option

WithUpdateHandler sets the UpdateHandler used when processing bubbletea Msg events in Update().

func WithViewHeight

func WithViewHeight(h int) Option

WithViewHeight sets the viewport height of the canvas.

func WithViewWidth

func WithViewWidth(w int) Option

WithViewWidth sets the viewport width of the canvas.

func WithZoneManager

func WithZoneManager(zm *zone.Manager) Option

WithZoneManager sets the bubblezone Manager used when processing bubbletea Msg mouse events in Update().

type Point

type Point = image.Point

Point is alias for image.Point

func CanvasPoint

func CanvasPoint(origin Point, p Point) (r Point)

CanvasPoint returns a Point in the canvas coordinates system (X,Y is top left) from a given Point in the Cartesian coordinates system (X,Y is bottom left) by passing the graph origin in the canvas coordinates system.

func CanvasPointFromFloat64Point

func CanvasPointFromFloat64Point(origin Point, f Float64Point) Point

CanvasPointFromFloat64Point returns a Point in the canvas coordinates systems (X,Y is top left) from a canvas Float64Point in the Cartesian coordinates system (X,Y is bottom left) by passing the graph origin in the canvas coordinates system.

func CanvasPoints

func CanvasPoints(origin Point, seq []Point) (r []Point)

CanvasPoints returns a sequence of Points in the canvas coordinates system (X,Y is top left) from a given sequence of Points in the Cartesian coordinates system (X,Y is bottom left) by passing the graph origin in the canvas coordinates system.

func NewPointFromFloat64Point

func NewPointFromFloat64Point(f Float64Point) Point

NewPointFromFloat64Point returns a new Point from a given Float64Point.

type UpdateHandler

type UpdateHandler func(*Model, tea.Msg)

UpdateHandler callback invoked during an Update() and passes in the canvas *Model and bubbletea Msg.

func DefaultUpdateHandler

func DefaultUpdateHandler() UpdateHandler

DefaultUpdateHandler is used by canvas chart to enable moving viewing window using the mouse wheel, holding down mouse left button and moving, and with the arrow keys. Uses canvas Keymap for keyboard messages.