Documentation
¶
Overview ¶
Package lightron makes desktop apps out of web pages, on a Chromium that is already on the machine instead of one shipped with every app (Electron's ~100MB). A Go program calls Run with the page to show; what users install is that program, a few MB.
- macOS: the user's own Chrome (or Edge, Brave, Chromium), run from a copy of its bundle renamed into the app (its name, id and icon), so the Dock, ⌘Tab, the menu bar and notifications are the app's. Windows are --app windows: a bare title bar. Lightron drives it over the DevTools protocol (a pipe, not a port).
- Windows: WebView2, the system's Chromium (Edge's), in a window of the app's own.
The page talks to Go through window.lightron (see bridge.js): invoke a bound Go function, send a message, listen to events. Links to other sites open in the default browser. See README.md and docs/ for how it works and why.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoBrowser = ErrUnsupported
ErrNoBrowser is macOS's; declared here so code using it builds everywhere.
var ErrUnsupported = errors.New("lightron: this platform isn't supported yet")
ErrUnsupported is returned by Run on a platform Lightron doesn't run on yet (Linux).
var Separator = MenuItem{Separator: true}
Separator is a menu separator line.
Functions ¶
func Accelerator ¶
Accelerator parses an accelerator ("Cmd+Shift+K", "Ctrl+Enter", "F5") into a key equivalent and its modifiers (cmd, ctrl, shift, alt), the way AppKit menus take them. An empty string gives "".
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is a running app.
func (*App) FocusOrOpen ¶
func (a *App) FocusOrOpen()
FocusOrOpen brings a window up, or opens one if there is none.
func (*App) NewWindow ¶
NewWindow opens a window on path ("" = the page's root). Not on Windows yet.
type MenuItem ¶
type MenuItem struct {
Label string
// Accelerator is shown next to the item and triggers it when the page doesn't take the key: "Cmd+Shift+K",
// "Cmd+,", "Ctrl+Enter", "F5".
Accelerator string
// Role makes it a standard item (Label and Click may be empty): hide, hideOthers, unhide, quit, undo, redo, cut,
// copy, paste, selectAll, minimize, zoom, front, close, toggleFullScreen, zoomIn, zoomOut, resetZoom, devTools,
// reload; and, at the top level of Menu, editMenu and windowMenu.
Role string
// Click runs when the item is chosen, with the focused window (nil if none).
Click func(w *Window)
Submenu []MenuItem
// Separator makes it a separator line.
Separator bool
}
MenuItem is a menu item, a separator, or a submenu.
func DefaultMenu ¶
DefaultMenu is the menu bar an app gets when Options.Menu is nil: the app menu (Hide, Hide Others, Show All, Quit), Edit and Window. Start from it to add your own:
menu := lightron.DefaultMenu("Notes")
menu = append(menu[:2], append([]lightron.MenuItem{{Label: "File", Submenu: …}}, menu[2:]...)...)
type Options ¶
type Options struct {
// Name is the app's name in the Dock / taskbar, ⌘Tab, the menu bar and notifications.
Name string
// ID is a reverse-DNS identifier (com.example.notes): macOS bundle ids, data directories.
ID string
// Version is the app's version (shown nowhere by Lightron; for your About box and updates).
Version string
// Icon is a square PNG, 512px or larger. On macOS it becomes the app's icon in the Dock.
Icon []byte
// URL is a page served by something else, e.g. a backend your app starts. An http URL on this machine is shown
// at http://<Host>/ (see Host); https and remote URLs are shown as they are.
URL string
// Handler serves the pages instead: Lightron runs it on a private loopback port that only the app's windows can
// use (a secret cookie, set on the first load).
Handler http.Handler
// Host is the name pages are shown at (http://<Host>/), on macOS. Chrome writes the page's origin under every
// web notification; "notes" reads better there than "127.0.0.1:53817". Default: the last part of ID, lowercased.
Host string
// Window is the first window. Path is relative to the page's root ("/" by default).
Window WindowOptions
// Menu is the macOS menu bar: its first item's Submenu is the app menu, the others are menus in order. Items
// with Role "editMenu" / "windowMenu" stand for the browser's own Edit and Window menus (they handle copy /
// paste, the window list). nil: an app menu (Hide, Quit…), Edit, Window.
Menu []MenuItem
// DockMenu is the menu of the app's Dock icon on macOS (above the window list and Quit macOS adds).
DockMenu []MenuItem
// Bind are Go functions the page can call: await lightron.invoke("name", ...args). Arguments arrive as JSON
// decoded into the parameters' types; return a value, an error, or (value, error). A first parameter of type
// *Window receives the window that called.
Bind map[string]any
// OnMessage receives what the page sends with lightron.send(value).
OnMessage func(w *Window, msg json.RawMessage)
// OnReady runs once the first window has been asked for.
OnReady func(a *App)
// OnSecondInstance runs when the app is opened again while running (only one runs at a time). Default: bring a
// window up, or open one.
OnSecondInstance func(a *App)
// KeepRunning keeps the app running when its last window closes (macOS: the Dock icon reopens one). Default:
// quit.
KeepRunning bool
// DataDir holds Lightron's state (the browser profile, the engine copy on macOS). Default:
// ~/Library/Application Support/<ID>/lightron, %LOCALAPPDATA%\<ID>\lightron.
DataDir string
// Logf receives Lightron's log lines. Default: log.Printf.
Logf func(format string, args ...any)
}
Options describe the app. Name, ID, and one of URL or Handler are required.
type Window ¶
type Window struct {
// contains filtered or unexported fields
}
Window is one window of the app.
type WindowOptions ¶
WindowOptions describe a window.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lightron
command
Command lightron starts, packages and publishes Lightron apps.
|
Command lightron starts, packages and publishes Lightron apps. |
|
examples
|
|
|
hello
command
hello: a Lightron app whose pages are served by a Go http.Handler, calling Go from JS and back.
|
hello: a Lightron app whose pages are served by a Go http.Handler, calling Go from JS and back. |
|
wrap
command
wrap: an app around a page served by something else, e.g.
|
wrap: an app around a page served by something else, e.g. |
|
internal
|
|
|
cdp
Package cdp is a minimal Chrome DevTools Protocol client over --remote-debugging-pipe: JSON messages, each followed by a NUL byte, the browser reading fd 3 and writing fd 4.
|
Package cdp is a minimal Chrome DevTools Protocol client over --remote-debugging-pipe: JSON messages, each followed by a NUL byte, the browser reading fd 3 and writing fd 4. |
|
macengine
Package macengine finds the Chromium-family browser on a Mac and makes the copy of it an app runs on: the app's name, id and icon in its Info.plist, so to macOS the running browser is the app (its Dock icon, ⌘Tab entry, menu bar, notifications), and its --app windows have a bare title bar.
|
Package macengine finds the Chromium-family browser on a Mac and makes the copy of it an app runs on: the app's name, id and icon in its Info.plist, so to macOS the running browser is the app (its Dock icon, ⌘Tab entry, menu bar, notifications), and its --app windows have a bare title bar. |
|
macmenu
Package macmenu holds the macOS menu library (objc/menu.m, built into lightronmenu.dylib by `make menulib`) and writes it out for the engine to load.
|
Package macmenu holds the macOS menu library (objc/menu.m, built into lightronmenu.dylib by `make menulib`) and writes it out for the engine to load. |
|
pack
Package pack writes what packaging needs without the platform's tools: icons (.icns, .ico), Info.plist, the NSIS installer script.
|
Package pack writes what packaging needs without the platform's tools: icons (.icns, .ico), Info.plist, the NSIS installer script. |
|
Package update keeps a Lightron app up to date from a feed: a JSON file listing the latest version and a package per platform (what `lightron feed` writes), e.g.
|
Package update keeps a Lightron app up to date from a feed: a JSON file listing the latest version and a package per platform (what `lightron feed` writes), e.g. |
