stgui

README

stgui

A simple, grid-based terminal GUI library for Go.

Installation

go get [github.com/jamieyoung5/stgui](https://github.com/jamieyoung5/stgui)

## Quick Start

package main

import (
	"fmt"
	"os"

	"[github.com/jamieyoung5/stgui](https://github.com/jamieyoung5/stgui)"
	"[github.com/jamieyoung5/stgui/widgets](https://github.com/jamieyoung5/stgui/widgets)"
)

func main() {
	// 1. Create Widgets
	lbl := widgets.NewLabel("Hello World")
	btn := widgets.NewButton("Quit", func() {
		os.Exit(0)
	})

	// 2. Define Grid Layout
	gridData := [][]any{
		{lbl},
		{btn},
	}
	grid, _ := stgui.NewGrid(gridData, stgui.WithGridSymbols())

	// 3. Setup Container and Cursor
	container := widgets.NewContainer(grid)
	cursor := stgui.NewCursor(container, grid, 1, 0, stgui.DefaultDirectionalControls)
	grid.Cells[1][0].Selected = true // Select the button initially

	// 4. Initialize Screen and App
	screen := stgui.NewScreen(
		[]*stgui.Cursor{cursor},
		[][]stgui.Widget{{container}},
	)

	if err := stgui.NewApp(screen).Run(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

Documentation

Index

• Variables
• type App
  • func NewApp(screen *Screen) *App
  • func (a *App) Display()
  • func (a *App) Run() error
• type Cell
  • func (c *Cell) RenderLines() []string
• type Cursor
  • func NewCursor(widget Widget, grid *Grid, row, col int, controls map[string]string) *Cursor
  • func (c *Cursor) Down()
  • func (c *Cursor) Left()
  • func (c *Cursor) Right()
  • func (c *Cursor) Select(input string) (screen *Screen, exit bool)
  • func (c *Cursor) Up()
• type Grid
  • func NewGrid(grid [][]any, style *GridStyle) (*Grid, error)
  • func (g *Grid) Refresh(grid [][]any) error
  • func (g *Grid) Render() string
  • func (g *Grid) RenderLines() []string
  • func (g *Grid) Size() (height int, width int)
• type GridStyle
  • func WithGridSymbols() *GridStyle
• type Renderable
• type Screen
  • func NewScreen(cursors []*Cursor, widgets [][]Widget) *Screen
  • func (s *Screen) Render() string
• type Widget

Variables

var DefaultDirectionalControls = map[string]string{
	keyboard.UpArrowKey:    "UP",
	keyboard.DownArrowKey:  "DOWN",
	keyboard.LeftArrowKey:  "LEFT",
	keyboard.RightArrowKey: "RIGHT",
}

Types

type App

type App struct {
	Screens *gostrc.Stack[*Screen]
	// contains filtered or unexported fields
}

func NewApp

func NewApp(screen *Screen) *App

func (*App) Display

func (a *App) Display()

func (*App) Run

func (a *App) Run() error

type Cell

type Cell struct {
	Value any
	Child Renderable

	Selected bool
}

func (*Cell) RenderLines

func (c *Cell) RenderLines() []string

type Cursor

type Cursor struct {
	Row int
	Col int

	Controls map[string]string
	// contains filtered or unexported fields
}

func NewCursor

func NewCursor(widget Widget, grid *Grid, row, col int, controls map[string]string) *Cursor

func (*Cursor) Down

func (c *Cursor) Down()

func (*Cursor) Left

func (c *Cursor) Left()

func (*Cursor) Right

func (c *Cursor) Right()

func (*Cursor) Select

func (c *Cursor) Select(input string) (screen *Screen, exit bool)

func (*Cursor) Up

func (c *Cursor) Up()

type Grid

type Grid struct {
	Cells [][]*Cell
	Style *GridStyle
	// contains filtered or unexported fields
}

func NewGrid

func NewGrid(grid [][]any, style *GridStyle) (*Grid, error)

TODO: add guarantees that this will be evenly sized (i.e it is a square/rectangle)

func (*Grid) Refresh

func (g *Grid) Refresh(grid [][]any) error

func (*Grid) Render

func (g *Grid) Render() string

func (*Grid) RenderLines

func (g *Grid) RenderLines() []string

func (*Grid) Size

func (g *Grid) Size() (height int, width int)

type GridStyle

type GridStyle struct {
	VerticalDivider   string
	HorizontalDivider string
	Intersection      string
	NoValue           string
}

func WithGridSymbols

func WithGridSymbols() *GridStyle

type Renderable

type Renderable interface {
	RenderLines() []string
}

type Screen

type Screen struct {
	Persist bool
	Cursors []*Cursor
	// contains filtered or unexported fields
}

func NewScreen

func NewScreen(cursors []*Cursor, widgets [][]Widget) *Screen

func (*Screen) Render

func (s *Screen) Render() string

type Widget

type Widget interface {
	Size() (width, height int)
	Render() string
	Select(cursor *Cursor, input string) (screen *Screen, exit bool)
}