Package app

AutostartEnabled reports whether an entry with the id is installed.

ClipboardImagePNG returns the clipboard's image as PNG bytes, ErrNoImage when it holds none, and ErrTooLarge when the PNG would exceed MaxClipboardImageBytes. The platforms hand over what they have in one of their native formats and Viva transcodes to PNG: macOS reads public.png or converts public.tiff, Windows reads the registered "PNG" format or converts CF_DIBV5 and CF_DIB (palette, 16, 24 and 32 bit, with alpha), and Linux reads the X11 CLIPBOARD target image/png in a single property transfer (an owner that streams it with INCR is reported as unsupported). The Web target returns ErrAsyncRequired; use RequestClipboardImage there. The caller owns the returned bytes; decode them with image/png. Nothing of the image is retained by Viva.

DeleteSecret removes the secret saved for the service and account. Removing what is not there is not an error.

HasClipboardImage reports whether the clipboard holds an image, without reading it, so a Paste button can be enabled cheaply. It never blocks on macOS, Windows or in a Driver run. On Linux a clipboard owned by another application is asked for its formats, which waits for that application for up to three seconds, so ask when a dialog opens or a window gains focus, not on every frame. The Web target cannot ask synchronously and reports false.

HighContrast reports whether the user turned on a high-contrast theme, which asks an application to draw in strong colors with clear borders rather than its own palette. Windows reports it; macOS and Linux do not yet, and report false. WatchSystemAppearance calls its watchers when it changes, as when the look switches between light and dark, so read it while painting.

LoadSecret returns the secret saved for the service and account, or ErrSecretNotFound. Like StoreSecret it may wait for the user.

MonospaceFamilies lists the fixed-pitch font families installed on this system, sorted and without duplicates. An application offers them to the user and gives the chosen one to ui.MonoFamily to draw terminal text in it.

The list is read from the system on every call and can take tens of milliseconds, so it is for a settings page, not for painting. It is empty where the platform cannot enumerate fonts (a browser, an unsupported target), in which case ui.MonoSystem and ui.MonoClassic remain the choices.

OpenDirectory asks the user to choose one existing local directory.

OpenPath opens a local file in the application the system has chosen for its type, as a double click in the file manager does. It is for documents; a file that the system would execute (a program, a script host's file, an installer, a shortcut, a bundle) is refused with ErrExecutablePath, because a path that came from somewhere else must never become a way to run it. The path must be absolute and name a regular file, not a link or a directory. Driver-backed runs record the request without asking the system to open anything.

PanelCornerRadius is the radius, in logical pixels, at which the system cuts the corners of a WindowPanel: whatever the panel paints beyond it is not shown. Draw the panel's edge as a ui.Canvas.RoundedBorder of this radius so the outline follows the corner instead of being clipped by it. It is zero where panels have square corners.

PlatformTextEngine is the text engine RunCanvas installs on a canvas: the platform's own shaped lines, so widths, carets and hits agree with the glyphs it draws. It is nil on a target that has none, whose canvases measure with the reference metrics.

PreferredLanguages lists the languages the user asked their system to speak, most preferred first, as BCP 47 tags such as "zh-Hans-CN" or "en-US". It is empty where the system does not say. An application uses it to pick the language of its own interface when the user has not chosen one: it follows the person's setting, which a time zone or a region does not (a Chinese time zone is common on an English system).

macOS and Windows report the user's UI language list, the browser reports navigator.languages, and Linux reads LANGUAGE, LC_ALL, LC_MESSAGES and LANG.

PrimarySelection is the primary selection's text, empty when nothing is selected anywhere. An editor reads it on a middle click. It returns ErrUnsupported where there is no primary selection.

ReduceMotion reports the system accessibility preference for reduced motion. Windows, macOS and Linux are queried (on Linux the settings portal, the XSETTINGS manager or KDE's animation speed); other targets report false.

RequestClipboardImage delivers ClipboardImagePNG's answer to done, which is the way to read an image on the Web target, where the browser answers through a Promise after asking permission (call it from an input handler). Native platforms and driver runs call done before returning, with the same result as ClipboardImagePNG. done runs exactly once.

Run starts the native application loop and blocks until the final window closes. It must be called from the program's main goroutine.

RunApplication starts the native application loop. start runs once on the locked native event-loop thread and must open at least one window. The call blocks until the final window closes or a platform error terminates the loop.

RunCanvas presents a retained canvas and blocks until the native window closes. When config.Paint is set the canvas is repainted on window resizes and pointer interactions; otherwise the initial canvas stays unchanged.

SetAutostart turns starting this program at login on or off for the current user: a launch agent on macOS, an autostart entry on Linux, a Run value on Windows. Nothing runs until the next login. It records the path of the running executable, so a program that moves must call it again.

SetNativeAppearance pins the look of what the system draws for the application, as opposed to what the application draws itself: window buttons, native menus, file dialogs, native text editing. An application that lets the user choose light or dark regardless of the system calls it when that choice changes, so those parts match the window; AppearanceUnknown gives them back to the system. SystemAppearance keeps reporting the system's own look meanwhile.

macOS applies it. Windows and Linux draw the window's buttons with Viva, so there is nothing for it to do there, and the browser's page colors are the application's own.

SetPrimarySelection makes text the primary selection, the second clipboard of X11 desktops that selecting text fills without a copy command and a middle click pastes. An editor calls it as its selection changes; empty text gives the selection up. Only Linux has one: elsewhere it returns ErrUnsupported, so a caller ignores that error.

StoreSecret saves a secret in the system's own store for credentials: the macOS Keychain, the Windows Credential Manager, or a Secret Service such as GNOME Keyring or KWallet. service names the application's use ("my-app vault key") and account tells entries of that use apart; together they are the key, and storing again replaces the secret. Another application cannot read it without the operating system's consent, and it is not in any file the application keeps.

The call is synchronous and may wait for the user: a locked store asks to be unlocked. It must not be made from a hot path.

TitlebarInsets is how much of a WindowCustomTitlebar's strip the system or Viva covers with window buttons: leading at the start of the strip, trailing at its end, in logical pixels. An application keeps its own content clear of both. On macOS the traffic lights are the system's, at the leading end.

UseApplicationRunner makes RunApplication use run instead of native windows. Package headless/auto installs this only in explicitly tagged tool builds.

UseRunner makes RunCanvas call run instead of opening a window. It is how development tools such as package headless drive an unmodified application: the application's main function still builds its Config and calls RunCanvas, and the tool decides what that means. Nothing calls it unless such a tool is linked in, so release builds keep the window loop only.

WatchSystemAppearance calls changed whenever the system switches between its light and dark looks, or turns high contrast on or off (HighContrast), and not when it merely says so again, until stop is called. changed runs on the event-loop thread: it should note the change and request a redraw (see Invalidator), then read SystemAppearance while painting.

macOS and the browser are told of the switch, Windows hears the settings change message, and Linux listens to the settings portal's signal on one connection to the session bus that the event loop polls, open only while something watches (no thread), plus the XSETTINGS manager's change and the window gaining focus for desktops without a portal.

MaxClipboardImageBytes is the largest PNG ClipboardImagePNG returns.

MaxSecretSize is the longest secret StoreSecret accepts, in bytes. It is what the smallest store (the Windows Credential Manager) holds with room to spare: the intended contents are keys and tokens, not documents.

WindowControlWidth is the width in logical pixels of each of the minimize, maximize and close buttons Viva draws in a custom titlebar. They are as tall as Config.TitlebarHeight.

ErrAutostartUnsupported means this system has no login-start mechanism Viva drives.

ErrExecutablePath is returned by OpenPath for a file the system would run instead of showing.

ErrNoGraphics is what opening a window returns, wrapped with what to install, on a machine that has no graphics driver: Linux without Vulkan, or Windows without even the software Direct3D device. A cloud server with no GPU runs a window through a software driver (Mesa's lavapipe on Linux, WARP on Windows, used automatically); one with no display needs the headless build. Test it with errors.Is.

ErrNoStatusArea is returned by AddStatusItem when the desktop has nowhere to put an icon, as a Linux session without a StatusNotifier host. The application is fine without one: keep its windows closable instead of hiding them.

ErrNoTerminal is returned by Driver.Chord when no terminal has the keyboard.

ErrNoTextInput is returned by Driver.Type and the editing shortcuts when no text field has keyboard focus.

ErrNoWindows is returned when an application startup callback returns without opening a window. A native application must always have at least one explicit owner for its event loop.