frostui

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 18 Imported by: 0

README

frostui

Go Reference

frostui is a Go module that gives desktop apps on MyGo a command-center window and the pieces to fill it, for frostyard's apps: ChairLift, Frostmail and Frostnotes.

Status: pre-release. Until v1, a minor version may change the API, and each change is listed in the design doc.

Documentation: pkg.go.dev/github.com/frostyard/frostui

The command-center example in the middle of a sync

What it does

Package What it gives you
frostui The shell (top bar with a command palette, rail, console and status bar), a serial job queue, dialogs, cards, rows, charts and the desktop's icons and accent.
frostuitest A stand-in for the UI thread, so tests run what workers post without a window.

It builds without CGO for Linux, Windows and macOS on amd64 and arm64, and for js/wasm. The freedesktop parts (app ID, icon theme, launching desktop apps) work on Linux and fall back elsewhere.

Requirements

  • Go 1.27.
  • At run time, what MyGo needs: GTK 3, libepoxy and Pango on Linux.
  • For the tests: Pango and cairo, and no display.

Install

go get github.com/frostyard/frostui

Use

import (
	"log"

	"github.com/egoist/mygo"
	"github.com/egoist/mygo/ui"

	"github.com/frostyard/frostui"
)

func main() {
	shell := &frostui.Shell{Brand: frostui.Brand{Name: "Notes"}, Selected: "all"}
	nav := []frostui.NavSection{{Title: "Notebooks", Items: []frostui.NavItem{
		{ID: "all", Title: "All notes", Icon: "folder"},
	}}}
	mygo.App.WhenReady(func() {
		mygo.NewWindow(mygo.WindowOptions{
			Title: "Notes", Width: 1100, Height: 720, TitleBarStyle: mygo.TitleBarHidden,
			Content: ui.View(func(c *ui.Context) {
				shell.View(c, frostui.Frame{
					Nav:     nav,
					Content: func() { frostui.PageHeader(c, "All notes", "3 notes", nil) },
				})
			}),
		})
	})
	if err := mygo.App.Run(); err != nil {
		log.Fatal(err)
	}
}

examples/commandcenter adds the palette, the console, the job queue and the status bar: go run ./examples/commandcenter.

Develop

mise install   # golangci-lint and Node; Go comes from go.mod
make ci        # what CI runs

Design and invariants: docs/design/frostui.md.

Where to go next

Documentation

Overview

Package frostui is frostyard's desktop UI kit on MyGo (github.com/egoist/mygo/ui): the command-center shell (top bar, left rail, status bar, console, command palette), the cards, figures, pills, banners and dialogs that every page is built from, a serial job queue whose output streams to the console, and desktop integration (the desktop's icon theme, its accent kept in inactive windows, and the Wayland app ID).

It imports only the standard library, MyGo and purego, so any frostyard desktop app can take it, and it builds with CGO_ENABLED=0 for Linux, Windows, macOS and js/wasm. The freedesktop parts (SetAppID, DesktopIconTheme, the icon theme of NewIcons, LaunchDesktopApp) work on Linux and fall back elsewhere, as each one's comment says. The repository's docs/design/frostui.md describes the parts and the rules.

Threads

Views run on the UI thread. Every model here (Console, Jobs, Palette, Dialogs) is changed on the UI thread, except Console.Add, which any goroutine may call. Workers hand results back with the post function the app gives NewJobs (MyGo's Window.Update); in tests, a frostuitest.Loop stands in for it.

Index

Constants

View Source
const (
	SpaceXS = 4
	SpaceS  = 8
	SpaceM  = 12
	SpaceL  = 16
	SpaceXL = 24

	// RadiusCard rounds cards and panels; RadiusChip rounds chips, pills
	// and small tiles.
	RadiusCard = 12
	RadiusChip = 8

	// RailWidth is the width of the left rail.
	RailWidth = 232
	// TopBarHeight is the height of the top bar.
	TopBarHeight = 52
)

Metrics of the kit, in DIPs. Pages use them instead of numbers of their own so that every frostyard app has the same rhythm.

View Source
const AllLevels = LevelSet(1<<levelCount - 1)

AllLevels is every level.

View Source
const DefaultLevels = AllLevels &^ (1 << LevelDebug)

DefaultLevels hides the app's debug log.

View Source
const HeroSize = 64

HeroSize is the side of a Hero's icon tile, in DIPs.

View Source
const ToastWidth = 640

ToastWidth is the widest a TopToasts toast grows, in DIPs.

Variables

View Source
var LevelNames = [levelCount]string{"Debug", "Output", "Info", "Command", "Dry run", "Warn", "Error"}

LevelNames are the names the console's filter buttons show, by Level.

Functions

func AboutBody

func AboutBody(a About) func(c *ui.Context)

AboutBody draws a for Info.Show.

func Adapt

func Adapt(c *ui.Context) *ui.Theme

Adapt makes MyGo's theme behave as GNOME's and KDE's do and returns it: the accent stays in windows without the focus (MyGo fades it to gray, as macOS does). The rest still follows the desktop: light or dark, accent, contrast and text size. Call it first in the root view.

func Banner(c *ui.Context, tone Tone, icon, text, action string, closable bool) (acted, closed bool)

Banner is a full-width notice in a tone, with an optional action and a close button. It reports a click on the action and on close.

func Body

func Body(c *ui.Context, s string) ui.Element

Body is ordinary text.

func Caption

func Caption(c *ui.Context, s string) ui.Element

Caption is small secondary text, as a label above a value.

func Card

func Card(c *ui.Context) ui.Element

Card is a panel: a column with padding, a hairline border and rounded corners, on the panel color. Chain Children to fill it.

func CardHeader

func CardHeader(c *ui.Context, title, subtitle string, trailing func())

CardHeader is a card's title row: a heading, an optional subtitle under it, and trailing controls at the end.

func Chrome

func Chrome(t *ui.Theme) ui.Color

Chrome is the color of the top bar, rail and status bar: a shade between the window's background and the surface of controls.

func CodeDialog

func CodeDialog(c *ui.Context, title, summary, text, action string) (acted, canceled bool)

CodeDialog asks about text the user should read exactly as it is, as a report before it is sent: a title, a summary, the text in a scrollable monospaced box with its spaces and lines kept, then Cancel and the action. It holds no state: draw it while the app's own state says it is open. It reports, in the frame they happen, a click on the action (acted) and a cancel: Cancel, Escape or a click outside (canceled).

func ColorPill

func ColorPill(c *ui.Context, text string, color ui.Color) ui.Element

ColorPill is a pill in a color of the app's own rather than a tone, as one color per kind of thing. Pass the color from the page's theme: under SoftSelection the accent of c's theme is a tint.

func CommandRow

func CommandRow(c *ui.Context, it CommandItem) ui.Element

CommandRow is a row for a command the app runs on request: an icon tile, the title with its command line under it in monospace, the command's state and its button. Rows of a list line their state and buttons up in cells of the same width.

func DesktopIconTheme

func DesktopIconTheme() string

DesktopIconTheme is the icon theme the desktop uses. On Linux it is the FROSTUI_ICON_THEME environment variable when set, else KDE's from kdeglobals, GNOME's from gsettings, and Adwaita when neither answers. Off Linux it is "": the desktop has no freedesktop icon theme.

func DisclosureCard

func DisclosureCard(c *ui.Context, open *bool, d Disclosure) (toggled bool)

DisclosureCard is a card whose head opens and closes it: an icon, a title over a subtitle, Trailing, and a chevron; open, Body shows under the head. *open says whether it is open; a click on the head flips it, and the card shows the new state in the same frame. It reports the click. Key it with c.Key when it is one of a list.

func DotPill

func DotPill(c *ui.Context, text string, color ui.Color) ui.Element

DotPill is a pill that starts with a dot in its color, as a state that waits for the user: "Update".

func Duration

func Duration(d time.Duration) string

Duration formats how long a job ran as a step's note: "8s", "1m 03s", "2h 05m".

func Empty

func Empty(c *ui.Context, icon, title, body string) ui.Element

Empty is the placeholder of a list with nothing in it.

func Figures

func Figures(c *ui.Context, figs []Figure) ui.Element

Figures is one strip of figures side by side, divided by hairlines.

func Gauge

func Gauge(c *ui.Context, value, maxValue float64, center, caption string, tone Tone, size float32) ui.Element

Gauge draws an open ring filled to value of max, with big text in its middle and a caption under it: free space, a share in use.

func Heading

func Heading(c *ui.Context, s string) ui.Element

Heading heads a card or section.

func Hero

func Hero(c *ui.Context, icon HeroIcon, title, description string) ui.Element

Hero is the centered top of a wizard's step or of a page that says one thing: a large icon, a title and a description under it.

func Icon

func Icon(c *ui.Context, name string) ui.Element

Icon draws the named icon at the text size, in the text color, which TextColor changes. A missing icon is an empty box of the text size, as a drawn icon is, so layouts do not move.

func IconButton

func IconButton(c *ui.Context, icon, label string) ui.Element

IconButton is a flat button showing only an icon. label names it for screen readers and its tooltip; it must not be empty.

func IconPill

func IconPill(c *ui.Context, icon, text string, tone Tone) ui.Element

IconPill is a pill that starts with an icon.

func IconSVG

func IconSVG(name string) *ui.SVG

IconSVG returns the named icon from the kit's icons, or nil.

func IconTile

func IconTile(c *ui.Context, icon string, tone Tone, size float32) ui.Element

IconTile is an icon on a rounded square, as rows and cards lead with. size is the square's side.

func Initials

func Initials(name string) string

Initials are the first letters of name's first two words, upper case: "Mission Center" is "MC", "fzf" is "F", and a name without a letter or digit is "?".

func JobCard

func JobCard(c *ui.Context, q *Jobs)

JobCard is the rail's card for the running job: its title, the batch's progress and "Job 2 of 5". It draws nothing while the queue is idle.

func JobStatus

func JobStatus(c *ui.Context, s RowStatus)

JobStatus draws s into the row it is in, at the end of a row of a list, before or instead of the row's button: its parts follow the row's gap. It draws nothing for a note without text.

func Kbd

func Kbd(c *ui.Context, key string) ui.Element

Kbd draws a keyboard key, as in "Ctrl K".

func KeyValues

func KeyValues(c *ui.Context, rows []KeyValue, style ...KeyValuesStyle) ui.Element

KeyValues is a two-column list of names and values. An optional style sets its metrics.

func LabeledButton

func LabeledButton(c *ui.Context, icon, label string, primary bool) ui.Element

LabeledButton is a button with an icon before its label. primary makes it the accent button.

func LaunchDesktopApp

func LaunchDesktopApp(id string) error

LaunchDesktopApp starts the desktop app whose desktop file ID is id ("org.mozilla.firefox", without ".desktop") and does not wait for it.

On Linux it runs gtk-launch, which finds the desktop file (Flatpak exports one per app) and starts the app as the desktop would; the app is a GUI app, and its end is reaped on a goroutine. It runs no shell; pass IDs from the app's configuration or a package manager's list, not typed input.

Desktop file IDs are a freedesktop idea: on other systems it starts nothing and returns an error that wraps errors.ErrUnsupported.

func Legend

func Legend(c *ui.Context, tone Tone, text string) ui.Element

Legend draws a colored square and a text, as a chart's key.

func LiveChart

func LiveChart(c *ui.Context, label string, height float32, series ...Series) ui.Element

LiveChart draws series as smoothed lines over a soft area on a 0–100 grid, for figures sampled every second. label names it for screen readers.

func Loading

func Loading(c *ui.Context, text string) ui.Element

Loading is a spinner with a line saying what loads.

func Match

func Match(query, text string) (score int, ok bool)

Match scores how well query matches text: every rune of query must appear in text in order, ignoring case. A higher score is a better match; runs of consecutive runes, the start of words and a match at the start count more. ok is false when query does not match.

func Mono

func Mono(c *ui.Context, s string) ui.Element

Mono is text in the monospace font: versions, IDs, commands.

func Muted

func Muted(c *ui.Context, s string) ui.Element

Muted is secondary text.

func PageHeader(c *ui.Context, title, subtitle string, actions func())

PageHeader is the top of a page: its title, a subtitle that says the page's state in one line, and the page's main actions at the end.

func Panel

func Panel(t *ui.Theme) ui.Color

Panel is the face of cards.

func Pill

func Pill(c *ui.Context, text string, tone Tone) ui.Element

Pill is a small rounded tag in a tone.

func PillTabs

func PillTabs(c *ui.Context, selected *int, tabs []Tab) ui.Element

PillTabs draws tabs as a row of pills, each an icon and a title, the chosen one filled with the surface color. *selected is the chosen index; a click writes it. It returns the tab list.

func Pipeline

func Pipeline(c *ui.Context, stages []Stage) ui.Element

Pipeline draws stages side by side, left to right, each a column of steps, with arrows between the stages: one run across sources. Screen readers hear it as a list named "Pipeline"; chain Label on the result to name the run.

func Problem

func Problem(c *ui.Context, text string) ui.Element

Problem is an inline error line in a card.

func RowDivider

func RowDivider(c *ui.Context) ui.Element

RowDivider is the hairline between rows of a card.

func RunSummary

func RunSummary(jobs []*Job) string

RunSummary says how a batch of jobs ended, as "9 done · 1 failed · 2 canceled"; jobs that did not end count for nothing, and it is "" when none ended.

func Section

func Section(c *ui.Context, icon, title, note string, fn func())

Section is a labelled group inside a page: an icon, a title and a muted note on one line (SectionHeader), then fn's content.

func SectionHeader

func SectionHeader(c *ui.Context, h SectionHead) ui.Element

SectionHeader is the line that heads a group of a page: an icon, a bold title, a note after it and an aside at the end. Section draws one over its content; a page that lays its group out itself draws it alone.

func SegmentBar

func SegmentBar(c *ui.Context, label string, total float64, parts []Segment, legend func(Segment) string) ui.Element

SegmentBar draws parts of a whole side by side in one bar, as where the disk goes, with a legend under it. total is the whole; what the parts leave is drawn empty.

func SetAppID

func SetAppID(id, displayName string) error

SetAppID names the program for the desktop before MyGo opens the display. Call it before mygo.App.Run; only the first call counts, as GLib allows, on every system.

On Linux, GTK takes the Wayland app ID and the X11 WM_CLASS from GLib's program name, which MyGo leaves to the executable's name. SetAppID sets it (g_set_prgname) to id, the reverse-DNS ID of the app's .desktop file, so the desktop shows the app's icon and name for its windows, and sets GLib's application name (g_set_application_name) to displayName, the human name, when it is not empty. It loads GLib with purego, so a host without GLib gets an error and the program runs on unnamed.

On other systems MyGo does not use GTK and the system names the app from its bundle (macOS), its executable (Windows) or its page (a browser), so SetAppID only checks that id is not empty.

func SetIcons

func SetIcons(ic *Icons)

SetIcons makes ic the icons the kit's components draw.

func Shortcut

func Shortcut(c *ui.Context, keys ...string) ui.Element

Shortcut draws a key combination, as "Ctrl" "K".

func ShortcutsBody

func ShortcutsBody(entries []ShortcutEntry) func(c *ui.Context)

ShortcutsBody draws shortcut entries grouped, for Info.Show.

func SoftSelection

func SoftSelection(t *ui.Theme) *ui.Theme

SoftSelection is t with the accent of chosen rows softened to a tint of it on a card, and the text on them left as it is, so the pills on a chosen row of a table still show. Draw the table under it with ui.Themed, and take the cells' colors from t.

func SquareAvatar

func SquareAvatar(c *ui.Context, name string, size float32) ui.Element

SquareAvatar is a rounded square with the initials of name on a color the name picks, the same color for the same name in every frame: an app or a package without an icon of its own. size is the square's side.

func StepDots

func StepDots(c *ui.Context, n, current int) ui.Element

StepDots is a wizard's step indicator: one dot per step, the current one (counted from 0) drawn long in the accent, the steps before it in a lighter accent. Screen readers hear it as a progress, "2 / 5".

func StepTile

func StepTile(c *ui.Context, s Tile) ui.Element

StepTile is one tile of a short chain of values read top to bottom, as versions of a system (the next, the running, the previous): an icon, a caption over the value and a smaller line under it. The current one is in the accent, an empty one dimmed.

func Strong

func Strong(c *ui.Context, s string) ui.Element

Strong is text that stands out in a row: a name.

func SwitchRow

func SwitchRow(c *ui.Context, title, subtitle string, on *bool) ui.Element

SwitchRow is a setting: its title, an optional line under it, and a switch at the end, labelled with the title. Without a subtitle the title is plain body text; with one it is bold over the muted subtitle. It returns the switch, for Disabled, Tooltip and Changed. Key it with c.Key, which keys the row.

func Text

func Text(lines []Line) string

Text renders lines as plain text, one per line, for the clipboard.

func TileGrid

func TileGrid(c *ui.Context) ui.Element

TileGrid lays tiles out in rows that wrap, as ToggleTiles: chain Children to fill it.

func Title

func Title(c *ui.Context, s string) ui.Element

Title is a page title.

func ToggleTile

func ToggleTile(c *ui.Context, icon, title, sub string, on, busy bool) bool

ToggleTile is a large tile that shows a thing on or off, as a quick setting: an icon, a title and a line under it, filled with the accent while on. It reports a click; the app decides what a click does (ask first). busy shows a spinner instead of the icon.

func ToneColor

func ToneColor(t *ui.Theme, tone Tone) ui.Color

ToneColor is the foreground color of tone.

func ToneFill

func ToneFill(t *ui.Theme, tone Tone) ui.Color

ToneFill is the soft background behind tone's foreground, as a pill's.

func Toned

func Toned(c *ui.Context, s string, tone Tone) ui.Element

Toned is text in a tone's color.

func TopToasts

func TopToasts(c *ui.Context, closeLabel string)

TopToasts gives a window's toasts their look: at the top of the window, centered, each with a close button named closeLabel (translated by the app). MyGo's own toasts sit at the bottom, where they cover a wizard's Back and Next, and have no close button, so a toast that stays until closed would stay for good; resting the pointer on a toast also stops its time. A toast of Type "error" leads with a warning icon. Plain text only (the Title). Call it once per frame, as ui.ToastViewportBase.

func VersionChange

func VersionChange(c *ui.Context, from, to string) ui.Element

VersionChange shows a change of version, "1.2 → 1.3": the old version muted and the new one, both in monospace. Either may be empty; the arrow shows only between two.

Types

type About

type About struct {
	Name, Version, Summary string
	Website, Issues        string
	License, Copyright     string
	Developers             []string
}

About is what an About dialog says.

type Brand

type Brand struct {
	Name, Tagline string
	Logo *ui.SVG
}

Brand is the app's identity at the top of the rail.

type Command

type Command struct {
	// ID identifies the command; it must be unique.
	ID string
	// Title is what the palette lists and matches, as "Update everything".
	Title string
	// Group heads the commands of one kind, as "Actions" or "Go to".
	Group string
	// Icon is a freedesktop icon name.
	Icon string
	// Keys is the shortcut that also runs it, as {"Ctrl", "U"}.
	Keys []string
	// Hint is matched as well as the title, but not shown: other words for
	// the command.
	Hint string
	// Disabled commands are listed, dimmed, and do not run; Reason says
	// why.
	Disabled bool
	Reason   string
	// Run runs on the UI thread after the palette closes.
	Run func()
}

Command is one entry of the command palette: an action the app offers, or a place to go.

func Filter

func Filter(cmds []Command, query string) []Command

Filter returns the commands that match query, best first. With an empty query it returns every command in its order, grouped.

type CommandItem

type CommandItem struct {
	Icon, Title string
	// Command is the command line, as it runs.
	Command string
	// Admin shows an "admin" pill after the title: the command asks for
	// administrator authentication.
	Admin bool
	// Status draws the command's state (JobStatus) in a cell before the
	// action; Action draws its button. Either may be nil.
	Status, Action func()
}

CommandItem is what a CommandRow shows.

type Confirm

type Confirm struct {
	Title string
	// Body says what will happen; Note adds a line under it, as "Needs
	// administrator authentication."
	Body, Note string
	// Details are shown as key and value lines, as versions.
	Details []KeyValue
	// Action labels the button that confirms ("Turn on"); Cancel the other
	// ("Cancel" when empty).
	Action, Cancel string
	// Destructive colors the action as a danger.
	Destructive bool
	// OnConfirm runs on the UI thread when the user confirms; OnCancel
	// when they do not.
	OnConfirm func()
	OnCancel  func()
}

Confirm is a question the app asks before it changes something.

type Console

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

Console holds the newest lines of everything an app ran and logged, up to a capacity. Add is safe from any goroutine; the rest is for the UI thread too, but locks, so a worker may read.

func NewConsole

func NewConsole(capacity int) *Console

NewConsole returns a console keeping the newest capacity lines.

func (*Console) Add

func (c *Console) Add(level Level, source, text string)

Add appends a line. Text with several lines becomes several lines, all of level.

func (*Console) Addf

func (c *Console) Addf(level Level, source, format string, args ...any)

Addf is Add with a format.

func (*Console) Clear

func (c *Console) Clear()

Clear removes every line.

func (*Console) Counts

func (c *Console) Counts() (warnings, errors int)

Counts returns how many warnings and errors were added since the last Clear.

func (*Console) Lines

func (c *Console) Lines(levels *LevelSet, query string) []Line

Lines returns the lines kept, oldest first, that match: a line matches when its level is in levels (nil for all) and its text or source holds query, ignoring case.

func (*Console) Seq

func (c *Console) Seq() uint64

Seq is the sequence number of the newest line, 0 when none was added.

func (*Console) SetNotify

func (c *Console) SetNotify(fn func())

SetNotify sets the function called after lines are added, from the goroutine that added them: usually one that wakes the UI.

func (*Console) Writer

func (c *Console) Writer(level Level, source string) *ConsoleWriter

Writer returns an io.Writer whose writes become lines of level from source, as a log.Logger's output: each write is one or more lines, split at its newlines. The writer keeps no partial line between writes, so a write that does not end in a newline still ends in a line of its own; a log.Logger's writes always end in one.

type ConsoleView

type ConsoleView struct {
	Open   bool
	Query  string
	Levels LevelSet
	// Subtitle follows the pane's title; empty shows "every command the
	// app runs, as it runs".
	Subtitle string
	// contains filtered or unexported fields
}

ConsoleView is the console pane: every command the app ran and its output, as it ran, with filters by level and text, follow, copy and clear.

func (*ConsoleView) View

func (v *ConsoleView) View(c *ui.Context, con *Console)

View draws the pane for con.

type ConsoleWriter

type ConsoleWriter struct {

	// Classify, when set, picks the level of each line from its text: it
	// runs once per line, so the lines of one write can differ in level.
	// It runs on the writing goroutine, outside the console's lock.
	Classify func(text string) Level
	// contains filtered or unexported fields
}

ConsoleWriter is the io.Writer Console.Writer returns. It does not strip the timestamp prefix the standard logger adds: for lines without it, set the logger's flags to 0 or strip it before the write.

func (*ConsoleWriter) Write

func (w *ConsoleWriter) Write(p []byte) (int, error)

type Dialogs

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

Dialogs shows the app's confirmations, one at a time, in the order they were asked.

func (*Dialogs) Ask

func (d *Dialogs) Ask(req Confirm)

Ask queues a confirmation.

func (*Dialogs) Showing

func (d *Dialogs) Showing() bool

Showing reports whether a confirmation is up.

func (*Dialogs) View

func (d *Dialogs) View(c *ui.Context)

View draws the first confirmation, if any.

type Disclosure

type Disclosure struct {
	Icon            string
	Title, Subtitle string
	// Trailing draws at the end of the head, before the chevron: a count
	// pill.
	Trailing func()
	// Body draws the open card's content, under a hairline.
	Body func()
}

Disclosure is what a DisclosureCard shows.

type Figure

type Figure struct {
	Label, Value, Note string
	// Tone colors the note.
	Tone Tone
	// OnClick makes the figure a button, as one that opens its page.
	OnClick func()
}

Figure is one figure of a Figures strip.

type Frame

type Frame struct {
	Nav []NavSection
	// Actions draws the top bar's buttons (IconButton) before the menu.
	Actions func()
	// Menu builds the top bar's menu, nil for none.
	Menu func(m *ui.Menu)
	// RailFooter draws under the rail's pages: the running job, the host.
	RailFooter func()
	// Content draws the selected page.
	Content func()
	// Commands are the palette's commands.
	Commands []Command
	// Status and StatusEnd are the status bar's items at its start and
	// at its end.
	Status, StatusEnd []StatusItem
	// ConsoleData is the console the console pane shows, nil for no
	// console.
	ConsoleData *Console
}

Frame is what the app gives the shell to draw each frame.

type HeroIcon

type HeroIcon struct {
	Name string
	Tone Tone
	Busy bool
}

HeroIcon is what tops a Hero: a named icon on a tile in a tone (the accent for Neutral), the app's logo on the accent, or a spinner while busy. Logo wins over Busy, Busy over Name.

type Icons

type Icons struct {
	Theme string
	// contains filtered or unexported fields
}

Icons finds icons by their freedesktop names. On Linux it looks in the desktop's own icon theme, so an app shows Adwaita's symbolic icons on GNOME and Breeze's on KDE; a theme without an icon falls back to Adwaita, then hicolor. Elsewhere (Windows, macOS, a browser) there is no freedesktop theme, and it finds only the icons the app embeds. Lookups are lazy and cached; an icon nobody has is nil, which Icon draws as an empty box of the same size.

func NewIcons

func NewIcons(embedded map[string][]byte) *Icons

NewIcons returns the icons of the desktop's theme. embedded holds icons the app ships itself, by name, which win over the theme's; off Linux they are the only icons.

func (*Icons) Get

func (ic *Icons) Get(name string) *ui.SVG

Get returns the named icon, preferring its symbolic form, or nil.

type Info

type Info struct {
	Open bool
	// contains filtered or unexported fields
}

Info is a dialog that only shows content and closes: About, keyboard shortcuts, help.

func (*Info) Show

func (i *Info) Show(title string, body func(c *ui.Context))

Show opens the dialog with title and the content body draws.

func (*Info) View

func (i *Info) View(c *ui.Context)

View draws the dialog while it is open.

type Job

type Job struct {
	// Title says what the job does, as "Syncing the inbox".
	Title string
	// Source groups jobs, as the account or the service they work for.
	Source string
	// Key identifies what the job works on within its source, so a view
	// can show the job's state on that item's row.
	Key string

	Run  func(ctx context.Context, p *Progress) error
	Done func(err error)

	// Unstoppable marks a job whose work a cancel cannot stop: one that
	// runs as another user (only the unprivileged parent can be signaled)
	// or writes to a device. CancelAll drops the jobs queued after
	// it but lets it run to its end and report what really happened, and
	// the queue stays busy until then, so no other change overlaps it.
	Unstoppable bool

	// Set by the queue; read on the UI thread.
	ID       int
	State    JobState
	Err      error
	Fraction float64 // 0..1, or -1 while it cannot tell
	Status   string
	Started  time.Time
	Ended    time.Time
}

Job is one unit of work the queue runs: one command, one download, one sync. Run runs on a goroutine of its own; Done runs on the UI thread after it, with Run's error.

type JobState

type JobState int

JobState is where a job is.

const (
	// JobQueued waits for the jobs before it.
	JobQueued JobState = iota
	// JobRunning runs now.
	JobRunning
	// JobDone ended without an error.
	JobDone
	// JobFailed ended with an error.
	JobFailed
	// JobCanceled was canceled before or while it ran.
	JobCanceled
)

func (JobState) Ended

func (s JobState) Ended() bool

Ended reports whether the job is over.

type Jobs

type Jobs struct {

	// OnIdle, when set, runs on the UI thread when the last queued job ends.
	OnIdle func(batch []*Job)
	// contains filtered or unexported fields
}

Jobs runs jobs one at a time, in the order they were queued, so that two changes never race (one password prompt at a time, one write to a device at a time). Every method is for the UI thread.

func NewJobs

func NewJobs(post func(func()), console *Console) *Jobs

NewJobs returns a queue that hands work back to the UI thread with post (MyGo's Window.Update) and logs each job's start and end to console, which may be nil.

func (*Jobs) Batch

func (q *Jobs) Batch() (done, total int)

Batch returns how many jobs of the current batch ended and how many it has: a batch is every job queued since the queue was last idle.

func (*Jobs) BatchFraction

func (q *Jobs) BatchFraction() float64

BatchFraction is the share of the batch done, counting the running job's own fraction.

func (*Jobs) BatchJobs

func (q *Jobs) BatchJobs() []*Job

BatchJobs returns the jobs of the current batch in the order they were queued: those that ended, the running one and those that wait. It is empty while the queue is idle, so a view that shows a run after it ended keeps its own copy.

func (*Jobs) Busy

func (q *Jobs) Busy() bool

Busy reports whether a job runs or waits.

func (*Jobs) CanStop

func (q *Jobs) CanStop() bool

CanStop reports whether CancelAll would stop the running job, false when nothing runs or the running job is Unstoppable.

func (*Jobs) CancelAll

func (q *Jobs) CancelAll()

CancelAll cancels the running job and drops the queued ones; each dropped job's Done runs with context.Canceled.

An Unstoppable running job is not canceled: it finishes and reports its own result, and the queue stays busy until it does.

func (*Jobs) Current

func (q *Jobs) Current() *Job

Current is the running job, or nil.

func (*Jobs) Enqueue

func (q *Jobs) Enqueue(jobs ...*Job)

Enqueue adds jobs at the end of the queue and starts the first when nothing runs.

func (*Jobs) Find

func (q *Jobs) Find(source, key string) *Job

Find returns the newest job of source and key that waits or runs, else the newest that ended in the current batch; nil when there is none. Newest is the order of Enqueue: a queued job is newer than the running one. Work still to end comes first, so a job CancelAll dropped while an Unstoppable job of the same source and key runs does not hide that running job.

func (*Jobs) History

func (q *Jobs) History() []*Job

History are the ended jobs, newest last, at most 200.

func (*Jobs) Pending

func (q *Jobs) Pending(source, key string) bool

Pending reports whether a job of source and key waits or runs, whatever became of newer jobs of the same source and key.

func (*Jobs) Queued

func (q *Jobs) Queued() []*Job

Queued are the jobs waiting, in order.

func (*Jobs) Stopping

func (q *Jobs) Stopping() bool

Stopping reports whether a stop was asked while an Unstoppable job runs: it finishes first.

type KeyValue

type KeyValue struct {
	Key, Value string
	// Mono shows the value in the monospace font.
	Mono bool
}

KeyValue is one line of a KeyValues list.

type KeyValuesStyle

type KeyValuesStyle struct {
	// KeyWidth is the width of the names' column: 120 when zero.
	KeyWidth float32
	// Gap is the space between the lines: 6 when zero.
	Gap float32
	// FontSize is the size of the values: 13 when zero. A monospaced value
	// is half a point smaller.
	FontSize float32
}

KeyValuesStyle fits a KeyValues list to its place; its zero value is the list of a dialog. A narrow side panel takes a narrower names column and smaller values, as an inspector beside a table: KeyWidth 72, Gap 10, FontSize 12.5.

type Level

type Level uint8

Level is the kind of a console line, which the console's filter and colors follow.

const (
	// LevelDebug is the app's own diagnostic log.
	LevelDebug Level = iota
	// LevelOutput is a line a command printed.
	LevelOutput
	// LevelInfo is a step the app took or finished.
	LevelInfo
	// LevelCommand is a command the app started, shown as "$ argv".
	LevelCommand
	// LevelDryRun is a command dry-run mode did not start.
	LevelDryRun
	// LevelWarn is something that went partly wrong.
	LevelWarn
	// LevelError is a failure.
	LevelError
)

type LevelSet

type LevelSet uint16

LevelSet is a set of levels.

func (*LevelSet) Has

func (s *LevelSet) Has(l Level) bool

Has reports whether l is in the set.

func (*LevelSet) Toggle

func (s *LevelSet) Toggle(l Level)

Toggle adds l to the set or takes it out.

type Line

type Line struct {
	Seq    uint64
	At     time.Time
	Level  Level
	Source string
	Text   string
}

Line is one console line.

type NavItem struct {
	ID, Title, Icon string
	// Badge is a count shown at the end of the item, "" for none.
	Badge     string
	BadgeTone Tone
	// Shortcut names the keys that open the page, for its tooltip.
	Shortcut string
}

NavItem is one page of the left rail.

type NavSection struct {
	Title string
	Items []NavItem
}

NavSection is a titled group of rail items.

type Palette

type Palette struct {
	Open     bool
	Query    string
	Selected int
	// contains filtered or unexported fields
}

Palette is the command palette: a dialog with a field that filters the app's commands, which Up, Down and Enter choose and run.

func (*Palette) RunPending

func (p *Palette) RunPending()

RunPending runs the command chosen in the last frame, once the palette closed. The shell calls it before it builds the page, so a command that changes the page or asks a question shows in the same frame.

func (*Palette) Show

func (p *Palette) Show()

Show opens the palette with an empty query, at its first command, selected: the list scrolls back to its top, so the command Enter runs is the one shown highlighted.

func (*Palette) View

func (p *Palette) View(c *ui.Context, cmds []Command)

View draws the palette while it is open, and runs a chosen command after it closes (RunPending, when the shell has not already).

type Progress

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

Progress is how a running job reports, from its goroutine.

func (*Progress) Log

func (p *Progress) Log(level Level, format string, args ...any)

Log adds a line to the console under the job's source.

func (*Progress) Set

func (p *Progress) Set(fraction float64, status string)

Set reports the fraction done (0..1, or -1 when unknown) and a status line. Calls are coalesced: a post rebuilds the whole view, and a job may report every output line, so at most one post waits at a time and it applies the latest value.

type RowStatus

type RowStatus struct {
	// State picks the look: StepQueued and StepRunning show a spinner,
	// StepDone a check in the success color, StepFailed an error icon in
	// the danger color, and any other state Text alone, muted.
	State StepState
	// Text says the state in a word or two: "Queued", "Updating",
	// "Cleaned".
	Text string
	// Label names the spinner, and a compact failure's icon, for screen
	// readers, as "Syncing the inbox": Text when empty.
	Label string
	// Tooltip says more on hover: when it ended, or the error.
	Tooltip string
	// Compact fits a dense row: a running job's text as a caption, a job
	// that worked as a pill, and a failure as its icon alone, which leaves
	// room for the row's button after it.
	Compact bool
}

RowStatus is what JobStatus shows at the end of a row: a job that waits or runs, how it ended, or a note.

type SectionHead

type SectionHead struct {
	Icon, Title string
	// Note follows the title, muted, on one line.
	Note string
	// Aside is a caption at the end of the line: counts, a status.
	Aside string
	// Quiet sets the title in the muted color too, for a group whose items
	// carry the weight.
	Quiet bool
}

SectionHead is what heads a group of a page.

type Segment

type Segment struct {
	Label string
	Value float64
	Tone  Tone
}

Segment is one part of a SegmentBar.

type Series

type Series struct {
	Name   string
	Values []float64
	Tone   Tone
}

Series is one line of a LiveChart: values from 0 to 100, oldest first.

type Shell

type Shell struct {
	Brand    Brand
	Selected string
	Palette  Palette
	Console  ConsoleView
	// Dialogs are the confirmations the shell draws; share one with the
	// app's pages. Nil draws none.
	Dialogs *Dialogs
	Info    Info
	// contains filtered or unexported fields
}

Shell is the command-center window: a top bar with the brand, a field that opens the command palette and the app's actions; a left rail of pages with a footer; the page; an optional console under it; and a status bar. Keep one Shell in the app's state and call View from the root view every frame.

func (*Shell) View

func (s *Shell) View(c *ui.Context, f Frame)

View draws the shell.

type ShortcutEntry

type ShortcutEntry struct {
	Group, Title string
	Keys         []string
}

ShortcutEntry is one line of a keyboard shortcuts dialog.

type Stage

type Stage struct {
	Title, Icon string
	Note        string
	Steps       []Step
	// Empty is what the stage says when it has no steps ("Up to date").
	Empty string
}

Stage is one column of a Pipeline: a source of work, as an account.

type StatusItem

type StatusItem struct {
	Icon, Text string
	Tone       Tone
	// Tooltip explains the item; it also names it for screen readers.
	Tooltip string
	// OnClick makes the item a button.
	OnClick func()
	// Progress, 0..1, draws a small bar after the text; a negative value
	// draws none.
	Progress float64
}

StatusItem is one entry of the status bar.

type Step

type Step struct {
	Title string
	Note  string
	State StepState
}

Step is one item of a pipeline stage: a package, a mailbox, a file.

type StepState

type StepState int

StepState is the state of one item of a Pipeline.

const (
	// StepReady waits for a run.
	StepReady StepState = iota
	// StepQueued is in the run, after the items before it.
	StepQueued
	// StepRunning runs now.
	StepRunning
	// StepDone ended well.
	StepDone
	// StepFailed ended with an error.
	StepFailed
	// StepHeld is left out of the run, as an item that waits for the
	// user's confirmation.
	StepHeld
	// StepSkipped was left out by the user or canceled.
	StepSkipped
)

func StateOf

func StateOf(j *Job) StepState

StateOf maps a job's state to a step's.

type Tab

type Tab struct {
	Title, Icon string
}

Tab is one tab of PillTabs.

type Tile

type Tile struct {
	Icon string
	// Caption names the tile's place above its value: "Running now".
	Caption string
	// Value is the tile's value, in monospace: a version.
	Value string
	// Detail is a smaller monospaced line under the value, as a short
	// digest, and DetailTooltip what hovering it shows: the digest in full.
	Detail, DetailTooltip string
	// Pill is a neutral pill at the end, with PillIcon before its text:
	// "pinned".
	Pill, PillIcon string
	// Current highlights the tile in the accent: the one in use.
	Current bool
	// Dim fades the tile: an empty place.
	Dim bool
}

Tile is what a StepTile shows.

type Tone

type Tone int

Tone is the meaning a color carries.

const (
	// Neutral is the default: muted text on the surface.
	Neutral Tone = iota
	// Accent is the desktop's accent.
	Accent
	// Success is what went well or is on.
	Success
	// Warning is what needs attention.
	Warning
	// Danger is a failure or a destructive action.
	Danger
)

Directories

Path Synopsis
examples
commandcenter command
Commandcenter opens frostui's command-center shell with a small mail sync for content: a top bar with the command palette (Ctrl K), a rail of pages with the running job, the console (Ctrl J) and a status bar.
Commandcenter opens frostui's command-center shell with a small mail sync for content: a top bar with the command palette (Ctrl K), a rail of pages with the running job, the console (Ctrl J) and a status bar.
Package frostuitest helps test frostui views and the models behind them without a window.
Package frostuitest helps test frostui views and the models behind them without a window.
internal
repocheck
Package repocheck holds the repository's guard tests: the kit's import rule, its exported API, and its cross-platform build.
Package repocheck holds the repository's guard tests: the kit's import rule, its exported API, and its cross-platform build.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL