stone

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Nov 29, 2022 License: GPL-3.0 Imports: 6 Imported by: 0

README

stone

Stone is a backend-agnostic application framework designed to:

  • Combine the simplicity and ease of development inherent to TUI programs with the extended capabilities of GUI programs
  • Be adaptable to run virtually anywhere

Currently, the only supported backend is X, but it is very easy to write and link your own. Stone will automatically run through the list of registered backends and instantiate the first one that doesn't throw an error.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterBackend 

func RegisterBackend(factory BackendFactory)

RegisterBackend registers a backend factory.

Types

type Application 

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

Application represents an application.

func (*Application) Config 

func (application *Application) Config() (config *Config)

Config returns a pointer to the application's configuration.

func (*Application) Draw 

func (application *Application) Draw()

Draw "commits" changes made in the buffer to the display.

func (*Application) Icon 

func (application *Application) Icon() (sizes []image.Image)

Icon returns all available sizes of the application's icon. If there is no icon, nil is returned.

func (*Application) OnMouseMove 

func (application *Application) OnMouseMove(
	onMouseMove func(x, y int),
)

OnMouseMove registers an event handler to be called when mouse motion is detected. The coordinates of the cell that the mouse now hovers over are given as input.

func (*Application) OnPress 

func (application *Application) OnPress(
	onPress func(button Button, modifiers Modifiers),
)

OnPress registers an event handler to be called when a key or mouse button is pressed.

func (*Application) OnQuit 

func (application *Application) OnQuit(
	onQuit func(),
)

OnQuit registers an event handler to be called just before the application quits. This can happen when the user closes the application, or the backend experiences an unrecoverable error.

func (*Application) OnRelease 

func (application *Application) OnRelease(
	onRelease func(button Button),
)

OnPress registers an event handler to be called when a key or mouse button is released.

func (*Application) OnResize 

func (application *Application) OnResize(
	onResize func(),
)

OnResize registers an event handler to be called when the application window is resized. After the event handler is called, any updates it makes will automatically be pushed to the screen.

func (*Application) OnScroll 

func (application *Application) OnScroll(
	onScroll func(x, y int),
)

OnScroll registers an event handler to be called when the user uses the mouse scroll wheel. Horizontal and vertical amounts are given as input.

func (*Application) OnStart 

func (application *Application) OnStart(
	onStart func(),
)

OnStart registers an event handler to be called once when the application starts, right before the first time updates are pushed to the screen. Anything done in here will be the first thing to appear on screen.

func (*Application) Run 

func (application *Application) Run() (
	err error,
)

Run initializes the application, starts it, and then returns a channel that broadcasts events. If no suitable backend can be found, an error is returned.

func (*Application) SetIcon 

func (application *Application) SetIcon(sizes []image.Image) (err error)

SetIcon takes in a list of different sizes of an icon, and sets it as the application's icon.

func (*Application) SetTitle 

func (application *Application) SetTitle(title string) (err error)

SetTitle sets the application's title. If in a window, it will appear as the window's name.

func (*Application) Title 

func (application *Application) Title() (title string)

Title returns the application's title.

type Backend 

type Backend interface {
	// Run is the backend's event loop. It must cleanly exit when the user
	// closes the window, but not before calling the OnQuit event. Run
	// must call event handlers within its own event loop in a
	// non-concurrent fashion.
	//
	// The OnStart event handler must run after the backend has been fully
	// initialized, and right before updates are first pushed to the screen.
	// Whatever the application draws from within this event handler must be
	// the first thing that appears on-screen.
	//
	// The OnResize event handler must run whenever the window is resized.
	// The backend must push updates to the screen after OnResize has been
	// run.
	//
	// The backend must not push updates to the screen in any other case,
	// except when its Draw() method is specifically called.
	//
	// The OnPress, OnRelease, OnMouseMove, and OnMouseScroll events are to
	// be called when such events happen. It is reccommended to compress
	// resize, mouse move, and mouse scroll events whenever possible to
	// reduce the likelihood of event buildup.
	Run()

	// SetTitle sets the application title. This will most often be the
	// window title. This method may not always produce an effect, depending
	// on the backend.
	SetTitle(title string) (err error)

	// SetIcon takes in a set of images of different sizes and sets the
	// window's icon to them. This method may not always produce an effect,
	// depending on the backend.
	SetIcon(icons []image.Image) (err error)

	// Draw pushes all updates made to the application's buffer to the
	// screen.
	Draw()
}

Backend represents a backend for stone. Backends can be registered for use with the RegisterBackend() function. All of the below methods MUST be thread safe!

type BackendFactory 

type BackendFactory func(
	application *Application,
	callbackManager *CallbackManager,
) (
	backend Backend,
	err error,
)

BackendFactory must completely initialize a backend, and return it. If anything goes wrong, it must stop, clean up any resources and return an error so another backend can be chosen.

type Buffer 

type Buffer interface {
	Size() (with, height int)
	Cell(x, y int) (cell Cell)
	SetColor(x, y int, color Color)
	SetSize(with, height int)
	SetStyle(x, y int, style Style)
	SetRune(x, y int, content rune)
	Clear()
}

Buffer represents a two dimensional text buffer.

type Button 

type Button int

Button represents a keyboard or mouse button. 

const (
	ButtonUnknown Button = 0

	KeyInsert      Button = 1
	KeyMenu        Button = 2
	KeyPrintScreen Button = 3
	KeyPause       Button = 4
	KeyCapsLock    Button = 5
	KeyScrollLock  Button = 6
	KeyNumLock     Button = 7
	KeyBackspace   Button = 8
	KeyTab         Button = 9
	KeyEnter       Button = 10
	KeyEscape      Button = 11

	KeyUp       Button = 12
	KeyDown     Button = 13
	KeyLeft     Button = 14
	KeyRight    Button = 15
	KeyPageUp   Button = 16
	KeyPageDown Button = 17
	KeyHome     Button = 18
	KeyEnd      Button = 19

	KeyLeftShift    Button = 20
	KeyRightShift   Button = 21
	KeyLeftControl  Button = 22
	KeyRightControl Button = 23
	KeyLeftAlt      Button = 24
	KeyRightAlt     Button = 25
	KeyLeftMeta     Button = 26
	KeyRightMeta    Button = 27
	KeyLeftSuper    Button = 28
	KeyRightSuper   Button = 29
	KeyLeftHyper    Button = 30
	KeyRightHyper   Button = 31

	KeyDelete Button = 127

	MouseButton1       Button = 128
	MouseButton2       Button = 129
	MouseButton3       Button = 130
	MouseButton4       Button = 131
	MouseButton5       Button = 132
	MouseButton6       Button = 133
	MouseButton7       Button = 134
	MouseButton8       Button = 135
	MouseButton9       Button = 136
	MouseButtonLeft    Button = MouseButton1
	MouseButtonMiddle  Button = MouseButton2
	MouseButtonRight   Button = MouseButton3
	MouseButtonBack    Button = MouseButton8
	MouseButtonForward Button = MouseButton9

	KeyF1  Button = 144
	KeyF2  Button = 145
	KeyF3  Button = 146
	KeyF4  Button = 147
	KeyF5  Button = 148
	KeyF6  Button = 149
	KeyF7  Button = 150
	KeyF8  Button = 151
	KeyF9  Button = 152
	KeyF10 Button = 153
	KeyF11 Button = 154
	KeyF12 Button = 155

	KeyDead Button = 156
)

func (Button) Printable 

func (button Button) Printable() (printable bool)

Printable returns whether or not the character could show up on screen. If this function returns true, the button can be cast to a rune and used as such.

type CallbackManager 

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

func (*CallbackManager) RunMouseMove 

func (manager *CallbackManager) RunMouseMove(x, y int)

func (*CallbackManager) RunPress 

func (manager *CallbackManager) RunPress(button Button, modifiers Modifiers)

func (*CallbackManager) RunQuit 

func (manager *CallbackManager) RunQuit()

func (*CallbackManager) RunRelease 

func (manager *CallbackManager) RunRelease(button Button)

func (*CallbackManager) RunResize 

func (manager *CallbackManager) RunResize()

func (*CallbackManager) RunScroll 

func (manager *CallbackManager) RunScroll(x, y int)

func (*CallbackManager) RunStart 

func (manager *CallbackManager) RunStart()

type Cell 

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

Cell is a grid-aligned rune in a buffer with associated styling and color informaiton.

func (Cell) Color 

func (cell Cell) Color() (color Color)

Color returns the cell's color.

func (Cell) Rune 

func (cell Cell) Rune() (content rune)

Rune returns the rune in the cell

func (Cell) Style 

func (cell Cell) Style() (style Style)

Style returns the styling information associated with the cell

type Color 

type Color uint8

Color represents all the different colors a cell can be. 

const (
	ColorBackground Color = 0x0
	ColorForeground Color = 0x1
	ColorDim        Color = 0x2
	ColorRed        Color = 0x3
	ColorYellow     Color = 0x4
	ColorGreen      Color = 0x5
	ColorBlue       Color = 0x6
	ColorPurple     Color = 0x7
)

type Config 

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

Config stores global, read-only configuration parameters that apply to all applications. Backends only should honor parameters that they can support.

func (*Config) Center 

func (public *Config) Center() (center bool)

Center returns whether the buffer should be displayed in the center of the window like in kitty, or aligned to one corner like in gnome-terminal.

func (*Config) Color 

func (public *Config) Color(index Color) (value color.Color)

Color returns the color value at the specified index.

func (*Config) FontNameBold added in v0.5.0 

func (public *Config) FontNameBold() (fontName string)

FontNameBold specifies the name of the font to use for bold text.

func (*Config) FontNameBoldItalic added in v0.5.0 

func (public *Config) FontNameBoldItalic() (fontName string)

FontName specifies the name of the font to use for text.

func (*Config) FontNameItalic added in v0.5.0 

func (public *Config) FontNameItalic() (fontName string)

FontName specifies the name of the font to use for text.

func (*Config) FontNameNormal added in v0.5.0 

func (public *Config) FontNameNormal() (fontName string)

FontNameNormal specifies the name of the font to use for normal text.

func (*Config) FontSize 

func (public *Config) FontSize() (fontSize int)

FontSize specifies how big the font should be.

func (*Config) Padding 

func (public *Config) Padding() (padding int)

Padding specifies how many cell's worth of padding should be on all sides of the buffer.

type DamageBuffer 

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

DamageBuffer is a two dimensional text buffer that stores a grid of cells, as well as information stating whether each cell is clean or dirty. Cells are dirty by default, are only clean when marked as clean, and become dirty again when they are altered in some way.

func (*DamageBuffer) Cell 

func (buffer *DamageBuffer) Cell(x, y int) (cell Cell)

Cell returns the cell at the specified x and y coordinates. If the coordinates are out of bounds, this method will return a blank cell.

func (*DamageBuffer) Clean 

func (buffer *DamageBuffer) Clean(x, y int) (clean bool)

Clean returns whether or not the cell at the specified x and y coordinates is clean.

func (*DamageBuffer) Clear 

func (buffer *DamageBuffer) Clear()

Clear resets the entire buffer.

func (*DamageBuffer) GetForRendering 

func (buffer *DamageBuffer) GetForRendering(x, y int) (cell Cell)

GetForRendering returns the cell at the specified x and y coordinates and marks it as clean.

func (*DamageBuffer) SetColor 

func (buffer *DamageBuffer) SetColor(x, y int, color Color)

SetColor sets the color of the cell at the specified x and y coordinates.

func (*DamageBuffer) SetDot 

func (buffer *DamageBuffer) SetDot(x, y int)

SetDot sets the buffer's text insertion position relative to the buffer origin point (0, 0).

func (*DamageBuffer) SetRune 

func (buffer *DamageBuffer) SetRune(x, y int, content rune)

SetRune sets the rune of the cell at the specified x and y coordinates.

func (*DamageBuffer) SetSize 

func (buffer *DamageBuffer) SetSize(width, height int)

SetSize sets the width and height of the buffer. This clears all data in the buffer. If the width or height is negative, this method does nothing.

func (*DamageBuffer) SetStyle 

func (buffer *DamageBuffer) SetStyle(x, y int, style Style)

SetStyle sets the style of the cell at the specified x and y coordinates.

func (*DamageBuffer) Size 

func (buffer *DamageBuffer) Size() (width, height int)

Size returns the width and height of the buffer.

func (*DamageBuffer) Write 

func (buffer *DamageBuffer) Write(bytes []byte) (bytesWritten int, err error)

Write writes data stored in a byte slice to the buffer at the current dot position. This makes Buffer an io.Writer.

type Modifiers 

type Modifiers struct {
	Shift   bool
	Control bool
	Alt     bool
	Meta    bool
	Super   bool
	Hyper   bool

	// NumberPad does not represent a key, but it behaves like one. If it is
	// set to true, the button was pressed on the number pad. It is treated
	// as a modifier key because if you don't care whether a key was pressed
	// on the number pad or not, you can just ignore this value.
	NumberPad bool
}

Modifiers lists what modifier keys are being pressed. This is used in conjunction with a button code in a button press event. These should be used instead of attempting to track the state of the modifier keys, because there is no guarantee that one press event will be coupled with one release event.

type Style 

type Style uint8

Style contains styling information about cells. These properties can be or'd together to combine them. 

const (
	StyleNormal     Style = 0
	StyleBold       Style = 1
	StyleItalic     Style = 2
	StyleUnderline  Style = 4
	StyleHighlight  Style = 8
	StyleBoldItalic Style = StyleBold | StyleItalic
)

Source Files

View all Source files

Directories

Path Synopsis
backends
x
examples
color
confview
draw
hello
printbuttons
style
type

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.