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
- Variables
- func AboutBody(a About) func(c *ui.Context)
- func Adapt(c *ui.Context) *ui.Theme
- func Banner(c *ui.Context, tone Tone, icon, text, action string, closable bool) (acted, closed bool)
- func BannerClose(c *ui.Context, tone Tone, icon, text, action, closeLabel string) (acted, closed bool)
- func Body(c *ui.Context, s string) ui.Element
- func Caption(c *ui.Context, s string) ui.Element
- func Card(c *ui.Context) ui.Element
- func CardHeader(c *ui.Context, title, subtitle string, trailing func())
- func Chrome(t *ui.Theme) ui.Color
- func CodeDialog(c *ui.Context, title, summary, text, action string) (acted, canceled bool)
- func ColorPill(c *ui.Context, text string, color ui.Color) ui.Element
- func CommandRow(c *ui.Context, it CommandItem) ui.Element
- func ConnectingScreen(c *ui.Context, conn Connection) ui.Element
- func ConnectionStatus(c *ui.Context, conn Connection) ui.Element
- func DefaultOpenSchemes() []string
- func DesktopIconTheme() string
- func DisclosureCard(c *ui.Context, open *bool, d Disclosure) (toggled bool)
- func DotPill(c *ui.Context, text string, color ui.Color) ui.Element
- func DropOn[K comparable, T any](l *SourceList[K], accept func(item K, v T) bool, ...)
- func Duration(d time.Duration) string
- func Empty(c *ui.Context, icon, title, body string) ui.Element
- func Figures(c *ui.Context, figs []Figure) ui.Element
- func Gauge(c *ui.Context, value, maxValue float64, center, caption string, tone Tone, ...) ui.Element
- func Heading(c *ui.Context, s string) ui.Element
- func Hero(c *ui.Context, icon HeroIcon, title, description string) ui.Element
- func Icon(c *ui.Context, name string) ui.Element
- func IconButton(c *ui.Context, icon, label string) ui.Element
- func IconPill(c *ui.Context, icon, text string, tone Tone) ui.Element
- func IconSVG(name string) *ui.SVG
- func IconTile(c *ui.Context, icon string, tone Tone, size float32) ui.Element
- func Initials(name string) string
- func JobCard(c *ui.Context, q *Jobs)
- func JobStatus(c *ui.Context, s RowStatus)
- func Kbd(c *ui.Context, key string) ui.Element
- func KeyValues(c *ui.Context, rows []KeyValue, style ...KeyValuesStyle) ui.Element
- func LabeledButton(c *ui.Context, icon, label string, primary bool) ui.Element
- func LaunchDesktopApp(id string) error
- func Legend(c *ui.Context, tone Tone, text string) ui.Element
- func LiveChart(c *ui.Context, label string, height float32, series ...Series) ui.Element
- func Loading(c *ui.Context, text string) ui.Element
- func Match(query, text string) (score int, ok bool)
- func Mono(c *ui.Context, s string) ui.Element
- func Muted(c *ui.Context, s string) ui.Element
- func NumberRow(c *ui.Context, title, subtitle string, value *float64, lo, hi, step float64) ui.Element
- func PageHeader(c *ui.Context, title, subtitle string, actions func())
- func PaletteField(c *ui.Context, p *Palette) ui.Element
- func Panel(t *ui.Theme) ui.Color
- func Pill(c *ui.Context, text string, tone Tone) ui.Element
- func PillTabs(c *ui.Context, selected *int, tabs []Tab) ui.Element
- func Pipeline(c *ui.Context, stages []Stage) ui.Element
- func Problem(c *ui.Context, text string) ui.Element
- func Rank[T any](items []T, query string, limit int, text func(T) string) []T
- func RowDivider(c *ui.Context) ui.Element
- func RunSummary(jobs []*Job) string
- func SanitizeMailto(raw string) (string, error)
- func Section(c *ui.Context, icon, title, note string, fn func())
- func SectionHeader(c *ui.Context, h SectionHead) ui.Element
- func SegmentBar(c *ui.Context, label string, total float64, parts []Segment, ...) ui.Element
- func SelectRow(c *ui.Context, title, subtitle string, selected *string, options []string) ui.Element
- func SetAppID(id, displayName string) error
- func SetIcons(ic *Icons)
- func Shortcut(c *ui.Context, keys ...string) ui.Element
- func ShortcutsBody(entries []ShortcutEntry) func(c *ui.Context)
- func ShowActionToast(c *ui.Context, t ActionToast) string
- func SoftSelection(t *ui.Theme) *ui.Theme
- func SquareAvatar(c *ui.Context, name string, size float32) ui.Element
- func StepDots(c *ui.Context, n, current int) ui.Element
- func StepTile(c *ui.Context, s Tile) ui.Element
- func Strong(c *ui.Context, s string) ui.Element
- func SwitchRow(c *ui.Context, title, subtitle string, on *bool) ui.Element
- func Text(lines []Line) string
- func TextRow(c *ui.Context, title, subtitle string, value *string) ui.Element
- func TileGrid(c *ui.Context) ui.Element
- func Title(c *ui.Context, s string) ui.Element
- func ToggleTile(c *ui.Context, icon, title, sub string, on, busy bool) bool
- func ToneColor(t *ui.Theme, tone Tone) ui.Color
- func ToneFill(t *ui.Theme, tone Tone) ui.Color
- func Toned(c *ui.Context, s string, tone Tone) ui.Element
- func TopToasts(c *ui.Context, closeLabel string)
- func VersionChange(c *ui.Context, from, to string) ui.Element
- type About
- type ActionToast
- type Brand
- type Command
- type CommandItem
- type CommandTable
- func (t *CommandTable) Add(cmds ...Command)
- func (t *CommandTable) Bind(c *ui.Context)
- func (t *CommandTable) BindKeys(c *ui.Context, keys []KeyBinding, run func())
- func (t *CommandTable) Command(id string) (Command, bool)
- func (t *CommandTable) Commands() []Command
- func (t *CommandTable) Enabled(id string) (ok bool, reason string)
- func (t *CommandTable) Menu(ids ...string) func(m *ui.Menu)
- func (t *CommandTable) MenuItem(m *ui.Menu, id string) *ui.MenuItem
- func (t *CommandTable) Remove(ids ...string)
- func (t *CommandTable) Run(id string) bool
- func (t *CommandTable) Shortcuts() []ShortcutEntry
- func (t *CommandTable) Tooltip(id string) string
- type Confirm
- type Connection
- type ConnectionState
- type Console
- func (c *Console) Add(level Level, source, text string)
- func (c *Console) Addf(level Level, source, format string, args ...any)
- func (c *Console) Clear()
- func (c *Console) Counts() (warnings, errors int)
- func (c *Console) Lines(levels *LevelSet, query string) []Line
- func (c *Console) Seq() uint64
- func (c *Console) SetNotify(fn func())
- func (c *Console) Writer(level Level, source string) *ConsoleWriter
- type ConsoleView
- type ConsoleWriter
- type Dialogs
- type Disclosure
- type Figure
- type Frame
- type HeroIcon
- type Icons
- type Info
- type Job
- type JobState
- type Jobs
- func (q *Jobs) Batch() (done, total int)
- func (q *Jobs) BatchFraction() float64
- func (q *Jobs) BatchJobs() []*Job
- func (q *Jobs) Busy() bool
- func (q *Jobs) CanStop() bool
- func (q *Jobs) CancelAll()
- func (q *Jobs) Current() *Job
- func (q *Jobs) Enqueue(jobs ...*Job)
- func (q *Jobs) Find(source, key string) *Job
- func (q *Jobs) History() []*Job
- func (q *Jobs) Pending(source, key string) bool
- func (q *Jobs) Queued() []*Job
- func (q *Jobs) Stopping() bool
- type KeyBinding
- type KeyScope
- type KeyValue
- type KeyValuesStyle
- type Level
- type LevelSet
- type Line
- type NavItem
- type NavSection
- type Opener
- type Palette
- type PaletteItem
- type PaletteQuery
- type PaletteSource
- type Pane
- type PaneFrame
- type PaneLayout
- type PaneShell
- type Panes
- type Progress
- type RowStatus
- type SectionHead
- type Segment
- type Series
- type Setting
- type Settings
- type SettingsGroup
- type SettingsPage
- type Shell
- type ShortcutEntry
- type SourceList
- func (s *SourceList[K]) ClearSelection()
- func (s *SourceList[K]) CollapseAll()
- func (s *SourceList[K]) ExpandAll()
- func (s *SourceList[K]) IsOpen(section string, item K) bool
- func (s *SourceList[K]) OpenGeneration() uint64
- func (s *SourceList[K]) OpenItems(section string) []K
- func (s *SourceList[K]) Renaming() bool
- func (s *SourceList[K]) SectionOpen(id string) bool
- func (s *SourceList[K]) Select(section string, item K)
- func (s *SourceList[K]) Selected() (item K, section string, ok bool)
- func (s *SourceList[K]) SetOpen(section string, item K, open bool)
- func (s *SourceList[K]) SetSectionOpen(id string, open bool)
- func (s *SourceList[K]) StartRename(section string, item K)
- func (s *SourceList[K]) View(c *ui.Context, sections []SourceSection[K]) ui.Element
- type SourceRow
- type SourceSection
- type Stage
- type StatusItem
- type Step
- type StepState
- type Tab
- type Tile
- type Tone
- type Waker
Constants ¶
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.
const AllLevels = LevelSet(1<<levelCount - 1)
AllLevels is every level.
const ConsoleCommandID = "frostui.console"
ConsoleCommandID is the ID of PaneShell.ConsoleCommand.
const DefaultLevels = AllLevels &^ (1 << LevelDebug)
DefaultLevels hides the app's debug log.
const HeroSize = 64
HeroSize is the side of a Hero's icon tile, in DIPs.
const PaletteCommandID = "frostui.palette"
PaletteCommandID is the ID of Palette.Command.
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.
const ToastWidth = 640
ToastWidth is the widest a TopToasts toast grows, in DIPs.
Variables ¶
var ErrNotAllowed = errors.New("not allowed")
ErrNotAllowed is what an Opener's refusals wrap: the target is not on its allow-lists.
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 Adapt ¶
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 ¶
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 Card ¶
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 ¶
CardHeader is a card's title row: a heading, an optional subtitle under it, and trailing controls at the end.
func Chrome ¶
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 ¶
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 ¶
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 ¶
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 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 Hero ¶
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 ¶
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 ¶
IconButton is a flat button showing only an icon. label names it for screen readers and its tooltip; it must not be empty.
func IconTile ¶
IconTile is an icon on a rounded square, as rows and cards lead with. size is the square's side.
func Initials ¶
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 ¶
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 ¶
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 KeyValues ¶
KeyValues is a two-column list of names and values. An optional style sets its metrics.
func LabeledButton ¶
LabeledButton is a button with an icon before its label. primary makes it the accent button.
func LaunchDesktopApp ¶
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 LiveChart ¶
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 Match ¶
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 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 ¶
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
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 PillTabs ¶
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 ¶
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 Rank ¶ added in v0.2.0
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 ¶
RowDivider is the hairline between rows of a card.
func RunSummary ¶
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
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 ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
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 ¶
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 SwitchRow ¶
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 TextRow ¶ added in v0.2.0
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 TileGrid ¶
TileGrid lays tiles out in rows that wrap, as ToggleTiles: chain Children to fill it.
func ToggleTile ¶
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 TopToasts ¶
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.
Types ¶
type About ¶
type About struct {
Name, Version, Summary string
Logo string // icon name
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 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.
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
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 ¶
NewConsole returns a console keeping the newest capacity lines.
func (*Console) Add ¶
Add appends a line. Text with several lines becomes several lines, all of level.
func (*Console) Counts ¶
Counts returns how many warnings and errors were added since the last Clear.
func (*Console) Lines ¶
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) 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.
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.
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.
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 {
// 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 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 ¶
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.
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.
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 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 ¶
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 ¶
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 ¶
BatchFraction is the share of the batch done, counting the running job's own fraction.
func (*Jobs) BatchJobs ¶
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) CanStop ¶
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) Enqueue ¶
Enqueue adds jobs at the end of the queue and starts the first when nothing runs.
func (*Jobs) Find ¶
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.
type KeyBinding ¶ added in v0.2.0
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 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 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
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
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.
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
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
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
ShownSource returns the ID of the source the palette shows alone, "" when it shows all of them.
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
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.
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
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
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.
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress is how a running job reports, from its goroutine.
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 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.
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
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.
type ShortcutEntry ¶
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 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 )
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 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.
Source Files
¶
- appid.go
- appid_linux.go
- commandtable.go
- components.go
- connection.go
- console.go
- consoleview.go
- dialogs.go
- doc.go
- icons.go
- icons_linux.go
- iconset.go
- jobs.go
- launch.go
- launch_linux.go
- opener.go
- palette.go
- panes.go
- paneshell.go
- pipeline.go
- rows.go
- settings.go
- shell.go
- sourcelist.go
- text.go
- theme.go
- toasts.go
- viz.go
- waker.go
- wizard.go
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. |
