frostui

package module
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 27 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 frame without the rail for apps made of panes, a serial job queue, a command table behind keys, menus and the palette, a source list, a settings layout, an allow-listed opener, dialogs, cards, rows, charts, the desktop's icons (with an embedded set), and frostyard's look: the Frostyard and Frostyard light themes, set in Inter.
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. examples/threepane is a window of panes with no rail: go run ./examples/threepane. examples/sourcelist shows a source list, a command table, a lazy palette source and a settings dialog: go run ./examples/sourcelist.

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), a frame without the rail for apps made of panes (PaneShell, Panes), the cards, figures, pills, banners and dialogs that every page is built from, a serial job queue whose output streams to the console, a command table behind the keys, menus and palette, a source list, a settings layout, an allow-listed opener, and desktop integration (the desktop's icon theme with an embedded set behind it, 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, CommandTable, SourceList, Settings) is changed on the UI thread, except Console.Add, Waker.Wake and an Opener, which any goroutine may use. Workers hand results back with the post function the app gives NewJobs (MyGo's Window.Update), as a palette source's PaletteQuery.Reply; 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,
	// fields, banners and small tiles. The brand is nearly square
	// (ADR-0011): buttons take the theme's Radius, 4.
	RadiusCard = 0
	RadiusChip = 2

	// 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 ConsoleCommandID = "frostui.console"

ConsoleCommandID is the ID of PaneShell.ConsoleCommand.

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

DefaultLevels hides the app's debug log.

View Source
const FontFamily = "Inter"

FontFamily is the family the kit's themes set their text in: Inter, embedded in the kit (fonts/, under the SIL Open Font License 1.1 in fonts/OFL.txt) and registered under this name on the first Adapt.

View Source
const HeroSize = 64

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

View Source
const PaletteCommandID = "frostui.palette"

PaletteCommandID is the ID of Palette.Command.

View Source
const PaletteCommands = "commands"

PaletteCommands is the ID of the palette's own source, the commands it is given: ShowSource(PaletteCommands) opens it on the commands alone.

View Source
const ToastWidth = 640

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

Variables

View Source
var ErrNotAllowed = errors.New("not allowed")

ErrNotAllowed is what an Opener's refusals wrap: the target is not on its allow-lists.

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 sets the kit's theme for this frame and returns it: Frostyard when MyGo picked a dark theme for the desktop, Frostyard light otherwise (ADR-0011). The desktop's high contrast and text size still apply, but not its accent: the accent is the brand's, and it stays in windows without the focus. A theme that is already Frostyard (an app chose one itself, or Adapt ran earlier in the frame) is kept. MyGo resets the theme at each build pass, so call it first in the root view; Shell.View and PaneShell.View do. The first call registers the kit's font.

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

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

BannerClose is Banner with its close button named closeLabel, for assistive technology and its tooltip; "" draws no close button.

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 and a hairline border, on the panel gradient. 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, pane bars and status bar.

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

func ConnectingScreen(c *ui.Context, conn Connection) ui.Element

ConnectingScreen fills the window while an app has no daemon: what it connects to, the reason of the last failure, Retry and Details. It is the window's drag region under a hidden title bar, so draw it as the whole view; a PaneShell draws it for the Connecting state.

func ConnectionStatus added in v0.2.0

func ConnectionStatus(c *ui.Context, conn Connection) ui.Element

ConnectionStatus draws the status bar's connection item: a dot with "Local" or the host. While reconnecting it takes the warning tone, with the reason in its tooltip. PaneFrame.Connection draws it first in the status bar.

func DefaultOpenSchemes added in v0.2.0

func DefaultOpenSchemes() []string

DefaultOpenSchemes are the URL schemes an Opener with no Schemes opens.

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

func DropOn[K comparable, T any](l *SourceList[K], accept func(item K, v T) bool, drop func(item K, v T, mods ui.Modifiers))

DropOn makes the items of l take values of type T dropped on them, as messages on a mailbox or notes on a folder: accept reports whether item takes v, and the row shows that it does while v is over it; drop gets what is dropped there, with the modifier keys held (Ctrl or Alt to copy rather than move). Call it once, as the list is set up; call it again for other types.

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

func FrostyardTheme(dark bool) *ui.Theme

FrostyardTheme returns the kit's dark theme (Frostyard) or its light one (Frostyard light), before the desktop's preferences. Adapt sets the one the desktop asks for each frame; an app with its own light or dark setting passes its choice here, then the desktop's preferences without the accent:

p := c.Preferences()
p.Accent = ui.Color{}
c.SetTheme(frostui.FrostyardTheme(dark).WithPreferences(p))

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. It is a ghost: a hairline and no face, its icon in the hover text while the pointer is over it, and the accent face while it is Selected.

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

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

Label is an uppercase monospace label with letter spacing, in the theme colors' Label: a section title in a rail or source list. It shows s in capitals and keeps s as its accessible name.

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 primary button, on the brand gradient; otherwise it is a ghost, as IconButton.

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 looks up the desktop entry by ID and launches it through GIO. Missing, hidden or unlaunchable entries fail before the call returns. Lookup and activation may block: call it from a worker. It is safe from any goroutine and does not require MyGo to be running. The application inherits neither stdout nor stderr; GIO is called without a display launch context, so startup notification and Wayland activation are not supplied. Pass IDs from configuration or a package manager's list, not typed input: even entries hidden from the desktop menu can be launched by ID.

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

func NumberRow(c *ui.Context, title, subtitle string, value *float64, lo, hi, step float64) ui.Element

NumberRow is a setting with a number field from lo to hi at its end, labelled with the title, laid out as SwitchRow. It returns the field, for Disabled and Changed. Key it with c.Key.

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

func PaletteField(c *ui.Context, p *Palette) ui.Element

PaletteField is the field that opens the command palette, the same in every window: it reads "Search or run a command" and shows its key. It is a button, 380 DIPs wide unless the caller sets another width.

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 tag in a tone: a 1px outline in the tone's line around its text in capitals, in the tone's color (the tag text for Neutral).

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

func Rank[T any](items []T, query string, limit int, text func(T) string) []T

Rank returns the items whose text matches query, best first (Match), at most limit of them (0 for all); ties keep the items' order. With an empty query it returns the first limit items. It reads no UI state: a palette source ranks a large set on a worker with it.

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

func SanitizeMailto(raw string) (string, error)

SanitizeMailto returns the mailto link raw with only its addressees, subject and body (ADR-0010). It keeps the address and every field named to, cc, bcc, subject or body, in any ASCII case, as written and in order. It removes, rather than refuses, every other field (attach=), a field whose name is encoded (%61ttach) or has no "=", the fragment, and a "?" with nothing after it. It decodes nothing: a kept value passes byte for byte, "+" and malformed escapes included. It refuses, with an error wrapping ErrNotAllowed, what is not a mailto link or holds spaces or control characters. Opener.CheckURL applies it to every mailto link, then refuses one that names nothing.

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

func SelectRow(c *ui.Context, title, subtitle string, selected *string, options []string) ui.Element

SelectRow is a setting with a drop-down of options at its end, labelled with the title, laid out as SwitchRow. It returns the drop-down, for Disabled, Tooltip and Changed. Key it with c.Key.

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

func ShowActionToast(c *ui.Context, t ActionToast) string

ShowActionToast shows t and returns its ID, for Context.CloseToast. Each call shows a toast of its own, so one never replaces another and loses its OnExpire. Draw the window's toasts with TopToasts.

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

func TextRow(c *ui.Context, title, subtitle string, value *string) ui.Element

TextRow is a setting with a text field at its end, labelled with the title, laid out as SwitchRow. It returns the field, for Placeholder, Disabled and Changed. Key it with c.Key.

func TextSize added in v0.5.0

func TextSize(c *ui.Context, size float32) float32

TextSize returns size, in DIPs at the platform's usual text size, scaled to the theme's: what a kit style of that size draws at.

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, tightly spaced as the brand's.

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

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

ToneLine is the 1px outline of a pill or badge in tone.

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, and one made by ShowActionToast has its action button and its countdown. 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 ActionToast added in v0.2.0

type ActionToast struct {
	// Title says what happened.
	Title string
	// Action labels the button.
	Action string
	// Type is the toast's kind: "error" leads with a warning icon.
	Type string
	// Timeout is how long the toast shows: 8 seconds when 0, until it is
	// closed when negative.
	Timeout time.Duration
	// Countdown shows the seconds left before the button.
	Countdown bool
	// OnAction runs on the UI thread when the user chooses the action.
	OnAction func()
	// OnExpire runs on the UI thread when the toast closes without the
	// action: its time ended, or the user or Context.CloseToast closed it.
	OnExpire func()
}

ActionToast is a toast with an action, as Undo after a delete, and an optional countdown, as Undo Send's seconds. Exactly one of OnAction and OnExpire runs while the window is open. Neither runs when the window closes while the toast shows, so finish the pending work on close.

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"}, as the
	// palette shows it. Empty, the palette shows the first of Bindings.
	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()
	// Bindings are the keys a CommandTable binds to run the command, the
	// first of which the palette, the menus and the shortcuts dialog show.
	// The palette alone binds none.
	Bindings []KeyBinding
	// Enabled, when set, says each time the command is read whether it
	// runs now, and why not: it decides Disabled and Reason (Resolve).
	Enabled func() (ok bool, reason string)
	// Checked, when set, makes the command's menu item a setting it
	// toggles, checked while Checked returns true.
	Checked func() bool
	// Unlisted commands are bound and in menus, but the palette does not
	// list them, as the command that opens the palette.
	Unlisted bool
}

Command is one entry of the command palette: an action the app offers, or a place to go. A CommandTable holds the app's commands, binds their keys, builds menus of them and fills the palette.

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.

func (Command) Resolve added in v0.2.0

func (cmd Command) Resolve() Command

Resolve returns the command as it stands now: Disabled and Reason from Enabled when it is set, and Keys from the first of Bindings when Keys is empty.

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

type CommandTable struct {
	// Editing reports whether a text editor has the keyboard focus in
	// c's window: keys of the scope OutsideEditors step aside while it
	// does. Nil counts any element that takes text as an editor
	// (c.FocusTakesText), so that a key never goes past a field; an app
	// with editors names them, as with handles bound to them:
	//
	//	table.Editing = func(c *ui.Context) bool { return c.FocusWithin(app.editor) }
	Editing func(c *ui.Context) bool
	// contains filtered or unexported fields
}

CommandTable is an app's commands, one entry per command: its ID, title, group, keys (Command.Bindings), enabled rule (Command.Enabled) and run function. From the one table the app binds the keys at the window (Bind), fills the palette (Commands, or Frame.Table), builds menus (Menu, MenuItem) and lists the shortcuts (Shortcuts). It belongs to the UI thread, and binds the keys of one window: give each window its own table.

func NewCommandTable added in v0.2.0

func NewCommandTable(cmds ...Command) *CommandTable

NewCommandTable returns a table of cmds, in their order.

func (*CommandTable) Add added in v0.2.0

func (t *CommandTable) Add(cmds ...Command)

Add adds commands at the end of the table; one whose ID the table holds replaces that command in its place.

func (*CommandTable) Bind added in v0.2.0

func (t *CommandTable) Bind(c *ui.Context)

Bind binds the keys of the table's enabled commands at c's window, with ui.Context.OnWindowShortcut, where their scopes let them work: call it in every frame, as the shell does with Frame.Table. When two commands bind one key, the first enabled one in the table takes it, and the key is bound once. Keys bound behind a dialog wait, as every window shortcut does.

func (*CommandTable) BindKeys added in v0.2.0

func (t *CommandTable) BindKeys(c *ui.Context, keys []KeyBinding, run func())

BindKeys binds keys that run run at c's window, with the table's rule of where each scope works, for keys outside the table, as a window of the app's own binds PaletteBindings.

func (*CommandTable) Command added in v0.2.0

func (t *CommandTable) Command(id string) (Command, bool)

Command returns the command with the ID, as Commands gives it.

func (*CommandTable) Commands added in v0.2.0

func (t *CommandTable) Commands() []Command

Commands returns the table's commands in order, each as Resolve gives it (Disabled and Reason from Enabled, Keys from Bindings): the palette's commands, as Frame.Commands.

func (*CommandTable) Enabled added in v0.2.0

func (t *CommandTable) Enabled(id string) (ok bool, reason string)

Enabled reports whether the command with the ID runs now, and why not: false with "" for an ID the table does not hold.

func (*CommandTable) Menu added in v0.2.0

func (t *CommandTable) Menu(ids ...string) func(m *ui.Menu)

Menu returns a function that builds a menu of the commands with these IDs, in order, "" adding a separator: for Frame.Menu, ui.MenuButton, Element.ContextMenu and Element.PopoverMenu. Nest one in another with ui.Menu.Submenu:

row.ContextMenu(table.Menu("reply", "forward", "", "archive"))
m.Submenu("Mark", table.Menu("mark-read", "mark-unread"))

func (*CommandTable) MenuItem added in v0.2.0

func (t *CommandTable) MenuItem(m *ui.Menu, id string) *ui.MenuItem

MenuItem adds the command with the ID to m: its title, its first key, a check mark when Checked says so, grayed out with the reason as its tooltip when it does not run. Choosing it runs the command. It returns the item, nil for an ID the table does not hold.

func (*CommandTable) Remove added in v0.2.0

func (t *CommandTable) Remove(ids ...string)

Remove takes the commands with these IDs out of the table.

func (*CommandTable) Run added in v0.2.0

func (t *CommandTable) Run(id string) bool

Run runs the command with the ID when it is enabled, and reports whether it ran.

func (*CommandTable) Shortcuts added in v0.2.0

func (t *CommandTable) Shortcuts() []ShortcutEntry

Shortcuts lists the commands that have keys, in the table's order, for ShortcutsBody: grouped by Group, in the order the groups first come, with a line for each key.

func (*CommandTable) Tooltip added in v0.2.0

func (t *CommandTable) Tooltip(id string) string

Tooltip returns the command's title with its first key, as "Reply (Ctrl+R)", for an icon button's label and tooltip; the title alone without a key, "" for an ID the table does not hold.

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

type Connection struct {
	State ConnectionState
	// Daemon names what the app connects to, as a program's name.
	Daemon string
	// Host is where the daemon runs, "" for this computer.
	Host string
	// Reason says why the last try failed, "" for none.
	Reason string
	// OnClick makes the status item a button.
	OnClick func()
	// OnRetry and OnDetails are the connecting screen's Retry and Details
	// buttons; nil draws none.
	OnRetry, OnDetails func()
}

Connection is an app's connection to its daemon, for the status bar's first item (ConnectionStatus) and the connecting screen (ConnectingScreen).

type ConnectionState added in v0.2.0

type ConnectionState int

ConnectionState is how an app stands with the daemon it is a client of.

const (
	// Connected is a working connection.
	Connected ConnectionState = iota
	// Connecting is the first try, before the app has anything to show:
	// a PaneShell draws the connecting screen over the whole window.
	Connecting
	// Reconnecting is a lost connection the app tries to get back, while
	// it keeps showing what it had.
	Reconnecting
)

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
	// Title names the pane, as "Activity"; empty is "Console".
	Title string
	// Offered are the levels the pane offers to filter by, every level
	// when 0. A level not offered has no toggle and its lines do not
	// show.
	Offered LevelSet
	// EmptyNote is what the empty pane says under "Nothing yet"; empty
	// says "Commands and their output show here as they run."
	EmptyNote 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
	// Table, when set, is the app's command table, which owns the window's
	// shortcuts: the shell adds the palette's command (Palette.Command)
	// and, with a console, the console's (Shell.ConsoleCommand) to it,
	// binds its keys (CommandTable.Bind), binds none of its own, and lists
	// its commands in the palette after Commands. Ctrl K then steps aside
	// in editors, by the table's rule, in place of a plain Ctrl K.
	Table *CommandTable
	// 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. Everywhere, a name nothing else has comes from the kit's own set of Lucide icons, for the names the kit and frostyard's apps draw. 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; the kit's own set comes last, after the theme on Linux and after embedded elsewhere.

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

type KeyBinding struct {
	Mods  ui.Modifiers
	Key   ui.Key
	Scope KeyScope
}

KeyBinding is a key that runs a command: the key, its modifiers (ui.Cmd is Ctrl, or Command on macOS) and where it works.

func PaletteBindings added in v0.2.0

func PaletteBindings() []KeyBinding

PaletteBindings are the keys that open the command palette in every frostyard window: Ctrl K, except while a text editor has the focus, where it is the editor's (Insert Link), and Ctrl+Shift+P everywhere, editors included.

func (KeyBinding) Caps added in v0.2.0

func (b KeyBinding) Caps() []string

Caps returns the key caps of the binding, as {"Ctrl", "Shift", "P"}, for Shortcut and the palette: Ctrl, Alt, Shift and Super (Win on Windows) in that order, and the symbols of macOS there (⌃ ⌥ ⇧ ⌘).

func (KeyBinding) String added in v0.2.0

func (b KeyBinding) String() string

String returns the binding as a menu or a tooltip writes it: "Ctrl+K", or "⌘K" on macOS.

type KeyScope added in v0.2.0

type KeyScope uint8

KeyScope says where a key of a command works, by what has the keyboard focus. Whatever the scope, a text input still takes the keys it types and edits with (letters, Backspace, the arrows, Ctrl+C), and an element around the focus that binds the key itself (Element.OnShortcut) takes it first.

const (
	// OutsideEditors keys work wherever the focus is, except in a text
	// editor (CommandTable.Editing), which takes them for itself: Ctrl K
	// opens the palette, but is Insert Link in an editor. The zero value.
	OutsideEditors KeyScope = iota
	// OutsideText keys step aside while any element that takes text has
	// the focus: a one-line field as well as an editor.
	OutsideText
	// Everywhere keys work wherever the focus is, editors included:
	// Ctrl+Shift+P opens the palette everywhere.
	Everywhere
)

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

type Opener struct {
	// Schemes are the URL schemes OpenURL opens, in any case; nil is
	// DefaultOpenSchemes. A "file" entry opens nothing: files go through
	// OpenFile, under Roots. A mailto link always goes through
	// SanitizeMailto.
	Schemes []string
	// Roots are the directories OpenFile opens files under; none opens
	// no file. Symbolic links are followed before the check, so one
	// under a root that leads out of it is refused.
	Roots []string
	// Extensions, when set, are the only file extensions OpenFile opens,
	// as ".pdf", in any case. Set it for files from outside the app, as
	// attachments: without it OpenFile relies on a deny list of types that
	// run, install or redirect, a backstop that cannot be complete. Types
	// on the deny list are refused whether listed here or not.
	Extensions []string
	// Folders lets OpenFile open directories under Roots, in the file
	// manager.
	Folders bool
	// Launch and LaunchFile open what passed the checks; nil uses MyGo's
	// Shell.OpenExternal and Shell.OpenPath. A test sets them.
	Launch     func(url string) error
	LaunchFile func(path string) error
}

Opener opens links and files with the system's handlers, behind allow-lists, for what comes from outside the app: a link in a message or a note, an attachment. Its zero value opens http, https and mailto links, and no file. Anything else is refused with an error wrapping ErrNotAllowed. A mailto link opens as SanitizeMailto returns it. It holds no state, and is safe from any goroutine.

func (Opener) CheckFile added in v0.2.0

func (o Opener) CheckFile(path string) (string, error)

CheckFile reports whether OpenFile would open path, which must be absolute: its real path, symbolic links followed, or why not.

func (Opener) CheckURL added in v0.2.0

func (o Opener) CheckURL(raw string) (string, error)

CheckURL reports whether OpenURL would open raw: the URL as it would be opened, or why not. A mailto link is returned as SanitizeMailto returns it.

func (Opener) OpenFile added in v0.2.0

func (o Opener) OpenFile(path string) error

OpenFile opens the file at path with the system's handler for its type, when it is under an allowed root and passes the checks. It waits for the system: call it from a worker rather than a view.

func (Opener) OpenURL added in v0.2.0

func (o Opener) OpenURL(raw string) error

OpenURL opens raw with the system's handler for its scheme, when it is on the allow-list. It waits for the system, which may take a while: call it from a worker rather than a view.

type Palette

type Palette struct {
	Open     bool
	Query    string
	Selected int
	// Sources are what the palette finds besides the commands, shown
	// after them in this order.
	Sources []PaletteSource
	// contains filtered or unexported fields
}

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

func (*Palette) Command added in v0.2.0

func (p *Palette) Command() Command

Command is the command that opens the palette, on PaletteBindings; the palette does not list it. A frame with a table adds it there; an app may add it first, with another Title or Group.

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. It shows the commands and every source.

func (*Palette) ShowSource added in v0.2.0

func (p *Palette) ShowSource(id string)

ShowSource opens the palette as Show does, on the source with the ID alone (PaletteCommands for the commands), or on all of them for "".

func (*Palette) ShownSource added in v0.2.0

func (p *Palette) ShownSource() string

ShownSource returns the ID of the source the palette shows alone, "" when it shows all of them.

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

type PaletteItem struct {
	// ID identifies the item among its source's.
	ID string
	// Title is what the palette lists; Detail follows it, muted, as a
	// note's folder or a message's sender.
	Title, Detail string
	// Icon is a freedesktop icon name.
	Icon string
	// Group heads the item and those after it with the same group;
	// empty, the source's Title heads it.
	Group string
	// Keys are key caps shown at the end.
	Keys []string
	// Disabled items are listed, dimmed, and do not run; Reason says why.
	Disabled bool
	Reason   string
	// Run runs on the UI thread after the palette closes, as Enter or a
	// click chooses the item.
	Run func()
	// RunWith, when set, runs in place of Run with the modifier keys held
	// as the item was chosen: Ctrl+Enter, Ctrl+Alt+Enter, Shift+Enter or
	// a click with them, as to open a note in a new tab or to create one.
	RunWith func(mods ui.Modifiers)
}

PaletteItem is one result of a palette source.

type PaletteQuery added in v0.2.0

type PaletteQuery struct {
	// Text is the query, trimmed; "" as the palette opens, for the
	// source's recent items.
	Text string
	// Alone tells that the palette shows this source alone (ShowSource).
	Alone bool
	// contains filtered or unexported fields
}

PaletteQuery is a question the palette asks a source.

func (*PaletteQuery) Context added in v0.2.0

func (q *PaletteQuery) Context() context.Context

Context is canceled once the query is stale: the user typed past it, or the palette closed. A worker stops on it.

func (*PaletteQuery) Reply added in v0.2.0

func (q *PaletteQuery) Reply(items []PaletteItem) bool

Reply gives the source's results for the query, best first, in place of any it gave before (a source may answer in steps), and reports whether the palette took them: it drops those of a stale query. Call it on the UI thread, where the window's Update runs what a worker posts.

func (*PaletteQuery) Stale added in v0.2.0

func (q *PaletteQuery) Stale() bool

Stale reports whether the palette no longer waits for this query's results. Call it on the UI thread.

type PaletteSource added in v0.2.0

type PaletteSource struct {
	// ID identifies the source, for ShowSource.
	ID string
	// Title heads the source's results whose items name no group of
	// their own, as "Notes".
	Title string
	// Placeholder is the field's text while the palette shows the source
	// alone, as "Find a note"; "Search" and the title when empty.
	Placeholder string
	// Limit is the most results the source shows while other sources
	// show too; 0 shows them all. Shown alone, it shows all it gives.
	Limit int
	// Query asks the source for the results of q.Text. The palette calls
	// it on the UI thread as it opens on the source and each time the
	// query changes. The source answers with q.Reply, at once or later
	// from a worker through the window's Update; the palette drops a
	// reply to a query the user typed past.
	Query func(q *PaletteQuery)
}

PaletteSource is one kind of thing the palette finds besides the commands: notes by name, mailboxes, messages. The palette asks a source lazily, only while it shows it, once for each query, and shows its results in sections after the commands, in the order of the sources.

type Pane added in v0.2.0

type Pane struct {
	// ID names the pane in PaneLayout and in Panes' methods. It must be
	// unique among the panes.
	ID string
	// Label names the pane and its separator for assistive technology,
	// which sees the pane as a region. Empty leaves the pane unnamed and
	// calls the separator "Divider".
	Label string
	// Width is the pane's width until the user or a restored PaneLayout
	// gives it another. The first pane whose Width is 0 takes the room
	// left, and when no pane does, the last one takes it. Another pane
	// without a width starts 240 DIPs wide.
	Width float32
	// Min and Max bound the pane's width. A Min of 0 is 40 DIPs; a Max of 0
	// is no limit. The pane that takes the room left uses only Min.
	Min, Max float32
	// Collapsible lets the pane hide, through Panes.Toggle and
	// Panes.SetCollapsed; a window too narrow for every pane's Min hides
	// such panes too, the last first. The pane that takes the room left
	// never hides. A hidden pane is not built, so keep what it must remember
	// in the app's state.
	Collapsible bool
	// Bar draws the pane's segment of a PaneShell's top bar, which is as
	// wide as the pane; nil leaves the segment empty. Panes.View does not
	// draw it. The bar's end (the palette field, the frame's End, the
	// console's button and the main menu) lies over the end of the last
	// pane's segment, and of the ones before it when that pane is too
	// narrow for it: a Bar's items give way there.
	Bar func()
	// Content draws the pane, which is full height and does not scroll.
	Content func()
}

Pane is one pane of a Panes split.

type PaneFrame added in v0.2.0

type PaneFrame struct {
	// SidebarPane is the ID of the pane the toggle at the far left of the
	// top bar shows and hides, of SidebarPanes, or of the shell's Panes
	// when that is nil; the pane must be Collapsible. "" draws no toggle.
	SidebarPane  string
	SidebarPanes *Panes
	// Panes are the window's panes, which take the room under the top bar.
	Panes []Pane
	// Start draws a bar without Panes' items, after the toggle.
	Start func()
	// End draws the items after the palette field, before the console's
	// button and the main menu.
	End func()
	// Content draws the window's content without Panes: full height, not
	// scrolled and not padded.
	Content func()
	// Menu builds the main menu, the last item before the window controls;
	// nil for none.
	Menu func(m *ui.Menu)
	// InEditor says a text editor has the focus, so Ctrl K stays with it.
	// An editor that binds Ctrl K on its own element needs no flag: the
	// element around the focus hears the key first. With a Table it is
	// not read: CommandTable.Editing says.
	InEditor bool
	// Commands are the palette's commands. The console's is added when
	// there is a console and none has its ID.
	Commands []Command
	// Table, when set, is the app's command table, which owns the window's
	// shortcuts: the shell adds the palette's command (Palette.Command)
	// and the console's to it, binds its keys (CommandTable.Bind) and
	// binds none of its own, and the palette lists Commands and then the
	// table's commands.
	Table *CommandTable
	// Connection is the status bar's first item; its Connecting state
	// draws the connecting screen over the whole window. Nil for none.
	Connection *Connection
	// Status and StatusEnd are the status bar's items at its start, after
	// the connection, and at its end.
	Status, StatusEnd []StatusItem
	// ConsoleData is the console the console pane shows, nil for no
	// console.
	ConsoleData *Console
	// ToastCloseLabel names the close button of the window's toasts;
	// empty is "Close". The shell draws the toasts as TopToasts does,
	// under the top bar, so that a toast does not land on the button that
	// raised it and stop its own time under the pointer.
	ToastCloseLabel string
}

PaneFrame is what the app gives the shell to draw each frame. With Panes the top bar is made of each pane's Bar, as wide as the panes under them; without, the bar has Start, the palette field in the middle, and End.

type PaneLayout added in v0.2.0

type PaneLayout struct {
	Widths    map[string]float32 `json:"widths,omitempty"`
	Collapsed map[string]bool    `json:"collapsed,omitempty"`
}

PaneLayout is what the user changed in a Panes split: the width given to each pane and the panes collapsed, by ID. An app saves it and restores it to bring the layout back; it holds plain values for encoding/json, and the kit stores nothing.

type PaneShell added in v0.2.0

type PaneShell struct {
	Palette Palette
	Console ConsoleView
	// Dialogs are the confirmations the shell draws; share one with the
	// app's views. Nil draws none.
	Dialogs *Dialogs
	Info    Info
	// Panes is the split of PaneFrame.Panes; save and restore its Layout.
	Panes Panes
	// ConsoleHeight is the console's height in DIPs, which the user
	// changes and the app may save and restore; 0 is 240.
	ConsoleHeight float32
	// contains filtered or unexported fields
}

PaneShell is the window of an app whose content is its own panes: a top bar, full-height unscrolled content with no rail, an optional console under it and a status bar. A top bar's far left is the sidebar toggle and its end the palette field's side, the console's button and the main menu, in every app. Keep one PaneShell in the app's state and call View from the root view every frame.

func (*PaneShell) ConsoleCommand added in v0.2.0

func (s *PaneShell) ConsoleCommand() Command

ConsoleCommand is the palette's command that shows or hides the console, in the group "View". PaneFrame adds it; an app that keeps its commands in a table of its own may add it there, with another Group.

func (*PaneShell) View added in v0.2.0

func (s *PaneShell) View(c *ui.Context, f PaneFrame)

View draws the shell. Ctrl K opens the palette, except inside a text editor, which keeps the key for itself (PaneFrame.InEditor, or the Table's Editing); Ctrl Shift P opens it from everywhere. Ctrl J shows or hides the console.

type Panes added in v0.2.0

type Panes struct {
	// Layout is the state an app saves and restores.
	Layout PaneLayout
	// Step is how far an arrow key moves a separator, in DIPs; 0 is 16.
	Step float32
	// contains filtered or unexported fields
}

Panes lays out panes side by side, with a separator between each two that the user drags, or moves with the arrow keys, Home and End once it has the focus. A double click puts its pane back at its Width. A separator resizes the pane on its far side from the pane that takes the room left. Keep one Panes in the app's state and call View every frame.

func (*Panes) SetCollapsed added in v0.2.0

func (p *Panes) SetCollapsed(id string, collapsed bool)

SetCollapsed hides or shows a Collapsible pane. A pane shown this way is the last to hide for want of room. It ignores an ID that cannot hide: one not Collapsible, the pane that takes the room left, one no frame drew, and so every ID before the first frame. To start with a pane collapsed, set it in Layout.

func (*Panes) Shown added in v0.2.0

func (p *Panes) Shown(id string) bool

Shown reports whether the pane shows: it is not collapsed, and the last frame had room for it. Before the first frame no pane is known to be able to hide, so every ID shows.

func (*Panes) Toggle added in v0.2.0

func (p *Panes) Toggle(id string)

Toggle hides a pane that shows and shows one that does not.

func (*Panes) View added in v0.2.0

func (p *Panes) View(c *ui.Context, panes []Pane) ui.Element

View draws panes and returns the row that holds them; give it a size, as Fill or Grow.

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

type Setting struct {
	// Title names the setting; Subtitle explains it under the title.
	Title, Subtitle string
	// Keywords are matched by the search with the title and the
	// subtitle, but not shown: other words for the setting.
	Keywords string
	// Switch draws a switch of the value.
	Switch *bool
	// Choice draws a drop-down of Options.
	Choice  *string
	Options []string
	// Text draws a text field, with Placeholder when it is empty.
	Text        *string
	Placeholder string
	// Number draws a number field from Min to Max, in Step's steps.
	Number         *float64
	Min, Max, Step float64
	// Control draws a control of the app's, as a button.
	Control func(c *ui.Context)
	// Value is a read-only value, as a version or a key.
	Value string
	// Disabled grays out the control.
	Disabled bool
	// OnChange runs as the user changes the control's value; for a text
	// or number field, as they type.
	OnChange func()
}

Setting is one row of a settings page: a title, an optional line under it, and one control at its end, which the first field set of Switch, Choice, Text, Number and Control says. With none it shows Value.

type Settings added in v0.2.0

type Settings struct {
	// Selected is the ID of the page shown; empty or unknown, the first.
	Selected string
	// Search shows a field over the list, which finds settings on every
	// page; Query is its text.
	Search bool
	Query  string
	// Open says whether Dialog shows.
	Open bool
}

Settings is a settings layout: a list of sections at the left and the chosen section's rows at the right, for a settings window (View) or a dialog (Dialog). Keep one in the app's state; it belongs to the UI thread and to one window.

func (*Settings) Dialog added in v0.2.0

func (s *Settings) Dialog(c *ui.Context, title string, pages []SettingsPage)

Dialog draws the layout in a dialog while Open is set, under a title and a close button.

func (*Settings) Show added in v0.2.0

func (s *Settings) Show(id string)

Show opens the dialog on the page with the ID, or as it was for "".

func (*Settings) View added in v0.2.0

func (s *Settings) View(c *ui.Context, pages []SettingsPage) ui.Element

View draws the layout, filling its parent, and returns its row.

type SettingsGroup added in v0.2.0

type SettingsGroup struct {
	// Title heads the group; Note explains it under the title.
	Title, Note string
	// Settings are the card's rows.
	Settings []Setting
	// Values are read-only lines under the card, drawn with KeyValues.
	Values []KeyValue
}

SettingsGroup is a titled card of settings on a page.

type SettingsPage added in v0.2.0

type SettingsPage struct {
	// ID identifies the page, for Settings.Selected.
	ID string
	// Title names the page, in the list and over its content; Icon is a
	// freedesktop icon name.
	Title, Icon string
	// Keywords are matched by the search: a match on them or the title
	// shows the whole page.
	Keywords string
	// Groups are the page's cards of settings.
	Groups []SettingsGroup
	// Body, when set, draws what is not a row after the groups, as a
	// list of accounts. The search does not read it.
	Body func(c *ui.Context)
}

SettingsPage is one section of a settings layout: an entry of the list at the left, and what shows at the right as it is chosen.

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) ConsoleCommand added in v0.2.0

func (s *Shell) ConsoleCommand() Command

ConsoleCommand is the command that shows or hides the console, in the group "View". With Frame.Table the shell adds it to the table, unless the table or Frame.Commands holds a command with its ID.

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

type SourceList[K comparable] struct {
	// Label names the tree for assistive technology, as "Mailboxes".
	Label string
	// Children returns an item's children, nil for an item without any
	// (a leaf); an empty, non-nil slice for a branch that holds nothing
	// now. View asks it for every item open, every frame: keep it cheap.
	Children func(item K) []K
	// Row returns how an item shows.
	Row func(item K) SourceRow
	// Menu, when set, builds the context menu of item, as it shows in
	// section.
	Menu func(m *ui.Menu, item K, section string)
	// OnSelect runs as the user chooses an item, by a click or the keys.
	OnSelect func(item K)
	// OnClick handles an item's primary click or accessible activation,
	// independently of arrow-key selection. When OnActivate is nil, Enter,
	// Cmd+Enter, Cmd+Alt+Enter and the second click of a double click also
	// call OnClick for the chosen item.
	OnClick func(item K, mods ui.Modifiers)
	// OnMiddleClick handles a middle-button press on a row released over
	// the same row, unless canceled, without changing selection.
	OnMiddleClick func(item K, mods ui.Modifiers)
	// OnActivate runs on Enter or a double click on an item, with the
	// modifier keys held: Ctrl+Enter opens a note in a new tab.
	OnActivate func(item K, mods ui.Modifiers)
	// Rename, when set, lets the user rename items in place: F2 on the
	// item chosen, or StartRename, shows a field of its title; Enter, or
	// the focus leaving it, keeps the name, and Escape gives up. Rename
	// gets the new name, trimmed, unless it is empty or the title. A
	// rename whose row goes away ends without a call.
	Rename func(item K, name string)
	// CanRename, with Rename, reports whether an item can be renamed; nil
	// lets every item be.
	CanRename func(item K) bool
	// DragItems, when set, lets the user drag items out of the list,
	// onto an item of it (DropOn) or elsewhere: it returns the value they
	// drag, as ui.Drop takes it, nil for items that do not drag.
	DragItems func(items []K) any
	// contains filtered or unexported fields
}

SourceList is a sidebar of items in a tree, under section headers, as a mail app's mailboxes or a notes app's files. It draws on MyGo's Outline, which builds only the rows in view, so a tree of thousands of items is as fast as a small one. A click or the arrows choose an item; Left and Right close and open it; a click on a section's header hides and shows its items. Rows show an icon, the title, a tag, a spinner or an alert, and a count. Items take context menus (Menu), values dropped on them (DropOn) and new names typed in place (Rename). Assistive technology sees a tree of items with their levels, open or closed.

Keep one SourceList per window in the app's state, and call View from the view every frame. Its fields are read as View runs.

func (*SourceList[K]) ClearSelection added in v0.2.0

func (s *SourceList[K]) ClearSelection()

ClearSelection chooses no item.

func (*SourceList[K]) CollapseAll added in v0.2.0

func (s *SourceList[K]) CollapseAll()

CollapseAll closes every item, leaving the sections as they are.

func (*SourceList[K]) ExpandAll added in v0.2.0

func (s *SourceList[K]) ExpandAll()

ExpandAll opens every item of the sections View last drew that has children, walking the whole tree.

func (*SourceList[K]) IsOpen added in v0.2.0

func (s *SourceList[K]) IsOpen(section string, item K) bool

IsOpen reports whether item in section shows its children.

func (*SourceList[K]) OpenGeneration added in v0.3.0

func (s *SourceList[K]) OpenGeneration() uint64

OpenGeneration changes when the set of open items changes, including changes made by the arrows, assistive technology, Select and SetOpen.

func (*SourceList[K]) OpenItems added in v0.2.0

func (s *SourceList[K]) OpenItems(section string) []K

OpenItems returns the items of section that show their children, to keep them open the next time the app starts (SetOpen).

func (*SourceList[K]) Renaming added in v0.2.0

func (s *SourceList[K]) Renaming() bool

Renaming reports whether an item's name is being typed.

func (*SourceList[K]) SectionOpen added in v0.2.0

func (s *SourceList[K]) SectionOpen(id string) bool

SectionOpen reports whether the section with the ID shows its items. A section shows them until the user or SetSectionOpen hides them.

func (*SourceList[K]) Select added in v0.2.0

func (s *SourceList[K]) Select(section string, item K)

Select chooses item in section, or in the first section that holds it for "": View opens the items above it and scrolls to it. OnSelect does not run.

func (*SourceList[K]) Selected added in v0.2.0

func (s *SourceList[K]) Selected() (item K, section string, ok bool)

Selected returns the item chosen and the section it shows in; ok is false when none is.

func (*SourceList[K]) SetOpen added in v0.2.0

func (s *SourceList[K]) SetOpen(section string, item K, open bool)

SetOpen opens or closes item in section, showing or hiding its children.

func (*SourceList[K]) SetSectionOpen added in v0.2.0

func (s *SourceList[K]) SetSectionOpen(id string, open bool)

SetSectionOpen shows or hides the items of the section with the ID, as a click on its header does.

func (*SourceList[K]) StartRename added in v0.2.0

func (s *SourceList[K]) StartRename(section string, item K)

StartRename chooses item in section, or in the first section that holds it for "", and shows a field of its title in its row, when Rename is set and CanRename lets it.

func (*SourceList[K]) View added in v0.2.0

func (s *SourceList[K]) View(c *ui.Context, sections []SourceSection[K]) ui.Element

View draws the list of the sections' trees, filling the height its parent gives it (Grow it in a column), and returns the outline.

type SourceRow added in v0.2.0

type SourceRow struct {
	// Title is the item's name, which assistive technology reads and
	// typing its first letters chooses; Icon is a freedesktop icon name.
	Title, Icon string
	// Count is the badge at the row's end, as an unread count, "" for
	// none; CountTone colors it.
	Count     string
	CountTone Tone
	// Tag is a small label after the title, as a file's extension.
	Tag string
	// Busy shows a spinner at the row's end, as while a mailbox syncs.
	Busy bool
	// Alert, when set, shows a warning sign at the row's end with the
	// text as its tooltip and name, as why a mailbox fails to sync.
	Alert string
	// Dim draws the row muted, as an item not loaded or not supported.
	Dim bool
	// Spoken, when set, is what assistive technology reads after the
	// title, as "12 unread, syncing"; empty, it reads the tag, the count,
	// "busy" and the alert.
	Spoken string
}

SourceRow is how a SourceList shows an item.

type SourceSection added in v0.2.0

type SourceSection[K comparable] struct {
	// ID identifies the section among the list's.
	ID string
	// Title heads the section; a click on it hides and shows its items.
	// Empty, the section has no header and its items always show.
	Title string
	// Items are the section's items at the top of its tree. One item may
	// show in several sections, as a favorite mailbox does.
	Items []K
}

SourceSection is a titled group of a SourceList's items, as Favorites or an account's mailboxes.

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()
	// Menu opens a menu when the item is activated. It takes precedence over OnClick.
	Menu func(*ui.Menu)
	// 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 ThemeColors added in v0.5.0

type ThemeColors struct {
	// Chrome paints the top bar, the rail, pane bars, the status bar, the
	// console and source lists.
	Chrome ui.Color
	// Panel paints cards, dialogs, the palette and toasts; a card's face
	// is the gradient from PanelFrom to PanelTo.
	Panel, PanelFrom, PanelTo ui.Color
	// SelectedFill and SelectedText are the selected rail item's and
	// source-list row's face and text; the row takes a 1px accent rule on
	// its leading edge.
	SelectedFill, SelectedText ui.Color
	// HoverText is the text and icon color of a hovered button, row or
	// link, whose face does not change.
	HoverText ui.Color
	// GradientFrom and GradientTo are the primary button's face, at 135
	// degrees, and OnGradient its text.
	GradientFrom, GradientTo, OnGradient ui.Color
	// Label colors uppercase section titles, TagText a neutral pill's text,
	// Code the face of fields and the console, and LineStrong the outline
	// of what floats over the window, as a toast.
	Label, TagText, Code, LineStrong ui.Color
	// contains filtered or unexported fields
}

ThemeColors holds the colors of the kit's roles that ui.Theme has no field for. ColorsOf returns the one that goes with a theme.

func ColorsOf added in v0.5.0

func ColorsOf(t *ui.Theme) ThemeColors

ColorsOf returns the theme colors that go with t: the Frostyard colors of a Frostyard theme, and for any other theme (MyGo's own, or an app's) one derived from it as the kit drew before ADR-0011.

func (ThemeColors) Fill added in v0.5.0

func (p ThemeColors) Fill(tone Tone) ui.Color

Fill is the soft face behind tone's foreground, as a banner's.

func (ThemeColors) Line added in v0.5.0

func (p ThemeColors) Line(tone Tone) ui.Color

Line is the 1px outline of a pill or badge in tone.

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
)

type Waker added in v0.2.0

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

Waker coalesces wake-ups from many goroutines into at most one post per interval. MyGo's Window.Update rebuilds the view on every call, so a stream such as a console's output must not call it once per line: give the console Wake (Console.SetNotify), and Window.Update as post.

func NewWaker added in v0.2.0

func NewWaker(post func(func()), every time.Duration) *Waker

NewWaker returns a Waker that posts an empty function through post at most once every interval.

func (*Waker) Wake added in v0.2.0

func (w *Waker) Wake()

Wake asks for a rebuild, one interval from now unless one is already due. It is safe from any goroutine.

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.
sourcelist command
Sourcelist opens a pretend notes app built from frostui's shared pieces: a source list of folders and notes (drag a note onto a folder, F2 renames, right-click for a menu), one command table behind the keys, the main menu, the palette and the shortcuts dialog (F1), a palette source that finds notes on a worker (Ctrl O), and a settings dialog (Ctrl ,).
Sourcelist opens a pretend notes app built from frostui's shared pieces: a source list of folders and notes (drag a note onto a folder, F2 renames, right-click for a menu), one command table behind the keys, the main menu, the palette and the shortcuts dialog (F1), a palette source that finds notes on a worker (Ctrl O), and a settings dialog (Ctrl ,).
threepane command
Threepane opens frostui's frame without the rail with a small mail reader for content: three panes under a top bar whose segments follow them, a console called Activity (Ctrl J), the connection in the status bar, and Undo after a delete.
Threepane opens frostui's frame without the rail with a small mail reader for content: three panes under a top bar whose segments follow them, a console called Activity (Ctrl J), the connection in the status bar, and Undo after a delete.
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, its cross-platform build, and its rule that no ui.Handle is made in a view.
Package repocheck holds the repository's guard tests: the kit's import rule, its exported API, its cross-platform build, and its rule that no ui.Handle is made in a view.

Jump to

Keyboard shortcuts

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