Instruct themes to return nil icons if the icon doesn't exist

It was a bad idea. Remedy #12.

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 8
+charset = utf-8
+
+[*.md]
+indent_style = space
+indent_size = 2

README.md

@@ -1,6 +1,8 @@
 # tomo
 
-WIP rewrite of tomo.
+[![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/tomo/tomo.svg)](https://pkg.go.dev/git.tebibyte.media/tomo/tomo)
 
-This module will serve as a wafer-thin collection of interfaces and glue code so
-that plugins will be an actual viable concept.
+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](https://git.tebibyte.media/tomo/nasin), which builds
+an application framework on top of Tomo.

backend.go

@@ -3,6 +3,7 @@ package tomo
 import "sort"
 import "image"
 import "errors"
+import "git.tebibyte.media/tomo/tomo/canvas"
 
 // Backend is any Tomo implementation. Backends handle window creation, layout,
 // rendering, and events so that there can be as many platform-specific
@@ -10,12 +11,24 @@ import "errors"
 type Backend interface {
 	// These methods create new objects. The backend must reject any object
 	// that was not made by it.
-	NewWindow       (image.Rectangle) (MainWindow, error)
 	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
+
 	// Run runs the event loop until Stop() is called, or the backend
 	// experiences a fatal error.
 	Run () error
@@ -47,11 +60,11 @@ func Register (priority int, factory Factory) {
 	})
 }
 
-// Initialize instantiates a backend. The first backend (sorted by priority)
+// 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.
-func Initialize () (Backend, error) {
+func initialize () (Backend, error) {
 	backend, err := instantiate()
 	if err != nil { return nil, err }
 	return backend, err

canvas/canvas.go

@@ -8,9 +8,9 @@ import "image/color"
 
 // Cap represents a stroke cap type.
 type Cap int; const (
-	CapButt Cap = iota // Square cap that ends at the point
-	CapRound           // Round cap that surrounds the point
-	CapSquare          // square cap that surrounds the point
+	CapRound Cap = iota // Round cap that surrounds the point
+	CapSquare           // Square cap that surrounds the point
+	CapButt             // Square cap that ends at the point
 )
 
 // Joint represents a stroke joint type.
@@ -30,22 +30,38 @@ type StrokeAlign int; const (
 
 // Pen represents a drawing context that is linked to a canvas. Each canvas can
 // have multiple pens associated with it, each maintaining their own drawing
-// context.
+// state.
 type Pen interface {
-	// Rectangle draws a rectangle
+	// Rectangle draws a rectangle.
 	Rectangle (image.Rectangle)
 
-	// Path draws a path
+	// Path draws a path, which is a series of connected points.
 	Path (points ...image.Point)
 
-	Closed       (bool)        // if the path is closed
-	Cap          (Cap)         // line cap stype
-	Joint        (Joint)       // line joint style
-	StrokeWeight (int)         // how thick the stroke is
-	StrokeAlign  (StrokeAlign) // where the stroke is drawn
+	// StrokeWeight sets how thick the stroke is. The default value is zero.
+	StrokeWeight (int)
+	// SetClosed sets whether the path is a closed shape, or has an open
+	// side. This only applies if the stroke weight is greater than zero.
+	Closed (bool)
+	// Cap sets how the ends of the stroke look. This only applies if the
+	// stroke weight is greater than zero, and if the path is not closed.
+	// The default value is CapRound.
+	Cap (Cap)
+	// Joint sets how bend points in the stroke look. This only applies if
+	// the stroke weight is greater than zero. The default value is
+	// JointRound.
+	Joint (Joint)
+	// StrokeAlign sets where the stroke is drawn in relation to the path.
+	// This only applies if the stroke weight is greater than zero. The
+	// default value is StrokeAlignCenter.
+	StrokeAlign (StrokeAlign)
 
-	Stroke (color.Color) // Sets the stroke to a solid color
-	Fill   (color.Color) // Sets the fill to a solid color
+	// Stroke sets the stroke to a solid color.
+	Stroke (color.Color)
+	// Fill sets the fill to a solid color.
+	Fill (color.Color)
+	// Texture overlaps a texture onto the fill color.
+	Texture (Texture)
 }
 
 // Canvas is an image that supports drawing paths.
@@ -55,11 +71,13 @@ type Canvas interface {
 	// Pen returns a new pen for this canvas.
 	Pen () Pen
 
-	// Clip returns a new canvas that points to a specific area of this one.
-	Clip (image.Rectangle) Canvas
+	// SubCanvas returns a returns a Canvas representing the portion of this
+	// Canvas visible and drawable through a rectangle. The returned value
+	// shares pixels with the original Canvas.
+	SubCanvas (image.Rectangle) Canvas
 }
 
-// Drawer is an object that can draw to a canvas.
+// Drawer can draw to a canvas.
 type Drawer interface {
 	// Draw draws to the given canvas.
 	Draw (Canvas)

canvas/texture.go

@@ -0,0 +1,21 @@
+package canvas
+
+import "io"
+import "image"
+
+// Texture is a handle that points to a 2D raster image managed by the backend.
+type Texture interface {
+	image.Image
+
+	// SubTexture returns a returns a Texture representing the portion of
+	// this Texture visible through a rectangle. The returned value shares
+	// pixels with the original Texture.
+	SubTexture (image.Rectangle) Texture
+}
+
+// TextureCloser is a texture that can be closed. Anything that receives a
+// TextureCloser must close it after use.
+type TextureCloser interface {
+	Texture
+	io.Closer
+}

icon.go

@@ -0,0 +1,393 @@
+package tomo
+
+import "git.tebibyte.media/tomo/tomo/data"
+import "git.tebibyte.media/tomo/tomo/canvas"
+
+// IconSize represents the size of an icon.
+type IconSize int; const (
+	IconSizeSmall IconSize = iota;
+	IconSizeMedium
+	IconSizeLarge
+)
+
+// String satisfies the fmt.Stringer interface.
+func (size IconSize) String () string {
+	switch size {
+	case IconSizeSmall:  return "small"
+	case IconSizeMedium: return "medium"
+	case IconSizeLarge:  return "large"
+	default:             return "unknown"
+	}
+}
+
+// Icon represents an icon ID.
+type Icon string
+
+// 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).
+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"
+)
+
+// Texture returns a texture of the corresponding icon ID.
+func (id Icon) Texture (size IconSize) canvas.Texture {
+	if theme == nil { return nil }
+	return theme.Icon(id, size)
+}
+
+// MimeIcon returns an icon corresponding to a MIME type.
+func MimeIcon (mime data.Mime, size IconSize) canvas.Texture {
+	if theme == nil { return nil }
+	return theme.MimeIcon(mime, size)
+}

object.go

@@ -101,13 +101,30 @@ type Align int; const (
 	AlignEven               // similar to justified text
 )
 
-// Object is any obscreen object. Each object must be linked to a box, even if
-// it is that 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 Object interface {
 	GetBox () Box
 }
 
-// Box is a basic styled box.
+// ContentObject is an object that has some kind of content.
+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
+}
+
+// Box is a basic styled box. Implementations of Box, as well as any interface
+// that embed Box, may only originate from a Backend.
 type Box interface {
 	Object
 
@@ -132,6 +149,16 @@ type Box interface {
 	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)
@@ -191,7 +218,12 @@ type CanvasBox interface {
 	Box
 
 	// SetDrawer sets the Drawer that will be called upon to draw the Box's
-	// content when it is invalidated.
+	// 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
@@ -199,8 +231,25 @@ type CanvasBox interface {
 	Invalidate ()
 }
 
-// ContentBox is an abstract box that has some kind of content. Its only purpose
-// is to be embedded into TextBox and ContainerBox.
+// SurfaceBox is a box that can be drawn to via a hardware accelerated (or
+// platform-specific) graphics context.
+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 Box's area to be redrawn at the end of the
+	// event cycle, even if it wouldn't be otherwise.
+	Invalidate ()
+}
+
+// ContentBox is a box that has some kind of content.
 type ContentBox interface {
 	Box
 
@@ -212,7 +261,7 @@ type ContentBox interface {
 	// vertically.
 	SetAlign (x, y Align)
 	// ContentBounds returns the bounds of the inner content of the Box
-	// relative to the window.
+	// 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.
@@ -254,30 +303,35 @@ type TextBox interface {
 type ContainerBox interface {
 	ContentBox
 
-	// SetPropagateEvents specifies whether or not child Objects will
-	// receive user input events. It is true by default. If it is false, all
-	// user input that would otherwise be directed to a child Box is
-	// directed to this Box.
-	SetPropagateEvents (bool)
 	// SetGap sets the gap between child Objects.
 	SetGap (image.Point)
-	// Add appends a child Object.
+	// 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)
-	// Delete removes a child Object, if it is a child of this Box.
-	Delete             (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 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)
 }
 
 // LayoutHints are passed to a layout to tell it how to arrange child boxes.
@@ -285,7 +339,7 @@ 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
+	// OverflowX and OverflowY control whether child Boxes may be positioned
 	// outside of Bounds.
 	OverflowX bool
 	OverflowY bool
@@ -333,10 +387,11 @@ type Window interface {
 	// 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     ()
+	// 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.

plugin.go

@@ -1,55 +0,0 @@
-package tomo
-
-import "os"
-import "plugin"
-import "path/filepath"
-
-var pluginPaths []string
-
-func loadPlugins () {
-	for _, dir := range pluginPaths {
-		if dir != "" {
-			loadPluginsFrom(dir)
-		}
-	}
-}
-
-func loadPluginsFrom (dir string) {
-	entries, err := os.ReadDir(dir)
-	// its no big deal if one of the dirs doesn't exist
-	if err != nil { return }
-
-	for _, entry := range entries {
-		if entry.IsDir() { continue }
-		if filepath.Ext(entry.Name()) != ".so" { continue }
-		pluginPath := filepath.Join(dir, entry.Name())
-		loadPlugin(pluginPath)
-	}
-}
-
-func loadPlugin (path string) {
-	die := func (reason string) {
-		println("tomo: could not load plugin at", path + ":", reason)
-	}
-
-	plugin, err := plugin.Open(path)
-	if err != nil {
-		die(err.Error())
-		return
-	}
-
-	// check for and obtain basic plugin functions
-	name, ok := extract[func () string](plugin, "Name")
-	if !ok { die("does not implement Name() string"); return }
-	_, ok = extract[func () string](plugin, "Description")
-	if !ok { die("does not implement Description() string"); return }
-
-	println("tomo: loaded plugin", name())
-}
-
-func extract[T any] (plugin *plugin.Plugin, name string) (value T, ok bool) {
-	symbol, err := plugin.Lookup(name)
-	if err != nil { return }
-	value, ok = symbol.(T)
-	return
-}

theme.go

@@ -0,0 +1,111 @@
+package tomo
+
+import "fmt"
+import "git.tebibyte.media/tomo/tomo/data"
+import "git.tebibyte.media/tomo/tomo/event"
+import "git.tebibyte.media/tomo/tomo/canvas"
+
+// Role describes the role of an object.
+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
+}
+
+// String satisfies the fmt.Stringer interface.
+// It follows the format of:
+// Package.Object[Variant]
+func (r Role) String () string {
+	return fmt.Sprintf("%s.%s[%s]", r.Package, r.Object, r.Variant)
+}
+
+// R is shorthand for creating a Role structure.
+func R (pack, object, variant string) Role {
+	return Role { Package: pack, Object: object, Variant: variant }
+}
+
+// Color represents a color ID.
+type Color int; const (
+	ColorBackground Color = iota
+	ColorForeground
+	ColorRaised
+	ColorSunken
+	ColorAccent
+)
+
+// String satisfies the fmt.Stringer interface.
+func (c Color) String () string {
+	switch c {
+	case ColorBackground: return "background"
+	case ColorForeground: return "foreground"
+	case ColorRaised:     return "raised"
+	case ColorSunken:     return "sunken"
+	case ColorAccent:     return "accent"
+	default:              return "unknown"
+	}
+}
+
+// RGBA satisfies the color.Color interface.
+func (id Color) RGBA () (r, g, b, a uint32) {
+	if theme == nil { return }
+	return theme.RGBA(id)
+}
+
+// Theme can apply a visual style to different objects.
+type Theme interface {
+	// A word on textures:
+	//
+	// Because textures can be linked to some resource that is outside of
+	// the control of Go's garbage collector, methods of Theme must not
+	// allocate new copies of a texture each time they are called. It is
+	// fine to lazily load textures and save them for later use, but the
+	// same texture must never be allocated multiple times as this could
+	// cause a memory leak.
+	//
+	// As such, textures returned by these methods must be protected.
+	
+	// Apply applies the theme to the given object, according to the given
+	// role. This may register event listeners with the given object;
+	// closing the returned cookie must remove them.
+	Apply (Object, Role) 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
+}
+
+var theme Theme
+
+// SetTheme sets the theme.
+func SetTheme (them Theme) {
+	theme = them
+}
+
+// Apply applies the current theme to the given object, according to the given
+// role. This may register event listeners with the given object; closing the
+// returned cookie will remove them.
+func Apply (object Object, role Role) event.Cookie {
+	if theme == nil { return event.NoCookie { } }
+	return theme.Apply(object, role)
+}

theme/theme.go

@@ -1,71 +0,0 @@
-package theme
-
-import "git.tebibyte.media/tomo/tomo"
-import "git.tebibyte.media/tomo/tomo/event"
-
-// Role describes the role of an object.
-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
-}
-
-// R is shorthand for creating a Role structure.
-func R (pack, object, variant string) Role {
-	return Role { Package: pack, Object: object, Variant: variant }
-} 
-
-// Color represents a color ID.
-type Color int; const (
-	ColorBackground Color = iota
-	ColorForeground
-	ColorRaised
-	ColorSunken
-	ColorAccent
-)
-
-// RGBA satisfies the color.Color interface.
-func (id Color) RGBA () (r, g, b, a uint32) {
-	if current == nil { return }
-	return current.RGBA(id)
-}
-
-// Theme is an object that can apply a visual style to different objects.
-type Theme interface {
-	// Apply applies the theme to the given object, according to the given
-	// role. This may register event listeners with the given object;
-	// closing the returned cookie will remove them.
-	Apply (tomo.Object, Role) event.Cookie
-	
-	// RGBA returns the RGBA values of the corresponding color ID.
-	RGBA (Color) (r, g, b, a uint32)
-}
-
-var current Theme
-
-// SetTheme sets the theme.
-func SetTheme (theme Theme) {
-	current = theme
-}
-
-// Apply applies the current theme to the given object, according to the given
-// role. This may register event listeners with the given object; closing the
-// returned cookie will remove them.
-func Apply (object tomo.Object, role Role) event.Cookie {
-	if current == nil { return event.NoCookie { } }
-	return current.Apply(object, role)
-}
-

tomo.go

@@ -3,6 +3,7 @@ package tomo
 import "sync"
 import "image"
 import "errors"
+import "git.tebibyte.media/tomo/tomo/canvas"
 
 var backendLock sync.Mutex
 var backend Backend
@@ -11,13 +12,11 @@ var backend Backend
 // event loop in that order. This function blocks until Stop is called, or the
 // backend experiences a fatal error.
 func Run (callback func ()) error {
-	loadPlugins()
-
 	if backend != nil {
 		return errors.New("there is already a backend running")
 	}
 
-	back, err := Initialize()
+	back, err := initialize()
 	if err != nil { return err }
 	
 	backendLock.Lock()
@@ -56,6 +55,14 @@ func NewWindow (bounds image.Rectangle) (MainWindow, error) {
 	return backend.NewWindow(bounds)
 }
 
+// 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 NewPlainWindow (bounds image.Rectangle) (MainWindow, error) {
+	assertBackend()
+	return backend.NewPlainWindow(bounds)
+}
+
 // NewBox creates and returns a basic Box.
 func NewBox () Box {
 	assertBackend()
@@ -79,3 +86,10 @@ func NewContainerBox () ContainerBox {
 	assertBackend()
 	return backend.NewContainerBox()
 }
+
+// NewTexture creates a new texture from an image. When no longer in use, it
+// must be freed using Close().
+func NewTexture (source image.Image) canvas.TextureCloser {
+	assertBackend()
+	return backend.NewTexture(source)
+}

unix.go

@@ -1,22 +0,0 @@
-//go:build linux || darwin || freebsd
-
-package tomo
-
-import "os"
-import "strings"
-import "path/filepath"
-
-func init () {
-	pathVariable := os.Getenv("TOMO_PLUGIN_PATH")
-	pluginPaths = strings.Split(pathVariable, ":")
-	pluginPaths = append (
-		pluginPaths,
-		"/usr/lib/tomo/plugins",
-		"/usr/local/lib/tomo/plugins")
-	homeDir, err := os.UserHomeDir()
-	if err == nil {
-		pluginPaths = append (
-			pluginPaths,
-			filepath.Join(homeDir, ".local/lib/tomo/plugins"))
-	}
-}