dull

package module
v0.0.0-...-4a525b6 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2019 License: MIT Imports: 25 Imported by: 0

README

dull

GoDoc Go Report Card

dull is a text user interface library. It provides a means of writing applications with windows that display a grid of cells. The windows bear a resemblance to terminal windows, but the similarity is purely visual.

warning : dull is currently just an experiment, and is not ready for prime time.

pre-requisites

  • go - essential
  • make - nice to have

getting started

go get -v -u github.com/pekim/dull
cd $GOPATH/src/github.com/pekim/dull

# install required go tools, and dull packages
make install

# run a simple demo
make run_simple

documentation

godoc.org/github.com/pekim/dull

Documentation

Overview

Package dull is a text user interface library. It provides a means of writing applications with windows that display a grid of cells. The windows bear a resemblance to terminal windows, but the similarity is purely visual.

Example initialisation and window creation 

func main() {
	dull.Run(initialise)
}

func initialise(app *dull.Application, err error) {
	if err != nil {
		panic(err)
	}

	window, err := app.NewWindow(&dull.WindowOptions{})
	if err != nil {
		panic(err)
	}

	// put some text in the top left corner
	window.Grid().PrintAt(0, 0, "some text")

	// make the window visible
	window.Show()
}

Threads

Because of the way that an underlying library (glfw) works, almost all calls to dull functions should occur in the main thread.

All callbacks to functions provided to dull will occur on the main thread. So it is safe to call any dull function in a callback.

A function may be run on the main thread by calling one of the Do... functions. 

go func(window *dull.Window) {
	c := 0

	t := time.Tick(time.Second)
	for range t {
		window.Do(func() {
			window.PrintAt(0, 2, fmt.Sprintf("count : %d", c++))
		})
	}
}(window)

Index

Constants

View Source 
const (
	KeyUnknown      = Key(glfw.KeyUnknown)
	KeySpace        = Key(glfw.KeySpace)
	KeyApostrophe   = Key(glfw.KeyApostrophe)
	KeyComma        = Key(glfw.KeyComma)
	KeyMinus        = Key(glfw.KeyMinus)
	KeyPeriod       = Key(glfw.KeyPeriod)
	KeySlash        = Key(glfw.KeySlash)
	Key0            = Key(glfw.Key0)
	Key1            = Key(glfw.Key1)
	Key2            = Key(glfw.Key2)
	Key3            = Key(glfw.Key3)
	Key4            = Key(glfw.Key4)
	Key5            = Key(glfw.Key5)
	Key6            = Key(glfw.Key6)
	Key7            = Key(glfw.Key7)
	Key8            = Key(glfw.Key8)
	Key9            = Key(glfw.Key9)
	KeySemicolon    = Key(glfw.KeySemicolon)
	KeyEqual        = Key(glfw.KeyEqual)
	KeyA            = Key(glfw.KeyA)
	KeyB            = Key(glfw.KeyB)
	KeyC            = Key(glfw.KeyC)
	KeyD            = Key(glfw.KeyD)
	KeyE            = Key(glfw.KeyE)
	KeyF            = Key(glfw.KeyF)
	KeyG            = Key(glfw.KeyG)
	KeyH            = Key(glfw.KeyH)
	KeyI            = Key(glfw.KeyI)
	KeyJ            = Key(glfw.KeyJ)
	KeyK            = Key(glfw.KeyK)
	KeyL            = Key(glfw.KeyL)
	KeyM            = Key(glfw.KeyM)
	KeyN            = Key(glfw.KeyN)
	KeyO            = Key(glfw.KeyO)
	KeyP            = Key(glfw.KeyP)
	KeyQ            = Key(glfw.KeyQ)
	KeyR            = Key(glfw.KeyR)
	KeyS            = Key(glfw.KeyS)
	KeyT            = Key(glfw.KeyT)
	KeyU            = Key(glfw.KeyU)
	KeyV            = Key(glfw.KeyV)
	KeyW            = Key(glfw.KeyW)
	KeyX            = Key(glfw.KeyX)
	KeyY            = Key(glfw.KeyY)
	KeyZ            = Key(glfw.KeyZ)
	KeyLeftBracket  = Key(glfw.KeyLeftBracket)
	KeyBackslash    = Key(glfw.KeyBackslash)
	KeyRightBracket = Key(glfw.KeyRightBracket)
	KeyGraveAccent  = Key(glfw.KeyGraveAccent)
	KeyWorld1       = Key(glfw.KeyWorld1)
	KeyWorld2       = Key(glfw.KeyWorld2)
	KeyEscape       = Key(glfw.KeyEscape)
	KeyEnter        = Key(glfw.KeyEnter)
	KeyTab          = Key(glfw.KeyTab)
	KeyBackspace    = Key(glfw.KeyBackspace)
	KeyInsert       = Key(glfw.KeyInsert)
	KeyDelete       = Key(glfw.KeyDelete)
	KeyRight        = Key(glfw.KeyRight)
	KeyLeft         = Key(glfw.KeyLeft)
	KeyDown         = Key(glfw.KeyDown)
	KeyUp           = Key(glfw.KeyUp)
	KeyPageUp       = Key(glfw.KeyPageUp)
	KeyPageDown     = Key(glfw.KeyPageDown)
	KeyHome         = Key(glfw.KeyHome)
	KeyEnd          = Key(glfw.KeyEnd)
	KeyCapsLock     = Key(glfw.KeyCapsLock)
	KeyScrollLock   = Key(glfw.KeyScrollLock)
	KeyNumLock      = Key(glfw.KeyNumLock)
	KeyPrintScreen  = Key(glfw.KeyPrintScreen)
	KeyPause        = Key(glfw.KeyPause)
	KeyF1           = Key(glfw.KeyF1)
	KeyF2           = Key(glfw.KeyF2)
	KeyF3           = Key(glfw.KeyF3)
	KeyF4           = Key(glfw.KeyF4)
	KeyF5           = Key(glfw.KeyF5)
	KeyF6           = Key(glfw.KeyF6)
	KeyF7           = Key(glfw.KeyF7)
	KeyF8           = Key(glfw.KeyF8)
	KeyF9           = Key(glfw.KeyF9)
	KeyF10          = Key(glfw.KeyF10)
	KeyF11          = Key(glfw.KeyF11)
	KeyF12          = Key(glfw.KeyF12)
	KeyF13          = Key(glfw.KeyF13)
	KeyF14          = Key(glfw.KeyF14)
	KeyF15          = Key(glfw.KeyF15)
	KeyF16          = Key(glfw.KeyF16)
	KeyF17          = Key(glfw.KeyF17)
	KeyF18          = Key(glfw.KeyF18)
	KeyF19          = Key(glfw.KeyF19)
	KeyF20          = Key(glfw.KeyF20)
	KeyF21          = Key(glfw.KeyF21)
	KeyF22          = Key(glfw.KeyF22)
	KeyF23          = Key(glfw.KeyF23)
	KeyF24          = Key(glfw.KeyF24)
	KeyF25          = Key(glfw.KeyF25)
	KeyKP0          = Key(glfw.KeyKP0)
	KeyKP1          = Key(glfw.KeyKP1)
	KeyKP2          = Key(glfw.KeyKP2)
	KeyKP3          = Key(glfw.KeyKP3)
	KeyKP4          = Key(glfw.KeyKP4)
	KeyKP5          = Key(glfw.KeyKP5)
	KeyKP6          = Key(glfw.KeyKP6)
	KeyKP7          = Key(glfw.KeyKP7)
	KeyKP8          = Key(glfw.KeyKP8)
	KeyKP9          = Key(glfw.KeyKP9)
	KeyKPDecimal    = Key(glfw.KeyKPDecimal)
	KeyKPDivide     = Key(glfw.KeyKPDivide)
	KeyKPMultiply   = Key(glfw.KeyKPMultiply)
	KeyKPSubtract   = Key(glfw.KeyKPSubtract)
	KeyKPAdd        = Key(glfw.KeyKPAdd)
	KeyKPEnter      = Key(glfw.KeyKPEnter)
	KeyKPEqual      = Key(glfw.KeyKPEqual)
	KeyLeftShift    = Key(glfw.KeyLeftShift)
	KeyLeftControl  = Key(glfw.KeyLeftControl)
	KeyLeftAlt      = Key(glfw.KeyLeftAlt)
	KeyLeftSuper    = Key(glfw.KeyLeftSuper)
	KeyRightShift   = Key(glfw.KeyRightShift)
	KeyRightControl = Key(glfw.KeyRightControl)
	KeyRightAlt     = Key(glfw.KeyRightAlt)
	KeyRightSuper   = Key(glfw.KeyRightSuper)
	KeyMenu         = Key(glfw.KeyMenu)
	KeyLast         = Key(glfw.KeyLast)
)

Key codes.

Variables

View Source 
var Black = NewColor(0.0, 0.0, 0.0, 1.0)
View Source 
var White = NewColor(1.0, 1.0, 1.0, 1.0)

Functions

func DoNoWait 

func DoNoWait(fn func())

DoNoWait will run a function on the main thread. It returns immediately, and does not wait for the function fn to finish.

Some API functions need to run on the main thread. See the package documentation for more details.

func DoWait 

func DoWait(fn func())

DoWait will run a function on the main thread. It blocks, and does not return until the function fn finishes.

Some API functions need to run on the main thread. See the package documentation for more details.

func Run 

func Run(initialisedFn InitialisedFn)

Run must be the first dull function called.

The initialisedFn function will be called once the library has been initialised, and functions other than Run may be called. The function will typically create and show a window (or multiple windows).

The initialisedFn function will run on the main thread.

Run blocks, and will not return until dull has terminated. This will typically be when all windows have closed.

Types

type Action 

type Action int

Action corresponds to a key or button action. 

const (
	Release Action = Action(glfw.Release) // The key or button was released.
	Press   Action = Action(glfw.Press)   // The key or button was pressed.
	Repeat  Action = Action(glfw.Repeat)  // The key was held down until it repeated.
)

Action types.

type Application 

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

Application represents a dull application and its windows.

An Application instance is provide to Run's callback function.

func (*Application) NewWindow 

func (a *Application) NewWindow(options *WindowOptions) (*Window, error)

NewWindow creates a new window.

It will not initially be visible. Call window.Show() to make it visible. This allows the window to be positioned (with window.SetPosition) before it becomes visible.

func (*Application) SetFontRenderer 

func (a *Application) SetFontRenderer(renderer FontRenderer)

SetFontRenderer allows the font renderering library to be specified. The default is FontRendererFreetype.

This function affects all subsequently created windows. A reasonable place to call it would be early in the dull.Initialised function that is passed to dull.Run.

type Border 

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

Border defines a border for a rectangle of cells.

The border will be rendered just inside the cells of the rectangle defined by the cell values.

func NewBorder 

func NewBorder(leftColumn, rightColumn, topRow, bottomRow int, color Color) Border

type BorderId 

type BorderId int

BorderId is an identifier provided when adding a border. It may later be used to remove a border.

type Borders 

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

Borders represents a collection of borders that a window may render.

An instance is provided by a Window.

func NewBorders 

func NewBorders() *Borders

func (*Borders) Add 

func (b *Borders) Add(border Border) BorderId

Add adds a border.

The returned BorderId may be later used to remove the border.

func (*Borders) Remove 

func (b *Borders) Remove(id BorderId)

Removes a border.

The border is identified by an id returned from the Add function.

func (*Borders) RemoveAll 

func (b *Borders) RemoveAll()

RemoveAll removes all borders.

type Cell 

type Cell struct {
	// Rune is the Rune to be rendered.
	Rune rune
	// Fg is the foreground colour, used to render the Rune.
	Fg Color
	// Bg is the background colour, used to fill the cell's background.
	Bg Color

	// Bold denotes whether the Rune is rendered in Bold.
	// May be combined with Italic.
	Bold bool
	// Italic denotes whether the Rune is rendered italicised.
	// May be combined with Bold.
	Italic bool

	// Underline denotes whether the Rune should be underlined (underscored).
	Underline bool
	// Strikethrough denotes whether the Rune should be struckthrough.
	Strikethrough bool

	// Invert denotes whether the foreground and background colours should be reversed.
	Invert bool
	// contains filtered or unexported fields
}

Cell represents a single cell in a grid of Cells, that are displayed in a window.

Fields in a Cell may be modified in a callback that runs on the main thread. Do not modify the cells outside of a mainthread callback.

If any fields are modified, then the containing window's MarkDirty must be called.

func (*Cell) ApplyOptions 

func (c *Cell) ApplyOptions(options *CellOptions)

type CellGrid 

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

CellGrid represents the grid of cells that are displayed in a window.

The cells may be modified in a callback that runs on the main thread. Do not modify the cells outside of a mainthread callback.

Cells are addressed at a column and row. An alternative point of view would be x and y.

Column and row indexes are zero-based.

func NewCellGrid 

func NewCellGrid(width, height int, bg, fg Color) *CellGrid

func (*CellGrid) Cell 

func (g *CellGrid) Cell(column, row int) (*Cell, error)

Cell gets a Cell at a particular column and row.

func (*CellGrid) Clear 

func (g *CellGrid) Clear()

Clear sets the Rune for all cells to the space character \u0020.

func (*CellGrid) ForAllCells 

func (g *CellGrid) ForAllCells(fn func(column, row int, cell *Cell))

ForAllCells calls the fn function for all cells in the grid.

Do not forget to call Cell.MakeDirty for a Cell if any of its fields are changed.

func (*CellGrid) PrintAt 

func (g *CellGrid) PrintAt(column, row int, text string)

PrintAt sets the runes for a sequence of cells from the runes in a string.

func (*CellGrid) SetAllCellsRune 

func (g *CellGrid) SetAllCellsRune(rune rune)

SetAllCellsRune sets the Rune for all cells to the provided value.

func (*CellGrid) SetCell 

func (g *CellGrid) SetCell(column, row int, cell *Cell) error

SetCell sets a cell's contents.

func (*CellGrid) Size 

func (g *CellGrid) Size() (columns int, rows int)

Size returns the size of the grid. That is, the number of columns of cells and the number of rows of cells.

type CellOptions 

type CellOptions struct {
	Fg            Color
	Bg            Color
	Bold          bool
	Italic        bool
	Underline     bool
	Strikethrough bool
	Invert        bool
}

type CharCallback 

type CharCallback func(char rune, mods ModifierKey)

CharCallback is a function for use with SetCharCallback.

type Color 

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

Color represents an alpha-premultiplied color.

For each value of R, G, B, and A the range is from 0.0 to 1.0 .

func NewColor 

func NewColor(r, g, b, a float32) Color

NewColor creates a Color.

type Cursor 

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

Cursor defines a cursor within a cell.

func (*Cursor) SetColor 

func (c *Cursor) SetColor(color Color)

func (*Cursor) SetPosition 

func (c *Cursor) SetPosition(column int, row int)

func (*Cursor) SetType 

func (c *Cursor) SetType(typ CursorType)

func (*Cursor) SetVisible 

func (c *Cursor) SetVisible(visible bool)

func (*Cursor) Visible 

func (c *Cursor) Visible() bool

type CursorId 

type CursorId int

CursorId is an identifier provided when adding a cursor. It may later be used to remove a cursor.

type CursorType 

type CursorType int
const (
	// Render the cursor as a line at the bottom of the cell.
	CursorTypeUnder CursorType = iota

	// Render the cursor as a block,
	// by inverting the cell's background and foreground colors.
	CursorTypeBlock

	// Render the cursor as a vertical bar between two cells.
	CursorTypeBar
)

type Cursors 

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

Cursors represents a collection of cursors that a window may render.

An instance is provided by a Window.

func NewCursors 

func NewCursors(window *Window) *Cursors

func (*Cursors) Add 

func (c *Cursors) Add(cursor *Cursor) CursorId

Add adds a cursor.

The returned CursorId may be later used to remove the cursor.

func (*Cursors) New 

func (c *Cursors) New() *Cursor

func (*Cursors) Remove 

func (c *Cursors) Remove(id CursorId)

Removes a cursor.

The cursor is identified by an id returned from the Add function.

func (*Cursors) RemoveAll 

func (c *Cursors) RemoveAll()

RemoveAll removes all cursors.

type FontRenderer 

type FontRenderer int
const (
	// FontRendererFreetype is a well respected font rendererer.
	// It should compile on most platforms.
	//
	// This is the default FontRenderer.
	FontRendererFreetype FontRenderer = iota

	// FontRendererStbtruetype is a simple bundled font renderer that should
	// compile on all platforms.
	// Not quite as good quality as freetype.
	FontRendererStbtruetype
)

type GridSizeCallback 

type GridSizeCallback func(columns, rows int)

GridSizeCallback is a function for use with SetGridSizeCallback.

type InitialisedFn 

type InitialisedFn func(app *Application, err error)

InitialisedFn is a function that will be called once library initialisation is complete.

A window (or windows) will normally be created within this function.

If something went wrong during initialisation, perhaps openGL could not be initialised, then err will be an error.

See also the Run function.

type Key 

type Key glfw.Key

Key corresponds to a keyboard key.

type KeyCallback 

type KeyCallback func(key Key, action Action, mods ModifierKey)

KeyCallback is a function for use with SetKeyCallback.

type KeyCombination 

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

func ParseKeyCombination 

func ParseKeyCombination(text string) (KeyCombination, error)

type ModifierKey 

type ModifierKey int

ModifierKey corresponds to a modifier key. 

const (
	ModNone    ModifierKey = 0
	ModShift   ModifierKey = ModifierKey(glfw.ModShift)
	ModControl ModifierKey = ModifierKey(glfw.ModControl)
	ModAlt     ModifierKey = ModifierKey(glfw.ModAlt)
	ModSuper   ModifierKey = ModifierKey(glfw.ModSuper)
)

Modifier keys. Use bitwise OR to create a combination of them.

type Window 

type Window struct {
	*Application
	// contains filtered or unexported fields
}

Window represents an X window.

Use Application.NewWindow to create a Window.

func (*Window) Bell 

func (w *Window) Bell()

Bell rings a bell on the default keyboard.

func (*Window) Borders 

func (w *Window) Borders() *Borders

Borders are rectangular borders that may be displayed around a rectangle of cells.

The borders may be manipulated in a callback.

func (*Window) Capture 

func (w *Window) Capture() image.Image

Capture captures the Window's pixels in an Image.

func (*Window) Cursors 

func (w *Window) Cursors() *Cursors

Cursors are cursors that may be displayed in a cell.

The cursors may be manipulated in a callback.

func (*Window) Destroy 

func (w *Window) Destroy()

Destroy destroys the window, and removes it from the Application.

This function may only be called from the main thread.

func (*Window) Do 

func (w *Window) Do(fn func())

Do is used to make updates to cells, and have the changes drawn to the window. Make all of the cell updates in the callback function, which will run on the main thread.

Threading and synchronisation issues are taken care off. As this results in some small overheads, take care that batches of changes are made in a single use of Do. This will also avoid a brief appearance of a partial set of changes. Take care to avoid any long running or blocking operations in the callback function.

Does not block; it does not wait for the function fn to run.

func (*Window) GetClipboard 

func (w *Window) GetClipboard() (string, error)

func (*Window) Grid 

func (w *Window) Grid() *CellGrid

Grid is the grid of Cells.

The Cells in the grid may be manipulated in a callback.

func (*Window) Hide 

func (w *Window) Hide()

Hide hides the window. It does not destroy the window, and the window may be made visible again by calling Show.

This function may only be called from the main thread.

func (*Window) LastRenderDuration 

func (w *Window) LastRenderDuration() time.Duration

LastRenderDuration returns the duration of the last render of cells. It is provided for informational purpose only.

func (*Window) SetCharCallback 

func (w *Window) SetCharCallback(fn CharCallback)

SetCharCallback sets or clears a function to call when a character is input.

To remove a previously set callback, pass nil for the callback.

The callback will run on the main thread, so there is no need to use the Do function to effect updates from the callback. Do not perform any long running or blocking operations in the callback.

func (*Window) SetClipboard 

func (w *Window) SetClipboard(text string)

func (*Window) SetGridSizeCallback 

func (w *Window) SetGridSizeCallback(fn GridSizeCallback)

SetGridSizeCallback sets or clears a function to call when the window's grid size changes. This might occur when the window size changes or when the font size changes.

When the callback is called, all cells in the new grid will be set to a blank Rune, with default background and foreground colors.

To remove a previously set callback, pass nil for the callback.

The callback will run on the main thread, so there is no need to use the Do function to effect updates from the callback. Do not perform any long running or blocking operations in the callback.

func (*Window) SetKeyCallback 

func (w *Window) SetKeyCallback(fn KeyCallback)

SetKeyCallback sets or clears a function to call when a key is pressed, repeated or released.

To remove a previously set callback, pass nil for the callback.

The callback will run on the main thread, so there is no need to use the Do function to effect updates from the callback. Do not perform any long running or blocking operations in the callback.

func (*Window) SetPosition 

func (w *Window) SetPosition(top, left int)

SetPosition sets the position, in screen coordinates, of the upper-left corner of the client area of the window.

It is very rarely a good idea to move an already visible window, as it will confuse and annoy the user.

The window manager may put limits on what positions are allowed.

This function may only be called from the main thread.

func (*Window) SetTitle 

func (w *Window) SetTitle(title string)

SetTitle sets the window title.

This function may only be called from the main thread.

func (*Window) Show 

func (w *Window) Show()

Show makes the window visible. See also Hide.

This function may only be called from the main thread.

func (*Window) ToggleFullscreen 

func (w *Window) ToggleFullscreen()

type WindowOptions 

type WindowOptions struct {
	Width  int // initial window width, in pixels
	Height int // initial window height, in pixels

	Bg *Color // default background color for cells
	Fg *Color // default foreground color for cells
}

WindowOptions is used when creating new windows to provide some initial window values.

Source Files

View all Source files

Directories

Path Synopsis
_demo
simple
widget
widget-text
font
font/freetype
font/stbtruetype
textureatlas

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.