render

Documentation

Overview

Package render turns the shell package's composition/model values into a live go-widgets widget tree and captures it to an image. It is the raw rendering layer: it imports the toolkit, the icon theme and the notification toast bridge, so it is exercised by the runtime smoke rather than the model coverage gate.

Index

• Constants
• type Config
• type IconLoader
  • func NewIconLoader(themeName string, size int) *IconLoader
  • func NewIconLoaderFunc(fn func(name string) ([]byte, bool), size int) *IconLoader
  • func (l *IconLoader) Image(name string) *toolkit.Image
• type Scene
  • func New(cfg Config) *Scene
  • func (s *Scene) AppCount() int
  • func (s *Scene) DockCount() int
  • func (s *Scene) FileCount() int
  • func (s *Scene) HostRoot() *scene.HostRoot
  • func (s *Scene) MenuCategoryCount() int
  • func (s *Scene) Render() (*image.RGBA, error)
  • func (s *Scene) Root() toolkit.Widget
  • func (s *Scene) SetQuery(q string)
  • func (s *Scene) SetToasts(ts []*toolkit.Toast)
  • func (s *Scene) ShowToast(t *toolkit.Toast)
  • func (s *Scene) Theme() *toolkit.Theme
  • func (s *Scene) ToastCount() int
  • func (s *Scene) Widget() toolkit.Widget

Constants

const DefaultIconSize = 48

DefaultIconSize is the nominal pixel size requested from the icon theme.

Types

type Config

type Config struct {
	// Source, when non-nil, provides the app index, menu, directory listing,
	// icon bytes and thumbnail keys; New fills Apps/Menu/Dir/Icons from it.
	Source shell.AppSource

	Apps        *shell.AppIndex
	Menu        *shell.MenuModel
	Dir         *shell.Dir
	Thumbnailer *shell.Thumbnailer
	Icons       *IconLoader
	Theme       *toolkit.Theme
	Width       int
	Height      int
	// DockMax caps how many app icons appear in the dock (0 -> a sane default).
	DockMax int
}

Config bundles the shell models and rendering resources a Scene composes.

There are two ways to fill it. Supply Source (a shell.AppSource) and New derives Apps, Menu, Dir, the icon loader and the thumbnail-key policy from it — the portable path: the identical Scene is produced whether Source scans a real XDG filesystem (native) or serves a curated set from an embed.FS (browser). Or supply the individual model fields directly (Apps, Menu, Dir, Thumbnailer, Icons) — the explicit path used by the render unit tests. Source takes precedence over the individual fields when both are set.

type IconLoader

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

IconLoader resolves icon names (or absolute paths) to go-widgets Image widgets, rasterizing PNG/JPEG/GIF icons and falling back to a solid placeholder when an icon is missing or cannot be decoded (e.g. an SVG-only icon). Results are cached per name.

It has two interchangeable resolution modes: the native mode resolves names through an XDG icon theme and reads the file (NewIconLoader), while the portable mode resolves the encoded bytes through a supplied function (NewIconLoaderFunc) — the seam an embed.FS-backed shell.AppSource plugs into, so the exact same rendering path runs in a browser with no filesystem.

func NewIconLoader

func NewIconLoader(themeName string, size int) *IconLoader

NewIconLoader builds a loader for the named icon theme (defaulting to hicolor) at the given nominal size — the native, filesystem-backed mode.

func NewIconLoaderFunc

func NewIconLoaderFunc(fn func(name string) ([]byte, bool), size int) *IconLoader

NewIconLoaderFunc builds a loader that resolves an icon name (or absolute path / virtual key) to encoded image bytes through fn — the portable mode used by an embed.FS-backed source in the browser, where there is no XDG icon theme to scan. A nil result from fn yields the placeholder swatch, exactly as a theme miss does in native mode.

func (*IconLoader) Image

func (l *IconLoader) Image(name string) *toolkit.Image

Image returns a cached Image for an icon name or absolute path. It never returns nil: an unresolved / undecodable icon yields a placeholder swatch.

type Scene

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

Scene is the composed desktop shell: a Border(menubar / dock / launcher / file-grid) plus a floating toast stack. All mutable state (the launcher search query and its results, the file model) flows through go-widgets/mvvm.

func New

func New(cfg Config) *Scene

New composes a Scene from cfg, wiring the mvvm bindings immediately. When cfg.Source is set, the app index, menu, directory listing, icon loader and thumbnail policy are all derived from it (so a browser embed.FS source and a native XDG source yield the same Scene); otherwise the explicit model fields are used as given.

func (*Scene) AppCount

func (s *Scene) AppCount() int

AppCount is the number of launchable apps currently listed in the launcher.

func (*Scene) DockCount

func (s *Scene) DockCount() int

DockCount is the number of icons in the dock.

func (*Scene) FileCount

func (s *Scene) FileCount() int

FileCount is the number of items in the file grid model.

func (*Scene) HostRoot

func (s *Scene) HostRoot() *scene.HostRoot

HostRoot builds a damage-aware root over the shell's widget tree for the windowed backend's incremental-present path (github.com/go-widgets/window v0.4.0 presents only the rectangles a scene.HostRoot reports, instead of the whole surface, every frame).

The returned *scene.HostRoot is a drop-in toolkit.Widget: handed to window.Backend.Run it drives RenderDamaged (small-rect present); handed to a damage-unaware host it still full-repaints correctly through Draw. It owns a Scene mirroring a hostShell — a thin composite of the shell's five border regions plus the floating toast stack — and repaints a widget's VACATED background as scene chrome, so an incremental frame is pixel-identical to the full composite by construction.

HostRoot also installs the Scene's incremental hooks: a launcher result-list change invalidates just the launcher (west) region, and any toast-stack mutation re-anchors and (conservatively) full-damages the surface. Pointer hover/scroll invalidate the region under the pointer; every other input event (click, key, drag) full-damages, because the region it affects is uncertain (a click may open a menu popup that spans regions). Correctness first: an uncertain region is always over-invalidated, never under-invalidated, so no frame can leave a stale pixel — the win is that the common high-frequency interactions (hover, a launcher keystroke, a grid scroll) present a small rect instead of the whole window.

func (*Scene) MenuCategoryCount

func (s *Scene) MenuCategoryCount() int

MenuCategoryCount is the number of application-menu categories.

func (*Scene) Render

func (s *Scene) Render() (*image.RGBA, error)

Render paints the whole shell (root widget then the toast stack) into a fresh image of the configured size.

func (*Scene) Root

func (s *Scene) Root() toolkit.Widget

Root returns the composed root widget.

func (*Scene) SetQuery

func (s *Scene) SetQuery(q string)

SetQuery updates the launcher search query, driving the results + launcher.

func (*Scene) SetToasts

func (s *Scene) SetToasts(ts []*toolkit.Toast)

SetToasts replaces the floating toast stack (e.g. from a notification daemon) and fires the toast-changed hook.

func (*Scene) ShowToast

func (s *Scene) ShowToast(t *toolkit.Toast)

ShowToast adds a toast to the floating stack (used to present notifications), then fires the toast-changed hook so the incremental path repaints the toast overlay. A nil toast is ignored (and never fires the hook).

func (*Scene) Theme

func (s *Scene) Theme() *toolkit.Theme

Theme returns the theme the scene paints with, so a windowing backend paints its background and widgets with the same palette the -capture path uses.

func (*Scene) ToastCount

func (s *Scene) ToastCount() int

ToastCount is the number of visible toasts.

func (*Scene) Widget

func (s *Scene) Widget() toolkit.Widget

Widget returns the whole shell — the Border root plus its floating toast overlay — as a single toolkit.Widget. A windowing backend such as github.com/go-widgets/window drives exactly one root widget through its Run loop, so wrapping the overlay here lets the live window show the same composition (dock, launcher, menu, file grid AND notification toasts) that Render paints to a PNG. It is backend-agnostic: it only touches toolkit primitives and reads the scene's live toast slice at Draw time, so a toast pushed by the notifications daemon appears on the next repaint.