tomo

README

tomo

Tomo is a lightweight GUI toolkit written in pure Go. This repository defines the API that other components of the toolkit agree on. In order to use Tomo in an application, use Nasin, which builds an application framework on top of Tomo.

Documentation

Index

• func Apply(object Object) event.Cookie
• func Do(callback func())
• func MimeIcon(mime data.Mime, size IconSize) canvas.Texture
• func NewCanvas(bounds image.Rectangle) canvas.CanvasCloser
• func NewTexture(source image.Image) canvas.TextureCloser
• func Register(priority int, factory Factory)
• func Run(callback func()) error
• func SetTheme(them Theme)
• func Stop()
• type Align
• type Backend
• type Border
• type Box
  • func NewBox() Box
• type CanvasBox
  • func NewCanvasBox() CanvasBox
• type Color
  • func (id Color) RGBA() (r, g, b, a uint32)
  • func (c Color) String() string
• type ContainerBox
  • func NewContainerBox() ContainerBox
• type ContentBox
• type ContentObject
• type Factory
• type Icon
  • func (id Icon) Texture(size IconSize) canvas.Texture
• type IconSize
  • func (size IconSize) String() string
• type Inset
  • func I(sides ...int) Inset
  • func (inset Inset) Apply(bigger image.Rectangle) (smaller image.Rectangle)
  • func (inset Inset) Horizontal() int
  • func (inset Inset) Inverse() (prime Inset)
  • func (inset Inset) Vertical() int
• type Layout
• type LayoutHints
• type MainWindow
  • func NewPlainWindow(bounds image.Rectangle) (MainWindow, error)
  • func NewWindow(bounds image.Rectangle) (MainWindow, error)
• type Object
• type Role
  • func R(pack, object, variant string) Role
  • func (r Role) String() string
• type Side
• type SurfaceBox
• type TextBox
  • func NewTextBox() TextBox
• type Theme
• type Window

Functions

func Apply

func Apply(object Object) event.Cookie

Apply applies the current theme to the given object, according its role. This may register event listeners with the given object; closing the returned cookie will remove them.

func Do

func Do(callback func())

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

func MimeIcon

func MimeIcon(mime data.Mime, size IconSize) canvas.Texture

MimeIcon returns an icon corresponding to a MIME type.

func NewCanvas

func NewCanvas(bounds image.Rectangle) canvas.CanvasCloser

NewCanvas creates a new canvas with the specified bounds. When no longer in use, it must be freed using Close().

func NewTexture

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 SetTheme

func SetTheme(them Theme)

SetTheme sets the theme.

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 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
	NewSurfaceBox() (SurfaceBox, error)
	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

	// NewCanvas creates a new canvas with the specified bounds. The backend
	// must reject any canvas that was not made by it.
	NewCanvas(image.Rectangle) canvas.CanvasCloser

	// 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.

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
	// Role returns this Box's role as set by SetRole.
	Role() Role
	// 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)
	// SetTextureTile sets a repeating background texture. If the texture is
	// transparent, it will be overlayed atop the color specified by
	// SetColor(). This will remove any previous texture set by this method
	// or another method.
	SetTextureTile(canvas.Texture)
	// SetTextureCenter sets a centered background texture. If the texture
	// is transparent, it will be overlayed atop the color specified by
	// SetColor(). This will remove any previous texture set by this method
	// or another method.
	SetTextureCenter(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)
	// SetRole sets what role this Box takes on. It is used to apply styling
	// from a theme.
	SetRole(Role)

	// 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. Implementations of Box, as well as any interface that embed Box, may only originate from a Backend.

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. The Canvas passed to the drawer will
	// have these properties:
	//   - It will have the same origin (0, 0) as the window which contains
	//     the CanvasBox
	//   - The Canvas bounds will describe the portion of the CanvasBox
	//     visible on screen
	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 Color

type Color int

Color represents a color ID.

const (
	ColorBackground Color = iota
	ColorForeground
	ColorRaised
	ColorSunken
	ColorAccent
)

func (Color) RGBA

func (id Color) RGBA() (r, g, b, a uint32)

RGBA satisfies the color.Color interface.

func (Color) String

func (c Color) String() string

String satisfies the fmt.Stringer interface.

type ContainerBox

type ContainerBox interface {
	ContentBox

	// SetGap sets the gap between child Objects.
	SetGap(image.Point)
	// Add appends a child Object. If the object is already a child of
	// another object, it will be removed from that object first.
	Add(Object)
	// Remove removes a child Object, if it is a child of this Box.
	Remove(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

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 Box's InnerBounds.
	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 a box that has some kind of content.

type ContentObject

type ContentObject interface {
	Object

	// ContentBounds returns the bounds of the inner content of the Box
	// relative to the Box's InnerBounds.
	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
}

ContentObject is an object that has some kind of content.

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 Icon

type Icon string

Icon represents an icon ID.

const (
	IconUnknown Icon = ""

	// actions
	IconAddressBookNew  Icon = "AddressBookNew"
	IconApplicationExit Icon = "ApplicationExit"
	IconAppointmentNew  Icon = "AppointmentNew"
	IconCallStart       Icon = "CallStart"
	IconCallStop        Icon = "CallStop"
	IconContactNew      Icon = "ContactNew"
	// actions: dialog
	IconDialogOkay   Icon = "DialogOkay"
	IconDialogCancel Icon = "DialogCancel"
	// actions: edit
	IconEditClear       Icon = "EditClear"
	IconEditCopy        Icon = "EditCopy"
	IconEditCut         Icon = "EditCut"
	IconEditDelete      Icon = "EditDelete"
	IconEditFind        Icon = "EditFind"
	IconEditFindReplace Icon = "EditFindReplace"
	IconEditPaste       Icon = "EditPaste"
	IconEditRedo        Icon = "EditRedo"
	IconEditSelectAll   Icon = "EditSelectAll"
	IconEditUndo        Icon = "EditUndo"
	// actions: file
	IconFileNew          Icon = "FileNew"
	IconDirectoryNew     Icon = "DirectoryNew"
	IconFileOpen         Icon = "FileOpen"
	IconFileOpenRecent   Icon = "FileOpenRecent"
	IconFilePageSetup    Icon = "FilePageSetup"
	IconFilePrint        Icon = "FilePrint"
	IconFilePrintPreview Icon = "FilePrintPreview"
	IconFilePermissions  Icon = "FilePermissions"
	IconFileProperties   Icon = "FileProperties"
	IconFileRename       Icon = "FileRename"
	IconFileRevert       Icon = "FileRevert"
	IconFileSave         Icon = "FileSave"
	IconFileSaveAs       Icon = "FileSaveAs"
	IconFileSend         Icon = "FileSend"
	// actions: format
	IconFormatIndentLess        Icon = "FormatIndentLess"
	IconFormatIndentMore        Icon = "FormatIndentMore"
	IconFormatAlignCenter       Icon = "FormatAlignCenter"
	IconFormatAlignEven         Icon = "FormatAlignEven"
	IconFormatAlignLeft         Icon = "FormatAlignLeft"
	IconFormatAlignRight        Icon = "FormatAlignRight"
	IconFormatTextDirectionLtr  Icon = "FormatTextDirectionLtr"
	IconFormatTextDirectionRtl  Icon = "FormatTextDirectionRtl"
	IconFormatTextBold          Icon = "FormatTextBold"
	IconFormatTextItalic        Icon = "FormatTextItalic"
	IconFormatTextUnderline     Icon = "FormatTextUnderline"
	IconFormatTextStrikethrough Icon = "FormatTextStrikethrough"
	// actions: go
	IconGoBottom   Icon = "GoBottom"
	IconGoDown     Icon = "GoDown"
	IconGoFirst    Icon = "GoFirst"
	IconGoHome     Icon = "GoHome"
	IconGoJump     Icon = "GoJump"
	IconGoLast     Icon = "GoLast"
	IconGoNext     Icon = "GoNext"
	IconGoPrevious Icon = "GoPrevious"
	IconGoTop      Icon = "GoTop"
	IconGoUp       Icon = "GoUp"
	// actions: help
	IconHelpAbout    Icon = "HelpAbout"
	IconHelpContents Icon = "HelpContents"
	IconHelpFaq      Icon = "HelpFaq"
	// actions: insert
	IconInsertImage  Icon = "InsertImage"
	IconInsertLink   Icon = "InsertLink"
	IconInsertObject Icon = "InsertObject"
	IconInsertText   Icon = "InsertText"
	// actions: list
	IconListAdd    Icon = "ListAdd"
	IconListRemove Icon = "ListRemove"
	// actions: mail
	IconMailForward       Icon = "MailForward"
	IconMailMarkImportant Icon = "MailMarkImportant"
	IconMailMarkJunk      Icon = "MailMarkJunk"
	IconMailMarkNotJunk   Icon = "MailMarkNotJunk"
	IconMailMarkRead      Icon = "MailMarkRead"
	IconMailMarkUnread    Icon = "MailMarkUnread"
	IconMailMessageNew    Icon = "MailMessageNew"
	IconMailReplyAll      Icon = "MailReplyAll"
	IconMailReplySender   Icon = "MailReplySender"
	IconMailSend          Icon = "MailSend"
	IconMailReceive       Icon = "MailReceive"
	// actions: media
	IconMediaEject         Icon = "MediaEject"
	IconMediaPlaybackPause Icon = "MediaPlaybackPause"
	IconMediaPlaybackStart Icon = "MediaPlaybackStart"
	IconMediaPlaybackStop  Icon = "MediaPlaybackStop"
	IconMediaRecord        Icon = "MediaRecord"
	IconMediaSeekBackward  Icon = "MediaSeekBackward"
	IconMediaSeekForward   Icon = "MediaSeekForward"
	IconMediaSkipBackward  Icon = "MediaSkipBackward"
	IconMediaSkipForward   Icon = "MediaSkipForward"
	// actions: object
	IconObjectFlipHorizontal Icon = "ObjectFlipHorizontal"
	IconObjectFlipVertical   Icon = "ObjectFlipVertical"
	IconObjectRotateLeft     Icon = "ObjectRotateLeft"
	IconObjectRotateRight    Icon = "ObjectRotateRight"
	// actions: process
	IconProcessStop Icon = "ProcessStop"
	// actions: system
	IconSystemLockScreen Icon = "SystemLockScreen"
	IconSystemLogOut     Icon = "SystemLogOut"
	IconSystemRun        Icon = "SystemRun"
	IconSystemSearch     Icon = "SystemSearch"
	IconSystemReboot     Icon = "SystemReboot"
	IconSystemShutdown   Icon = "SystemShutdown"
	// actions: tools
	IconToolsCheckSpelling Icon = "ToolsCheckSpelling"
	// actions: value
	IconValueIncrement Icon = "ValueIncrement"
	IconValueDecrement Icon = "ValueDecrement"
	IconValueReset     Icon = "ValueReset"
	// actions: view
	IconViewFullscreen     Icon = "ViewFullscreen"
	IconViewRefresh        Icon = "ViewRefresh"
	IconViewRestore        Icon = "ViewRestore"
	IconViewSortAscending  Icon = "ViewSortAscending"
	IconViewSortDescending Icon = "ViewSortDescending"
	// actions: window
	IconWindowClose Icon = "WindowClose"
	IconWindowNew   Icon = "WindowNew"
	// actions: zoom
	IconZoomFitBest  Icon = "ZoomFitBest"
	IconZoomIn       Icon = "ZoomIn"
	IconZoomOriginal Icon = "ZoomOriginal"
	IconZoomOut      Icon = "ZoomOut"

	// applications
	// Keep these in sync with nasin.ApplicationRole!
	IconApplication                  Icon = "Application" // generic
	IconApplicationWebBrowser        Icon = "ApplicationWebBrowser"
	IconApplicationMesssanger        Icon = "ApplicationMesssanger"
	IconApplicationPhone             Icon = "ApplicationPhone"
	IconApplicationMail              Icon = "ApplicationMail"
	IconApplicationTerminalEmulator  Icon = "ApplicationTerminalEmulator"
	IconApplicationFileBrowser       Icon = "ApplicationFileBrowser"
	IconApplicationTextEditor        Icon = "ApplicationTextEditor"
	IconApplicationDocumentViewer    Icon = "ApplicationDocumentViewer"
	IconApplicationWordProcessor     Icon = "ApplicationWordProcessor"
	IconApplicationSpreadsheet       Icon = "ApplicationSpreadsheet"
	IconApplicationSlideshow         Icon = "ApplicationSlideshow"
	IconApplicationCalculator        Icon = "ApplicationCalculator"
	IconApplicationPreferences       Icon = "ApplicationPreferences"
	IconApplicationProcessManager    Icon = "ApplicationProcessManager"
	IconApplicationSystemInformation Icon = "ApplicationSystemInformation"
	IconApplicationManual            Icon = "ApplicationManual"
	IconApplicationCamera            Icon = "ApplicationCamera"
	IconApplicationImageViewer       Icon = "ApplicationImageViewer"
	IconApplicationMediaPlayer       Icon = "ApplicationMediaPlayer"
	IconApplicationImageEditor       Icon = "ApplicationImageEditor"
	IconApplicationAudioEditor       Icon = "ApplicationAudioEditor"
	IconApplicationVideoEditor       Icon = "ApplicationVideoEditor"
	IconApplicationClock             Icon = "ApplicationClock"
	IconApplicationCalendar          Icon = "ApplicationCalendar"
	IconApplicationChecklist         Icon = "ApplicationChecklist"

	// categories: applications
	IconApplications            Icon = "Applications"
	IconApplicationsAccessories Icon = "ApplicationsAccessories"
	IconApplicationsDevelopment Icon = "ApplicationsDevelopment"
	IconApplicationsEngineering Icon = "ApplicationsEngineering"
	IconApplicationsGames       Icon = "ApplicationsGames"
	IconApplicationsGraphics    Icon = "ApplicationsGraphics"
	IconApplicationsInternet    Icon = "ApplicationsInternet"
	IconApplicationsMultimedia  Icon = "ApplicationsMultimedia"
	IconApplicationsOffice      Icon = "ApplicationsOffice"
	IconApplicationsScience     Icon = "ApplicationsScience"
	IconApplicationsSystem      Icon = "ApplicationsSystem"
	IconApplicationsUtilities   Icon = "ApplicationsUtilities"
	// categories: preferences
	IconPreferences            Icon = "Preferences"
	IconPreferencesDesktop     Icon = "PreferencesDesktop"
	IconPreferencesPeripherals Icon = "PreferencesPeripherals"
	IconPreferencesPersonal    Icon = "PreferencesPersonal"
	IconPreferencesSystem      Icon = "PreferencesSystem"
	IconPreferencesNetwork     Icon = "PreferencesNetwork"

	// devices
	IconDevice                 Icon = "Device"
	IconDeviceCamera           Icon = "DeviceCamera"
	IconDeviceWebCamera        Icon = "DeviceWebCamera"
	IconDeviceComputer         Icon = "DeviceComputer"
	IconDevicePda              Icon = "DevicePda"
	IconDevicePhone            Icon = "DevicePhone"
	IconDevicePrinter          Icon = "DevicePrinter"
	IconDeviceScanner          Icon = "DeviceScanner"
	IconDeviceMultimediaPlayer Icon = "DeviceMultimediaPlayer"
	IconDeviceVideoDisplay     Icon = "DeviceVideoDisplay"
	IconDeviceAudioInput       Icon = "DeviceAudioInput"
	IconDeviceAudioOutput      Icon = "DeviceAudioOutput"
	// devices: hardware
	IconHardware               Icon = "Hardware"
	IconHardwareCPU            Icon = "HardwareCPU"
	IconHardwareGPU            Icon = "HardwareGPU"
	IconHardwareRAM            Icon = "HardwareRAM"
	IconHardwareSoundCard      Icon = "HardwareSoundCard"
	IconHardwareNetworkAdapter Icon = "HardwareNetworkAdapter"
	// devices: power
	IconPowerBattery Icon = "PowerBattery"
	// devices: storage
	IconStorageHardDisk     Icon = "StorageHardDisk"
	IconStorageFloppyDisk   Icon = "StorageFloppyDisk"
	IconStorageSolidState   Icon = "StorageSolidState"
	IconStorageOptical      Icon = "StorageOptical"
	IconStorageFlashStick   Icon = "StorageFlashStick"
	IconStorageFlashCard    Icon = "StorageFlashCard"
	IconStorageMagneticTape Icon = "StorageMagneticTape"
	// devices: input
	IconInputGaming   Icon = "InputGaming"
	IconInputKeyboard Icon = "InputKeyboard"
	IconInputMouse    Icon = "InputMouse"
	IconInputTablet   Icon = "InputTablet"
	// devices: network
	IconNetworkWired     Icon = "NetworkWired"
	IconNetworkWireless  Icon = "NetworkWireless"
	IconNetworkCellular  Icon = "NetworkCellular"
	IconNetworkLocal     Icon = "NetworkLocal"
	IconNetworkInternet  Icon = "NetworkInternet"
	IconNetworkVPN       Icon = "NetworkVPN"
	IconNetworkServer    Icon = "NetworkServer"
	IconNetworkWorkgroup Icon = "NetworkWorkgroup"

	// emblems
	IconEmblemDefault      Icon = "EmblemDefault"
	IconEmblemEncrypted    Icon = "EmblemEncrypted"
	IconEmblemFavorite     Icon = "EmblemFavorite"
	IconEmblemImportant    Icon = "EmblemImportant"
	IconEmblemReadOnly     Icon = "EmblemReadOnly"
	IconEmblemShared       Icon = "EmblemShared"
	IconEmblemSymbolicLink Icon = "EmblemSymbolicLink"
	IconEmblemSynchronized Icon = "EmblemSynchronized"
	IconEmblemSystem       Icon = "EmblemSystem"
	IconEmblemUnreadable   Icon = "EmblemUnreadable"

	// places
	IconPlaceDirectory    Icon = "PlaceDirectory"
	IconPlaceRemote       Icon = "PlaceRemote"
	IconPlaceHome         Icon = "PlaceHome"
	IconPlaceDownloads    Icon = "PlaceDownloads"
	IconPlaceDesktop      Icon = "PlaceDesktop"
	IconPlacePhotos       Icon = "PlacePhotos"
	IconPlaceBooks        Icon = "PlaceBooks"
	IconPlaceBookmarks    Icon = "PlaceBookmarks"
	IconPlaceTrash        Icon = "PlaceTrash"
	IconPlaceDocuments    Icon = "PlaceDocuments"
	IconPlaceRepositories Icon = "PlaceRepositories"
	IconPlaceMusic        Icon = "PlaceMusic"
	IconPlaceArchives     Icon = "PlaceArchives"
	IconPlaceFonts        Icon = "PlaceFonts"
	IconPlaceBinaries     Icon = "PlaceBinaries"
	IconPlaceVideos       Icon = "PlaceVideos"
	IconPlace3DObjects    Icon = "Place3DObjects"
	IconPlaceHistory      Icon = "PlaceHistory"
	IconPlacePreferences  Icon = "PlacePreferences"

	// status: checkbox
	IconCheckboxChecked   Icon = "CheckboxChecked"
	IconCheckboxUnchecked Icon = "CheckboxUnchecked"
	// status: appointments
	IconAppointmentMissed Icon = "AppointmentMissed"
	IconAppointmentSoon   Icon = "AppointmentSoon"
	// status: dialogs
	IconDialogError       Icon = "DialogError"
	IconDialogInformation Icon = "DialogInformation"
	IconDialogPassword    Icon = "DialogPassword"
	IconDialogQuestion    Icon = "DialogQuestion"
	IconDialogWarning     Icon = "DialogWarning"
	// status: directories
	IconDirectoryDragAccept Icon = "DirectoryDragAccept"
	IconDirectoryFull       Icon = "DirectoryFull"
	IconDirectoryOpen       Icon = "DirectoryOpen"
	IconDirectoryVisiting   Icon = "DirectoryVisiting"
	// status: trash
	IconTrashFull Icon = "TrashFull"
	// status: resource
	IconResourceLoading Icon = "ResourceLoading"
	IconResourceMissing Icon = "ResourceMissing"
	// status: mail
	IconMailAttachment     Icon = "MailAttachment"
	IconMailUnread         Icon = "MailUnread"
	IconMailReplied        Icon = "MailReplied"
	IconMailSigned         Icon = "MailSigned"
	IconMailSignedVerified Icon = "MailSignedVerified"
	// status: network
	IconCellularSignal0        Icon = "CellularSignal0"
	IconCellularSignal1        Icon = "CellularSignal1"
	IconCellularSignal2        Icon = "CellularSignal2"
	IconCellularSignal3        Icon = "CellularSignal3"
	IconWirelessSignal0        Icon = "WirelessSignal0"
	IconWirelessSignal1        Icon = "WirelessSignal1"
	IconWirelessSignal2        Icon = "WirelessSignal2"
	IconWirelessSignal3        Icon = "WirelessSignal3"
	IconNetworkError           Icon = "NetworkError"
	IconNetworkIdle            Icon = "NetworkIdle"
	IconNetworkOffline         Icon = "NetworkOffline"
	IconNetworkReceive         Icon = "NetworkReceive"
	IconNetworkTransmit        Icon = "NetworkTransmit"
	IconNetworkTransmitReceive Icon = "NetworkTransmitReceive"
	// status: print
	IconPrintError    Icon = "PrintError"
	IconPrintPrinting Icon = "PrintPrinting"
	// status: security
	IconSecurityHigh   Icon = "SecurityHigh"
	IconSecurityMedium Icon = "SecurityMedium"
	IconSecurityLow    Icon = "SecurityLow"
	// status: software
	IconSoftwareUpdateAvailable Icon = "SoftwareUpdateAvailable"
	IconSoftwareUpdateUrgent    Icon = "SoftwareUpdateUrgent"
	IconSoftwareInstalling      Icon = "SoftwareInstalling"
	// status: sync
	IconSyncError         Icon = "SyncError"
	IconSyncSynchronizing Icon = "SyncSynchronizing"
	// status: tasks
	IconTaskDue     Icon = "TaskDue"
	IconTaskPastDue Icon = "TaskPastDue"
	// status: users
	IconUserAvailable Icon = "UserAvailable"
	IconUserAway      Icon = "UserAway"
	IconUserIdle      Icon = "UserIdle"
	IconUserOffline   Icon = "UserOffline"
	// status: power
	IconBattery0    Icon = "Battery0"
	IconBattery1    Icon = "Battery1"
	IconBattery2    Icon = "Battery2"
	IconBattery3    Icon = "Battery3"
	IconBrightness0 Icon = "Brightness0"
	IconBrightness1 Icon = "Brightness1"
	IconBrightness2 Icon = "Brightness2"
	IconBrightness3 Icon = "Brightness3"
	// status: media
	IconVolume0         Icon = "Volume0"
	IconVolume1         Icon = "Volume1"
	IconVolume2         Icon = "Volume2"
	IconVolume3         Icon = "Volume3"
	IconPlaylistRepeat  Icon = "PlaylistRepeat"
	IconPlaylistShuffle Icon = "PlaylistShuffle"
	// status: weather
	IconWeatherClear            Icon = "WeatherClear"
	IconWeatherClearNight       Icon = "WeatherClearNight"
	IconWeatherFewClouds        Icon = "WeatherFewClouds"
	IconWeatherFewCloudsNight   Icon = "WeatherFewCloudsNight"
	IconWeatherFog              Icon = "WeatherFog"
	IconWeatherOvercast         Icon = "WeatherOvercast"
	IconWeatherSevereAlert      Icon = "WeatherSevereAlert"
	IconWeatherShowers          Icon = "WeatherShowers"
	IconWeatherShowersScattered Icon = "WeatherShowersScattered"
	IconWeatherSnow             Icon = "WeatherSnow"
	IconWeatherStorm            Icon = "WeatherStorm"
)

A list of standard icon IDs. This is roughly based off of the XDG Icon Naming Specification (https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html).

func (Icon) Texture

func (id Icon) Texture(size IconSize) canvas.Texture

Texture returns a texture of the corresponding icon ID.

type IconSize

type IconSize int

IconSize represents the size of an icon.

const (
	IconSizeSmall IconSize = iota
	IconSizeMedium
	IconSizeLarge
)

func (IconSize) String

func (size IconSize) String() string

String satisfies the fmt.Stringer interface.

type Inset

type Inset [4]int

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

func I

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

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

func (inset Inset) Horizontal() int

Horizontal returns the sum of SideRight and SideLeft.

func (Inset) Inverse

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

Inverse returns a negated version of the inset.

func (Inset) Vertical

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

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 whether 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 NewPlainWindow

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 onscreen object that is linked to a box (or is that box). Unlike the Box interface and associated interfaces, Object implementations may originate from anywhere.

type Role

type Role struct {
	// Package is an optional namespace field. If specified, it should be
	// the package name or module name the object is from.
	Package string

	// Object specifies what type of object it is. For example:
	//   - TextInput
	//   - Table
	//   - Label
	//   - Dial
	// This should correspond directly to the type name of the object.
	Object string

	// Variant is an optional field to be used when an object has one or
	// more soft variants under one type. For example, an object "Slider"
	// may have variations "horizontal" and "vertical".
	Variant string
}

Role describes the role of an object.

func R

func R(pack, object, variant string) Role

R is shorthand for creating a Role structure.

func (Role) String

func (r Role) String() string

String satisfies the fmt.Stringer interface. It follows the format of: Package.Object[Variant]

type Side

type Side int

Side represents one side of a rectangle.

const (
	SideTop Side = iota
	SideRight
	SideBottom
	SideLeft
)

type SurfaceBox

type SurfaceBox interface {
	Box

	// Surface returns the underlying graphics context. The result must be
	// asserted to the expected type or passed through a type switch before
	// use. The exact type returned here depends on the backend being used,
	// and it is up to the application author to ensure that the application
	// and backend agree on it. Applications should fail gracefully if the
	// expected type was not found.
	Surface() any

	// Invalidate causes the data within the surface to be pushed to the
	// screen at the end of the event cycle, even if it wouldn't be
	// otherwise.
	Invalidate()

	// OnSizeChange specifies a function to be called when the size of the
	// Box is changed, or the surface is re-allocated. The application must
	// call Surface() each time this event fires in order to not draw to a
	// closed surface.
	OnSizeChange(func())
}

SurfaceBox is a box that can be drawn to via a hardware accelerated (or platform-specific) graphics context.

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 Theme

type Theme interface {

	// Apply applies the theme to the given object, according to its role.
	// This may register event listeners with the given object; closing the
	// returned cookie must remove them.
	Apply(Object) event.Cookie

	// RGBA returns the RGBA values of the corresponding color ID.
	RGBA(Color) (r, g, b, a uint32)

	// Icon returns a texture of the corresponding icon ID. If there is no
	// suitable option, it should return nil.
	Icon(Icon, IconSize) canvas.Texture

	// MimeIcon returns a texture of an icon corresponding to a MIME type.
	// If there is no suitable specific option, it should return a more
	// generic icon or a plain file icon.
	MimeIcon(data.Mime, IconSize) canvas.Texture
}

Theme can apply a visual style to different objects.

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)
	// SetVisible sets whether or not this window is visible. Windows are
	// invisible by default.
	SetVisible(bool)
	// Visible returns whether or not this window is visible.
	Visible() bool
	// 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.