window

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: AGPL-3.0 Imports: 46 Imported by: 0

README

ui/window

English | 简体中文

Window: open, close, bring to front (including activation token), window shortcut keys, event loop, off-screen screenshots, as well as read system preferences and complete platform events that Gio does not have.

File Responsibility
window.go Open, Main, Options (including Overlay), Window (Raise, Activate, WaylandDisplay…)
shortcut.go Shortcut key analysis and distribution
icon*.go SetIcon: The runtime application icon (macOS Dock, Windows window, X11 _NET_WM_ICON), the shape is cut out by internal/appicon according to the platform specification
root.go Window root view: background, scroll, 24dp margins
position_* First display centered; macOS calculated based on available screen area, other platforms use Gio actions
screenshot.go Screenshot Off-screen rendering to PNG
decorations*.go Linux compositor is drawn by Keel when not drawing title bar
titlebar_darwin.* Title bar drag area of macOS borderless window
scene_ios.* Experimental iOS scene lifecycle adapter, selected by KeelSceneDelegate in Info.plist; see iOS simulator
activation_* Activate(token): Wayland uses xdg-activation, X11 writes the startup ID and then requests activation
motion_* System preferences: reduce dynamic effects (macOS), scrollbar auto-hide (macOS, Windows), write in theme
scroll_darwin.m, scroll_wayland* The device and gesture stages of scrolling (trackpad hand lift, scroll wheel) are not provided by Gio and are left to core.ReportScrollGesture
automation.go Automation mode: memory window, semantic snapshot, simulated click input scrolling
automation_server.go Automation protocol: JSON request on KEEL_AUTOMATION socket
testdata/raise Real window deadlock regression testing
  • Dependencies: core, theme, internal/appicon (icon shape, shared with scaffolding), and jezek/xgb (X11 activation) and libwayland-client (Gio natively linked) on Linux. Does not rely on el, kit: the window only recognizes the core.Widget interface, and the system preferences are handed over to el through theme.
  • Used by: Application code. cmd/keel-mcp drives it through the socket protocol and does not reference its code.

When the environment variable KEEL_AUTOMATION=1 (or socket path) is set to start the application, each window will have an additional shadow window for Agent operations; the real window will be displayed as usual, and the Agent's operations will be reflected on the screen in real time. Adding KEEL_HEADLESS=1 will not display the window, see Agent end-to-end test.

window.Open(window.Options{Title: "Hello", Content: page})
window.Main() // Exit the process after the last window is closed

Before changing the code here, read Architecture · Cannot wait for the main thread in the lock. See Window and Application for details.

Main for macOS subscribes to NSWorkspace's accessibility display preferences and scrollbar styles, reading "Reduce Dynamic Effects" and "Show Scrollbars" on startup, and updating theme.ReducedMotion and theme.SystemScrollbarsAutoHide when they change. The AppKit callback is handed to the background consumer through a bounded queue, and then the topic is updated in core.Update to avoid the main thread waiting for the frame lock. "Auto-hide scroll bars" is read once when Windows starts. Windowless and off-screen automation modes do not install native observers, Linux currently uses application settings.

macOS native traffic light layout

Frameless windows can retain AppKit's standard buttons and center them within a custom titlebar. Layout uses dp; native button size, appearance and behavior remain owned by AppKit. A nil TrafficLightLayout keeps system placement. A positive Height enables custom placement, Left sets the first button's left inset, and OffsetY shifts its center down (positive) or up (negative). Zero Spacing preserves the system spacing.

w := window.Open(window.Options{
    Frameless: true,
    NativeTrafficLights: true,
    TrafficLightLayout: &window.TrafficLightLayout{
        Height: 44, Left: 15, Spacing: 23,
    },
    Content: page,
})
w.SetTrafficLightLayout(window.TrafficLightLayout{Height: 64, Left: 20})

Reserve the top-left button area in your content. Keel reapplies placement after resizing, fullscreen transitions and AppKit layout passes. The option is macOS-only; runtime updates are safe from callbacks and background goroutines.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Main 

func Main()

Main runs the platform event loop. The process exits after the last window closes. With KEEL_AUTOMATION set it also serves automation requests, or only those with KEEL_HEADLESS=1; see automation.go.

func Screenshot 

func Screenshot(content core.Widget, width, height int, path string) error

Screenshot renders content as a window would, off-screen at 2× scale, and writes a PNG. Width and height are in dp.

func ScreenshotAtScale 

func ScreenshotAtScale(content core.Widget, width, height int, scale float32, path string) error

ScreenshotAtScale renders the first frame at an explicit pixel density. Dimensions are in dp; scale must be finite and positive.

func SetIcon added in v0.0.7 

func SetIcon(artwork []byte) error

SetIcon sets the app's icon from full-bleed square PNG artwork, as in a keel project's appicon.png: macOS shows it in the Dock with Apple's plate and shadow; Windows on every window's title bar and taskbar button; Linux X11 on every window (_NET_WM_ICON). Wayland and the browser take their icon from the installed .desktop entry and the page, so SetIcon does nothing there. It applies to open windows and to those opened later; call it before Open, or any time to change the icon.

func SocketDir 

func SocketDir() string

SocketDir is where apps started with KEEL_AUTOMATION=1 listen. keel-mcp computes the same path; keep the two in sync.

Types

type Element 

type Element struct {
	Ref      string `json:"ref"`
	Role     string `json:"role"` // see roleOf
	Name     string `json:"name,omitempty"`
	Value    string `json:"value,omitempty"`    // textbox content, select choice, progress
	Checked  *bool  `json:"checked,omitempty"`  // checkbox, radio, switch
	Selected *bool  `json:"selected,omitempty"` // tab, row, option; a button only when selected
	Disabled bool   `json:"disabled,omitempty"`
	X        int    `json:"x"`
	Y        int    `json:"y"`
	Width    int    `json:"width"`
	Height   int    `json:"height"`
}

Element is one node of a window's semantic tree, as reported to agents.

type Options 

type Options struct {
	Title         string
	Width, Height int
	Content       core.Widget
	// Overlay is drawn over the whole window, above Content, for hand-written
	// Gio content; el views declare overlays with cx.Overlay instead. It should
	// take no space while it has nothing to show.
	Overlay core.Widget
	// Shortcuts maps accelerators to callbacks while the window has focus, e.g.
	// "mod+," (Cmd on macOS, Ctrl elsewhere), "ctrl+shift+s", "esc".
	Shortcuts map[string]func()
	OnClose   func()
	// Frameless hides the system title bar so the content can draw its own,
	// e.g. a kit.TitleBar; the content then starts at the window's top edge.
	Frameless bool
	// NativeTrafficLights keeps AppKit's standard window buttons visible over
	// frameless content on macOS. Reserve the top-left titlebar area in Content.
	// Other platforms ignore this option.
	NativeTrafficLights bool
	TrafficLightLayout  *TrafficLightLayout
}

Options configures a window. Width and Height are in dp; zero uses 640×480.

type Snapshot 

type Snapshot struct {
	Window   WindowInfo `json:"window"`
	Elements []Element  `json:"elements"`
}

Snapshot is a window and its elements.

type TrafficLightLayout added in v0.1.5 

type TrafficLightLayout struct {
	Height, Left, OffsetY, Spacing float32
}

TrafficLightLayout positions macOS's standard window buttons in dp. Buttons retain their system size, rendering and native behavior. Height is the custom titlebar height; buttons are centered vertically in it. Left is the first button's left inset. OffsetY moves the center down (or up when negative). Spacing is the distance between button centers; zero keeps AppKit's spacing. A nil layout in Options keeps AppKit's default placement.

type Window 

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

func Open 

func Open(o Options) *Window

Open creates and shows a centered window where the platform supports it. Call it before Main or from any callback. It panics on an invalid shortcut, which is a programming error.

func (*Window) Activate added in v0.0.4 

func (w *Window) Activate(token string)

Activate brings the window to the front with an activation token that another program granted, such as notification.Activation.Token after a system notification was clicked. Window managers let a token through their focus-stealing prevention, where a plain Raise may only flash the taskbar. On Wayland the token goes to xdg-activation; on X11 it is a startup ID. Elsewhere, with an empty token, or if the platform refuses, Activate is Raise.

func (*Window) Close 

func (w *Window) Close()

Close closes the window as if the user clicked its close button.

func (*Window) Closed 

func (w *Window) Closed() bool

Closed reports whether the window has been destroyed. Call it from UI code.

func (*Window) Focused 

func (w *Window) Focused() bool

func (*Window) Frameless 

func (w *Window) Frameless() bool

Frameless reports whether the window draws its own title bar.

func (*Window) Maximized 

func (w *Window) Maximized() bool

Maximized reports whether the window is maximized. Call it from UI code.

func (*Window) Minimize 

func (w *Window) Minimize()

Minimize hides the window in the Dock or taskbar.

func (*Window) Raise 

func (w *Window) Raise()

Raise brings the window to the front.

func (*Window) SetTrafficLightLayout added in v0.1.5 

func (w *Window) SetTrafficLightLayout(layout TrafficLightLayout)

SetTrafficLightLayout updates native button placement without recreating the window. It is safe from callbacks or background goroutines; the change is applied on the next frame. NativeTrafficLights must be enabled in Options.

func (*Window) TitleBarArea 

func (w *Window) TitleBarArea(x, y, width, height float32)

func (*Window) ToggleMaximize 

func (w *Window) ToggleMaximize()

ToggleMaximize maximizes the window (zooms it on macOS), or restores it when it is maximized.

func (*Window) WaylandDisplay added in v0.0.4 

func (w *Window) WaylandDisplay() unsafe.Pointer

WaylandDisplay is this window's wl_display on Linux Wayland, nil elsewhere or before the window is shown. Pass it to native/clipboard's UseWaylandDisplay to read the clipboard while this window has focus.

type WindowInfo 

type WindowInfo struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
	Active bool   `json:"active"`
}

WindowInfo describes an open window.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.