tomo

package module
v0.29.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2023 License: GPL-3.0 Imports: 17 Imported by: 6

README

tomo

Go Reference

Tomo is a lightweight GUI toolkit written in pure Go.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Do added in v0.16.0 

func Do(callback func())

Do performs a callback function in the event loop thread as soon as possible.

func NewTexture added in v0.24.0 

func NewTexture(source image.Image) canvas.TextureCloser

NewTexture creates a new texture from an image. When no longer in use, it must be freed using Close().

func Register 

func Register(priority int, factory Factory)

Register registers a backend factory with the given priority number.

func Run 

func Run(callback func()) error

Run initializes a backend, runs the specified callback function, and runs the event loop in that order. This function blocks until Stop is called, or the backend experiences a fatal error.

func RunApplication added in v0.27.0 

func RunApplication(application Application) error

RunApplication is like Run, but runs an application.

func Stop 

func Stop()

Stop stops the backend, unblocking run. Run may be called again after calling Stop.

Types

type Align 

type Align int

Align lists basic alignment types. 

const (
	AlignStart  Align = iota // similar to left-aligned text
	AlignMiddle              // similar to center-aligned text
	AlignEnd                 // similar to right-aligned text
	AlignEven                // similar to justified text
)

type Application added in v0.27.0 

type Application interface {
	// Describe returns a description of the application.
	Describe() ApplicationDescription

	// Init performs the initial setup of the application.
	Init()
}

Application represents an application object.

type ApplicationDescription added in v0.27.0 

type ApplicationDescription struct {
	// The name or ID of the application.
	Name string

	// Role describes what the application does.
	Role ApplicationRole
}

ApplicationDescription describes the name and type of an application.

func (ApplicationDescription) String added in v0.27.0 

func (application ApplicationDescription) String() string

String satisfies the fmt.Stringer interface.

type ApplicationRole added in v0.27.0 

type ApplicationRole int

ApplicationRole describes what an application does. 

const (
	RoleUnknown ApplicationRole = iota

	RoleWebBrowser
	RoleMesssanger
	RolePhone
	RoleMail

	RoleTerminalEmulator
	RoleFileBrowser
	RoleTextEditor

	RoleDocumentViewer
	RoleWordProcessor
	RoleSpreadsheet
	RoleSlideshow
	RoleCalculator

	RolePreferences
	RoleProcessManager
	RoleSystemInformation
	RoleManual

	RoleCamera
	RoleImageViewer
	RoleMediaPlayer
	RoleImageEditor
	RoleAudioEditor
	RoleVideoEditor

	RoleClock
	RoleCalendar
	RoleChecklist
)

func (ApplicationRole) String added in v0.27.0 

func (role ApplicationRole) String() string

String satisfies the fmt.Stringer interface.

type Backend 

type Backend interface {
	// These methods create new objects. The backend must reject any object
	// that was not made by it.
	NewBox() Box
	NewTextBox() TextBox
	NewCanvasBox() CanvasBox
	NewContainerBox() ContainerBox

	// NewWindow creates a normal MainWindow and returns it.
	NewWindow(image.Rectangle) (MainWindow, error)

	// NewPlainWindow creates an undecorated window that does not appear in
	// window lists and returns it. This is intended for making things like
	// panels, docks, etc.
	NewPlainWindow(image.Rectangle) (MainWindow, error)

	// NewTexture creates a new texture from an image. The backend must
	// reject any texture that was not made by it.
	NewTexture(image.Image) canvas.TextureCloser

	// Run runs the event loop until Stop() is called, or the backend
	// experiences a fatal error.
	Run() error

	// Stop must unblock run.
	Stop()

	// Do performs a callback function in the event loop thread as soon as
	// possible. This method must be safe to call concurrently.
	Do(func())
}

Backend is any Tomo implementation. Backends handle window creation, layout, rendering, and events so that there can be as many platform-specific optimizations as possible.

func Initialize 

func Initialize() (Backend, error)

Initialize instantiates a backend. The first backend (sorted by priority) that does not throw an error when initialized is used. If no backend could be instantiated, this function returns an error. This function should be called only once.

type Border 

type Border struct {
	Width Inset
	Color [4]color.Color
}

Border represents a single border of a box.

type Box 

type Box interface {
	Object

	// Window returns the Window this Box is a part of.
	Window() Window
	// Bounds returns the outer bounding rectangle of the Box relative to
	// the Window.
	Bounds() image.Rectangle
	// InnerBounds returns the inner bounding rectangle of the box. It is
	// the value of Bounds inset by the Box's border and padding.
	InnerBounds() image.Rectangle
	// MinimumSize returns the minimum width and height this Box's bounds
	// can be set to. This will return the value of whichever of these is
	// greater:
	//   - The size as set by SetMinimumSize
	//   - The size taken up by the Box's border and padding. If there is
	//     internal content that does not overflow, the size of that is also
	//     taken into account here.
	MinimumSize() image.Point
	// SetBounds sets the bounding rectangle of this Box relative to the
	// Window.
	SetBounds(image.Rectangle)
	// SetColor sets the background color of this Box.
	SetColor(color.Color)
	// SetTexture sets a repeating background texture. If the texture is
	// transparent, it will be overlayed atop the color specified by
	// SetColor().
	SetTexture(canvas.Texture)
	// SetBorder sets the Border(s) of the box. The first Border will be the
	// most outset, and the last Border will be the most inset.
	SetBorder(...Border)
	// SetMinimumSize sets the minimum width and height of the box, as
	// described in MinimumSize.
	SetMinimumSize(image.Point)
	// SetPadding sets the padding between the Box's innermost Border and
	// its content.
	SetPadding(Inset)

	// SetDNDData sets the data that will be picked up if this Box is
	// dragged. If this is nil (which is the default), this Box will not be
	// picked up.
	SetDNDData(data.Data)
	// SetDNDAccept sets the type of data that can be dropped onto this Box.
	// If this is nil (which is the default), this Box will reject all
	// drops.
	SetDNDAccept(...data.Mime)
	// SetFocused sets whether or not this Box has keyboard focus. If set to
	// true, this method will steal focus away from whichever Object
	// currently has focus.
	SetFocused(bool)
	// SetFocusable sets whether or not this Box can receive keyboard focus.
	// If set to false and the Box is already focused. the focus is removed.
	SetFocusable(bool)

	// Focused returns whether or not this Box has keyboard focus.
	Focused() bool
	// Modifiers returns which modifier keys on the keyboard are currently
	// being held down.
	Modifiers() input.Modifiers
	// MousePosition returns the position of the mouse pointer relative to
	// the Window.
	MousePosition() image.Point

	// These are event subscription functions that allow callbacks to be
	// connected to particular events. Multiple callbacks may be connected
	// to the same event at once. Callbacks can be removed by closing the
	// returned cookie.
	OnFocusEnter(func()) event.Cookie
	OnFocusLeave(func()) event.Cookie
	OnDNDEnter(func()) event.Cookie
	OnDNDLeave(func()) event.Cookie
	OnDNDDrop(func(data.Data)) event.Cookie
	OnMouseEnter(func()) event.Cookie
	OnMouseLeave(func()) event.Cookie
	OnMouseMove(func()) event.Cookie
	OnMouseDown(func(input.Button)) event.Cookie
	OnMouseUp(func(input.Button)) event.Cookie
	OnScroll(func(deltaX, deltaY float64)) event.Cookie
	OnKeyDown(func(key input.Key, numberPad bool)) event.Cookie
	OnKeyUp(func(key input.Key, numberPad bool)) event.Cookie
}

Box is a basic styled box.

func NewBox 

func NewBox() Box

NewBox creates and returns a basic Box.

type CanvasBox 

type CanvasBox interface {
	Box

	// SetDrawer sets the Drawer that will be called upon to draw the Box's
	// content when it is invalidated.
	SetDrawer(canvas.Drawer)

	// Invalidate causes the Box's area to be redrawn at the end of the
	// event cycle, even if it wouldn't be otherwise.
	Invalidate()
}

CanvasBox is a box that can be drawn to.

func NewCanvasBox 

func NewCanvasBox() CanvasBox

NewCanvasBox creates and returns a Box that can display custom graphics.

type ContainerBox 

type ContainerBox interface {
	ContentBox

	// SetGap sets the gap between child Objects.
	SetGap(image.Point)
	// Add appends a child Object.
	Add(Object)
	// Delete removes a child Object, if it is a child of this Box.
	Delete(Object)
	// Insert inserts a child Object before a specified Object. If the
	// before Object is nil or is not contained within this Box, the
	// inserted Object is appended.
	Insert(child Object, before Object)
	// Clear removes all child Objects.
	Clear()
	// Length returns the amount of child Objects.
	Length() int
	// At returns the child Object at the specified index.
	At(int) Object
	// SetLayout sets the layout of this Box. Child Objects will be
	// positioned according to it.
	SetLayout(Layout)

	// These methods control whether certain user input events get
	// propagated to child Objects. If set to true, the relevant events will
	// be sent to this container. If set to false (which is the default),
	// the events will be sent to the appropriate child Object.
	CaptureDND(bool)
	CaptureMouse(bool)
	CaptureScroll(bool)
	CaptureKeyboard(bool)
}

ContentBox is a box that can contain child Objects. It arranges them according to a layout rule.

func NewContainerBox 

func NewContainerBox() ContainerBox

NewContainerBox creates and returns a Box that can contain other boxes.

type ContentBox added in v0.7.3 

type ContentBox interface {
	Box

	// SetOverflow sets whether or not the Box's content overflows
	// horizontally and vertically. Overflowing content is clipped to the
	// bounds of the Box inset by all Borders (but not padding).
	SetOverflow(horizontal, vertical bool)
	// SetAlign sets how the Box's content is distributed horizontally and
	// vertically.
	SetAlign(x, y Align)
	// ContentBounds returns the bounds of the inner content of the Box
	// relative to the window.
	ContentBounds() image.Rectangle
	// ScrollTo shifts the origin of the Box's content to the origin of the
	// Box's InnerBounds, offset by the given point.
	ScrollTo(image.Point)
	// OnContentBoundsChange specifies a function to be called when the
	// Box's ContentBounds or InnerBounds changes.
	OnContentBoundsChange(func()) event.Cookie
}

ContentBox is an abstract box that has some kind of content. Its only purpose is to be embedded into TextBox and ContainerBox.

type FS added in v0.28.0 

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

FS is Tomo's implementation of fs.FS. It provides access to a specific part of the filesystem.

func ApplicationUserCacheFS added in v0.28.0 

func ApplicationUserCacheFS(app ApplicationDescription) (*FS, error)

ApplicationUserCacheFS returns an FS that an application can use to store user cache files.

func ApplicationUserConfigFS added in v0.28.0 

func ApplicationUserConfigFS(app ApplicationDescription) (*FS, error)

ApplicationUserConfigFS returns an FS that an application can use to store user configuration files.

func ApplicationUserDataFS added in v0.28.0 

func ApplicationUserDataFS(app ApplicationDescription) (*FS, error)

ApplicationUserDataFS returns an FS that an application can use to store user data files.

func (FS) Create added in v0.28.0 

func (this FS) Create(name string) (FileWriter, error)

Create creates or truncates the named file.

func (FS) Open added in v0.28.0 

func (this FS) Open(name string) (fs.File, error)

Open opens the named file.

func (FS) OpenFile added in v0.28.0 

func (this FS) OpenFile(
	name string,
	flag int,
	perm os.FileMode,
) (
	FileWriter,
	error,
)

OpenFile is the generalized open call; most users will use Open or Create instead.

func (FS) ReadDir added in v0.28.0 

func (this FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads the named directory and returns a list of directory entries sorted by filename.

func (FS) ReadFile added in v0.28.0 

func (this FS) ReadFile(name string) ([]byte, error)

ReadFile reads the named file and returns its contents. A successful call returns a nil error, not io.EOF. (Because ReadFile reads the whole file, the expected EOF from the final Read is not treated as an error to be reported.)

The caller is permitted to modify the returned byte slice.

func (FS) Remove added in v0.28.0 

func (this FS) Remove(name string) error

Remove removes the named file or (empty) directory.

func (FS) RemoveAll added in v0.28.0 

func (this FS) RemoveAll(name string) error

RemoveAll removes name and any children it contains.

func (FS) Rename added in v0.28.0 

func (this FS) Rename(oldname, newname string) error

Rename renames (moves) oldname to newname.

func (FS) Stat added in v0.28.0 

func (this FS) Stat(name string) (fs.FileInfo, error)

Stat returns a FileInfo describing the file.

func (FS) WriteFile added in v0.28.0 

func (this FS) WriteFile(name string, data []byte, perm os.FileMode) error

WriteFile writes data to the named file, creating it if necessary.

type Factory 

type Factory func() (Backend, error)

Factory is a function that attempts to instatiate a backend. If the instantiation process fails at any point, it must clean up all resources and return nil and an error explaining what happened.

type FileWriter added in v0.28.0 

type FileWriter interface {
	fs.File
	io.Writer
}

FileWriter is a writable version of fs.File.

type Inset 

type Inset [4]int

Inset represents a rectangle inset that can have a different value for each side.

func I added in v0.7.0 

func I(sides ...int) Inset

I allows you to create an inset in a CSS-ish way:

  • One argument: all sides are set to this value
  • Two arguments: the top and bottom sides are set to the first value, and the left and right sides are set to the second value.
  • Three arguments: the top side is set by the first value, the left and right sides are set by the second vaue, and the bottom side is set by the third value.
  • Four arguments: each value corresponds to a side.

This function will panic if an argument count that isn't one of these is given.

func (Inset) Apply added in v0.7.0 

func (inset Inset) Apply(bigger image.Rectangle) (smaller image.Rectangle)

Apply returns the given rectangle, shrunk on all four sides by the given inset. If a measurment of the inset is negative, that side will instead be expanded outward. If the rectangle's dimensions cannot be reduced any further, an empty rectangle near its center will be returned.

func (Inset) Horizontal added in v0.7.0 

func (inset Inset) Horizontal() int

Horizontal returns the sum of SideRight and SideLeft.

func (Inset) Inverse added in v0.7.0 

func (inset Inset) Inverse() (prime Inset)

Inverse returns a negated version of the inset.

func (Inset) Vertical added in v0.7.0 

func (inset Inset) Vertical() int

Vertical returns the sum of SideTop and SideBottom.

type Layout 

type Layout interface {
	// MinimumSize returns the minimum width and height of
	// LayoutHints.Bounds needed to properly lay out all child Boxes.
	MinimumSize(LayoutHints, []Box) image.Point
	// Arrange arranges child boxes according to the given LayoutHints.
	Arrange(LayoutHints, []Box)
}

A Layout can be given to a ContainerBox to arrange child objects.

type LayoutHints added in v0.9.0 

type LayoutHints struct {
	// Bounds is the bounding rectangle that children should be placed
	// within. Any padding values are already applied.
	Bounds image.Rectangle
	// OverflowX and OverflowY control wether child Boxes may be positioned
	// outside of Bounds.
	OverflowX bool
	OverflowY bool
	// AlignX and AlignY control how child Boxes are aligned horizontally
	// and vertically. The effect of this may vary depending on the Layout.
	AlignX Align
	AlignY Align
	// Gap controls the amount of horizontal and vertical spacing in-between
	// child Boxes.
	Gap image.Point
}

LayoutHints are passed to a layout to tell it how to arrange child boxes.

type MainWindow 

type MainWindow interface {
	Window

	// NewChild creates a new window that is semantically a child of this
	// window. It does not actually reside within this window, but it may be
	// linked to it via some other means. This is intended for things like
	// toolboxes and tear-off menus.
	NewChild(image.Rectangle) (Window, error)
}

MainWindow is a top-level operating system window.

func NewApplicationWindow added in v0.27.0 

func NewApplicationWindow(application Application, bounds image.Rectangle) (MainWindow, error)

NewApplicationWindow creates a window for an application. It will automatically set window information to signal to the OS that the window is owned by the application.

func NewPlainWindow added in v0.29.0 

func NewPlainWindow(bounds image.Rectangle) (MainWindow, error)

NewPlainWindow is like NewWindow, but it creates an undecorated window that does not appear in window lists. It is intended for creating things like docks, panels, etc.

func NewWindow 

func NewWindow(bounds image.Rectangle) (MainWindow, error)

NewWindow creates and returns a window within the specified bounds on screen.

type Object 

type Object interface {
	GetBox() Box
}

Object is any obscreen object. Each object must be linked to a box, even if it is that box.

type Side added in v0.7.0 

type Side int

Side represents one side of a rectangle. 

const (
	SideTop Side = iota
	SideRight
	SideBottom
	SideLeft
)

type TextBox 

type TextBox interface {
	ContentBox

	// SetText sets the text content of the Box.
	SetText(string)
	// SetTextColor sets the text color.
	SetTextColor(color.Color)
	// SetFace sets the font face text is rendered in.
	SetFace(font.Face)
	// SetWrap sets whether or not the text wraps.
	SetWrap(bool)

	// SetSelectable sets whether or not the text content can be
	// highlighted/selected.
	SetSelectable(bool)
	// SetDotColor sets the highlight color of selected text.
	SetDotColor(color.Color)
	// Select sets the text cursor or selection.
	Select(text.Dot)
	// Dot returns the text cursor or selection.
	Dot() text.Dot
	// OnDotChange specifies a function to be called when the text cursor or
	// selection changes.
	OnDotChange(func()) event.Cookie
}

TextBox is a box that contains text content.

func NewTextBox 

func NewTextBox() TextBox

NewTextBox creates and returns a Box that can display text.

type Window 

type Window interface {
	// SetRoot sets the root child of the window. There can only be one at
	// a time, and setting it will remove the current child if there is one.
	SetRoot(Object)
	// SetTitle sets the title of the window.
	SetTitle(string)
	// SetIcon sets the icon of the window. When multiple icon sizes are
	// provided, the best fitting one is chosen for display.
	SetIcon(...image.Image)
	// Widget returns a window representing a smaller iconified form of this
	// window. How exactly this window is used depends on the platform.
	// Subsequent calls to this method on the same window will return the
	// same window object.
	Widget() (Window, error)
	// NewMenu creates a new menu window. This window is undecorated and
	// will close once the user clicks outside of it.
	NewMenu(image.Rectangle) (Window, error)
	// NewModal creates a new modal window that blocks all input to this
	// window until it is closed.
	NewModal(image.Rectangle) (Window, error)
	// Copy copies data to the clipboard.
	Copy(data.Data)
	// Paste reads data from the clipboard. When the data is available or an
	// error has occurred, the provided function will be called.
	Paste(callback func(data.Data, error), accept ...data.Mime)
	// Show shows the window.
	Show()
	// Hide hides the window.
	Hide()
	// Close closes the window.
	Close()
	// OnClose specifies a function to be called when the window is closed.
	OnClose(func()) event.Cookie
}

Window is an operating system window. It can contain one object.

Source Files

View all Source files

Directories

Path Synopsis
Canvas defines a standard interface for images that support drawing primitives.
 Canvas defines a standard interface for images that support drawing primitives.
Package data provides operations to deal with arbitrary data and MIME types.
 Package data provides operations to deal with arbitrary data and MIME types.
Package event provides a system for broadcasting events to multiple event handlers.
 Package event provides a system for broadcasting events to multiple event handlers.
Package input defines keyboard and mouse code constants.
 Package input defines keyboard and mouse code constants.

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.