goat

README

goat

A go tui library, that uses a declarative, yet stateful, widget tree to describe an app. Heavily inspired by Flutter and React.

Documentation

Index

• Variables
• func RunApp(w Widget) error
• func UseCleanup(cleanup func())
• func UseEffect(setup func() func(), dependencies []any)
• func UseEvent(fn func(context EventContext))
• func UseRawState[T any](initialValue T) (T, func(T))
• func UseRawStateFunc[T any](initialValue func() T) (T, func(func(T) T))
• func UseRef[T any](initialValue *T) *T
• func UseRefFunc[T any](initialValue func() *T) *T
• func UseSetup(setup func())
• func UseState[T comparable](initialValue T) (T, func(T))
• func UseStateFunc[T comparable](initialValue func() T) (T, func(func(T) T))
• func UseTriggerRender() func()
• type Canvas
  • func NewCanvas(size Size) Canvas
  • func (c *Canvas) FillBackground(x, y, width, height int, background Color)
  • func (c *Canvas) GetCell(x, y int) Cell
  • func (c *Canvas) OverlayCanvas(x, y int, topCanvas Canvas)
  • func (c *Canvas) OverlayImage(x, y int, image image.Image)
  • func (c *Canvas) SetCell(x, y int, cell Cell)
  • func (c *Canvas) Size() Size
• type Cell
  • func (bottom Cell) Blend(top Cell) Cell
• type CellTextStyle
• type Color
  • func ColorFromImageColor(c imageColor.Color) Color
  • func ColorRGB(r, g, b uint8) Color
  • func (bottom Color) Blend(top Color) Color
  • func (c Color) String() string
• type ConstraintViolationErr
  • func (err *ConstraintViolationErr) Error() string
• type Constraints
  • func (c Constraints) Check(size Size) bool
• type Dimension
  • func DimensionInt(value int) Dimension
  • func (d Dimension) Add(other Dimension) Dimension
  • func (d Dimension) AddInt(other int) Dimension
  • func (d Dimension) Int() int
  • func (d Dimension) IsInf() bool
  • func (d Dimension) IsNeg() bool
  • func (d Dimension) IsZero() bool
  • func (d Dimension) String() string
  • func (d Dimension) Sub(other Dimension) Dimension
  • func (d Dimension) SubInt(other int) Dimension
• type EdgeInserts
  • func EdgeInsertsAll(value int) EdgeInserts
  • func EdgeInsertsSymmetric(vertical int, horizontal int) EdgeInserts
  • func (ei EdgeInserts) String() string
• type Element
  • func (e *Element) Children() map[int]*Element
  • func (e *Element) MarkNeedsBuild()
  • func (e *Element) MarkNeedsPaint()
  • func (e *Element) Parent() *Element
  • func (e *Element) RenderData() any
  • func (e *Element) RenderParentData() any
  • func (e *Element) SetRenderData(renderData any)
  • func (e *Element) SetRenderParentData(renderParentData any)
• type Equality
• type EventContext
• type LayoutContext
• type PaintContext
• type Pos
  • func (pos Pos) Add(other Pos) Pos
  • func (p Pos) String() string
  • func (pos Pos) Sub(other Pos) Pos
• type RenderViewport
• type RenderWidget
• type Size
  • func SizeInt(width, height int) Size
  • func SizeSquare(value int) Size
  • func SizeSquareVisual(value int) Size
  • func (s Size) Add(other Size) Size
  • func (s Size) AddEdgeInserts(edgeInserts EdgeInserts) Size
  • func (s Size) Clamp(constraints Constraints) Size
  • func (s Size) HasInf() bool
  • func (s Size) HasNeg() bool
  • func (s Size) HasZero() bool
  • func (s Size) LooseConstraints() Constraints
  • func (s Size) String() string
  • func (s Size) Sub(other Size) Size
  • func (s Size) SubEdgeInserts(edgeInserts EdgeInserts) Size
  • func (s Size) TightConstraints() Constraints
• type StateWidget
• type Widget

Variables

var (
	DimensionZero     = Dimension{0}
	DimensionInfinite = Dimension{math.MaxInt}
)

var (
	SizeZero = Size{
		Width:  DimensionZero,
		Height: DimensionZero,
	}
	SizeInfinite = Size{
		Width:  DimensionInfinite,
		Height: DimensionInfinite,
	}
)

Functions

func RunApp

func RunApp(w Widget) error

func UseCleanup

func UseCleanup(cleanup func())

A hook that runs a cleanup function when the widget is unmounted/destroyed.

func UseEffect

func UseEffect(setup func() func(), dependencies []any)

A hook that lets you synchronize a widget with an external system. The setup function will be run when the widget is first mounted, and also whenever the effect's dependencies change. Setup can optionally return a cleanup function, which will be run when the widget is unmounted and also before a dependency change setup is triggered.

func UseEvent

func UseEvent(fn func(context EventContext))

func UseRawState

func UseRawState[T any](initialValue T) (T, func(T))

Like UseState, but will not check if a new value is equal to the old and will always trigger a rerender when set. Only use this if your state contains incomparable values.

func UseRawStateFunc

func UseRawStateFunc[T any](initialValue func() T) (T, func(func(T) T))

Like UseRawState, but uses functions to retrieve the initialization and setter values.

func UseRef

func UseRef[T any](initialValue *T) *T

A hook that lets you reference a value that’s not needed for rendering. If the value you're using is needed for rendering (which is the case the majority of the time), then use one of the UseState hooks.

func UseRefFunc

func UseRefFunc[T any](initialValue func() *T) *T

The most primitive hook to associate persistent data with a widget. A getter function is passed in that will be run once to retrieve the initial value and a reference to the variable is returned by the hook.

If you need to pass in the initial value directly, use UseRef instead. If the value you're using is needed for rendering (which is the case the majority of the time), then use one of the UseState hooks.

func UseSetup

func UseSetup(setup func())

A hook that runs a setup function when the widget is first mounted

func UseState

func UseState[T comparable](initialValue T) (T, func(T))

func UseStateFunc

func UseStateFunc[T comparable](initialValue func() T) (T, func(func(T) T))

func UseTriggerRender

func UseTriggerRender() func()

A hook used to queue a widget render. This should almost never be needed for standard use cases; try using one of the UseState hooks instead.

Types

type Canvas

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

func NewCanvas

func NewCanvas(size Size) Canvas

func (*Canvas) FillBackground

func (c *Canvas) FillBackground(x, y, width, height int, background Color)

func (*Canvas) GetCell

func (c *Canvas) GetCell(x, y int) Cell

func (*Canvas) OverlayCanvas

func (c *Canvas) OverlayCanvas(x, y int, topCanvas Canvas)

func (*Canvas) OverlayImage

func (c *Canvas) OverlayImage(x, y int, image image.Image)

func (*Canvas) SetCell

func (c *Canvas) SetCell(x, y int, cell Cell)

func (*Canvas) Size

func (c *Canvas) Size() Size

type Cell

type Cell struct {
	// Default rune represents no change in text
	Rune rune

	Background, Foreground Color

	TextStyle *CellTextStyle
}

func (Cell) Blend

func (bottom Cell) Blend(top Cell) Cell

type CellTextStyle

type CellTextStyle struct {
	Bold, Blink, Dim, Italic, Underline, StrikeThrough bool

	Url   string
	UrlId string
}

type Color

type Color struct {
	R, G, B, A uint8
}

func ColorFromImageColor

func ColorFromImageColor(c imageColor.Color) Color

func ColorRGB

func ColorRGB(r, g, b uint8) Color

func (Color) Blend

func (bottom Color) Blend(top Color) Color

func (Color) String

func (c Color) String() string

type ConstraintViolationErr

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

func (*ConstraintViolationErr) Error

func (err *ConstraintViolationErr) Error() string

type Constraints

type Constraints struct {
	Min Size
	Max Size
}

func (Constraints) Check

func (c Constraints) Check(size Size) bool

type Dimension

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

func DimensionInt

func DimensionInt(value int) Dimension

Creates a new Dimension from an integer

func (Dimension) Add

func (d Dimension) Add(other Dimension) Dimension

func (Dimension) AddInt

func (d Dimension) AddInt(other int) Dimension

func (Dimension) Int

func (d Dimension) Int() int

Returns the underlying integer value

func (Dimension) IsInf

func (d Dimension) IsInf() bool

Reports whether the Dimension is infinite

func (Dimension) IsNeg

func (d Dimension) IsNeg() bool

Reports whether the Dimension is less than zero

func (Dimension) IsZero

func (d Dimension) IsZero() bool

Reports whether the Dimension is equal to zero

func (Dimension) String

func (d Dimension) String() string

Returns the string representation, either it's integer value, or "Inf"

func (Dimension) Sub

func (d Dimension) Sub(other Dimension) Dimension

func (Dimension) SubInt

func (d Dimension) SubInt(other int) Dimension

type EdgeInserts

type EdgeInserts struct {
	Top    int
	Left   int
	Right  int
	Bottom int
}

func EdgeInsertsAll

func EdgeInsertsAll(value int) EdgeInserts

func EdgeInsertsSymmetric

func EdgeInsertsSymmetric(vertical int, horizontal int) EdgeInserts

func (EdgeInserts) String

func (ei EdgeInserts) String() string

type Element

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

func (*Element) Children

func (e *Element) Children() map[int]*Element

func (*Element) MarkNeedsBuild

func (e *Element) MarkNeedsBuild()

func (*Element) MarkNeedsPaint

func (e *Element) MarkNeedsPaint()

func (*Element) Parent

func (e *Element) Parent() *Element

func (*Element) RenderData

func (e *Element) RenderData() any

func (*Element) RenderParentData

func (e *Element) RenderParentData() any

func (*Element) SetRenderData

func (e *Element) SetRenderData(renderData any)

func (*Element) SetRenderParentData

func (e *Element) SetRenderParentData(renderParentData any)

type Equality

type Equality[T any] interface {
	Equal(T) bool
}

type EventContext

type EventContext struct {
	Event      tcell.Event
	RenderPos  Pos
	RenderSize Size
}

type LayoutContext

type LayoutContext struct {
	Constraints   Constraints
	LayoutChild   func(key int, c Widget, constraints Constraints) (Size, error)
	PositionChild func(key int, pos Pos) error
}

type PaintContext

type PaintContext struct {
	Canvas Canvas
	Size   Size
}

type Pos

type Pos struct {
	X int
	Y int
}

func (Pos) Add

func (pos Pos) Add(other Pos) Pos

func (Pos) String

func (p Pos) String() string

func (Pos) Sub

func (pos Pos) Sub(other Pos) Pos

type RenderViewport

type RenderViewport struct {
	AbsoluteStart Pos
	AbsoluteEnd   Pos
	LocalStart    Pos
	LocalEnd      Pos
}

type RenderWidget

type RenderWidget interface {
	Widget
	Layout(context LayoutContext) (Size, error)
	Paint(context PaintContext) error
}

type Size

type Size struct {
	Width  Dimension
	Height Dimension
}

func SizeInt

func SizeInt(width, height int) Size

func SizeSquare

func SizeSquare(value int) Size

func SizeSquareVisual

func SizeSquareVisual(value int) Size

func (Size) Add

func (s Size) Add(other Size) Size

func (Size) AddEdgeInserts

func (s Size) AddEdgeInserts(edgeInserts EdgeInserts) Size

Creates a Size with the original size plus edge inserts

func (Size) Clamp

func (s Size) Clamp(constraints Constraints) Size

func (Size) HasInf

func (s Size) HasInf() bool

func (Size) HasNeg

func (s Size) HasNeg() bool

func (Size) HasZero

func (s Size) HasZero() bool

func (Size) LooseConstraints

func (s Size) LooseConstraints() Constraints

Creates constraints that forbid sizes larger than this size

func (Size) String

func (s Size) String() string

func (Size) Sub

func (s Size) Sub(other Size) Size

func (Size) SubEdgeInserts

func (s Size) SubEdgeInserts(edgeInserts EdgeInserts) Size

Creates a Size with the original size plus edge inserts

func (Size) TightConstraints

func (s Size) TightConstraints() Constraints

Creates constraints that is respected only by this size

type StateWidget

type StateWidget interface {
	Widget
	Build() (Widget, error)
}

type Widget

type Widget interface {
	// contains filtered or unexported methods
}