render

package
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Aug 17, 2026 License: BSD-3-Clause Imports: 20 Imported by: 0

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

View Source 
const (
	ViewList    = 0 // Liste
	ViewIcons   = 1 // Vignettes
	ViewColumns = 2 // Colonnes
	ViewGallery = 3 // Galerie
)

View modes, in the toolbar segmented control's order.

View Source 
const DefaultIconSize = 48

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

View Source 
const UIFontSizePx = 13

UIFontSizePx is the em size, in pixels, the shell renders its proportional UI text at. Inter reads cleanly at this size through the toolkit's pure-Go TrueType rasteriser (truetype.go), sitting comfortably inside the 18 px ListBox row and the 22 px menu/title bars.

Variables

This section is empty.

Functions

func NativeLister added in v0.11.0 

func NativeLister(path string) (*shell.Dir, error)

NativeLister lists path from the real filesystem and classifies it by name (the portable, content-sniff-free classifier). It is the default navigation backend; in the browser (no filesystem) os.ReadDir fails and the finder shows its empty state.

func UseUIFont added in v0.9.0 

func UseUIFont()

UseUIFont installs a real proportional TrueType face (Inter, embedded via github.com/go-opentype/fonts) as the toolkit's active font, replacing the built-in 5x7 bitmap font for the whole shell. This is a pure app-level call: it only invokes the toolkit's public SetFont/NewTrueTypeFont seam (the toolkit itself is never modified), and swapping the active font rescales every widget's typography to crisp anti-aliased glyphs without touching a single widget — layout follows because widgets measure through the active font.

It runs at most once (subsequent calls are no-ops) and is safe to call from every entry point — the native binary, the browser client and render.New — so any path that builds a Scene renders with the good font. A parse failure leaves the bitmap default in place rather than aborting the shell.

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

	// Places is the file-manager sidebar model (Favoris + Emplacements). When
	// nil the finder resolves shell.DefaultPlaces() for the running OS.
	Places *shell.Places
	// Lister is the directory-navigation backend the finder calls as the user
	// browses. When nil it defaults to render.NativeLister (real filesystem +
	// name-based classification); the browser build degrades to an empty state.
	Lister func(path string) (*shell.Dir, error)
}

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 FinderConfig added in v0.11.0 

type FinderConfig struct {
	Icons      *IconLoader
	Theme      *toolkit.Theme
	Places     *shell.Places
	Lister     func(path string) (*shell.Dir, error)
	ThumbKey   func(shell.FileItem) string
	InitialDir *shell.Dir
}

FinderConfig bundles what a FinderPane needs from the shell/render layer.

type FinderPane added in v0.11.0 

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

FinderPane is the macOS-Finder-like file browser that fills the desktop shell's content region: a Favoris/Emplacements sidebar, a toolbar with a Liste/Vignettes/Colonnes/Galerie view switcher and an icon-size slider, and the four swappable content views over a shared, sortable directory model. It composes only public toolkit widgets (Border, HBox, ViewSwitcher, Scale, Table, IconGrid, ColumnBrowser, GalleryView, Stack) plus shell-level adapters for the gaps the toolkit has no widget for (the sectioned sidebar) and thin projections of the shared model onto each toolkit view — the toolkit itself is never modified.

func NewFinderPane added in v0.11.0 

func NewFinderPane(cfg FinderConfig) *FinderPane

NewFinderPane builds the file browser. Places defaults to shell.DefaultPlaces and Lister to a native ListDir+ClassifyLite lister when left nil, so a caller that only supplies an InitialDir still gets a fully navigable pane on a real filesystem (and a graceful, empty one in the browser).

func (*FinderPane) CascadeColumns added in v0.11.0 

func (f *FinderPane) CascadeColumns(n int)

CascadeColumns opens the first sub-directory of each rightmost Miller column until n columns show — the folder chain a user would click, used to populate a column-view screenshot with the signature cascade. It switches to the column view first so the strip is rooted.

func (*FinderPane) Clipboard added in v0.14.0 

func (f *FinderPane) Clipboard() *shell.Clipboard

Clipboard exposes the finder's file clipboard for the capture CLI and tests.

func (*FinderPane) ConfirmDialog added in v0.14.0 

func (f *FinderPane) ConfirmDialog()

ConfirmDialog accepts the active paste confirmation (the peer of clicking its confirm button), applying the pending move/overwrite — the programmatic hook the capture CLI and the on-device proof use to drive the modal without a live pointer. It is a no-op when no paste is pending.

func (*FinderPane) CurrentDir added in v0.11.0 

func (f *FinderPane) CurrentDir() string

CurrentDir is the path currently shown ("" in the network empty state).

func (*FinderPane) DemoMoveConfirm added in v0.12.0 

func (f *FinderPane) DemoMoveConfirm()

DemoMoveConfirm pops the move-confirmation dialog for the first file over the first folder in the current directory — a screenshot/testing helper so the confirmation overlay can be captured without a live drag. It is a no-op when the current directory has no file + folder pair.

func (*FinderPane) DialogActive added in v0.12.0 

func (f *FinderPane) DialogActive() bool

DialogActive reports whether a modal dialog (move confirmation or error) is currently shown — for the capture CLI and tests.

func (*FinderPane) FileCount added in v0.11.0 

func (f *FinderPane) FileCount() int

FileCount is the number of items in the current directory model.

func (*FinderPane) FocusGalleryImage added in v0.15.0 

func (f *FinderPane) FocusGalleryImage()

FocusGalleryImage selects the current directory's first image item in the Galerie view, so the big preview shows a real photo rather than the gallery's default first-item selection — which, because folders sort first, is often a folder glyph. It switches to the gallery view first, then selects the image (a no-op when the directory has no image). It is the gallery peer of CascadeColumns: a screenshot/testing helper that stages the signature look of the view without a live pointer.

func (*FinderPane) GoToPlace added in v0.11.0 

func (f *FinderPane) GoToPlace(kind shell.PlaceKind)

GoToPlace navigates the finder to the sidebar place of the given kind (the first match in Favoris then Emplacements), a no-op when no such place exists. It is the programmatic peer of clicking that sidebar row (used by the capture CLI and tests).

func (*FinderPane) HandleKey added in v0.14.0 

func (f *FinderPane) HandleKey(ev toolkit.Event) bool

HandleKey dispatches a synthetic key event to the finder exactly as the windowed backend would, so the capture CLI and tests can drive the keyboard file operations without a live compositor. It returns whether the event was consumed as a shortcut.

func (*FinderPane) IconSize added in v0.11.0 

func (f *FinderPane) IconSize() int

IconSize is the current Vignettes icon size in pixels.

func (*FinderPane) Navigate added in v0.11.0 

func (f *FinderPane) Navigate(path string)

Navigate lists path and shows it in every view.

func (*FinderPane) Root added in v0.11.0 

func (f *FinderPane) Root() toolkit.Widget

Root returns the composed pane (the border plus its modal-dialog overlay) for embedding in the shell.

func (*FinderPane) SelectByPath added in v0.14.0 

func (f *FinderPane) SelectByPath(path string)

SelectByPath selects the model row at path in the active view — the programmatic peer of clicking it, used by the capture CLI and tests to set a selection before firing a keyboard shortcut.

func (*FinderPane) SetIconSize added in v0.11.0 

func (f *FinderPane) SetIconSize(px int)

SetIconSize sets the Vignettes icon size (clamped to the slider range) and keeps the slider thumb in step.

func (*FinderPane) SetView added in v0.11.0 

func (f *FinderPane) SetView(mode int)

SetView switches the visible content view (and roots the Miller strip at the current directory the first time it is shown).

func (*FinderPane) ViewMode added in v0.11.0 

func (f *FinderPane) ViewMode() int

ViewMode is the active view-mode constant.

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 added in v0.4.0 

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) Fork added in v0.10.0 

func (l *IconLoader) Fork() *IconLoader

Fork returns a new loader that resolves icons through the SAME backend (theme or bytes function, at the same size/scale) but keeps its OWN, independent image cache — so the Images it hands out are distinct objects from the original's. This is the seam an imperative drawer (the launcher's per-row icon) uses to avoid aliasing the very Image objects a retained widget (the dock) holds as scene children: two consumers that both mutate a shared Image's bounds each frame would otherwise cross-contaminate, and the damage-aware scene would repaint one consumer's icon inside the other's region. A forked loader shares no Image with its parent, so each consumer owns the bounds of the icons it draws.

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.

func (*IconLoader) TryImage added in v0.9.0 

func (l *IconLoader) TryImage(name string) (*toolkit.Image, bool)

TryImage returns a cached Image for an icon name or absolute path and ok=true when it resolved to real pixels, or (nil, false) on a miss (an empty name, a theme/asset lookup that found nothing, or an undecodable file) WITHOUT substituting a placeholder. It is the seam the file grid and dock use to fall back to a tasteful drawn glyph (folder / document / app tile) instead of a blank grey square when there is no real icon — the whole reason the native macOS shell, which has no XDG icon theme, need never show an empty placeholder.

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) Finder added in v0.11.0 

func (s *Scene) Finder() *FinderPane

Finder returns the composed file-manager pane, so a caller (the -capture CLI, tests) can select a view mode, icon size or directory before rendering.

func (*Scene) HostRoot added in v0.3.0 

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 presents only the rectangles a scene.HostRoot reports, instead of the whole surface, every frame — on X11/Wayland natively and in the wasmbox browser client alike).

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.

Source Files

View all Source files

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.